1 rollouts.replay

rollouts.replay

Finite-candidate replay state, policies, and transition generation.

This package exports in-memory rollout contracts from leaf modules; persisted normalized tables remain owned by aria_nbv.rollouts.storage.

1.1 Package guide

aria_nbv.rollouts.replay owns the in-memory transition protocol used during rollout generation. It combines a finite candidate table, a score source, a policy specification, and a state transition while retaining masks and provenance.

1.2 Main Contracts

Contract	Purpose
`CandidateScores`	Compact values aligned to the hard-valid candidate rows.
`RolloutPolicySpec`	Selection family and its deterministic/stochastic parameters.
`CounterfactualPoseGeneratorConfig`	Bounded rollout and candidate-generation composition.
`CounterfactualTrajectory`	Ordered selected poses and transition facts.
`CounterfactualRolloutResult`	Complete generated chain plus diagnostics.

Import the stable surface from aria_nbv.rollouts:

from aria_nbv.rollouts import (
    CandidateScores,
    CounterfactualPoseGeneratorConfig,
    RolloutPolicySpec,
)

Policies select only from hard-valid rows. Invalid rows never receive sentinel scores, and negative valid scores remain selectable because masking—not zero-filling—defines the support.

directed_orbit_only and directed_orbit_plus_bypass are opt-in, single-branch collection policies. They require a fixed target context, a clockwise or counter-clockwise direction, and measured candidate scores. Progress is reconstructed from the calibrated physical root camera and each branch’s committed camera centres; the trajectory’s corrected rig root still anchors Oracle state. The bypass mode additionally admits lateral-bypass rows inside its root-radius envelope. Neither policy changes Oracle labels or action-validity masks.

Replay is storage-independent. trace.py and zarr_store.py own conversion to persisted factual tables; Oracle pipeline composition supplies targets, candidate generation, scoring, and environment transitions.

Detailed state, policy, and callback protocols live in public docstrings and the generated API reference.

1.3 Verification

cd aria_nbv
uv run ruff check aria_nbv/rollouts/replay
uv run pytest tests/rollouts/test_counterfactuals.py \
  tests/rollouts/test_replay_oracle_golden_parity.py

# rollouts.replay { #aria_nbv.rollouts.replay } `rollouts.replay` Finite-candidate replay state, policies, and transition generation. This package exports in-memory rollout contracts from leaf modules; persisted normalized tables remain owned by :mod:`aria_nbv.rollouts.storage`.  ## Package guide `aria_nbv.rollouts.replay` owns the in-memory transition protocol used during rollout generation. It combines a finite candidate table, a score source, a policy specification, and a state transition while retaining masks and provenance. ## Main Contracts | Contract | Purpose | | --- | --- | | `CandidateScores` | Compact values aligned to the hard-valid candidate rows. | | `RolloutPolicySpec` | Selection family and its deterministic/stochastic parameters. | | `CounterfactualPoseGeneratorConfig` | Bounded rollout and candidate-generation composition. | | `CounterfactualTrajectory` | Ordered selected poses and transition facts. | | `CounterfactualRolloutResult` | Complete generated chain plus diagnostics. | Import the stable surface from `aria_nbv.rollouts`: ```python from aria_nbv.rollouts import ( CandidateScores, CounterfactualPoseGeneratorConfig, RolloutPolicySpec, ) ``` Policies select only from hard-valid rows. Invalid rows never receive sentinel scores, and negative valid scores remain selectable because masking—not zero-filling—defines the support. `directed_orbit_only` and `directed_orbit_plus_bypass` are opt-in, single-branch collection policies. They require a fixed target context, a clockwise or counter-clockwise direction, and measured candidate scores. Progress is reconstructed from the calibrated physical root camera and each branch's committed camera centres; the trajectory's corrected rig root still anchors Oracle state. The bypass mode additionally admits lateral-bypass rows inside its root-radius envelope. Neither policy changes Oracle labels or action-validity masks. Replay is storage-independent. `trace.py` and `zarr_store.py` own conversion to persisted factual tables; Oracle pipeline composition supplies targets, candidate generation, scoring, and environment transitions. Detailed state, policy, and callback protocols live in public docstrings and the [generated API reference](index.qmd). ## Verification ```sh cd aria_nbv uv run ruff check aria_nbv/rollouts/replay uv run pytest tests/rollouts/test_counterfactuals.py \ tests/rollouts/test_replay_oracle_golden_parity.py ```