1 oracle.pipelines.evaluated_execution
oracle.pipelines.evaluated_execution
Generation-bound source acquisition and evaluated Oracle rollout execution.
This module is the shared execution seam for persisted rollout generation and interactive inspection. It owns source-generation validation, V1 observed target acquisition, one-shot root-support preparation, replay execution, and optional selected-depth materialization. Zarr persistence, campaign statistics, lineage, and multi-recipe iteration remain with aria_nbv.oracle.pipelines.rollout_dataset.
1.1 Classes
| Name | Description |
|---|---|
| EvaluatedExecutionFailure | Expected target- or recipe-level failure that must not become a label. |
| EvaluatedExecutionFailureKind | Expected fail-closed outcome category at the shared execution seam. |
| EvaluatedExecutionObservation | Bounded caller-independent Console output captured during execution. |
| EvaluatedExecutionSuccess | One evaluated recipe and the exact replay config that produced it. |
| EvaluatedScoringMode | Objective used to score one live rollout recipe. |
| LiveRolloutRun | One generation-bound live outcome with isolated bounded observations. |
| LiveRolloutSource | One acquired source sample and its complete observed-target audit. |
| LiveRolloutSourceRequest | Metadata-only request binding a writer config to one root generation. |
| PreparedEvaluatedTarget | Session-local scorer and support evidence reused across selected recipes. |
1.1.1 EvaluatedExecutionFailure
oracle.pipelines.evaluated_execution.EvaluatedExecutionFailure(
kind,
reason,
message,
valid_root_candidates=None,
)Expected target- or recipe-level failure that must not become a label.
1.1.1.1 Attributes
| Name | Description |
|---|---|
| kind | Stable stage-level category used by writer statistics and live rendering. |
| reason | Existing machine-readable invalidity or support reason. |
| message | Actionable operator-facing explanation; never interpreted as a label. |
| valid_root_candidates | Observed support in the actual materialized root shell, when available. |
1.1.2 EvaluatedExecutionFailureKind
oracle.pipelines.evaluated_execution.EvaluatedExecutionFailureKind()Expected fail-closed outcome category at the shared execution seam.
1.1.3 EvaluatedExecutionObservation
oracle.pipelines.evaluated_execution.EvaluatedExecutionObservation(
lines,
dropped_line_count=0,
elapsed_seconds=0.0,
)Bounded caller-independent Console output captured during execution.
1.1.3.1 Attributes
| Name | Description |
|---|---|
| lines | Newest bounded sanitized Console messages in emission order. |
| dropped_line_count | Number of earlier lines evicted after the bounded tail became full. |
| elapsed_seconds | Non-negative wall-clock duration of the evaluated execution in seconds. |
1.1.4 EvaluatedExecutionSuccess
oracle.pipelines.evaluated_execution.EvaluatedExecutionSuccess(
evaluated,
rollout_config,
valid_root_candidates,
)One evaluated recipe and the exact replay config that produced it.
1.1.4.1 Attributes
| Name | Description |
|---|---|
| evaluated | Factual replay transitions joined to compact Oracle evaluation sidecars. |
| rollout_config | Exact replay config used for policy lineage and parity inspection. |
| valid_root_candidates | Valid count from the actual materialized root shell. |
1.1.5 EvaluatedScoringMode
oracle.pipelines.evaluated_execution.EvaluatedScoringMode()Objective used to score one live rollout recipe.
1.1.5.1 Attributes
| Name | Description |
|---|---|
| TARGET_RRI | Thesis-core target RRI using an admitted observed target and GT reference. |
| SCENE_RRI | Diagnostic scene-level RRI using the existing scene scorer config. |
| GEOMETRY | Diagnostic policy-only execution without Oracle candidate labels. |
1.1.6 LiveRolloutRun
oracle.pipelines.evaluated_execution.LiveRolloutRun(
run_identity,
outcome,
observation,
)One generation-bound live outcome with isolated bounded observations.
1.1.6.1 Attributes
| Name | Description |
|---|---|
| run_identity | Stable key over source generation, full config, recipe, target, and mode. |
| outcome | Evaluated evidence or an expected fail-closed outcome. |
| observation | Run-local bounded Console tail independent of Streamlit state. |
1.1.7 LiveRolloutSource
oracle.pipelines.evaluated_execution.LiveRolloutSource(
request,
sample,
target_selection,
)One acquired source sample and its complete observed-target audit.
1.1.7.1 Attributes
| Name | Description |
|---|---|
| request | Metadata-only request whose generation remains authoritative. |
| sample | Loaded source sample with the exact assets declared by the source config. |
| target_selection | All observed-target outcomes and admitted rollout tasks for this sample. |
1.1.8 LiveRolloutSourceRequest
oracle.pipelines.evaluated_execution.LiveRolloutSourceRequest(
config,
sample_index,
generation,
request_digest,
)Metadata-only request binding a writer config to one root generation.
Constructing this DTO fingerprints bounded root metadata but does not open a dataset or initialize CUDA-dependent runtime objects.
1.1.8.1 Attributes
| Name | Description |
|---|---|
| config | Complete validated writer configuration; no source fields are rewritten. |
| sample_index | Zero-based row within the source config’s exact split/limit selection. |
| generation | Replacement-sensitive identity captured for the configured VIN store. |
| request_digest | Stable retained-state key over config, sample index, and generation. |
1.1.9 PreparedEvaluatedTarget
oracle.pipelines.evaluated_execution.PreparedEvaluatedTarget(
sample,
target,
scorer,
runtime_context,
selected_depth_renderer,
)Session-local scorer and support evidence reused across selected recipes.
This object owns live runtime references and is intentionally neither serializable nor cacheable across processes. Candidate generation receives only the actor-visible descriptor; privileged GT evidence remains inside the Oracle scorer.
1.1.9.1 Attributes
| Name | Description |
|---|---|
| sample | Source sample whose runtime evidence remains owned for recipe execution. |
| target | Admitted task carrying actor geometry and a privileged GT reference row. |
| scorer | Prepared target scorer reused across selected recipes. |
| runtime_context | Actor-visible descriptor passed to candidate generation. |
| selected_depth_renderer | Optional exact-resolution renderer reused for selected action retention. |
1.2 Functions
| Name | Description |
|---|---|
| acquire_live_rollout_source | Acquire one sample and all V1 observed-target admission outcomes. |
| apply_rollout_source_manifest | Filter and order a VIN reader from one validated reviewed manifest. |
| apply_rollout_source_rows | Filter a VIN reader to exact manifest rows without reacquiring samples. |
| assert_live_rollout_source_current | Reject a retained source after its selected store generation changes. |
| attach_selected_depths | Attach one exact-resolution selected depth map to each retained step. |
| build_live_rollout_source_request | Fingerprint a source request without opening the VIN dataset. |
| execute_evaluated_recipe | Execute one recipe with a prepared target and retain configured evidence. |
| execute_live_rollout | Execute one production-equivalent or explicitly diagnostic live recipe. |
| live_rollout_run_identity | Return the deterministic retained-result identity for one live run. |
| low_valid_root_reason | Return the policy-level root-support reason for a completed rollout. |
| prepare_evaluated_target | Prepare one target scorer without generating candidate shells. |
| select_rollout_source_manifest_rows | Select reviewed source rows in the exact requested sample-key order. |
1.2.1 acquire_live_rollout_source
oracle.pipelines.evaluated_execution.acquire_live_rollout_source(request)Acquire one sample and all V1 observed-target admission outcomes.
Generation identity is checked both before and after dataset acquisition so a same-path store replacement cannot silently relabel retained evidence. Required source assets are validated before runtime construction.
1.2.2 apply_rollout_source_manifest
oracle.pipelines.evaluated_execution.apply_rollout_source_manifest(
dataset,
manifest,
*,
sample_keys=None,
)Filter and order a VIN reader from one validated reviewed manifest.
1.2.3 apply_rollout_source_rows
oracle.pipelines.evaluated_execution.apply_rollout_source_rows(
dataset,
rows,
*,
owner,
)Filter a VIN reader to exact manifest rows without reacquiring samples.
1.2.4 assert_live_rollout_source_current
oracle.pipelines.evaluated_execution.assert_live_rollout_source_current(source)Reject a retained source after its selected store generation changes.
1.2.5 attach_selected_depths
oracle.pipelines.evaluated_execution.attach_selected_depths(
evaluated,
*,
sample,
renderer,
height_px,
width_px,
)Attach one exact-resolution selected depth map to each retained step.
1.2.6 build_live_rollout_source_request
oracle.pipelines.evaluated_execution.build_live_rollout_source_request(
config,
*,
sample_index,
)Fingerprint a source request without opening the VIN dataset.
The complete source config is authoritative, including split, limit, device, and asset flags. Callers must edit and validate those fields before constructing this request rather than relying on hidden live-mode overrides.
1.2.7 execute_evaluated_recipe
oracle.pipelines.evaluated_execution.execute_evaluated_recipe(
prepared,
recipe,
config,
)Execute one recipe with a prepared target and retain configured evidence.
1.2.8 execute_live_rollout
oracle.pipelines.evaluated_execution.execute_live_rollout(
source,
config,
recipe,
*,
scoring_mode,
target,
scene_scorer_config=None,
max_log_lines=_LIVE_LOG_MAX_LINES,
)Execute one production-equivalent or explicitly diagnostic live recipe.
1.2.9 live_rollout_run_identity
oracle.pipelines.evaluated_execution.live_rollout_run_identity(
source,
config,
recipe,
*,
scoring_mode,
target,
scene_scorer_config=None,
)Return the deterministic retained-result identity for one live run.
1.2.10 low_valid_root_reason
oracle.pipelines.evaluated_execution.low_valid_root_reason(result, *, minimum)Return the policy-level root-support reason for a completed rollout.
This retained public inspection helper preserves the historical post-hoc interpretation of a rollout result. Production execution uses the earlier root-admission callback so unsupported shells are rejected before scoring.
1.2.11 prepare_evaluated_target
oracle.pipelines.evaluated_execution.prepare_evaluated_target(
sample,
target,
config,
)Prepare one target scorer without generating candidate shells.
Each recipe materializes its authoritative seeded root shell inside replay, where the configured support gate observes that same shell before scoring.
1.2.12 select_rollout_source_manifest_rows
oracle.pipelines.evaluated_execution.select_rollout_source_manifest_rows(
manifest,
sample_keys,
)Select reviewed source rows in the exact requested sample-key order.