1 data_handling.qh_contracts

data_handling.qh_contracts

Dependency-light Q_H profile and selected-observation contracts.

This leaf owns the shared names and structural validation needed by Q_H data, VIN scorers, Lightning, and bundle admission. It intentionally does not import the rich aria_nbv.data_handling.qh_data runtime graph, so scorers can depend on these contracts during package initialization without forming a data_handling -> vin -> qh_data cycle. Tensor DTOs, materialization, learning, and deployment remain in their respective owners.

1.1 Functions

Name Description
validate_experiment_profile Validate one named Q_H source/execution role.
validate_selected_observation_prefix Validate the structural contract of one causal CF-GT carrier.

1.1.1 validate_experiment_profile

data_handling.qh_contracts.validate_experiment_profile(
    profile,
    *,
    root_evl_profile,
    selected_observation_protocol,
    target_protocol=None,
    privileged=False,
)

Validate one named Q_H source/execution role.

1.1.1.1 Parameters

Name Type Description Default
profile QhExperimentProfile Closed CF0 or privileged CF+ role. required
root_evl_profile QhRootEvlProfile Root scene-evidence carrier paired with the role. required
selected_observation_protocol QhSelectedObservationProtocol Dynamic selected-observation source. required
target_protocol str | None Optional target-source identity when known. None
privileged bool Whether the calling execution owner admits privileged CF+. False

1.1.1.2 Raises

Name Type Description
ValueError If the named role and its source or execution contracts are inconsistent.

1.1.2 validate_selected_observation_prefix

data_handling.qh_contracts.validate_selected_observation_prefix(
    prefix,
    *,
    history_mask,
    step_mask,
)

Validate the structural contract of one causal CF-GT carrier.

This validator owns only carrier identity, tensor layout, dtype, device, and causal support. It deliberately does not interpret depth, calibration, or pose values. That distinction lets the root_moments_v1 CF+ H0 control admit the exact same source population as the S1 encoder while proving that no selected-observation payload reaches H0 prediction. S1 separately strengthens numeric geometry validation before interpreting the structurally admitted carrier.

The two trailing axes of history_mask are query state :math:s and selected-observation index :math:j. prefix_mask must equal the factual pose-history mask and must be true exactly for realized :math:j<s pairs. Therefore neither future observations nor observations attached to padded query/source states can enter the carrier.

1.1.2.1 Parameters

Name Type Description Default
prefix QhSelectedObservationPrefix Unbatched S,S,... or batched B,S,S,... selected-depth carrier. required
history_mask Tensor Factual selected-pose support with shape S,S or B,S,S. required
step_mask Tensor Realized-state support with shape S or B,S. required

1.1.2.2 Raises

Name Type Description
ValueError If source identity, shapes, dtypes, devices, or exact strictly causal support differ from the Q_H actor contract.
Back to top