1 oracle.pipelines.evaluated_inspection

oracle.pipelines.evaluated_inspection

Presentation-free inspection of in-memory Oracle-evaluated rollouts.

The module projects EvaluatedRollout into frozen CPU evidence for the Live Rollout Lab and tests. It owns joins between replay transitions, compact Oracle labels, candidate-shell provenance, and retained selected-depth evidence. Plotting and Streamlit rendering consume the resulting values; they never repeat these scientific reductions.

Selected root-normalized target rewards preserve the finite-horizon contract

\[ G_0^{(H)}=\sum_{t=0}^{H-1}\gamma^t r_t. \]

Missing labels remain None and terminated tails remain absent. In particular, a measured reward or RRI of zero is valid evidence, not a missing value.

1.1 Classes

Name	Description
CandidateGroupCount	One full-shell candidate allocation or rejection count.
CandidateReconstructionEvidence	One explicitly retained prepared target successor on immutable CPU storage.
CandidateTargetMetricReceipt	Raw target point-mesh measurements already emitted by the scorer.
EvaluatedCandidateRow	One hard-valid candidate joined across shell, policy, and Oracle evidence.
EvaluatedCandidateStep	Candidate evidence for one factual trajectory step.
EvaluatedRolloutInspection	Complete presentation-free inspection projection for one live rollout.
EvaluatedStepEvidence	Selected reward and valid-candidate distribution for one factual step.
EvaluatedTrajectorySummary	One factual retained trajectory and its canonical target-return summary.
SelectedDepthEvidence	Frozen CPU selected-depth evidence for one factual trajectory step.

1.1.1 CandidateGroupCount

oracle.pipelines.evaluated_inspection.CandidateGroupCount(
    group,
    count,
    valid=None,
    invalid=None,
)

One full-shell candidate allocation or rejection count.

1.1.1.1 Attributes

Name	Description
group	Stable position-family or rejection-reason identifier.
count	Number of full-shell candidate rows in the group.
valid	Hard-valid subset for allocation groups.
invalid	Rejected subset for allocation groups.

1.1.2 CandidateReconstructionEvidence

oracle.pipelines.evaluated_inspection.CandidateReconstructionEvidence(
    trajectory_index,
    step_index,
    shell_index,
    valid_index,
    available,
    warning,
    points_world_m,
    source_device,
    source_dtype,
    preparation,
    crop_policy,
    mesh_crop_policy,
    voxel_size_m,
    max_points,
)

One explicitly retained prepared target successor on immutable CPU storage.

1.1.2.1 Attributes

Name	Description
trajectory_index	Zero-based retained trajectory index.
step_index	Zero-based factual replay step index.
shell_index	Full-shell row requested by the diagnostic.
valid_index	Compact hard-valid row id, absent when the requested row was not retained.
available	Whether the requested prepared successor was retained.
warning	Actionable unavailability or shape failure, when present.
points_world_m	Read-only ndarray["P_a 3", float32] prepared target points in world metres.
source_device	Tensor device before the explicit CPU inspection copy.
source_dtype	Tensor dtype before the explicit CPU inspection copy.
preparation	Complete ordered fusion, crop, and cap provenance for this cloud.
crop_policy	Versioned point-membership crop policy used to prepare the successor.
mesh_crop_policy	Reference-mesh face crop policy used by the target metric.
voxel_size_m	Evaluation fusion voxel size in metres.
max_points	Configured target-evaluation point cap.

1.1.3 CandidateTargetMetricReceipt

oracle.pipelines.evaluated_inspection.CandidateTargetMetricReceipt(
    root_error_m2,
    before_error_m2,
    after_error_m2,
    before_accuracy_m2,
    before_completeness_m2,
    after_accuracy_m2,
    after_completeness_m2,
    current_support,
    candidate_support,
)

Raw target point-mesh measurements already emitted by the scorer.

1.1.3.1 Attributes

Name	Description
root_error_m2	Root target point-mesh error used by the root-normalized reward.
before_error_m2	Target point-mesh error for the current prepared reconstruction.
after_error_m2	Target point-mesh error for this prepared candidate successor.
before_accuracy_m2	Current prepared reconstruction-to-mesh error component.
before_completeness_m2	Current mesh-to-reconstruction error component.
after_accuracy_m2	Candidate-successor reconstruction-to-mesh error component.
after_completeness_m2	Candidate-successor mesh-to-reconstruction error component.
current_support	Number of points in the current target reconstruction, if retained.
candidate_support	Number of target-local points contributed by the candidate observation.

1.1.4 EvaluatedCandidateRow

oracle.pipelines.evaluated_inspection.EvaluatedCandidateRow(
    trajectory_index,
    step_index,
    valid_index,
    shell_index,
    selected,
    position,
    strategy,
    mixture,
    component,
    selection_score,
    selection_probability,
    selection_logit,
    target_root_gain,
    target_rri,
    scene_root_gain,
    scene_rri,
    target_metric_receipt,
    sampler_probability,
)

One hard-valid candidate joined across shell, policy, and Oracle evidence.

1.1.4.1 Attributes

Name	Description
trajectory_index	Zero-based retained trajectory index.
step_index	Zero-based factual replay step index.
valid_index	Zero-based row on the compact hard-valid candidate axis.
shell_index	Corresponding row on the full sampled shell axis.
selected	Whether replay selected this candidate row.
position	Stable decoded position-family name.
strategy	Stable decoded camera-orientation strategy name.
mixture	Stable mixture-component identifier.
component	Configured human-readable component name, when retained.
selection_score	Finite policy score aligned to this hard-valid candidate.
selection_probability	Finite policy probability aligned to this hard-valid candidate.
selection_logit	Finite pre-softmax logit aligned to this hard-valid candidate.
target_root_gain	Privileged target root-normalized gain for this candidate.
target_rri	Privileged state-relative target RRI for this candidate.
scene_root_gain	Privileged scene root-normalized gain for this candidate.
scene_rri	Privileged state-relative scene RRI for this candidate.
target_metric_receipt	Raw target metric inputs and components, without recomputation.
sampler_probability	Candidate generator proposal probability, when retained.

1.1.5 EvaluatedCandidateStep

oracle.pipelines.evaluated_inspection.EvaluatedCandidateStep(
    trajectory_index,
    step_index,
    full_shell_count,
    valid_count,
    candidates,
    position_counts,
    invalid_reason_counts,
)

Candidate evidence for one factual trajectory step.

1.1.5.1 Attributes

Name	Description
trajectory_index	Zero-based retained trajectory index.
step_index	Zero-based factual replay step index.
full_shell_count	Number of generated candidate rows before hard masking.
valid_count	Number of hard-valid action rows.
candidates	Rows joined on the compact hard-valid candidate axis.
position_counts	Full-shell allocation and validity counts by position family.
invalid_reason_counts	Rejected full-shell rows by stable primary reason.

1.1.6 EvaluatedRolloutInspection

oracle.pipelines.evaluated_inspection.EvaluatedRolloutInspection(
    configured_horizon,
    trajectories,
    steps,
    candidate_steps,
    selected_depths,
)

Complete presentation-free inspection projection for one live rollout.

1.1.6.1 Attributes

Name	Description
configured_horizon	Maximum configured replay depth, retained for termination context.
trajectories	One summary per factual retained trajectory.
steps	Selected reward and candidate-range evidence in trajectory/step order.
candidate_steps	Valid-candidate joins and full-shell diagnostic counts per factual step.
selected_depths	Selected-depth availability and immutable CPU images per factual step.

1.1.6.2 Methods

Name	Description
reward_metric_family	Choose the highest-priority metric family retained by this inspection.
candidate_step	Return candidate evidence for one factual step.
selected_depth	Return selected-depth evidence for one factual step.

1.1.6.2.1 reward_metric_family

oracle.pipelines.evaluated_inspection.EvaluatedRolloutInspection.reward_metric_family(
)

Choose the highest-priority metric family retained by this inspection.

1.1.6.2.2 candidate_step

oracle.pipelines.evaluated_inspection.EvaluatedRolloutInspection.candidate_step(
    trajectory_index,
    step_index,
)

Return candidate evidence for one factual step.

1.1.6.2.3 selected_depth

oracle.pipelines.evaluated_inspection.EvaluatedRolloutInspection.selected_depth(
    trajectory_index,
    step_index,
)

Return selected-depth evidence for one factual step.

1.1.7 EvaluatedStepEvidence

oracle.pipelines.evaluated_inspection.EvaluatedStepEvidence(
    trajectory_index,
    step_index,
    acquisition_number,
    selection_score,
    selection_score_label,
    selected_target_rri,
    selected_target_root_gain,
    selected_scene_rri,
    selected_scene_root_gain,
    cumulative_target_root_gain,
    cumulative_target_rri,
    cumulative_scene_rri,
    cumulative_scene_root_gain,
    candidate_target_rri_q025,
    candidate_target_rri_q975,
    candidate_target_root_gain_q025,
    candidate_target_root_gain_q975,
    candidate_scene_rri_q025,
    candidate_scene_rri_q975,
    candidate_scene_root_gain_q025,
    candidate_scene_root_gain_q975,
    candidate_selection_score_q025,
    candidate_selection_score_q975,
    valid_candidate_count,
    top_target_rri,
    top_target_root_gain,
)

Selected reward and valid-candidate distribution for one factual step.

1.1.7.1 Attributes

Name	Description
trajectory_index	Zero-based retained trajectory index.
step_index	Zero-based factual replay step index.
acquisition_number	One-based selected-view number used by human-facing plots.
selection_score	Finite policy score used to select the action, including geometry-only modes.
selection_score_label	Stable semantic name of the policy score channel.
selected_target_rri	Finite selected marginal target RRI, if emitted by the scorer.
selected_target_root_gain	Finite selected root-normalized target reward, if emitted by the scorer.
selected_scene_rri	Finite selected marginal scene RRI for the scene diagnostic mode.
selected_scene_root_gain	Finite selected scene root-normalized gain, when emitted.
cumulative_target_root_gain	Observed prefix return at this step, absent when this step has no reward.
cumulative_target_rri	Observed prefix sum of selected marginal target RRI diagnostics.
cumulative_scene_rri	Observed prefix sum of selected marginal scene RRI values.
cumulative_scene_root_gain	Observed prefix sum of selected scene root-normalized gains.
candidate_target_rri_q025	Empirical 2.5th percentile across finite hard-valid candidate RRI values.
candidate_target_rri_q975	Empirical 97.5th percentile across finite hard-valid candidate RRI values.
candidate_target_root_gain_q025	Empirical 2.5th percentile across finite hard-valid candidate rewards.
candidate_target_root_gain_q975	Empirical 97.5th percentile across finite hard-valid candidate rewards.
candidate_scene_rri_q025	Empirical 2.5th percentile across finite hard-valid scene RRI values.
candidate_scene_rri_q975	Empirical 97.5th percentile across finite hard-valid scene RRI values.
candidate_scene_root_gain_q025	Empirical 2.5th percentile across finite hard-valid scene rewards.
candidate_scene_root_gain_q975	Empirical 97.5th percentile across finite hard-valid scene rewards.
candidate_selection_score_q025	Empirical 2.5th percentile across finite hard-valid policy scores.
candidate_selection_score_q975	Empirical 97.5th percentile across finite hard-valid policy scores.
valid_candidate_count	Number of hard-valid actions in the full sampled shell.
top_target_rri	Up to five largest finite valid-candidate target RRI values.
top_target_root_gain	Up to five largest finite valid-candidate target rewards.

1.1.7.2 Methods

Name	Description
selected_metric	Return the selected value for one normalized metric family.
cumulative_metric	Return the observed prefix value for one metric family.
candidate_metric_range	Return the empirical q025/q975 range for one metric family.

1.1.7.2.1 selected_metric

oracle.pipelines.evaluated_inspection.EvaluatedStepEvidence.selected_metric(
    metric_family,
)

Return the selected value for one normalized metric family.

1.1.7.2.2 cumulative_metric

oracle.pipelines.evaluated_inspection.EvaluatedStepEvidence.cumulative_metric(
    metric_family,
)

Return the observed prefix value for one metric family.

Policy selection scores are per-step actor evidence and have no cumulative metric in the reward figures.

1.1.7.2.3 candidate_metric_range

oracle.pipelines.evaluated_inspection.EvaluatedStepEvidence.candidate_metric_range(
    metric_family,
)

Return the empirical q025/q975 range for one metric family.

1.1.8 EvaluatedTrajectorySummary

oracle.pipelines.evaluated_inspection.EvaluatedTrajectorySummary(
    trajectory_index,
    factual_steps,
    cumulative_score,
    cumulative_rri,
    cumulative_target_root_gain,
    endpoint_gain,
    endpoint_log_gain,
    terminated_early,
    final_position_world_m,
)

One factual retained trajectory and its canonical target-return summary.

1.1.8.1 Attributes

Name	Description
trajectory_index	Zero-based retained trajectory index.
factual_steps	Number of observed selected transitions; no horizon padding is included.
cumulative_score	Sum of the policy selection-score channel along the retained trajectory.
cumulative_rri	Sum of finite selected target RRI values, including a valid 0.0 sum.
cumulative_target_root_gain	Canonical finite-horizon return over selected root-normalized rewards.
endpoint_gain	Root-normalized target reconstruction improvement between root and endpoint.
endpoint_log_gain	Logarithmic target reconstruction-error reduction between root and endpoint.
terminated_early	Whether replay ended before the configured horizon.
final_position_world_m	Final selected camera centre in world-frame metres.

1.1.9 SelectedDepthEvidence

oracle.pipelines.evaluated_inspection.SelectedDepthEvidence(
    trajectory_index,
    step_index,
    acquisition_number,
    available,
    warning,
    depth_m,
    valid_mask,
    focal_px,
    principal_point_px,
    image_size_hw,
    selected_pose_world,
    valid_fraction,
    finite_fraction,
    minimum_depth_m,
    mean_depth_m,
    maximum_depth_m,
)

Frozen CPU selected-depth evidence for one factual trajectory step.

Arrays are copied to CPU and marked read-only. Depth values are metric ray distances in metres; valid_mask identifies renderer hits independently from numerical finiteness.

1.1.9.1 Attributes

Name	Description
trajectory_index	Zero-based retained trajectory index.
step_index	Zero-based factual replay step index.
acquisition_number	One-based selected-view number used by human-facing plots.
available	Whether a valid depth/mask pair was retained.
warning	Actionable unavailability or shape failure, when present.
depth_m	Read-only ndarray["H_d W_d", float32] ray distances in metres.
valid_mask	Read-only ndarray["H_d W_d", bool] renderer-hit mask.
focal_px	Retained focal lengths (fx, fy) in pixels.
principal_point_px	Retained principal point (cx, cy) in pixels.
image_size_hw	Retained depth image size (height, width).
selected_pose_world	Flattened 12-value selected world-from-camera pose.
valid_fraction	Fraction of pixels marked valid by the renderer.
finite_fraction	Fraction of pixels that are both valid and finite.
minimum_depth_m	Minimum finite valid depth in metres.
mean_depth_m	Mean finite valid depth in metres.
maximum_depth_m	Maximum finite valid depth in metres.

1.2 Functions

Name	Description
inspect_candidate_reconstruction	Materialize one explicitly retained prepared candidate successor.
inspect_evaluated_rollout	Project one evaluated replay result into immutable CPU inspection evidence.
inspect_selected_depth	Materialize selected-depth evidence only for one explicitly chosen step.

1.2.1 inspect_candidate_reconstruction

oracle.pipelines.evaluated_inspection.inspect_candidate_reconstruction(
    evaluated,
    trajectory_index,
    step_index,
    shell_index,
)

Materialize one explicitly retained prepared candidate successor.

The returned cloud is the target-evaluation after-state that was passed to the canonical point-mesh metric, not the candidate observation by itself. No cloud is copied unless the requested full-shell identity was retained.

1.2.2 inspect_evaluated_rollout

oracle.pipelines.evaluated_inspection.inspect_evaluated_rollout(
    evaluated,
    *,
    include_selected_depth=False,
)

Project one evaluated replay result into immutable CPU inspection evidence.

The join validates every retained Oracle sidecar against its replay step and keeps factual early termination. It performs no source acquisition, rollout execution, rendering, or plotting. Selected-depth images are omitted by default so reward or admission views do not copy large tensors; use inspect_selected_depth for one explicitly chosen step.

1.2.3 inspect_selected_depth

oracle.pipelines.evaluated_inspection.inspect_selected_depth(
    evaluated,
    trajectory_index,
    step_index,
)

Materialize selected-depth evidence only for one explicitly chosen step.