1 oracle.labels

oracle.labels

Oracle candidate labels and scorer results.

Oracle scorers produce compact valid-candidate labels. Replay receives only a separate CandidateScores projection assembled at a pipeline boundary.

1.1 Attributes

Name	Description
MAX_AUDITED_CANDIDATE_RECONSTRUCTIONS	Hard upper bound on prepared successor rows retained by one evaluation.

1.2 Classes

Name	Description
OracleCandidateEvaluation	One scorer result split into compact labels and retained evidence.
OracleCandidateLabels	Compact Oracle labels aligned with stable valid candidate rows.
RetainedOracleEvidence	Heavy Oracle evidence retained temporarily or for explicit audits.
SelectedCandidateObservation	Full-scene acquisition for one selected compact candidate.
TargetReconstructionPreparation	Ordered preparation contract for retained target successor states.

1.2.1 OracleCandidateEvaluation

oracle.labels.OracleCandidateEvaluation(labels, evidence)

One scorer result split into compact labels and retained evidence.

Both payloads align to the same hard-valid axis V; validation rejects any shell-index or leading-axis mismatch before replay consumes scores.

1.2.1.1 Attributes

Name	Description
labels	Compact supervision labels and full-shell row mapping.
evidence	Optional heavy geometry retained outside actor-visible state.

1.2.1.2 Methods

Name	Description
validate	Return a normalized scorer result aligned with candidates.

1.2.1.2.1 validate

oracle.labels.OracleCandidateEvaluation.validate(candidates, *, device, dtype)

Return a normalized scorer result aligned with candidates.

1.2.2 OracleCandidateLabels

oracle.labels.OracleCandidateLabels(
    scores,
    score_label,
    metrics,
    candidate_shell_indices,
    provenance,
)

Compact Oracle labels aligned with stable valid candidate rows.

V is the hard-valid subset of a candidate shell. These labels are privileged supervision and audit outputs; actor inputs receive only the separately projected candidate context.

1.2.2.1 Attributes

Name	Description
scores	Selection-objective values as Tensor["V", float32].
score_label	Stable semantic name for scores.
metrics	Oracle metrics, each Tensor["V", float32] in compact-valid order.
candidate_shell_indices	Full-shell row ids as Tensor["V", int64] for compact label rows.
provenance	Scorer family that produced the labels, such as target_rri.

1.2.2.2 Methods

Name	Description
selected	Return scalar labels for one selected compact candidate row.
validate	Normalize tensors and verify compact rows against the candidate table.

1.2.2.2.1 selected

oracle.labels.OracleCandidateLabels.selected(valid_index)

Return scalar labels for one selected compact candidate row.

1.2.2.2.2 validate

oracle.labels.OracleCandidateLabels.validate(candidates, *, device, dtype)

Normalize tensors and verify compact rows against the candidate table.

1.2.3 RetainedOracleEvidence

oracle.labels.RetainedOracleEvidence(
    candidate_point_clouds_world=None,
    candidate_point_cloud_lengths=None,
    candidate_observation_scope='full_scene',
    target_eval_current_points_world=None,
    target_eval_candidate_points_world=None,
    target_eval_candidate_point_lengths=None,
    target_eval_crop_policy=None,
    target_eval_voxel_size_m=None,
    target_eval_max_points=None,
    target_eval_reconstruction_points_world=None,
    target_eval_reconstruction_point_lengths=None,
    target_eval_reconstruction_shell_indices=None,
    target_eval_reconstruction_valid_indices=None,
    target_eval_reconstruction_preparation=None,
    selected_depth_m=None,
    selected_depth_valid_mask=None,
    selected_depth_focal_px=None,
    selected_depth_principal_point_px=None,
    selected_depth_image_size_hw=None,
)

Heavy Oracle evidence retained temporarily or for explicit audits.

Candidate-leading tensors use the compact hard-valid axis V. Point coordinates are world-frame metres and padded axes are paired with length vectors so padding never becomes geometric evidence.

1.2.3.1 Attributes

Name	Description
candidate_point_clouds_world	Padded clouds as Tensor["V P 3", float32] in world metres.
candidate_point_cloud_lengths	Valid point counts as Tensor["V", int64] for padded clouds.
candidate_observation_scope	Acquisition geometry scope; cropped clouds require full selected acquisition before history.
target_eval_current_points_world	Current target crop as Tensor["P_t 3", float32] in world metres.
target_eval_candidate_points_world	Candidate target crops as Tensor["V P_q 3", float32] in world metres.
target_eval_candidate_point_lengths	Valid target-crop counts as Tensor["V", int64].
target_eval_crop_policy	Versioned target-crop policy used for retained evidence.
target_eval_voxel_size_m	Voxel size used to fuse target evaluation evidence, in metres.
target_eval_max_points	Configured target-evidence point budget.
target_eval_reconstruction_points_world	Audited prepared successors as Tensor["A P_a 3", float32] in world metres.
target_eval_reconstruction_point_lengths	Valid point counts as Tensor["A", int64] for audited successors.
target_eval_reconstruction_shell_indices	Full-shell row ids as Tensor["A", int64] for audited successors.
target_eval_reconstruction_valid_indices	Compact hard-valid row ids as Tensor["A", int64] for audited successors.
target_eval_reconstruction_preparation	Complete ordered preparation provenance for audited successor rows.
selected_depth_m	Selected depth as Tensor["H_d W_d", float32] in metres.
selected_depth_valid_mask	Finite-hit mask as Tensor["H_d W_d", bool] for selected_depth_m.
selected_depth_focal_px	Selected-depth focal lengths (fx, fy) in pixels.
selected_depth_principal_point_px	Selected-depth principal point (cx, cy) in pixels.
selected_depth_image_size_hw	Selected-depth image size (height, width).

1.2.3.2 Methods

Name	Description
selected_point_cloud	Return the unpadded point cloud for one compact candidate row.
compact_for_selection	Drop non-selected render evidence while preserving configured audits.
validate	Normalize candidate evidence and verify compact-row alignment.

1.2.3.2.1 selected_point_cloud

oracle.labels.RetainedOracleEvidence.selected_point_cloud(valid_index)

Return the unpadded point cloud for one compact candidate row.

1.2.3.2.2 compact_for_selection

oracle.labels.RetainedOracleEvidence.compact_for_selection(
    valid_index,
    *,
    retain_target_crops,
)

Drop non-selected render evidence while preserving configured audits.

1.2.3.2.3 validate

oracle.labels.RetainedOracleEvidence.validate(
    num_valid,
    candidate_shell_indices,
    device,
    dtype,
)

Normalize candidate evidence and verify compact-row alignment.

1.2.4 SelectedCandidateObservation

oracle.labels.SelectedCandidateObservation(
    depths,
    points_world,
    acquisition_s=0.0,
)

Full-scene acquisition for one selected compact candidate.

Raw low-resolution depth and unpadded world points remain alive until history consumption/materialization. The separately retained store depth can use a higher resolution; it does not substitute for causal points.

1.2.4.1 Attributes

Name	Description
depths	One actual calibrated raster with depth Tensor["1 H W", float32] and hit mask.
points_world	Unpadded raw unprojection Tensor["P 3", float32] in world metres.
acquisition_s	Full selected render and unprojection duration in seconds; capture synchronizes device work.

1.2.4.2 Methods

Name	Description
validate	Reject mismatched selected identity and malformed or nonfinite observations.

1.2.4.2.1 validate

oracle.labels.SelectedCandidateObservation.validate(candidates, compact_index)

Reject mismatched selected identity and malformed or nonfinite observations.

1.2.5 TargetReconstructionPreparation

oracle.labels.TargetReconstructionPreparation(
    ordered_stages,
    global_voxel_size_m,
    global_max_points,
    target_point_crop_policy,
    target_mesh_crop_policy,
    target_crop_margin_m,
    target_voxel_size_m,
    target_max_points,
    metric_voxel_size_m,
    metric_max_points,
)

Ordered preparation contract for retained target successor states.

Zero voxel sizes and None point caps explicitly disable their respective operations. The global cap is disabled in target scoring even when the scene-evaluation path uses a configured cap.

1.2.5.1 Attributes

Name	Description
ordered_stages	Exact operation order used to prepare every before/after state.
global_voxel_size_m	Global fusion voxel edge; zero disables global voxel fusion.
global_max_points	Global point cap; None disables this cap.
target_point_crop_policy	Versioned point-membership crop policy applied to successor reconstructions.
target_mesh_crop_policy	Reference-mesh face crop policy used by the metric, when applicable.
target_crop_margin_m	Symmetric target crop margin in metres.
target_voxel_size_m	Post-crop fusion voxel edge; zero disables target voxel fusion.
target_max_points	Post-crop point cap; None disables this cap.
metric_voxel_size_m	Final metric fusion voxel edge; zero disables metric voxel fusion.
metric_max_points	Final metric point cap; None disables this cap.
enabled_stages	Return ordered stage activation derived from the retained parameters.
enabled_operations	Expose every fuse/crop/cap operation without hiding disabled halves.