1 oracle

oracle

Privileged evidence preparation, scoring, and label-generation pipelines.

1.1 Package guide

aria_nbv.oracle owns privileged evidence preparation, scene- and target-level RRI scoring, GT target-task selection, label payloads, and generation pipeline composition. Its outputs supervise and evaluate actor-side models; privileged geometry is not an ordinary VIN or QH input.

1.2 Public Scorers

from aria_nbv.oracle import (
    SceneRriScorerConfig,
    TargetRriScorerConfig,
)

scene_scorer = SceneRriScorerConfig().setup_target(sample=snippet)
target_scorer = TargetRriScorerConfig().setup_target(sample=snippet)

Both scorers evaluate finite candidate tables against prepared point-mesh evidence. SceneRriScorer evaluates the scene crop; TargetRriScorer evaluates a selected target crop and may retain diagnostic scene RRI from the same candidate renders.

Expected target-evidence failures return stable invalidity reasons suitable for hard masks and diagnostics. They do not become numeric RRI targets.

1.3 Ownership Map

Module	Responsibility
evidence	Privileged root/current point clouds, target crops, and evaluation provenance.
labels	Candidate-aligned labels separated from optional retained evidence.
scene_rri	Scene-level oracle scorer facade.
target_rri	Target-cropped oracle scorer facade and invalidity.
target_selection	GT matching and privileged target-task sampling.
target_sampling	Diagnostic balanced allocation with exact marginal inclusion probabilities.
environment	Decision context and actor-visible state transition boundary.
pipelines	Offline VIN, rollout, shard, campaign, and online-QH composition.

The private _scoring.py engine shares rendering and point-mesh mechanics between the public scorers; consumers should use the scorer facades.

1.4 Actor/Oracle Boundary

Actor-visible target instructions are defined in aria_nbv.targets and may be stored in QhActorTensors. GT meshes, GT OBB matching, dense counterfactual renders, target crops, oracle labels, and headroom diagnostics remain supervision/evaluation assets. The distinction is preserved through stores, QH datasets, bundles, and online inference.

Operational generation commands are documented in the pipeline guide. Detailed fields and failure contracts live in public docstrings and the generated API reference.

1.5 Support diagnostics

The training-only support challenger allocates over the current V1 admitted observed-target population. Admission still retains every uniquely matched observed descriptor, including explicit rejection outcomes; the diagnostic allocation is a separate step. Legacy V0 uniform sampling remains unchanged. The explicit entry point is OracleTargetTaskSampler.sample_observed_support_diagnostic; its source docstring defines the required manifest, decision, and support inputs. targets.observation_support owns acquired-prefix summaries, target_sampling owns balanced quotas, and rollouts.inspection.support owns the independently declared root population and proposal/continuation comparisons.

Missing observations form a distinct stratum from measured zero. Returned probabilities describe marginal inclusion in the allocated subset, not the first draw or successful persistence after acquisition failures. Source, training splits, root pose, decision cutoff, and target identities must match independent inputs. These checks validate declarations; real acquisition provenance still requires a source adapter.

Production rollout configuration and execution reject this challenger until causal source extraction and complete allocation/failure persistence are implemented. Diagnostic fixtures establish arithmetic and boundary behavior; they do not establish better learning or complete issue #277.

1.6 Verification

cd aria_nbv
uv run ruff check aria_nbv/oracle
uv run pytest tests/oracle

1.7 Optional candidate rendering crop

TargetRriScorerConfig.candidate_render_crop accepts CandidateRenderCropConfig from oracle.target_rri. Its default None retains full-scene rendering and is omitted from serialized configuration. Enabled cropping requires target-only labels (include_scene_rri=False), hard rasterization and float32. The scorer rebuilds a conservative camera-to-target viewing region for every candidate batch; scoring margins, pixel sampling and reward semantics are unchanged.

The evaluated rollout pipeline acquires the selected candidate against the original full scene at scoring resolution before constructing successor history. A branch-specific cache retains this depth and unpadded world cloud; final actions are acquired during materialization even when no successor exists. Cropped candidate clouds are marked viewing_crop and the replay adapter rejects them without a full-scene selected-observation provider. The separate retained high-resolution selected depth remains full-scene on its existing store route.

This is an optional implementation, not a claim of universal equivalence or speedup. Matched multi-step validation must establish selection, causal-history and endpoint agreement plus complete worker runtime before promotion.

1.8 Classes

Name	Description
SceneRriScorer	Prepare scene evidence and score valid candidate views with Oracle RRI.
SceneRriScorerConfig	Configure scene-level Oracle RRI scoring for finite candidates.
TargetRriScorer	Evaluate valid candidates with target-cropped oracle RRI.
TargetRriScorerConfig	Config-as-factory wrapper for target-cropped oracle-RRI rollout scoring.

1.8.1 SceneRriScorer

oracle.SceneRriScorer(config, *, sample)

Prepare scene evidence and score valid candidate views with Oracle RRI.

1.8.2 SceneRriScorerConfig

oracle.SceneRriScorerConfig()

Configure scene-level Oracle RRI scoring for finite candidates.

1.8.3 TargetRriScorer

oracle.TargetRriScorer(config, *, sample, target_sample, target_task)

Evaluate valid candidates with target-cropped oracle RRI.

The scorer renders candidate depth, backprojects world-frame point clouds, crops current and candidate points to the matched target OBB, crops the mesh with the configured policy, and returns target-RRI labels plus audit metrics. Invalid target crops abort the target row rather than producing low labels. If any candidate has no prepared successor support, the scorer rejects the aligned table as measurement-invalid instead of filtering candidate rows.

1.8.3.1 Attributes

Name	Description
invalidity	Return evidence invalidity known before candidate scoring.

1.8.3.2 Methods

Name	Description
measure_endpoint_pair	Measure root and final states once without rendering new candidates.
score_candidate_depths	Score a complete hard-valid table from one already captured raster.
acquire_selected_observation	Acquire full-scene selected depth and raw world points at scoring resolution.

1.8.3.2.1 measure_endpoint_pair

oracle.TargetRriScorer.measure_endpoint_pair(root_state, final_state)

Measure root and final states once without rendering new candidates.

Both endpoints pass independently through the same canonical fusion, target crop, and metric preparation used for candidate labels. This is deliberately distinct from reducing stored one-step gains. Every primary, repeated, and no-op scalar must pass numerical admission; unmeasurable evidence returns a typed invalidity instead of a label.

1.8.3.2.2 score_candidate_depths

oracle.TargetRriScorer.score_candidate_depths(
    candidates,
    state,
    depths,
    *,
    backprojection_stride,
)

Score a complete hard-valid table from one already captured raster.

This measurement-only seam isolates point sampling from rasterization: callers may pass the same :class:CandidateDepths object with several positive strides. Candidate shell indices, physical world-camera poses, reference pose, and raster camera dimensions are validated before any measurement. Rendering cost is deliberately absent; a panel runner must retain it once as shared acquisition cost.

1.8.3.2.2.1 Parameters

Name	Type	Description	Default
candidates	CandidateSamplingResult	Candidate table that originally produced depths.	required
state	OracleRriState	Fixed factual state and prepared root evidence.	required
depths	CandidateDepths	Complete rendered hard-valid candidate table.	required
backprojection_stride	int	Positive pixel sampling stride. Booleans are rejected rather than coerced to integers.	required

1.8.3.2.2.2 Returns

Name	Type	Description
	OracleCandidateEvaluation | TargetRriInvalidity	Canonical candidate evaluation or the scorer’s typed invalidity.

1.8.3.2.3 acquire_selected_observation

oracle.TargetRriScorer.acquire_selected_observation(candidates, compact_index)

Acquire full-scene selected depth and raw world points at scoring resolution.

Original mesh, camera calibration and pixel stride define causal history; neither cropped background nor later high-resolution retention substitutes for these observations. Compact-row and shell identity are checked.

1.8.4 TargetRriScorerConfig

oracle.TargetRriScorerConfig()

Config-as-factory wrapper for target-cropped oracle-RRI rollout scoring.

1.8.4.1 Attributes

Name	Description
target_type	Return the target-aware Oracle scorer constructed by this config.
depth	Depth renderer used once per candidate table before target/scene scoring.
oracle	Point-mesh oracle metric configuration shared by target and scene RRI.
candidate_render_crop	Opt-in crop; None preserves full rendering and historical serialization.
backprojection_stride	Pixel stride for backprojecting rendered candidate depths.
target_crop_margin_m	Optional symmetric margin applied in GT-OBB local coordinates.
min_current_target_points	Minimum current observed/support points inside the target crop.
include_scene_rri	Whether to compute diagnostic scene RRI from the same point-cloud batch.
eval_point_cloud_source	Oracle current/root point-cloud source used for target and scene labels.
eval_camera_label	Camera stream used for ASE-depth root evaluation points.
eval_depth_far_m	Maximum ASE root depth to retain; defaults to the renderer zfar.
eval_fusion_voxel_size_m	Voxel size used to canonical-fuse root and selected-history eval points.
eval_fusion_max_points	Maximum retained current-eval points after canonical fusion.
target_eval_max_points	Maximum retained oracle/eval points after target-local crop fusion.
reward_mode	Candidate score used for rollout selection.
target_crop_policy	Versioned reference-mesh crop stored as lineage; exact v2 requires zero margin.
scene_crop_policy	Diagnostic scene-RRI crop policy matching the scene-level scorer.
verbosity	Console verbosity.
is_debug	Enable debug logging in scorer dependencies.
log_timing	Emit per-call timing diagnostics for rollout evidence generation.
audit_candidate_reconstruction_shell_indices	Up to eight full-shell rows whose prepared target successors are retained.