1 data_handling.qh_data.views
data_handling.qh_data.views
Factual views of finite-candidate, fixed-budget rollout chains.
These immutable DTOs separate actor-visible state from oracle supervision and CPU-only source identity. They describe stored facts only: learner-specific backup admission and value-target construction belong to the fitted-Q learner. The shapes below use this shared legend. A QhChain has no batch axis: S is its realized number of decision states, N its stored candidate width, P its semidense-point capacity, and F its root trajectory length. QhBatch adds a leading B axis and owns all padded-batch shape documentation. D_v H_v W_v are EVL voxel-grid axes; V=D_v*H_v*W_v is the flattened voxel-centre axis; H_d W_d are selected depth-raster axes; and C_p is the number of extra semidense point channels after XYZ. 12 is the stored PoseTW representation and 6 is the voxel-frame extent [x_min, x_max, y_min, y_max, z_min, z_max].
Every tensor field below documents only its canonical, non-batched chain shape. Remaining horizon is represented as the stored acquisition budget at each state, not as a scorer query object. This module owns those factual DTO definitions, not storage decoding or batch construction.
1.1 Attributes
| Name | Description |
|---|---|
| QhRepresentationSemantics | Representations admitted by online decisions; privileged selected depth is excluded. |
1.2 Classes
| Name | Description |
|---|---|
| QhActorTensors | Actor-visible tensors for one complete, non-batched chain. |
| QhAudit | CPU-only chain provenance retained when explicit diagnostics are requested. |
| QhChain | One complete, non-empty rollout chain before batch-axis padding. |
| QhChainKey | CPU-only identity and generation support for one joined rollout chain. |
| QhSelectedObservationPrefix | Strictly causal CF-GT depth history for every realized rollout state. |
| QhStaticContext | Immutable root evidence shared by every realized state in one chain. |
| QhSupervision | Oracle labels and factual selected transitions kept outside the actor. |
1.2.1 QhActorTensors
data_handling.qh_data.views.QhActorTensors(
vin_snippet,
root_pose_world,
target_pose_relative_root,
target_extents,
candidate_pose_relative_root,
candidate_mask,
action_mask,
history_pose_relative_root,
history_mask,
horizon_remaining,
step_mask,
static_context=None,
selected_observation_prefix=None,
)Actor-visible tensors for one complete, non-batched chain.
A chain state combines immutable root observation evidence with a finite candidate table, strictly causal factual-action history, and the fixed-task acquisition budget remaining at that state. Oracle rewards and label availability are deliberately absent so a scorer cannot condition on privileged supervision. For every row, action_mask implies candidate_mask. QhBatch owns padding and its leading batch axis.
1.2.1.1 Attributes
| Name | Description |
|---|---|
| vin_snippet | VinSnippetView with points_world Tensor["P 3+C_p", float32]; see QhStaticContext.vin_snippet for complete root fields. |
| root_pose_world | PoseTW["12"]: world-from-root-rig pose after the fixed local-Z basis correction; translation is metres. |
| target_pose_relative_root | PoseTW["12"]: root-rig-from-target-object pose; translation is metres. |
| target_extents | Tensor["3", float32]: target object-frame OBB side lengths [x,y,z] in metres. |
| candidate_pose_relative_root | PoseTW["S N 12"]: root-rig-from-candidate-camera poses in stored order. The root uses the corrected sampling basis, not the native logged rig basis. N is per-state width, never a planning-tree branch axis. |
| candidate_mask | Tensor["S N", bool]: materialization support; false means stored-row padding. |
| action_mask | Tensor["S N", bool]: actor-valid candidate support, a subset of candidate_mask. |
| history_pose_relative_root | PoseTW["S S 12"]: factual selected-pose prefix. At query state s, history index j stores selected pose j only when j<s. |
| history_mask | Tensor["S S", bool]: factual-pose-prefix support, true exactly for realized j<s pairs. |
| horizon_remaining | Tensor["S", int64]: acquisition budget remaining, including the current factual action. |
| step_mask | Tensor["S", bool]: realized candidate-bearing states; this complete chain has all entries true. |
| static_context | Optional compositional root EVL context; absent only for explicit legacy diagnostic reads. |
| selected_observation_prefix | Optional strictly causal selected CF-GT depth prefix; required by rich-training admission. |
1.2.2 QhAudit
data_handling.qh_data.views.QhAudit(
rollout_store_dir,
actor_store_version,
source_manifest_hash,
selected_depth_renderer,
state_step_row_ids=(),
candidate_row_ids=(),
rollout_manifest_hash='',
)CPU-only chain provenance retained when explicit diagnostics are requested.
1.2.2.1 Attributes
| Name | Description |
|---|---|
| rollout_store_dir | Absolute validated rollout-store directory for reopening presentation-only diagnostics. |
| actor_store_version | Immutable VIN actor-store version bound to the source row. |
| source_manifest_hash | VIN source-manifest digest bound to the chain’s immutable source identity. |
| selected_depth_renderer | Selected-depth renderer recorded by the store, or None when disabled. |
| state_step_row_ids | Persisted step IDs in realized state order; empty means no exact row mapping. |
| candidate_row_ids | Persisted candidate IDs by state in actor row order, without batch padding. |
| rollout_manifest_hash | Validated rollout-manifest digest qualifying local row IDs; empty means unavailable. |
1.2.3 QhChain
data_handling.qh_data.views.QhChain(actor, supervision, key, audit=None)One complete, non-empty rollout chain before batch-axis padding.
actor.step_mask is true for all S stored states. Candidate widths may already be row-padded, but candidate_mask preserves which entries were materially present in each stored state.
1.2.3.1 Attributes
| Name | Description |
|---|---|
| actor | Actor-visible state, candidates, causal history, and remaining budget for all S states. |
| supervision | Oracle support and factual actions aligned exactly with the actor’s S state rows. |
| key | CPU-only source identity retained for audit and debugging, never scorer input. |
| audit | Optional CPU-only diagnostic provenance; batch tensor transfer never touches this payload. |
| num_steps | Return the number of true entries in the chain’s step_mask. |
1.2.4 QhChainKey
data_handling.qh_data.views.QhChainKey(
store_index,
rollout_row_id,
source_sample_index,
scene_id,
target_row_id,
configured_horizon=0,
candidate_width_min=0,
candidate_width_max=0,
candidate_config_hash='',
rollout_config_hash='',
selection_policy='',
source_manifest_hash='',
)CPU-only identity and generation support for one joined rollout chain.
These fields remain outside QhActorTensors: they may stratify diagnostics and bind receipts, but must never become learned scorer inputs. Candidate widths describe realized finite tables rather than nodes in a planning tree.
1.2.4.1 Attributes
| Name | Description |
|---|---|
| store_index | Zero-based ordinal of the rollout store within the configured reader sequence. |
| rollout_row_id | Persistent rollout-chain row identifier inside the selected source store. |
| source_sample_index | Exact immutable VIN actor-store row joined through rollout source identity. |
| scene_id | ASE scene identifier verified equal across rollout and actor-store records. |
| target_row_id | Persistent target-entity row identifier for this chain within the rollout record. |
| configured_horizon | Acquisition budget configured for this factual rollout 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 persisted candidate-generator configuration digest. |
| rollout_config_hash | Exact persisted rollout-recipe configuration digest. |
| selection_policy | Factual behavior-policy identifier used to collect the chain. |
| source_manifest_hash | Exact immutable root qualifier; empty only for historical manually constructed keys. |
1.2.5 QhSelectedObservationPrefix
data_handling.qh_data.views.QhSelectedObservationPrefix(
depth_m,
valid_mask,
camera,
camera_pose_relative_root,
prefix_mask,
source_protocol='cf_gt',
)Strictly causal CF-GT depth history for every realized rollout state.
Row s contains only observations acquired by selected actions before state s. Entries outside prefix_mask are padding, not future observations. The source protocol is fixed to "cf_gt" for this first rich carrier.
1.2.5.1 Attributes
| Name | Description |
|---|---|
| depth_m | Tensor["S S H_d W_d", float16]: selected-depth rasters in metres. Axes are query state s then selected observation j; only j<s is supported. |
| valid_mask | Tensor["S S H_d W_d", bool]: valid metric-depth support aligned with depth_m. |
| camera | Linear CameraTW["S S 22"] reconstructed from the exact persisted focal, principal-point, and raster rows; masked slots are padding. |
| camera_pose_relative_root | PoseTW["S S 12"]: root-rig-from-selected-camera poses; entry [s,j] belongs to selected action j. |
| prefix_mask | Tensor["S S", bool]: causal selected-observation support, true exactly for realized j<s pairs. |
| source_protocol | Declared selected-observation protocol; only "cf_gt" is admitted by this carrier. |
1.2.6 QhStaticContext
data_handling.qh_data.views.QhStaticContext(
vin_snippet,
t_world_voxel,
voxel_extent,
occ_pr,
occ_input,
free_input,
counts,
cent_pr,
pts_world,
evl_presence,
)Immutable root evidence shared by every realized state in one chain.
The optional EVL fields are never substituted with numeric zeros. Their corresponding entries in evl_presence distinguish unavailable source evidence from an observed zero-valued voxel. Rich-training admission owns whether every field must be present.
1.2.6.1 Attributes
| Name | Description |
|---|---|
| vin_snippet | VinSnippetView with points_world Tensor["P 3+C_p", float32], lengths Tensor["1", int64], and trajectory PoseTW["F 12"]. |
| t_world_voxel | PoseTW["12"]: world-from-voxel pose for root EVL evidence; translation is metres. |
| voxel_extent | Tensor["6", float32]: metric voxel-frame extent in metres. |
| occ_pr | Tensor["1 D_v H_v W_v", float32]: root EVL occupancy prediction. |
| occ_input | Tensor["1 D_v H_v W_v", float32]: voxelized occupied input evidence. |
| free_input | Tensor["1 D_v H_v W_v", float32]: voxelized free-space input evidence. |
| counts | Tensor["D_v H_v W_v", int64]: valid image-feature projection counts, not measured depth support. |
| cent_pr | Tensor["1 D_v H_v W_v", float32]: root EVL centerness prediction. |
| pts_world | Tensor["V 3", float32]: world voxel centres, where V=D_v*H_v*W_v. |
| evl_presence | Tensor["8", bool]: availability for pose, extent, then six optional EVL fields. |
1.2.7 QhSupervision
data_handling.qh_data.views.QhSupervision(
label_mask,
candidate_reward,
one_step_target_rri,
selected_index,
discount,
terminal,
)Oracle labels and factual selected transitions kept outside the actor.
Candidate rewards provide immediate supervision where label_mask is true, and label support always implies actor validity. The selected action is the factual rollout-policy decision, not a learner choice. Discount and terminal state describe the persisted TD transition; they do not guarantee actor-valid or label-supported successor candidates.
1.2.7.1 Attributes
| Name | Description |
|---|---|
| label_mask | Tensor["S N", bool]: reward-label support, a subset of action_mask. |
| candidate_reward | Tensor["S N", float32]: persisted immediate rewards; values matter only where label_mask is true. |
| one_step_target_rri | Tensor["S N", float32]: supervision-only target RRI, finite only where label_mask is true; never an actor input or root-gain replacement. |
| selected_index | Tensor["S", int64]: factual rollout-policy candidate index. |
| discount | Tensor["S", float32]: stored TD discount, applied only when the learner admits a successor backup. |
| terminal | Tensor["S", bool]: persisted terminal flag. |