1 rollouts.inspection.invariants

rollouts.inspection.invariants

QH, target, mask, selected-depth, corruption, and suspicious-row audits.

1.1 Classes

Name Description
RolloutSuspiciousQueryConfig Thresholds used by suspicious_rollout_rows.

1.1.1 RolloutSuspiciousQueryConfig

rollouts.inspection.invariants.RolloutSuspiciousQueryConfig(
    min_valid_candidates=3,
    dominant_invalid_fraction=0.8,
    high_target_score=0.5,
    max_step_distance_m=1.25,
    max_height_delta_m=0.6,
    max_backward_step_m=0.35,
    max_yaw_delta_deg=85.0,
)

Thresholds used by suspicious_rollout_rows.

1.1.1.1 Attributes

Name Description
min_valid_candidates Flag steps with fewer actor-valid candidates than this count.
dominant_invalid_fraction Flag a step when one invalid reason explains at least this fraction of invalid rows.
high_target_score Flag invalid GT target rows whose selection score is at least this value.
max_step_distance_m Motion-realism threshold for selected candidate step length.
max_height_delta_m Motion-realism threshold for selected candidate height delta.
max_backward_step_m Motion-realism threshold for selected candidate backward motion.
max_yaw_delta_deg Motion-realism threshold for selected candidate yaw delta.

1.2 Functions

Name Description
candidate_result_diagnostic_counts Return live CandidateSamplingResult counts by position and invalid reason.
mask_combination_rows Return observed candidate-mask combinations with explicit denominators.
q_h_evidence_rows Read store-local Q_H contract facts without dataset-stage admission.
selected_depth_preview Return one downsampled selected-depth payload for Plotly app previews.
selected_depth_summary_rows Return bounded summaries for persisted selected-action depth rasters.
store_invariant_rows Project the store’s scientific and structural invariants as evidence rows.
suspicious_rollout_rows Return heuristic anomaly rows for rollout-store QA triage.
target_audit_rows Return stored target-task rows with frozen selection and GT-audit fields.
validity_waterfall_rows Return full-shell to selected counts for one rollout store.

1.2.1 candidate_result_diagnostic_counts

rollouts.inspection.invariants.candidate_result_diagnostic_counts(candidates)

Return live CandidateSamplingResult counts by position and invalid reason.

1.2.2 mask_combination_rows

rollouts.inspection.invariants.mask_combination_rows(reader)

Return observed candidate-mask combinations with explicit denominators.

selected_mask is an actor decision and therefore only implies actor_action_mask. It is not a stage after q_train_mask. The training mask independently requires actor validity and oracle-label availability, so selected-but-not-training rows remain valid evidence.

1.2.2.1 Parameters

Name Type Description Default
reader RolloutZarrStoreReader Read-only rollout-store adapter. required

1.2.2.2 Returns

Name Type Description
list[dict[str, Any]] Rows for observed Boolean combinations. Counts use the full persisted
list[dict[str, Any]] candidate table as their denominator, including invalid candidates.

1.2.3 q_h_evidence_rows

rollouts.inspection.invariants.q_h_evidence_rows(
    reader,
    *,
    deep_count=False,
    chunk_size=1024,
    state_row_limit=None,
    progress_callback=None,
    validation_result=None,
)

Read store-local Q_H contract facts without dataset-stage admission.

Canonical validation is mandatory. The default path reads metadata only; deep_count=True performs the explicitly requested bounded mask count.

1.2.4 selected_depth_preview

rollouts.inspection.invariants.selected_depth_preview(
    reader,
    *,
    step_row_id,
    max_size=96,
)

Return one downsampled selected-depth payload for Plotly app previews.

1.2.5 selected_depth_summary_rows

rollouts.inspection.invariants.selected_depth_summary_rows(
    reader,
    *,
    rollout_row_id=None,
    step_row_id=None,
    limit=128,
)

Return bounded summaries for persisted selected-action depth rasters.

Dense selected-depth arrays are intentionally read only for the filtered step rows. The default limit keeps app and CLI inspections from scanning a production store by accident.

1.2.6 store_invariant_rows

rollouts.inspection.invariants.store_invariant_rows(
    reader,
    *,
    manifest=None,
    manifest_payload=None,
)

Project the store’s scientific and structural invariants as evidence rows.

1.2.6.1 Parameters

Name Type Description Default
reader RolloutZarrStoreReader Read-only rollout-store adapter. required
manifest dict[str, Any] | None Optional result of RolloutZarrStoreReader.manifest. The sidecar is read when omitted. None
manifest_payload dict[str, Any] | None Backward-compatible keyword for manifest used by existing inspection callers. Passing both keywords is invalid. None

1.2.6.2 Returns

Name Type Description
list[dict[str, Any]] Deterministically ordered PASS/WARN/FAIL rows with expected conditions,
list[dict[str, Any]] observed evidence, source arrays, and actor/oracle/derived-data roles.

1.2.6.3 Notes

This helper does not repair stale or inconsistent data. In particular, the factual steps/ and candidates/ tables remain authoritative; q_h/ is checked as a derived training cache.

1.2.7 suspicious_rollout_rows

rollouts.inspection.invariants.suspicious_rollout_rows(reader, *, config=None)

Return heuristic anomaly rows for rollout-store QA triage.

1.2.8 target_audit_rows

rollouts.inspection.invariants.target_audit_rows(reader)

Return stored target-task rows with frozen selection and GT-audit fields.

1.2.9 validity_waterfall_rows

rollouts.inspection.invariants.validity_waterfall_rows(reader)

Return full-shell to selected counts for one rollout store.

Back to top