OPERA

This repository contains the experiment-side software and frozen research artifacts associated with Physical residuals guide decisions in autonomous optical experiments. OPERA represents executable experimental actions as optical operators and evaluates their outcomes with physically interpretable residuals. The release focuses on the digital-twin task backends, provider-neutral agent interfaces, prompt protocols, deterministic validators, and frozen records needed to inspect this decision boundary.

Scope

Included:

• optical forward models and serial task backends for beam shaping, interferometry, and structured-light three-dimensional reconstruction;
• provider-neutral request, observation, and action interfaces;
• operator libraries, residual schemas, visible-score calculations, budget accounting, and protocol-level prompts;
• frozen decision, trajectory, and generated-strategy records where practical;
• deterministic backend replay and data-integrity checks; and
• tests for field visibility, action parsing, physical transitions, withheld offline-reference access, and frozen artifact hashes.

Not included:

• model-provider SDKs, credentials, endpoints, or network clients;
• rate limiting, retry, concurrency, and deployment infrastructure;
• live laboratory instrument control or hardware-specific control APIs; and
• the source-to-table statistical aggregation, resampling analyses, and final article-figure rendering pipeline.

No live model call is required to run the tests, validators, or deterministic replay included in this repository.

Repository map

Some directory and archive names retain an earlier figure numbering to preserve existing paths and checksums. The table below maps them to the current article.

Current article component	Repository entry point	Released material
Figure 1: operator-residual framework	backends/, interfaces/, and data/	Shared task backends, typed interfaces, operator records, residual fields, and budget accounting
Figure 2: feedback and physical outcomes	experiments/fig3_metric_exploitation/	Frozen decision records, prompt protocol, transition validation, and backend replay reports
Figure 3: target attainment and stability	experiments/fig2_target_attainment/	Prompt protocol, task interfaces, trajectory schema, target and budget records, and companion-data validation
Figure 4: residual prediction and operator selection	experiments/counterfactual_feedback_fidelity/ and experiments/counterfactual_kernels/	Candidate generation, cloned-state evaluation, deterministic selection, and transition validation
Figure 5: physical validation of generated strategies	experiments/fig5_strategy_discovery/	Task runtimes, protocol snapshots, frozen strategies, reference-snapshot tables, and validators
Figure 6: transfer to optical hardware	Outside this software release	The repository validates the digital-twin side of the frozen transfer protocols; live instrument control is not included
Sensitivity and confirmatory analyses	Companion source-data and analysis package	Composite-scalar control, tolerance sensitivity, reasoning-mode sensitivity, separate resource and attainment reporting, and problem-root resampling

A file-level map is provided in docs/CODE_MAP.md.

Installation

Python 3.13 on Linux x86-64 was used for release verification. Create a clean environment and install the pinned dependencies:

python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

See ENVIRONMENT.md for the tested package versions and hardware notes.

Verification

Run the default suite from the repository root:

PYTHONDONTWRITEBYTECODE=1 pytest -q -p no:cacheprovider
python tools/release_integrity.py .

Run the principal artifact validators directly:

python -m experiments.fig2_target_attainment.validate_release
python -m experiments.fig3_metric_exploitation.validate_data
python -m experiments.counterfactual_feedback_fidelity.validate_data
python -m experiments.counterfactual_kernels.validate_data
python -m experiments.fig5_strategy_discovery.validate_release

The target-attainment replay runner accepts the extracted companion-data directory:

python replay/replay_run.py --data /path/to/fig2_oracle_data/data --limit 1

The fig2_oracle_data name is retained for compatibility and corresponds to the target-attainment analysis shown as Figure 3 in the current article. Best-policy-at-each-budget records are aggregate visual references calculated after execution rather than executable trajectories. The replay command reports these records as skipped and evaluates the executable strategies. Release verification replays the 270 scripted Figure 3 trajectory records against the deterministic backend.

Data and protocol records

Compact frozen inputs used by the validators are included where practical. The complete target-attainment record archive and its standalone backend package are distributed as companion artifacts under their compatibility filenames:

• fig2_oracle_data_20260722.tar.gz
• fig2_oracle_backend_20260722.tar.gz

Prompt text, model identifiers, model responses, and model-generated strategy files appearing in the experimental artifacts are scientific provenance. They are not required for, and are not used as, model-provider credentials or live API configuration. See docs/DATA.md and docs/MODEL_PROVENANCE.md.

Reproducibility boundary

The released validators establish file integrity, interface restrictions, prompt rendering, selected backend transitions, and deterministic replay where an archived record represents an executable trajectory. Offline physical performance remains unavailable to the agent during execution. Statistical aggregation, bootstrap and sign-flip inference, sensitivity analyses, and final figure rendering are maintained in a separate companion analysis package. Physical-instrument control for the hardware-transfer experiments is outside this software release. See docs/REPRODUCIBILITY.md for the exact boundary.