1 oracle.pipelines.rollout_dataset
oracle.pipelines.rollout_dataset
Build standalone target-RRI rollout replay stores from VIN offline rows.
This module owns the first rollout-data generation path, not a migration of the immutable VIN offline cache. It reads VinOfflineDataset samples with live EfmSnippetView snippets and GT meshes attached, samples oracle target tasks, generates fixed-count mixed candidate tables, scores valid candidates with the target-cropped oracle, and writes a separate rollouts.zarr store.
The generated store must be interpretable as replay data for finite-candidate value learning. Lineage includes source manifest hashes, split hashes, candidate/oracle/rollout config hashes, selected target records, GT match audit fields, candidate strategy provenance, and rollout policy identifiers. Invalid targets or actions are skipped or masked with reason codes; they are never encoded as low target RRI.
1.1 Classes
| Name | Description |
|---|---|
| ExplicitRolloutTarget | Immutable V1 observed target consumed by one rollout writer unit. |
| ExplicitRolloutTargetConfig | Discriminated configuration for one explicit observed target. |
| InsufficientRootSupportError | Typed preflight outcome that must not create a rollout store. |
| RolloutDatasetWriter | Generate target-RRI rollout records and write a standalone Zarr store. |
| RolloutDatasetWriterConfig | Configuration for building standalone target-RRI rollout Zarr stores. |
| RolloutDatasetWriterStats | Counters reported by one rollout-store build. |
| RolloutRecipeConfig | One rollout policy recipe materialized into the replay store. |
| SelectedDepthRetentionConfig | High-resolution oracle depth retained only for selected rollout actions. |
1.1.1 ExplicitRolloutTarget
oracle.pipelines.rollout_dataset.ExplicitRolloutTarget(
sample_key,
actor_descriptor,
detected_source_row,
gt_match_row,
gt_match_id,
oriented_iou,
status,
reason,
target_id,
protocol=TargetInputProtocol.V1_OBSERVED,
explicit_target_hash='',
)Immutable V1 observed target consumed by one rollout writer unit.
1.1.2 ExplicitRolloutTargetConfig
oracle.pipelines.rollout_dataset.ExplicitRolloutTargetConfig()Discriminated configuration for one explicit observed target.
1.1.2.1 Methods
| Name | Description |
|---|---|
| setup_target | Materialize the immutable runtime DTO without sampling. |
1.1.2.1.1 setup_target
oracle.pipelines.rollout_dataset.ExplicitRolloutTargetConfig.setup_target()Materialize the immutable runtime DTO without sampling.
1.1.3 InsufficientRootSupportError
oracle.pipelines.rollout_dataset.InsufficientRootSupportError(
reason,
*,
target_task_sampling=None,
)Typed preflight outcome that must not create a rollout store.
1.1.4 RolloutDatasetWriter
oracle.pipelines.rollout_dataset.RolloutDatasetWriter(config)Generate target-RRI rollout records and write a standalone Zarr store.
For each source row the writer samples geometry-valid Oracle target tasks, passes sanitized descriptors to candidate generation, regenerates candidates from updated history/budget, scores target RRI, and persists compact replay records. Heavy diagnostics should be retained only for selected actions or retained chains through the downstream Zarr policy.
This class is the handoff point between data_handling and pose_generation: it reads immutable VinOfflineSample roots, calls the finite-candidate counterfactual generator, and emits evaluated rollout records objects that are stored independently of the VIN offline cache.
1.1.4.1 Methods
| Name | Description |
|---|---|
| root_support_preflight | Apply the campaign root-support gate before recipe generation. |
| run | Build the configured rollout store. |
1.1.4.1.1 root_support_preflight
oracle.pipelines.rollout_dataset.RolloutDatasetWriter.root_support_preflight(
valid_candidates,
)Apply the campaign root-support gate before recipe generation.
The caller supplies the one-shot probe count; probe tensors are not retained by this writer. A shortfall is a typed skip reason and must be handled by the shard owner without creating a store.
1.1.4.1.2 run
oracle.pipelines.rollout_dataset.RolloutDatasetWriter.run(
invocation=None,
shard_entry=None,
)Build the configured rollout store.
In normal mode the configured source split and max_samples decide the rows. In shard mode the RolloutShardEntry is authoritative: source rows are filtered and ordered from the manifest, max_samples is ignored, and source/config hash mismatches fail before generation.
1.1.5 RolloutDatasetWriterConfig
oracle.pipelines.rollout_dataset.RolloutDatasetWriterConfig()Configuration for building standalone target-RRI rollout Zarr stores.
The source is a strict-v7 VIN offline dataset opened in sample mode with enough live assets to rerun candidate generation and oracle scoring. The destination is a standalone rollout store; the source cache version is recorded as lineage and is not modified.
1.1.5.1 Attributes
| Name | Description |
|---|---|
| target_type | Return the concrete standalone rollout writer constructed by this config. |
| source | VIN strict-v7 source reader; must return samples with live snippet and GT mesh. |
| source_manifest_path | Optional reviewed ordered-source manifest enforced before direct generation. |
| sample_keys | Optional exact ordered sample-key subset of source_manifest_path. |
| oracle_target_task_sampler | Target-task sampler; the production writer admits only its uniform V0 policy. |
| require_current_root_target_support | Opt in to uniform V0 sampling only among GT tasks with measurable current-root target crops. |
| explicit_target | Optional one-target V1 input; mutually exclusive with target resampling. |
| candidate_mixture | Fixed-count mixed finite-candidate generator regenerated at every rollout step. |
| target_scorer | Target-specific oracle scorer that also emits diagnostic scene RRI. |
| selected_depth | High-resolution selected-depth persistence; separate from low-res all-candidate RRI scoring. |
| renderer_validation_output | Optional diagnostic capture root; single-chain actual low-resolution traces only. |
| endpoint_audit_enabled | Persist independent zero-render root/final target measurements and raw clouds. |
| store | Standalone rollout Zarr destination; the VIN offline store remains unchanged. |
| recipes | Rollout policies/branch schedules materialized into the replay store. |
| max_samples | Optional local smoke cap on source samples. |
| max_targets_per_sample | Optional local smoke cap on selected targets rolled out per source sample. |
| log_timing | Emit generation/scoring timing diagnostics for local evidence builds. |
| require_label_valid | Skip selected targets without valid GT/evaluation labels when true. |
| min_valid_root_candidates | Skip rollout roots whose materialized first step has too few valid actions. |
| min_target_aware_root_candidates | Minimum hard-valid root rows from target-bearing, bypass, or orbit center modes; zero disables this gate. |
| verbosity | Console verbosity. |
| is_debug | Enable debug logging in writer dependencies. |
1.1.5.2 Methods
| Name | Description |
|---|---|
| selected_source_manifest_rows | Return source-manifest rows in the exact configured sample-key order. |
1.1.5.2.1 selected_source_manifest_rows
oracle.pipelines.rollout_dataset.RolloutDatasetWriterConfig.selected_source_manifest_rows(
manifest,
)Return source-manifest rows in the exact configured sample-key order.
The full reviewed manifest remains authoritative for immutable row identity. When sample_keys is unset, its complete order is preserved.
1.1.6 RolloutDatasetWriterStats
oracle.pipelines.rollout_dataset.RolloutDatasetWriterStats(
samples_seen=0,
samples_without_snippet_or_mesh=0,
targets_selected=0,
targets_label_invalid=0,
target_invalid_skips=0,
rollout_invalid_skips=0,
rollouts_written=0,
skipped_reasons=dict(),
)Counters reported by one rollout-store build.
The counters are operational diagnostics for local smoke builds. They are not dataset labels; invalidity details that affect training/evaluation must also be represented in rollout trace masks and lineage.
1.1.6.1 Attributes
| Name | Description |
|---|---|
| samples_seen | Number of VIN source rows visited by the writer. |
| samples_without_snippet_or_mesh | Rows skipped because live snippet evidence or oracle mesh was absent. |
| targets_selected | Target tasks admitted for rollout generation before label-validity gates. |
| targets_label_invalid | Selected targets lacking an admissible oracle evaluation label. |
| target_invalid_skips | Targets skipped by target-level validity requirements. |
| rollout_invalid_skips | Generated roots skipped because rollout-level action checks failed. |
| rollouts_written | Root-target-recipe records handed to standalone Zarr persistence. |
| skipped_reasons | Operational skip counts keyed by stable diagnostic reason. |
1.1.6.2 Methods
| Name | Description |
|---|---|
| skip | Increment one operational skip reason without creating a label. |
1.1.6.2.1 skip
oracle.pipelines.rollout_dataset.RolloutDatasetWriterStats.skip(reason)Increment one operational skip reason without creating a label.
Training-relevant invalidity must still be represented by explicit trace masks and versioned reason codes; this counter is build telemetry only.
1.1.7 RolloutRecipeConfig
oracle.pipelines.rollout_dataset.RolloutRecipeConfig()One rollout policy recipe materialized into the replay store.
Recipes control action selection and may select an explicit independent proposal replica. Proposal roots are otherwise shared across recipe and temperature comparisons. The first supported policies cover random valid selection, greedy oracle selection, retained-beam oracle lookahead, and temperature-softmax records for rollout diversity.
1.1.7.1 Attributes
| Name | Description |
|---|---|
| name | Stable recipe name stored as branch schedule lineage. |
| policy | Complete branching and action-selection policy for this recipe. |
1.1.7.2 Methods
| Name | Description |
|---|---|
| default_suite | Return deterministic two-step recipes for local evidence builds. |
| diverse_suite | Return the radial/backtrack rollout-diversity recipe suite. |
1.1.7.2.1 default_suite
oracle.pipelines.rollout_dataset.RolloutRecipeConfig.default_suite()Return deterministic two-step recipes for local evidence builds.
The suite covers one factual path for random-valid and greedy policies plus two retained branches for oracle-lookahead and temperature-softmax policies. These recipe axes are rollout controls, not candidate-shell widths; every step still persists its complete generated shell.
1.1.7.2.2 diverse_suite
oracle.pipelines.rollout_dataset.RolloutRecipeConfig.diverse_suite()Return the radial/backtrack rollout-diversity recipe suite.
The suite mirrors .configs/historical/build_rollouts_v1_diverse.toml and is intended to pair with CandidateMixtureViewGeneratorConfig.radial_target_backtrack_family. Sibling-diversity controls are best-effort after candidate validity pruning, so the recipes record the intended action-family pressure without changing rollout hard-mask semantics.
1.1.8 SelectedDepthRetentionConfig
oracle.pipelines.rollout_dataset.SelectedDepthRetentionConfig()High-resolution oracle depth retained only for selected rollout actions.
Mesh-rendered depth supports successor-history reconstruction and audits. It is not actor-visible evidence and is stored in the rollout destination, never backfilled into the immutable VIN source cache.
1.1.8.1 Attributes
| Name | Description |
|---|---|
| enabled | Persist one selected-action depth map for every materialized rollout step. |
| width_px | Persisted selected-depth width in pixels. |
| height_px | Persisted selected-depth height in pixels. |
| chunk_steps | Number of selected steps per Zarr depth chunk. |
1.1.8.2 Methods
| Name | Description |
|---|---|
| renderer_config | Return a selected-only renderer config derived from the scorer renderer. |
1.1.8.2.1 renderer_config
oracle.pipelines.rollout_dataset.SelectedDepthRetentionConfig.renderer_config(
base,
)Return a selected-only renderer config derived from the scorer renderer.