1 rollouts.storage.qh_reader
rollouts.storage.qh_reader
Bounded reader for validated finite-candidate Q_H rollout chains.
Persisted integrity belongs to zarr_store; tensor and actor-store composition belongs to aria_nbv.data_handling.qh_data.
1.1 Classes
| Name | Description |
|---|---|
| QhDataContract | Replay support, learning semantics, and selected-observation compatibility. |
| QhRolloutChainIdentity | Metadata-only identity and support facts for one admitted rollout chain. |
| QhRolloutReader | Read compatible validated stores through bounded chain slices. |
1.1.1 QhDataContract
rollouts.storage.qh_reader.QhDataContract(
schema_version,
target_protocol,
reward_metric,
return_semantics,
td_semantics,
discount_gamma,
reason_code_version,
actor_store_version,
candidate_config_hashes=(),
rollout_config_hashes=(),
selection_policies=(),
oracle_query_mode='legacy_unspecified',
label_support_semantics='subset_of_action_v1',
selected_depth_enabled=False,
selected_depth_role=None,
selected_depth_renderer=None,
selected_depth_image_size_hw=None,
selected_depth_dtype=None,
selected_depth_units=None,
selected_depth_znear_m=None,
selected_depth_zfar_m=None,
selected_depth_source_resolution=None,
selected_depth_projection_model=None,
selected_depth_value_semantics=None,
selected_depth_pixel_convention=None,
selected_depth_camera_axes=None,
selected_depth_pose_convention=None,
selected_depth_geometry=None,
action_mask_semantics='oracle_action_mask_v1',
)Replay support, learning semantics, and selected-observation compatibility.
1.1.1.1 Attributes
| Name | Description |
|---|---|
| candidate_config_hashes | Referenced candidate-generation configurations admitted by the corpus. |
| rollout_config_hashes | Referenced rollout configurations admitted by the corpus. |
| selection_policies | Referenced behavior-policy vocabulary admitted by the corpus. |
| oracle_query_mode | Oracle candidate-query support persisted by every admitted rollout store. |
| label_support_semantics | Relationship between oracle labels and actor-valid rows on realized states. |
| selected_depth_enabled | Whether each factual step has aligned selected-action depth evidence. |
| selected_depth_role | Semantic role of persisted selected depth when enabled. |
| selected_depth_renderer | Renderer provenance for selected depth when enabled. |
| selected_depth_image_size_hw | Common selected-depth raster height and width in pixels. |
| selected_depth_dtype | Persisted metric-depth dtype name. |
| selected_depth_units | Physical units of finite selected-depth values. |
| selected_depth_znear_m | Near clipping plane in metres. |
| selected_depth_zfar_m | Far clipping plane in metres. |
| selected_depth_source_resolution | Recorded resolution policy used to produce selected depth. |
| selected_depth_projection_model | Versioned camera model implied by the schema and renderer provenance. |
| selected_depth_value_semantics | Meaning of each finite depth value; the supported contract is camera-frame z in metres. |
| selected_depth_pixel_convention | Pixel sampling convention used by rendering and PyTorch3D backprojection. |
| selected_depth_camera_axes | Physical camera-axis convention used by the selected render. |
| selected_depth_pose_convention | Direction of the aligned selected camera pose stored elsewhere in the rollout. |
| selected_depth_geometry | Complete validated geometry facts for selected depth, when enabled. |
| action_mask_semantics | Meaning of actor-valid support; current generated stores use Oracle hard-valid masks. |
1.1.1.2 Methods
| Name | Description |
|---|---|
| learning_semantics | Return the population-independent fitted-Q compatibility contract. |
1.1.1.2.1 learning_semantics
rollouts.storage.qh_reader.QhDataContract.learning_semantics()Return the population-independent fitted-Q compatibility contract.
Candidate-generator, rollout-recipe, and behavior-policy hashes describe which populations a stage contains. They are valuable provenance and remain bound in each dataset and bundle, but they are not mathematical reward, mask, target, horizon, or replay semantics. Removing only these three vocabularies lets scene-disjoint validation and test stages probe controlled population shift without pretending their artifacts are the training corpus.
1.1.1.2.1.1 Returns
| Name | Type | Description |
|---|---|---|
| 'QhDataContract' | A value-equal contract projection suitable only for cross-stage | |
| 'QhDataContract' | compatibility checks. The original stage contract remains the | |
| 'QhDataContract' | training and provenance owner. |
1.1.2 QhRolloutChainIdentity
rollouts.storage.qh_reader.QhRolloutChainIdentity(
store_index,
rollout_row_id,
source_sample_index,
scene_id,
target_row_id,
configured_horizon,
candidate_width_min,
candidate_width_max,
candidate_config_hash,
rollout_config_hash,
selection_policy,
)Metadata-only identity and support facts for one admitted rollout chain.
The identity is available without decoding candidate poses, oracle labels, or actor-store tensors. It therefore supports deterministic corpus census and bounded diagnostic selection without creating a second scorer input path. Candidate widths describe materialized finite-action support, not a planning-tree branching axis.
1.1.2.1 Attributes
| Name | Description |
|---|---|
| store_index | Zero-based store ordinal in the reader’s ordered store tuple. |
| rollout_row_id | Persistent rollout-chain row identifier inside the source store. |
| source_sample_index | Immutable VIN actor-store row referenced by the rollout chain. |
| scene_id | ASE scene identifier validated through the source record. |
| target_row_id | Persistent target row identifier inside the source store. |
| configured_horizon | Fixed acquisition budget used to generate this factual chain. |
| candidate_width_min | Smallest materialized candidate-table width across realized states. |
| candidate_width_max | Largest materialized candidate-table width across realized states. |
| candidate_config_hash | Exact candidate-generator configuration digest bound by lineage. |
| rollout_config_hash | Exact rollout-recipe configuration digest bound by lineage. |
| selection_policy | Persisted factual behavior-policy identifier. |
1.1.3 QhRolloutReader
rollouts.storage.qh_reader.QhRolloutReader(
store_dirs,
*,
campaign_split=None,
include_selected_depth=False,
)Read compatible validated stores through bounded chain slices.
1.1.3.1 Attributes
| Name | Description |
|---|---|
| source_target_task_identities | Return root-qualified source and semantic target keys for chains. |
| source_refs | Return unique private source identities admitted during preflight. |
| scenes | Return scenes referenced by the admitted source identities. |
| max_horizon | Return the largest configured horizon among admitted chains. |
| contract | Return common semantics plus the exact admitted replay-support mixture. |
| provenance | Return preflighted corpus identity without reopening stores. |
| target_descriptor_identity | Return the admitted target-descriptor identities for experiment receipts. |
1.1.3.2 Methods
| Name | Description |
|---|---|
| chain_identity | Return bounded-selection metadata without materializing a chain. |
| termination_reason | Return the validated stored stop cause for one factual chain. |
1.1.3.2.1 chain_identity
rollouts.storage.qh_reader.QhRolloutReader.chain_identity(index)Return bounded-selection metadata without materializing a chain.
1.1.3.2.1.1 Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| index | int | Zero-based admitted-chain index; negative indices follow standard Python sequence semantics. | required |
1.1.3.2.1.2 Returns
| Name | Type | Description |
|---|---|---|
| QhRolloutChainIdentity | Immutable source, target, candidate-support, and behavior-lineage | |
| QhRolloutChainIdentity | identity for stratified diagnostics. No actor or oracle tensor is | |
| QhRolloutChainIdentity | read through this method. |
1.1.3.2.1.3 Raises
| Name | Type | Description |
|---|---|---|
| IndexError | If index is outside the admitted corpus. |
1.1.3.2.2 termination_reason
rollouts.storage.qh_reader.QhRolloutReader.termination_reason(index)Return the validated stored stop cause for one factual chain.
This controls learning admission but stays outside the exact-Q2 chain identity, which describes the materialized actor and action data.