1 rollouts.inspection.policies

rollouts.inspection.policies

Selection, temporal, return, headroom, and paired-policy evidence.

1.1 Classes

Name Description
TemporalMetricSpec Public field and unit contract for one supported temporal metric.

1.1.1 TemporalMetricSpec

rollouts.inspection.policies.TemporalMetricSpec(value_field, units)

Public field and unit contract for one supported temporal metric.

1.1.1.1 Attributes

Name Description
value_field Persisted rollout-step row key consumed by the temporal reducer.
units Measurement units displayed with the reduced metric.

1.2 Functions

Name Description
candidate_selection_pooled_summary_rows Pool one compatible candidate-family fraction over factual trajectories.
candidate_selection_sequence_rows Return one selected-family sequence and terminal gain per factual rollout.
candidate_selection_temporal_summary_rows Summarize one state-level candidate-family quantity over factual depth.
candidate_selection_transition_rows Summarize expected and realized family transitions over factual depth.
candidate_sequence_return_summary_rows Summarize terminal return by exact selected-family sequence.
comparable_policy_cohorts Build exact matched cohorts for scientifically valid policy comparison.
discounted_rollout_return_rows Derive discounted factual selected gain under the persisted contract.
exact_policy_role_rows Attach roles from exact persisted pairs without dropping unknown rows.
normalize_temporal_value Normalize one temporal observation without fabricating missing values.
oracle_headroom_evidence Return exact-role diagnostic endpoint contrasts with honest exclusions.
paired_policy_comparison_rows Summarize paired endpoint differences over exact policy cohorts.
reconstruction_endpoint_rows Return one greatest persisted factual step per rollout.
reconstruction_endpoint_summary_rows Summarize factual endpoints over supported exact display strata.
reconstruction_metric_summary_rows Summarize the fixed factual reconstruction and selection metric plan.
rollout_endpoint_metric_summary Summarize one terminal factual step per rollout for a metric.
rollout_step_objective_rows Return per-step objective, branching, and selected-action audit rows.
rollout_tree_summary_rows Summarize selected rollout-tree provenance by policy, step, and family.
root_relative_candidate_rows Return candidate centers relative to each rollout root in Z-up metres.
selected_candidate_rank_rows Rank selected actions by policy score and oracle target diagnostics.
temporal_metric_spec Return the persisted field and units for a validated temporal metric.
temporal_metric_summary_rows Aggregate one factual rollout metric over depth and explicit strata.

1.2.1 candidate_selection_pooled_summary_rows

rollouts.inspection.policies.candidate_selection_pooled_summary_rows(
    dynamics_rows,
    *,
    metric,
)

Pool one compatible candidate-family fraction over factual trajectories.

This is a sample-population view for one selected store. It deliberately omits temperature and exact generation-cohort identity only within a proven non-temperature generation identity. Rows without that proof remain cohort-separated. Policy, horizon, branch factor, and beam width remain explicit compatibility controls. Candidate and selected shares are recomputed from additive counts; policy mass is the equal-state mean of complete persisted probability vectors.

1.2.2 candidate_selection_sequence_rows

rollouts.inspection.policies.candidate_selection_sequence_rows(dynamics_rows)

Return one selected-family sequence and terminal gain per factual rollout.

1.2.3 candidate_selection_temporal_summary_rows

rollouts.inspection.policies.candidate_selection_temporal_summary_rows(
    dynamics_rows,
    *,
    metric,
)

Summarize one state-level candidate-family quantity over factual depth.

1.2.4 candidate_selection_transition_rows

rollouts.inspection.policies.candidate_selection_transition_rows(
    dynamics_rows,
    *,
    pool_temperatures=False,
)

Summarize expected and realized family transitions over factual depth.

policy_mass is the complete candidate-level selection-probability mass for the next family. Realized transitions use the one persisted selected family. Both remain conditioned on the previous selected family and exact generation cohort unless pool_temperatures is requested. The pooled view recomputes frequencies from factual states only within a proven non-temperature generation identity. Rows without that proof remain isolated by generation cohort.

1.2.5 candidate_sequence_return_summary_rows

rollouts.inspection.policies.candidate_sequence_return_summary_rows(
    sequence_rows,
)

Summarize terminal return by exact selected-family sequence.

1.2.6 comparable_policy_cohorts

rollouts.inspection.policies.comparable_policy_cohorts(reader)

Build exact matched cohorts for scientifically valid policy comparison.

Cohorts match on source sample, target identity/protocol, horizon and search budget, candidate/oracle configuration, and branch schedule. Policy and rollout recipe identify the comparison dimension and are never averaged as if they were independent unmatched populations.

1.2.6.1 Parameters

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

1.2.6.2 Returns

Name Type Description
dict[str, Any] Mapping with rollout-level cohort_rows, exact
dict[str, Any] eligible_cohort_rows, nearest-key mismatch_rows, comparison
dict[str, Any] labels, and the ordered cohort-key field names.

1.2.7 discounted_rollout_return_rows

rollouts.inspection.policies.discounted_rollout_return_rows(
    source,
    *,
    return_semantics,
    discount_gamma,
)

Derive discounted factual selected gain under the persisted contract.

1.2.8 exact_policy_role_rows

rollouts.inspection.policies.exact_policy_role_rows(cohort_rows)

Attach roles from exact persisted pairs without dropping unknown rows.

1.2.9 normalize_temporal_value

rollouts.inspection.policies.normalize_temporal_value(value)

Normalize one temporal observation without fabricating missing values.

1.2.10 oracle_headroom_evidence

rollouts.inspection.policies.oracle_headroom_evidence(
    source,
    *,
    threshold=1e-08,
)

Return exact-role diagnostic endpoint contrasts with honest exclusions.

1.2.11 paired_policy_comparison_rows

rollouts.inspection.policies.paired_policy_comparison_rows(
    reader,
    *,
    bootstrap_samples=2000,
    confidence=0.95,
    seed=0,
)

Summarize paired endpoint differences over exact policy cohorts.

1.2.11.1 Parameters

Name Type Description Default
reader RolloutZarrStoreReader Read-only rollout-store adapter. required
bootstrap_samples int Number of paired bootstrap resamples. Intervals are emitted only for at least three matched cohorts. 2000
confidence float Central bootstrap interval probability in (0, 1). 0.95
seed int Base seed for deterministic policy-pair and metric resampling. 0

1.2.11.2 Returns

Name Type Description
list[dict[str, Any]] One row per sorted policy/recipe pair and endpoint metric, including
list[dict[str, Any]] cohort count, median/IQR per policy, median paired delta B - A, and
list[dict[str, Any]] a deterministic bootstrap interval when sufficiently supported.

1.2.11.3 Raises

Name Type Description
ValueError If bootstrap_samples or confidence is invalid.

1.2.12 reconstruction_endpoint_rows

rollouts.inspection.policies.reconstruction_endpoint_rows(source)

Return one greatest persisted factual step per rollout.

1.2.13 reconstruction_endpoint_summary_rows

rollouts.inspection.policies.reconstruction_endpoint_summary_rows(
    source,
    *,
    group_fields=('policy', 'horizon'),
)

Summarize factual endpoints over supported exact display strata.

1.2.14 reconstruction_metric_summary_rows

rollouts.inspection.policies.reconstruction_metric_summary_rows(source)

Summarize the fixed factual reconstruction and selection metric plan.

1.2.15 rollout_endpoint_metric_summary

rollouts.inspection.policies.rollout_endpoint_metric_summary(source, *, metric)

Summarize one terminal factual step per rollout for a metric.

Each rollout contributes exactly its greatest persisted step_index; shorter factual chains are therefore retained. Statistics use finite terminal values only, while the denominator counts every rollout endpoint.

1.2.16 rollout_step_objective_rows

rollouts.inspection.policies.rollout_step_objective_rows(
    reader,
    *,
    rollout_row_id=None,
)

Return per-step objective, branching, and selected-action audit rows.

1.2.17 rollout_tree_summary_rows

rollouts.inspection.policies.rollout_tree_summary_rows(
    reader,
    *,
    step_rows=None,
)

Summarize selected rollout-tree provenance by policy, step, and family.

Rollout stores persist factual selected chains, not a full parent-edge tree. This helper therefore reports the observed branching/provenance distribution across selected steps: policy/recipe parameters, candidate family, fanout, invalidity, and selected objective values.

1.2.17.1 Parameters

Name Type Description Default
reader RolloutZarrStoreReader Read-only rollout-store adapter used when step_rows is not supplied. required
step_rows Iterable[Mapping[str, Any]] | None Optional already-materialized rows from rollout_step_objective_rows. Reusing the exact projection avoids a duplicate rollout-store traversal in report builders. None

1.2.18 root_relative_candidate_rows

rollouts.inspection.policies.root_relative_candidate_rows(
    reader,
    *,
    rollout_row_id=None,
    step_row_id=None,
    actor_valid_only=False,
)

Return candidate centers relative to each rollout root in Z-up metres.

The translation is candidate_center_world - root_center_world. This keeps ARIA world axes, including the gravity-aligned Z axis, while removing unrelated scene origins. It intentionally does not aggregate or expose raw absolute world coordinates as comparison axes.

1.2.18.1 Parameters

Name Type Description Default
reader RolloutZarrStoreReader Read-only rollout-store adapter. required
rollout_row_id int | None Optional stable rollout-row filter. None
step_row_id int | None Optional stable step-row filter. None
actor_valid_only bool Exclude candidates outside the hard actor action set. False

1.2.18.2 Returns

Name Type Description
list[dict[str, Any]] Candidate rows in root-centered ARIA world coordinates with metres as
list[dict[str, Any]] units and RIGHT_HAND_Z_UP as the frame convention.

1.2.19 selected_candidate_rank_rows

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

Rank selected actions by policy score and oracle target diagnostics.

Root-gain rank/regret preserve the historical projection contract. selection_score_rank uses the persisted logits that actually governed selection, while target_rri_rank is a separate oracle diagnostic. All ranks use competition ranking over finite actor-valid alternatives, so ties share a rank and invalid or missing labels are never assigned a low score.

1.2.19.1 Parameters

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

1.2.19.2 Returns

Name Type Description
list[dict[str, Any]] One row per selected rollout step with policy mechanics, exact ranks,
list[dict[str, Any]] regret to the best valid alternative, and finite reward bands.

1.2.20 temporal_metric_spec

rollouts.inspection.policies.temporal_metric_spec(metric)

Return the persisted field and units for a validated temporal metric.

1.2.21 temporal_metric_summary_rows

rollouts.inspection.policies.temporal_metric_summary_rows(
    source,
    *,
    metric,
    group_fields=(),
)

Aggregate one factual rollout metric over depth and explicit strata.

1.2.21.1 Parameters

Name Type Description Default
source RolloutZarrStoreReader | Iterable[Mapping[str, Any]] Reader or already-normalized output from rollout_step_objective_rows. required
metric str Validated scientific metric name. valid_fanout maps to the factual num_valid_candidates field. required
group_fields Iterable[str] Upstream experiment dimensions or selected-action provenance fields. Selected-action fields are descriptive post-selection strata, not causal sampling-policy effects. ()

1.2.21.2 Returns

Name Type Description
list[dict[str, Any]] One deterministic row per grouping tuple and step_index. Counts
list[dict[str, Any]] include all source rows; statistics use finite values only and use
list[dict[str, Any]] linear interpolation for quartiles.

1.2.21.3 Raises

Name Type Description
ValueError If the metric or a grouping field is unsupported.
Back to top