1 oracle.target_selection

oracle.target_selection

Oracle target-task sampling for ARIA-NBV.

select_observed_rollout_targets owns current V1 actor-visible admission and OracleTargetTaskSampler owns the legacy V0 GT task population. Both produce the same rollout task DTO while keeping actor instructions separate from the privileged GT row used for crop and scoring. Persistence-only compatibility columns are encoded by the rollout writer rather than carried by this module.

1.1 Attributes

Name Description
ORACLE_TARGET_TASK_SOURCE Source label for oracle target-task rows sampled from GT OBBs.
TARGET_INVALID_REASON_CODES Version-1 target invalidity reason bit positions.
TARGET_INVALID_REASON_VERSION Version label for TARGET_INVALID_REASON_CODES.

1.2 Classes

Name Description
ObservedRolloutTargetAllocation Complete V1 admission outcomes and one diagnostic capped allocation.
ObservedRolloutTargetSelection V1 observed-target admission and rollout tasks for one source sample.
ObservedTargetSamplingEvidence Complete admitted-population evidence for the V1 diagnostic allocator.
ObservedTargetSupportAssignment Causal support assigned to one admitted actor-visible target.
OracleTargetTask One oracle target-task row for rollout/data-generation labeling.
OracleTargetTaskSampler Sample V0 GT tasks or explicitly allocate admitted V1 diagnostic tasks.
OracleTargetTaskSamplerConfig Configuration for V0 reference sampling and the V1 diagnostic allocator.
OracleTargetTaskSamplingResult Oracle target-task pool and seeded selected sample for one snippet.
OracleTargetTaskSelectionPolicy Reference and diagnostic policies for admitted oracle target tasks.
TargetTaskIdentityStatus Task-admission status for oracle target-task rows.

1.2.1 ObservedRolloutTargetAllocation

oracle.target_selection.ObservedRolloutTargetAllocation(
    admission,
    selected_rows,
    allocation,
    evidence,
    decision,
    source_manifest,
    max_targets_per_sample,
    seed,
)

Complete V1 admission outcomes and one diagnostic capped allocation.

1.2.1.1 Attributes

Name Description
admission Every actor-visible admission outcome and the complete admitted V1 population.
selected_rows Allocated admitted rows with rank and marginal inclusion probability populated.
allocation Selected admitted-row indices and probabilities for the entire admitted population.
evidence Full actor-identity support assignment used to derive the allocation strata.
decision Independently supplied source, root, cutoff, split, and reference-pose binding.
source_manifest Existing rollout source-manifest DTO used to validate the decision provenance.
max_targets_per_sample Configured diagnostic cap applied to the admitted V1 population.
seed Local Torch generator seed used for the allocation, if configured.

1.2.2 ObservedRolloutTargetSelection

oracle.target_selection.ObservedRolloutTargetSelection(
    matches,
    selected_rows,
    source,
    warnings=(),
)

V1 observed-target admission and rollout tasks for one source sample.

1.2.2.1 Attributes

Name Description
matches All actor-visible descriptors with explicit admission outcomes.
selected_rows Every uniquely matched actor target, ordered by observed source identity.
source Actor-visible target source, or None when none was available.
warnings Non-fatal actor-source and privileged-reference diagnostics.

1.2.3 ObservedTargetSamplingEvidence

oracle.target_selection.ObservedTargetSamplingEvidence(
    count_boundaries,
    assignments,
)

Complete admitted-population evidence for the V1 diagnostic allocator.

1.2.3.1 Attributes

Name Description
count_boundaries Strictly increasing positive surface-count edges; equality enters the upper bin.
assignments Exactly one assignment for every admitted actor target, including unavailable support.

1.2.4 ObservedTargetSupportAssignment

oracle.target_selection.ObservedTargetSupportAssignment(
    target_id,
    descriptor_hash,
    support,
)

Causal support assigned to one admitted actor-visible target.

1.2.4.1 Attributes

Name Description
target_id Stable actor target identity, never a privileged GT source-row index.
descriptor_hash Hash of the actor-visible descriptor admitted for this allocation.
support Bound causal prefix; its summary retains unavailable versus measured-empty support.

1.2.5 OracleTargetTask

oracle.target_selection.OracleTargetTask(
    source_index,
    target_row_id,
    target_id,
    descriptor,
    inst_id,
    confidence,
    identity_status,
    selected_rank=None,
    selection_probability=None,
    obb_data=None,
)

One oracle target-task row for rollout/data-generation labeling.

V1 rows carry an actor-visible descriptor and detector identity while source_index points to the uniquely matched GT row used for privileged evaluation. Legacy V0 rows derive both sides from one descriptor-constructible GT OBB. A V0 row is sampled only when its serialized payload is finite and its extents are finite and strictly positive; auxiliary-invalid rows remain auditable. Persistence-only compatibility values are added by the rollout writer.

1.2.5.1 Attributes

Name Description
source_index Privileged GT OBB row index before padded rows are removed.
target_row_id Actor OBB source row for V1, or GT task-pool row for legacy V0.
target_id Stable actor target identity for V1, or GT task identity for legacy V0.
descriptor Actor-visible V1 instruction, or GT-derived legacy V0 instruction.
inst_id Detector instance ID for V1, or GT instance ID for legacy V0.
confidence Detector confidence for V1, or audited GT confidence for legacy V0.
identity_status Serialized admission status produced by the owning V1 or V0 gate.
selected_rank Zero-based rank in the seeded capped sample, or None when unselected.
selection_probability Marginal capped-sample inclusion probability, populated on selected rows.
obb_data Flattened world-frame GT OBB retained only for privileged admission IoU.

1.2.6 OracleTargetTaskSampler

oracle.target_selection.OracleTargetTaskSampler(config)

Sample V0 GT tasks or explicitly allocate admitted V1 diagnostic tasks.

1.2.6.1 Methods

Name Description
sample Build and uniformly order the oracle target-task pool.
sample_inspected_pool Draw once from a previously inspected GT pool without rereading it.
inspect_pool Return all GT task rows without drawing or assigning probabilities.
sample_observed_support_diagnostic Allocate currently admitted V1 targets by causal observed support.
1.2.6.1.1 sample
oracle.target_selection.OracleTargetTaskSampler.sample(
    sample,
    *,
    eligible_target_ids=None,
)

Build and uniformly order the oracle target-task pool.

1.2.6.1.1.1 Parameters
Name Type Description Default
sample 'VinOfflineSample' VIN offline sample carrying the privileged gt_obbs task source. required
1.2.6.1.1.2 Returns
Name Type Description
OracleTargetTaskSamplingResult Descriptor-constructible GT rows, the matched-only pool, and a
OracleTargetTaskSamplingResult seeded selection. A configured cap selects a uniform subset;
OracleTargetTaskSamplingResult None selects every matched task. eligible_target_ids may
OracleTargetTaskSamplingResult restrict the matched population before the uniform draw; None
OracleTargetTaskSamplingResult preserves the complete reference population. Auxiliary-invalid
OracleTargetTaskSamplingResult payload rows remain auditable but do not enter the sampling pool.
1.2.6.1.2 sample_inspected_pool
oracle.target_selection.OracleTargetTaskSampler.sample_inspected_pool(
    pool,
    *,
    eligible_target_ids=None,
)

Draw once from a previously inspected GT pool without rereading it.

1.2.6.1.3 inspect_pool
oracle.target_selection.OracleTargetTaskSampler.inspect_pool(sample)

Return all GT task rows without drawing or assigning probabilities.

This lets a caller measure source-bound eligibility before the one authoritative uniform draw. The same row validation and ordering are used by sample.

1.2.6.1.4 sample_observed_support_diagnostic
oracle.target_selection.OracleTargetTaskSampler.sample_observed_support_diagnostic(
    sample,
    *,
    source_manifest,
    decision,
    evidence,
)

Allocate currently admitted V1 targets by causal observed support.

This library-only challenger begins with :func:select_observed_rollout_targets; it cannot allocate legacy V0 GT tasks or change the V1 admission gate. The existing source manifest and an independently constructed decision receipt bind source and collection training splits, source hashes, sample, root, cutoff, and reference pose. Every admitted actor target is then accounted for exactly once by target_id and descriptor hash before allocation.

1.2.6.1.4.1 Parameters
Name Type Description Default
sample 'VinOfflineSample' Current VIN source sample used by V1 observed-target admission. required
source_manifest 'RolloutSourceManifest' Existing rollout source-population manifest. required
decision ObservationSupportDecision Independent decision/root receipt for support validation. required
evidence ObservedTargetSamplingEvidence Complete support assignments and frozen stratum boundaries. required
1.2.6.1.4.2 Returns
Name Type Description
ObservedRolloutTargetAllocation Complete V1 admission outcomes, selected rows, population-level
ObservedRolloutTargetAllocation allocation probabilities, and the exact evidence/provenance inputs.

1.2.7 OracleTargetTaskSamplerConfig

oracle.target_selection.OracleTargetTaskSamplerConfig()

Configuration for V0 reference sampling and the V1 diagnostic allocator.

1.2.7.1 Attributes

Name Description
target_type Factory target for BaseConfig.setup_target.
max_targets_per_sample Maximum admitted tasks, or None for every V0 reference task.
seed Seed for uniform capped sampling without replacement.
policy Policy used to select admitted GT target tasks.

1.2.8 OracleTargetTaskSamplingResult

oracle.target_selection.OracleTargetTaskSamplingResult(
    rows,
    selected_rows,
    max_targets_per_sample,
    seed,
    source,
    warnings=(),
)

Oracle target-task pool and seeded selected sample for one snippet.

1.2.8.1 Attributes

Name Description
rows All non-padded GT OBB rows interpreted as candidate target tasks.
selected_rows Uniformly ordered matched rows with sampling audit fields populated.
max_targets_per_sample Configured upper bound, or None when every matched task is selected.
seed Random seed used for capped sampling, or None for an unseeded generator.
source Oracle OBB source name, or None when no GT source is available.
warnings Non-fatal source and sampling diagnostics.

1.2.8.2 Methods

Name Description
diagnostic_summary Return compact counts for target-task pool and sample audits.
1.2.8.2.1 diagnostic_summary
oracle.target_selection.OracleTargetTaskSamplingResult.diagnostic_summary()

Return compact counts for target-task pool and sample audits.

1.2.9 OracleTargetTaskSelectionPolicy

oracle.target_selection.OracleTargetTaskSelectionPolicy()

Reference and diagnostic policies for admitted oracle target tasks.

1.2.9.1 Attributes

Name Description
UNIFORM_WITHOUT_REPLACEMENT Seeded capped uniform sampling without replacement.
OBSERVED_SUPPORT_STRATIFIED Library-only V1 diagnostic allocation over causal observed support.

1.2.10 TargetTaskIdentityStatus

oracle.target_selection.TargetTaskIdentityStatus()

Task-admission status for oracle target-task rows.

1.2.10.1 Attributes

Name Description
MATCHED The GT payload is finite, its extents are positive, and it is admitted.
AMBIGUOUS Legacy persisted status retained for reason-code decoding.
UNMATCHED Legacy persisted status retained for reason-code decoding.
INVALID_GEOMETRY The target payload is non-finite or has non-positive extents.
Back to top