1 rollouts.inspection.candidates

rollouts.inspection.candidates

Candidate population, support, calibration, collision, and composition evidence.

1.1 Classes

Name Description
CandidateValidityEvidence Immutable descriptive evidence for an admitted sequence of stored steps.
CandidateValidityStep Exact materialized candidate counts at one persisted decision state.

1.1.1 CandidateValidityEvidence

rollouts.inspection.candidates.CandidateValidityEvidence(
    steps,
    outcomes,
    families,
    triggered_reasons,
)

Immutable descriptive evidence for an admitted sequence of stored steps.

outcomes starts with VALID; rejected primary names and family names are sorted lexically. Triggered reasons use canonical numeric bit order, followed by unknown bits and any unspecified-invalid category. No missing proposals or independent-population inference is supplied by this projection.

1.1.2 CandidateValidityStep

rollouts.inspection.candidates.CandidateValidityStep(
    step_index,
    step_row_id,
    candidate_row_ids,
    materialized,
    valid,
    primary_counts,
    family_primary_counts,
    triggered_counts,
)

Exact materialized candidate counts at one persisted decision state.

Candidate identities retain shell order. Primary counts partition those rows; triggered counts overlap and include only actor-invalid candidates. Matrix axes are declared by the enclosing CandidateValidityEvidence.

1.2 Functions

Name Description
candidate_audit_rows Project full source-qualified candidate rows without mutating the store.
candidate_collision_support_rows Expose cohort-preserving collision and clearance availability.
candidate_composition_rows Macro-summarize candidate populations without pooling decision states.
candidate_direction_evidence Summarize directions per factual state, then scene and cohort macros.
candidate_flow_rows Return a count-conserving categorical candidate-provenance flow.
candidate_geometry_evidence_rows Attach a target-normalized, root-centred 2-D frame to audit rows.
candidate_group_summary_rows Summarize candidate validity and labels by a decoded categorical field.
candidate_motion_support_evidence Summarize motion and collision diagnostics per state and real macros.
candidate_population_evidence Collect candidate evidence once and expose bounded public projections.
candidate_proposal_calibration_rows Compare proposal mass and selected share inside exact decision states.
candidate_spatial_support_evidence Summarize spatial support with shell- and population-preserving macros.
candidate_target_view_evidence Summarize actor-visible target framing and explicit visibility gaps.
candidate_validity_evidence Project stored candidate validity without changing source arrays.
deterministic_candidate_display_sample Return an order-invariant, explicitly descriptive bounded sample.

1.2.1 candidate_audit_rows

rollouts.inspection.candidates.candidate_audit_rows(
    reader,
    *,
    rollout_row_id=None,
    step_row_id=None,
    limit=None,
    row_callback=None,
)

Project full source-qualified candidate rows without mutating the store.

Original primary names/IDs/bitsets and masks remain intact. primary_outcome is a separate display partition, whose sampler subcategories reconstruct the original acquisition’s audited motion bounds. Missing or unsupported source evidence yields an explicitly unresolved sampler explanation. Callback mode streams every admitted row without retaining a display-sized subset.

1.2.2 candidate_collision_support_rows

rollouts.inspection.candidates.candidate_collision_support_rows(audit_rows)

Expose cohort-preserving collision and clearance availability.

Counts remain exact populations. Rates are additionally reported as a state-then-scene macro so uneven candidate fan-out cannot dominate the descriptive comparison.

1.2.3 candidate_composition_rows

rollouts.inspection.candidates.candidate_composition_rows(
    audit_rows,
    *,
    group_by='mixture',
)

Macro-summarize candidate populations without pooling decision states.

audit_rows must be the one materialized candidate_audit_rows projection for a validated store. Counts remain exact; rates are first averaged within a state, then within a scene, then equally across scenes.

1.2.4 candidate_direction_evidence

rollouts.inspection.candidates.candidate_direction_evidence(rows)

Summarize directions per factual state, then scene and cohort macros.

1.2.5 candidate_flow_rows

rollouts.inspection.candidates.candidate_flow_rows(
    reader,
    *,
    policies=None,
    step_indices=None,
)

Return a count-conserving categorical candidate-provenance flow.

The projection reads only rollout policy, candidate depth, provenance, actor-validity, invalid-reason, and selected-status arrays. It deliberately excludes geometry, rewards, oracle labels, training masks, motion, and dense depth.

1.2.5.1 Parameters

Name Type Description Default
reader RolloutZarrStoreReader Read-only rollout-store adapter. required
policies Iterable[str] | None Optional decoded policy allowlist applied before aggregation. None
step_indices Iterable[int] | None Optional rollout-depth allowlist applied before aggregation. None

1.2.5.2 Returns

Name Type Description
list[dict[str, Any]] Consecutive links from the complete filtered candidate population to a
list[dict[str, Any]] combined proposal signature, actor validity, and terminal outcome.
list[dict[str, Any]] Every count and fraction uses the filtered population as its root
list[dict[str, Any]] denominator. A selected actor-invalid row terminates at
list[dict[str, Any]] selection_contract_violation.

1.2.6 candidate_geometry_evidence_rows

rollouts.inspection.candidates.candidate_geometry_evidence_rows(rows)

Attach a target-normalized, root-centred 2-D frame to audit rows.

The frame is deliberately local: the root is (0, 0) and the observed target is (1, 0). A positive lateral coordinate is the right-handed perpendicular to the root-to-target direction. Degenerate or absent target baselines remain unavailable rather than being fabricated.

1.2.7 candidate_group_summary_rows

rollouts.inspection.candidates.candidate_group_summary_rows(
    reader,
    *,
    group_by,
    audit_rows=None,
)

Summarize candidate validity and labels by a decoded categorical field.

1.2.7.1 Parameters

Name Type Description Default
reader RolloutZarrStoreReader Read-only rollout-store adapter. required
group_by CandidateGroupField Decoded categorical key present in candidate audit rows. required
audit_rows Iterable[dict[str, Any]] | None Optional already-materialized candidate rows. Reusing this projection avoids repeated full-store joins when one active view needs several groupings. None

1.2.8 candidate_motion_support_evidence

rollouts.inspection.candidates.candidate_motion_support_evidence(rows)

Summarize motion and collision diagnostics per state and real macros.

1.2.9 candidate_population_evidence

rollouts.inspection.candidates.candidate_population_evidence(
    reader,
    *,
    group_by=None,
    sample_size=500,
    scientific_support=True,
    audit_reader=candidate_audit_rows,
)

Collect candidate evidence once and expose bounded public projections.

The callback path keeps Zarr access incremental and centralizes all candidate-derived projections behind one validated grouping vocabulary. sample is deterministic and capped independently from aggregate rows.

1.2.10 candidate_proposal_calibration_rows

rollouts.inspection.candidates.candidate_proposal_calibration_rows(
    audit_rows,
    *,
    group_by='mixture',
)

Compare proposal mass and selected share inside exact decision states.

1.2.11 candidate_spatial_support_evidence

rollouts.inspection.candidates.candidate_spatial_support_evidence(rows)

Summarize spatial support with shell- and population-preserving macros.

1.2.12 candidate_target_view_evidence

rollouts.inspection.candidates.candidate_target_view_evidence(rows)

Summarize actor-visible target framing and explicit visibility gaps.

1.2.13 candidate_validity_evidence

rollouts.inspection.candidates.candidate_validity_evidence(
    steps,
    *,
    primary_outcomes=None,
)

Project stored candidate validity without changing source arrays.

The actor action mask owns the valid/invalid partition, even when a stored primary name disagrees. An invalid row named VALID becomes UNSPECIFIED_INVALID. Triggered reason bitsets are overlapping evidence, rather than additional primary outcomes; VALID bits on invalid rows are ignored, and rows lacking a failure bit remain explicitly unspecified.

1.2.13.1 Parameters

Name Type Description Default
steps Sequence[StoredStep] Ordered steps from one rollout, including empty realized steps. required
primary_outcomes Mapping[int, str] | None Optional source-bound post-hoc outcomes keyed by exact candidate row ID. Only primary sampler reasons may be refined. None

1.2.13.2 Returns

Name Type Description
CandidateValidityEvidence Frozen counts over exactly the supplied materialized candidate rows.

1.2.13.3 Raises

Name Type Description
ValueError Step/candidate identities repeat, or diagnostic columns do not have one scalar entry per materialized candidate.

1.2.14 deterministic_candidate_display_sample

rollouts.inspection.candidates.deterministic_candidate_display_sample(
    audit_rows,
    *,
    max_rows=500,
    seed='stored-rollout-display-v1',
)

Return an order-invariant, explicitly descriptive bounded sample.

Back to top