1 data_handling.qh_data

data_handling.qh_data

Actor-safe chain data for finite-candidate Q_H training.

The package joins private rollout-source identity to immutable VIN actor evidence, exposes factual chain views, and pads heterogeneous chains for fitted value learning. Storage interpretation remains owned by aria_nbv.rollouts.storage.qh_reader; scorer- and objective-specific admission remains owned by the Lightning training module.

This package provides only the six public data-seam symbols listed in __all__; supervision and source-key DTOs remain leaf-internal contracts.

The package interface intentionally omits supervision and identity detail that only sibling implementations need. Import QhSupervision and QhChainKey from aria_nbv.data_handling.qh_data.views when implementing another Q_H data adapter.

1.1 Classes

Name	Description
QhActorTensors	Actor-visible tensors for one complete, non-batched chain.
QhBatch	Padded Q_H chain batch with centralized tensor transfer.
QhChain	One complete, non-empty rollout chain before batch-axis padding.
QhDataset	Join validated rollout chains to one immutable actor snippet per chain.
QhDatasetConfig	Configure ordered rollout stores and their exact immutable VIN actor source.

1.1.1 QhActorTensors

data_handling.qh_data.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.1.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.1.2 QhBatch

data_handling.qh_data.QhBatch(actor, supervision, keys, audits)

Padded Q_H chain batch with centralized tensor transfer.

B denotes chains, S padded rollout states, and N padded candidates. Candidate, action, label, history, and step masks retain their separate support meanings after collation. Tensor transfer and pinning recurse through actor and supervision fields while preserving CPU-only chain keys by identity.

1.1.2.1 Attributes

Name	Description
actor	Actor-visible tensors with leading B and common state, candidate, history, point, and pose extents.
supervision	Oracle label support and factual transition tensors padded exactly like actor state/candidate axes.
keys	Length-B CPU-only audit keys in input order; never transferred or exposed to the scorer.
audits	Length-B optional diagnostic records aligned with keys and preserved by identity during transfer.
num_steps	Return Tensor["B", int64] realized-state counts from step_mask.
selected_train_mask	Return Tensor["B S", bool] selected rows with finite immediate-target support.
successor_backup_mask	Return Tensor["B S N", bool] label-supported actions at each next state.
successor_action_mask	Return Tensor["B S N", bool] actor-valid actions at each next state.
successor_record_present	Return Tensor["B S", bool] indicating a recorded next actor state.
actor_successor_present	Return Tensor["B S", bool] indicating any actor-valid next-state action.
successor_present	Return Tensor["B S", bool] indicating any label-supported next-state action.
bootstrap_mask	Return Tensor["B S", bool] rows eligible for a supported TD backup.

1.1.2.2 Methods

Name	Description
pin_memory	Return a batch with every nested tensor pinned and the same CPU key tuple.
to	Move every nested tensor to device while leaving audit keys on the CPU.

1.1.2.2.1 pin_memory

data_handling.qh_data.QhBatch.pin_memory()

Return a batch with every nested tensor pinned and the same CPU key tuple.

1.1.2.2.2 to

data_handling.qh_data.QhBatch.to(device, *, non_blocking=True)

Move every nested tensor to device while leaving audit keys on the CPU.

1.1.2.2.2.1 Parameters

Name	Type	Description	Default
device	str | torch.device	Destination accepted by torch.Tensor.to.	required
non_blocking	bool	Request asynchronous transfer where the source and destination support it. MPS transfers are always blocking: temporary CPU batches must remain alive until their copies complete, matching Lightning’s MPS transfer policy.	True

1.1.2.2.2.2 Returns

Name	Type	Description
	QhBatch	New batch with aligned actor and supervision tensors on device.

1.1.3 QhChain

data_handling.qh_data.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.1.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.1.4 QhDataset

data_handling.qh_data.QhDataset(
    rollout_reader,
    actor_reader=None,
    actor_readers=None,
    split=None,
    root_evl_profile='none',
    selected_observation_protocol='none',
    experiment_profile=None,
    include_audit=False,
)

Join validated rollout chains to one immutable actor snippet per chain.

Construction preflights every private source reference against the actor manifest and complete immutable actor index. split has already selected campaign chains at the rollout-reader boundary. __getitem__ then reads one stored chain and its chain-constant root snippet exactly once. The result separates actor state from label support and other oracle transition facts; it does not decide fitted-Q admission.

1.1.4.1 Attributes

Name	Description
scenes	Return immutable ASE scene identifiers represented by the validated corpus.
max_horizon	Return the largest configured horizon among the validated stores.
contract	Return semantic compatibility and the exact replay-support mixture.
actor_state_contract	Return metadata-only scorer-input compatibility facts for this stage.
requires_empirical_pooling_qualification	Flag a readable multi-root corpus whose backend pooling lacks empirical approval.
provenance	Return rollout/actor store identity for audit displays, never scorer input.
target_descriptor_identity	Return receipt-only target descriptor lineage for admitted rollout rows.
admission_coverage	Report source coverage without inventing a target-task denominator.

1.1.4.2 Methods

Name	Description
chain_identity	Return metadata-only chain identity for bounded diagnostics.

1.1.4.2.1 chain_identity

data_handling.qh_data.QhDataset.chain_identity(index)

Return metadata-only chain identity for bounded diagnostics.

This pass-through deliberately bypasses actor-store reads and tensor materialization. It is suitable for deterministic population census and selection, but it is not part of the scorer’s actor-visible state.

1.1.5 QhDatasetConfig

data_handling.qh_data.QhDatasetConfig()

Configure ordered rollout stores and their exact immutable VIN actor source.

1.1.5.1 Attributes

Name	Description
rollout_store_dirs	Non-empty rollout-store paths; tuple order defines QhChainKey.store_index.
actor	Immutable VIN store whose actor-visible root rows must match every rollout source reference.
actors	Explicit V2 root population; mutually exclusive with explicitly supplied actor.
split	Learning/campaign split admitted by the rollout reader; None reads all chains.
root_evl_profile	Root scene-evidence profile; evl_v1 requires the canonical eight-block EVL carrier.
selected_observation_protocol	Causal selected-observation source; cf_gt explicitly enables privileged rendered depth.
experiment_profile	Closed CF0/CF+ role; None retains legacy diagnostic-only setup.
include_audit	Attach CPU-only chain provenance for debugging; never adds payloads to scorer tensors or device transfer.
target_type	Return QhDataset for config-as-factory construction.

1.1.5.2 Methods

Name	Description
setup_target	Construct both readers and preflight rollout-to-actor source identity.

1.1.5.2.1 setup_target

data_handling.qh_data.QhDatasetConfig.setup_target()

Construct both readers and preflight rollout-to-actor source identity.

1.1.5.2.1.1 Returns

Name	Type	Description
	QhDataset	class:QhDataset ready for indexed chain reads after validating
	QhDataset	the configured actor manifest, split, and source rows.

1.2 Functions

Name	Description
collate_qh_chains	Pad heterogeneous chain axes and validate factual mask implications.

1.2.1 collate_qh_chains

data_handling.qh_data.collate_qh_chains(
    chains,
    *,
    objective_profile='legacy_selected_rows_v1',
)

Pad heterogeneous chain axes and validate factual mask implications.

1.2.1.1 Parameters

Name	Type	Description	Default
chains	list[QhChain]	Non-empty complete chains in desired batch order. Each chain may have different state, candidate, VIN-point, and trajectory extents while preserving one fixed-task remaining-budget sequence.	required

1.2.1.2 Returns

Name	Type	Description
	QhBatch	class:QhBatch whose axes cover every input and whose keys retain
	QhBatch	input order. Boolean support padding is false; rewards, discounts, and
	QhBatch	poses use zero; selected indices use -1; terminal padding is true;
	QhBatch	VIN point padding is NaN. Padding never creates actor-valid or
	QhBatch	label-supported entries, and validation enforces
	QhBatch	label_mask <= action_mask <= candidate_mask. The dense-valid
	QhBatch	objective additionally requires finite root-gain rewards exactly on
	QhBatch	realized actor-valid support. Diagnostic RRI may remain unavailable;
	QhBatch	both arrays are canonicalized to NaN outside realized support.