1 vin.models.target_spatial_query

vin.models.target_spatial_query

Explicit candidate-local QH composition with reusable configured stages.

Physical feasibility reads only root/current pose and global evidence. Value queries additionally read local EVL evidence and target geometry; four shared state tokens carry target, causal history, budget and requested horizon. Candidate rows never exchange features. Existing scorers remain independent.

1.1 Classes

Name	Description
TargetSpatialQueryScorer	Compose candidate-local physical and target-conditioned value predictions.
TargetSpatialQueryScorerConfig	Select concrete feature stages without implicit child setting propagation.

1.1.1 TargetSpatialQueryScorer

vin.models.target_spatial_query.TargetSpatialQueryScorer(config)

Compose candidate-local physical and target-conditioned value predictions.

1.1.1.1 Theory

For candidate i at state s, let e denote the shared pose encoder and R_g the target-independent global evidence readout. The physical token is \(p_i=P([e(T_{r\leftarrow i}),e(T_{c_s\leftarrow i}),R_g])\); an affine head maps p_i to a feasibility logit. Readout values are paired with availability bits so missing evidence is distinct from measured zero. Neither target geometry nor requested horizon enters this physical branch.

The value query adds target-relative pose, selectable evidence R_i and optional target/current geometry g_i: \(q_i=Q([p_i,e(T_{i\leftarrow t}),R_i,g_i])\). Four shared state tokens Z encode target, strictly causal history, factual budget and requested horizon. Fusion computes \(c_i=F(q_i,Z)\) and the configured decoder returns \(\widehat Q_h(i)=D([q_i,c_i,q_i\odot c_i])\). P and Q are learned projections, brackets concatenate features, and omitted optional geometry contributes no columns. The stage contracts live in aria_nbv.vin.modules.qh_candidate_readout, aria_nbv.vin.encoders.target_current_geometry, aria_nbv.vin.modules.qh_history_encoders, aria_nbv.vin.modules.qh_state_fusion and aria_nbv.vin.modules.qh_value_decoders.

1.1.1.2 Notes

Candidate queries never interact with one another: shared state tokens preserve candidate permutation equivariance in deterministic evaluation. History carries selected poses, not reconstructed observations. CF+ profiles validate a privileged prefix but this composition does not read its numeric observation payload. Predicted feasibility is not hard action validity; only caller-owned masks determine supervision or deployment. A learned conditional-Q descriptor does not establish improved empirical reconstruction or calibrated predictions without evaluation.

1.1.1.3 Methods

Name	Description
validate_artifact_state	Validate decoder support independently of feature selection.
forward	Predict raw candidate values through the configured shared interfaces.

1.1.1.3.1 validate_artifact_state

vin.models.target_spatial_query.TargetSpatialQueryScorer.validate_artifact_state(
    require_publishable=False,
)

Validate decoder support independently of feature selection.

1.1.1.3.2 forward

vin.models.target_spatial_query.TargetSpatialQueryScorer.forward(
    actor,
    *,
    requested_horizon=None,
)

Predict raw candidate values through the configured shared interfaces.

1.1.1.3.2.1 Parameters

Name	Type	Description	Default
actor	QhActorTensors	Factual actor with B batch, S state and N candidate axes. Root-relative poses and evidence retain the package frame conventions. Action validity is checked for consistency but never used to mask raw predictions.	required
requested_horizon	Tensor | None	Optional Tensor["B S", int64] scalar query on the actor device. Legacy bounds queries by factual budget and defaults to it; continuing requires an explicit query in [1,max_horizon] and omits recorded budget features. Padding is zero in both profiles.	None

1.1.1.3.2.2 Returns

Name	Type	Description
	QhScoreOutput	QhScoreOutput with float32 Q and feasibility tensors of shape
	QhScoreOutput	B S N and optional candidate-aligned CORAL auxiliary tensors.
	QhScoreOutput	Padded rows are zero; active rows must be finite. Gradients remain
	QhScoreOutput	attached and actor inputs are not mutated.

1.1.1.3.2.3 Raises

Name	Type	Description
	ValueError	If actor admission, source profile, optional frame or decoder contracts fail, or materialized predictions are nonfinite.

1.1.2 TargetSpatialQueryScorerConfig

vin.models.target_spatial_query.TargetSpatialQueryScorerConfig()

Select concrete feature stages without implicit child setting propagation.

1.1.2.1 Attributes

Name	Description
propagation_exclude_fields	Composition settings injected explicitly, never recursively imposed on child configs.
model_kind	Closed model selector; legacy configurations omit this field.
hidden_dim	Candidate/state interface width; does not overwrite child feature widths.
dropout	Dropout injected into fusion/history/decoder runtime stages.
max_horizon	Largest admitted bounded scalar horizon query.
experiment_profile	Actor-source profile; CF+ remains privileged and non-deployable.
representation_semantics	Versioned composition identity bound into inference manifests.
horizon_query_semantics	Budget-bounded legacy query or explicit finite continuing lookahead.
pose_encoder	One shared pose encoder instance for candidates, target and factual history.
scene_evidence	Geometry-only bypasses both evidence readers; allocated feature widths remain fixed.
physical_readout	Target-independent global evidence for the physical feasibility branch.
readout	Selectable global control or target/ray spatial evidence for value queries.
history_encoder	Existing H0/H1 pose-history stage with unchanged input semantics.
target_geometry	Optional gravity-aligned target/current frame features; degeneracy fails explicitly.
directional_history	Optional coverage in the exact geometry-stage frame; actor inputs support uniform weighting.
state_fusion	Candidate-independent interaction with target, history, budget and horizon tokens.
value_decoder	Continuous regression or explicitly selected CORAL objective payload.
target_type	Return the concrete spatial-query model.