opal-optimizer 0.3.5__tar.gz

opal_optimizer-0.3.5/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+## 0.3.5 (2026-10-21)
+
+- Reject uneven DDP inputs on every rank through the optimizer's Joinable interface instead of hanging (#2).
+- Update installation, LightningDiT results and run records, remove the overfit result, and document mailbox leases, checkpoint state and the unfreezing workaround.
+- Exclude local opal_runs artifacts from the wheel and source distribution.
+
+- Normalize logged NumPy metrics and allowlist checkpoint observations for safe plain and Accelerate resumes (B1).
+- Send SSH lease arguments and large answers over stdin; failed answer retries no longer block new requests (B2).
+- Clear and release claims after SSH failures; let a restarted broker reclaim its own lease with generation fencing (B3).
+- Keep the remote lease helper compatible with Python 3.6+ and check python3 availability in mailbox doctor (B4).
+- Reclaim the same broker's lease immediately after restart instead of waiting for the stale timeout (F1).
+- Log mailbox lease backoff once per request (F2).
+- Keep aggressive LR interpolation on-device with tensor-list weights and exact zero/one endpoints (F3).
+- Normalize NumPy updater state without calling rejected container hooks; record dropped fields in events and HTML, including quiet runs (F4).
+
+- Check updater state with a closed allowlist without invoking custom serialization hooks.
+- Redact form-encoded bearers, access tokens, triple-quoted, adjacent and bytes literals in diagnostics.
+- Serialize mailbox lease takeovers and fence stale renewals, releases and responses by generation (#1).
+- Save pending losses, analysis reports and authorized metrics so checkpoint resumes preserve observations (#3).
+
+- Preserve Accelerate's public optimizer state, parameter groups and defaults through a checkpoint adapter.
+- Resolve conjugate and negative parameter views before DDP byte fingerprints.
+- Accept weights-only-safe updater values and preserve the starting updater exemption after analysis edits.
+- Redact credentials inside nested escaped JSON, exception reprs and adjacent string fragments through the shared filter.
+- Restore legacy Accelerate raw optimizer checkpoints with one warning about missing OPAL programs and progress.
+- Preserve ordinary model names, identifiers, hashes, base64 code and credential-free URLs during redaction.
+- Bound noncontiguous parameter fingerprint copies by slicing before flattening.
+- Keep pending and unreported decision costs unknown in summaries and HTML until a numeric charge arrives.
+
+- Redact API keys and bearer tokens from backend diagnostics, decision records, prompts, logs and HTML reports.
+- Reject raw optimizer parameter-set changes after wrapping, before step or zero_grad (#5).
+- Reject GradScaler steps on wrappers combining multiple optimizers.
+- Include OPAL programs, versions and update counts in Accelerate save_state/load_state checkpoints.
+- Share one version source across package metadata, runtime, Codex client and provenance.
+- Update wrap docstrings for cost-budget stopping and the Codex backend.
+- Advance truncated loss-window indices and record omitted observation counts.
+- Settle cancelled decisions with a bounded wait and include late charges in reports.
+- Discard pending wake reasons when no further agent call can use them.
+- Reject unsupported or cyclic agent updater state before installation and checkpointing.
+- Compare ordered parameter bytes with SHA-256 in DDP consistency checks.
+
+- Resolve repository documentation from test files for non-editable installs.
+- Set tested direct dependency lower bounds and require Python 3.10 or newer.
+- Make the mailbox cancellation test use an instance-level wait.
+- Publish complete mailbox claims atomically so concurrent brokers cannot run the same request twice.
+- Use file rendezvous in the DDP crash-resume test to avoid ephemeral-port races.
+- Include docs, skills, examples and the changelog in the source distribution.
+- Add MNIST --max-cost-usd and --no-summarize flags.
+- Run CPU CI across Linux, macOS and supported Python versions, including direct dependency minima.
+
+## 0.3.4 (2026-10-21)
+
+- Stop agent calls when the remaining cost budget is below the estimated call cost (#6).
+- Apply the default waiting cap to the remaining schedule after early decisions, excluding agent waits from training time (#4).
+
+## 0.3.3 (2026-10-21)
+
+First public release.
+
+- `opal.wrap` turns a PyTorch optimizer into a reactive optimizer: a coding agent (Claude Code by default) reads the
+  training run and rewrites the update rule and its own analysis while the model trains.
+- Examples on CPU and one GPU, and the reproductions in the README (SiT-B/2, RAEv2-B, Goldfish, modded-nanogpt).
+- `opal report`, `opal show`, `opal estimate`, `opal doctor`; the Hugging Face Trainer through `opal.hf.OpalTrainer`.
+- An experimental Codex backend (`backend="codex"`).

opal_optimizer-0.3.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xingjian Bai, Jia-Hao Liang, Jayden Teoh, Vincent Sitzmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opal_optimizer-0.3.5/MANIFEST.in

@@ -0,0 +1,7 @@
+prune tests
+prune opal_runs
+graft docs
+graft skills
+graft examples
+include CHANGELOG.md
+global-exclude __pycache__ *.py[cod]

opal_optimizer-0.3.5/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: opal-optimizer
+Version: 0.3.5
+Summary: A coding agent inside your training run, rewriting the optimizer while it trains
+Author: Xingjian Bai, Jia-Hao Liang, Jayden Teoh, Vincent Sitzmann
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.5; python_version < "3.13"
+Requires-Dist: torch>=2.6; python_version >= "3.13"
+Requires-Dist: numpy>=1.26.4
+Provides-Extra: examples
+Requires-Dist: torchvision>=0.20; python_version < "3.13" and extra == "examples"
+Requires-Dist: torchvision>=0.21; python_version >= "3.13" and extra == "examples"
+Requires-Dist: numpy>=1.26.4; extra == "examples"
+Requires-Dist: pyarrow>=15.0; extra == "examples"
+Requires-Dist: pillow>=10.2; extra == "examples"
+Provides-Extra: test
+Requires-Dist: pytest>=8.2; extra == "test"
+Provides-Extra: hf
+Requires-Dist: transformers>=4.57.1; extra == "hf"
+Requires-Dist: accelerate>=1.4.0; extra == "hf"
+Dynamic: license-file
+
+
+<h1 align="center">OPAL: a reactive optimizer</h1>
+
+<p align="center"><b>A PyTorch optimizer wrapper that lets a coding agent change the optimizer while your model trains.</b></p>
+
+<p align="center">
+  <a href="https://xingjianbai.com/reactive-optimizers/">Blog post</a> ·
+  <a href="docs/GUIDE.md">Guide</a> ·
+  <a href="#start-with-your-coding-agent">Start with your agent</a> ·
+  <a href="examples/README.md">Examples</a>
+</p>
+
+Most networks are trained with an optimizer that is fixed before training starts. OPAL (OPtimizer with an Agent in
+the Loop) turns the optimizer into a program that an agent keeps rewriting during the run. You wrap your PyTorch
+optimizer in one line. Every so often the agent (Claude Code) reads what the run reports and decides whether to
+rewrite two small programs: the optimizer program, which turns gradients into updates at every step, and an analysis
+program, which measures whatever the agent wants to look at.
+
+The agent can change anything that can be written as optimizer code: the update rule of each parameter group, the
+learning rates and their schedules, momentum and β₂, preconditioning, clipping, guards against loss spikes. It is
+asked not to touch your model, data, loss, batch size, number of steps or evaluation. Its programs run inside your
+training process, so this is a rule, not a sandbox (see [Safety](docs/GUIDE.md#safety)). Until the agent changes
+something, the wrapped run is bit-for-bit the same as the plain one.
+
+## Start with your coding agent
+
+Clone this repository, open your own project in a coding agent (Claude Code, Codex, Cursor or similar) and paste this
+prompt. The agent installs OPAL, wires it into your training script, asks you what it cannot know, and checks that
+nothing changed before anything costs money.
+
+```text
+I want to train my model with OPAL, a reactive optimizer: a coding agent that rewrites the optimizer while the
+model trains. OPAL is cloned at <PATH TO OPAL>. Please set it up for this project:
+
+1. Read <PATH TO OPAL>/README.md and <PATH TO OPAL>/skills/train-with-agent/SKILL.md, and follow the skill. Do not
+   edit any file inside <PATH TO OPAL>; configure everything through opal.wrap arguments.
+2. Install OPAL into the Python environment this project trains with (pip install -e <PATH TO OPAL>), and
+   run `opal doctor` (free, offline) to check that torch and Claude Code are ready on the machine that will run
+   training; run `opal doctor --live` (one tiny paid agent call) only once I approve an agent run. If Claude Code is
+   missing or not logged in there, tell me what to run; do not log in for me.
+3. Find my training script and loop. Tell me what you found (optimizer, scheduler, number of steps, single GPU or
+   DDP, gradient clipping, mixed precision, checkpoints) and anything OPAL does not support.
+4. Ask me for the goal sentence: what the run trains and what it is judged by at the end. Do not invent the metric.
+5. Wrap the optimizer and show me the diff before running anything.
+6. Smoke test: about 100 steps unwrapped and 100 steps wrapped with backend="keep" (no agent, no cost); the losses
+   must match step for step. Show me both. If I only asked for a dry run, stop here.
+7. Before the real run, time an update in the smoke test and run `opal estimate --total-steps N --sec-per-step S`;
+   show me what it prints (how long training will wait for the agent, also as a multiple of the run's own time, and
+   the cost). Ask me for a cost cap (max_cost_usd) and how many times the agent should decide, and wait for my
+   go-ahead; then give me the exact command to launch it, and how to follow it (opal show, opal report).
+```
+
+## Start by hand
+
+```bash
+pip install opal-optimizer           # or: git clone, then pip install -e ".[examples]"
+opal doctor                          # torch and Claude Code ready?
+```
+
+The package is called `opal-optimizer` on PyPI, because `opal` there is an unrelated web framework. Both install as `import opal`, so do not install both.
+
+```python
+import torch, opal
+
+opt = torch.optim.AdamW(model.parameters(), lr=3e-4)                  # your optimizer, unchanged
+sched = torch.optim.lr_scheduler.CosineAnnealingLR(opt, T_max=steps)  # your scheduler, unchanged
+opt = opal.wrap(opt, model, scheduler=sched, total_steps=steps,
+                goal="ResNet-18 on CIFAR-10; judged by test accuracy after the last update",
+                backend="keep")    # a dry run: no agent, no cost. For the agent run, use max_cost_usd=20 instead.
+
+for step in range(steps):
+    loss = criterion(model(x), y)
+    loss.backward()
+    opt.step(loss=loss)                     # pass the loss so the agent sees it
+    opt.zero_grad()
+    sched.step()
+    if step % 500 == 0:
+        opt.log(test_acc=evaluate(model))   # recorded for you, not shown to the agent
+opt.close()
+```
+
+`goal` is one sentence: what you train and how it is judged. Then:
+
+```bash
+python train.py                                  # backend="keep": must match the plain run exactly
+opal doctor --live                               # one tiny agent call to check the setup
+opal estimate --total-steps 10000 --sec-per-step 0.05   # waiting time and cost, before you launch
+python train.py                                  # with max_cost_usd=20: the agent rewrites the optimizer
+opal show   opal_runs/<folder>                   # one line per decision
+opal report opal_runs/<folder>                   # one HTML page: loss, learning rates, rationales, code diffs
+```
+
+The guide shows how to check the keep run against your plain run byte for byte, and how to use the Hugging Face
+Trainer: [Try it without an agent](docs/GUIDE.md#try-it-without-an-agent).
+
+## Prerequisites
+
+- **A PyTorch training script** that uses `torch.optim` optimizers, on CPU, one GPU or several GPUs of one node (DDP).
+  Python 3.10 or newer, PyTorch 2.5 or newer (2.6 on Python 3.13).
+- **For an agent run, Claude Code, logged in on the machine that runs rank 0.** Install
+  [Claude Code](https://docs.claude.com/en/docs/claude-code), run `claude` once and log in with a Claude subscription
+  or an API key. The agent's usage is billed to that account. `max_cost_usd` caps it; there is no cap by default.
+  The short summaries of code changes in the report are not counted (`summarize=False` turns them off). A dry run
+  with `backend="keep"` needs neither and makes no model calls.
+- **No internet or no login on the GPU machine?** Run the agent on your laptop or a login node and connect it to the
+  training job through a shared folder (see [the mailbox broker](docs/GUIDE.md#gpu-machines-without-an-agent)).
+
+## Results
+
+Each number is one run, and each agent started from the task's own recipe:
+
+| Example | Measure | Official recipe | Reactive optimizer |
+|---|---|---|---|
+| SiT-B/2, ImageNet 256, 400K updates | FID-50K ↓ | 35.7 (our evaluator) | 23.6 |
+| RAEv2-B, ImageNet 256, 20 epochs | FID-50K ↓ | 3.39 | 3.10 (prompt asked for efficiency), 3.46 (neutral prompt); rerun on OPAL 0.3: 3.19 |
+| Goldfish 125M GPT, Swahili | FLORES-200 bits ↓ | 79.37 | 77.60; rerun on OPAL 0.3: 77.25 |
+| modded-nanogpt record #36 | validation loss ↓ | 3.2781 | 3.2749 |
+| LightningDiT-B/1, ImageNet 256, 160 epochs | FID-50K ↓ (with guidance) | 3.22 | rerun on OPAL 0.3: 2.31 |
+
+It does not always help: a run of modded-nanogpt on OPAL 0.2.0 ended at 3.2878, worse than record #36. Your
+numbers may also differ from ours, because the agent can choose differently from one run to the next. The
+[examples page](examples/README.md) has every number with its version, hardware, time and cost, the small CPU and
+one-GPU scripts, and how to rerun each setting.
+
+Our run records and final weights are on Hugging Face: [snow-leopard/opal-results](https://huggingface.co/datasets/snow-leopard/opal-results).
+
+## How it works
+
+```
+ training script ──grads──▶ updater.py ──▶ parameters        (every step, every rank)
+        │                      ▲
+        └──observations──▶ analysis.py ──reports──▶ agent    (rank 0, every `every` steps / at decisions)
+                               ▲                      │
+                               └──── new programs ◀───┘      (at decision points)
+```
+
+- **Two programs.** `updater.py` starts as a call to your own optimizer and scheduler. `analysis.py` starts with a few
+  statistics of the loss and the gradients. The agent edits both in `opal_runs/<folder>/workspace/`.
+- **One conversation for the whole run.** The agent remembers what it tried, what it predicted and what happened. Each
+  decision ends with a short rationale: what it saw, what it changed and what it expects.
+- **Safe swaps.** A new optimizer program takes over at the next step, on every GPU at once, and runs on trial for 20
+  steps. If it raises an error, the run goes back to the previous program. A failure at its first step is undone
+  exactly when a copy of the parameters and optimizer state fits in `snapshot_limit_gb` (default 2); a later failure
+  is not undone, and the agent is told. Every version is kept in `programs/`.
+- **Training waits for the agent by default.** With `blocking=False` training keeps going while the agent thinks, and
+  `"auto"` waits only when an edit would land too late. Both are faster, and noisier.
+- **What the agent sees.** Your goal sentence, the names and shapes of the parameters, the training losses, its own
+  analysis reports, and read-only copies of your training script and model code (`share_code=False` keeps them out).
+  Values you log are only recorded, unless you pass `show_agent=True`. With `validation=N` it also sees the
+  development-set values you report with `opt.report_dev(...)`.
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `decisions` | see right | How many times the agent is asked. Each time it may also keep everything as it is. If you do not set it, a run that waits for the agent asks at most as many times as keep the waiting under 4× the run's own training time (`opal estimate` shows the number), and at most 50. If you set it, that cap is off. A fifth of the decisions fall in the first 5% of the run; `schedule="uniform"` spaces them evenly. More in the [guide](docs/GUIDE.md#cost-and-limits). |
+| `every` | 50 | Steps between checks: losses are read, a non-finite loss is caught, the analysis program runs. |
+| `blocking` | `True` | `False` or `"auto"` to keep training while the agent thinks. |
+| `max_cost_usd` | none | Stop asking the agent once it has spent this much. |
+| `backend_options` | `{}` | `model=` (default `claude-opus-5-5`), `effort=` (default `high`) and `timeout=`. A failed agent turn is retried with growing pauses; an agent that is unavailable (login, usage limit, outage) is waited for, with no deadline unless you set `unavailable_timeout=`. Details in the [guide](docs/GUIDE.md#cost-and-limits). |
+| `prompt` | `"neutral"` | The agent's instructions: the facts of the run and the protocol, with no recommended values. `"aggressive"` adds a review of every group's hyperparameters at each decision. You can also pass the path of your own template. |
+| `validation` | none | `N`: your script evaluates a held-out development set about every N updates, at times it does not announce, and reports it with `opt.report_dev(loss=..., accuracy=...)`. The agent sees each result. See the [guide](docs/GUIDE.md#what-it-can-and-cannot-change). |
+| `eval_integrity` | on with `validation` | Flags a run whose program moves the parameters somewhere else for an evaluation and back afterwards. The agent is not told. |
+
+Gradient accumulation, GradScaler, checkpoints and resume, DDP, GPU machines without internet, privacy and cost are
+covered in the [guide](docs/GUIDE.md).
+
+### Experimental Codex backend
+
+Claude is the default. To use Codex, pass `backend="codex", backend_options=dict(model="gpt-6.1-sol", effort="high")`
+(`xhigh` works too), or run `opal broker <box> --backend codex --model gpt-6.1-sol --effort high`. Log in separately
+with `CODEX_HOME=~/.codex-opal codex login --device-auth`, and do not copy or link the `auth.json` of your default
+Codex home. `max_cost_usd` does not cap Codex; `backend_options=dict(max_tokens=N)` is a soft token cap that a turn
+in progress can exceed. The run stops with an error if Codex compacts the conversation (around 450k tokens of context
+with Codex CLI 0.160.1).
+
+## Tests
+
+The whole test suite runs on CPU with no agent and no cost: `pip install -e ".[examples,test,hf]"`, then `pytest -q`. It
+takes a few minutes on a laptop. Three tests are skipped unless you set `OPAL_REAL_CLI=1`; they start the real Claude
+Code CLI against a local mock.
+
+## Status and limitations
+
+v0.3.5, under active development. Tested on one GPU and on DDP within one node (NCCL, eager and `torch.compile`).
+Multi-node, FSDP and DeepSpeed are not supported. Accelerate works if you wrap after `accelerator.prepare`, without
+fp16 GradScaler or Accelerate's gradient accumulation; the HF Trainer works through `opal.hf.OpalTrainer`. Both are
+tested on CPU. Lightning should work through `opt.observe(loss)` but we have not tried it. The agent can make a run
+worse: it cannot restart or roll back training, it can only fix its programs at the next decision.
+
+## Citation
+
+```bibtex
+@misc{bai2026reactive,
+  title  = {Reactive Optimizers},
+  author = {Bai, Xingjian and Liang, Jia-Hao and Teoh, Jayden and Sitzmann, Vincent},
+  year   = {2026},
+  month  = {oct},
+  note   = {Blog post}
+}
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+*The name:* OPAL stands for OPtimizer with an Agent in the Loop.

opal_optimizer-0.3.5/README.md

@@ -0,0 +1,207 @@
+
+<h1 align="center">OPAL: a reactive optimizer</h1>
+
+<p align="center"><b>A PyTorch optimizer wrapper that lets a coding agent change the optimizer while your model trains.</b></p>
+
+<p align="center">
+  <a href="https://xingjianbai.com/reactive-optimizers/">Blog post</a> ·
+  <a href="docs/GUIDE.md">Guide</a> ·
+  <a href="#start-with-your-coding-agent">Start with your agent</a> ·
+  <a href="examples/README.md">Examples</a>
+</p>
+
+Most networks are trained with an optimizer that is fixed before training starts. OPAL (OPtimizer with an Agent in
+the Loop) turns the optimizer into a program that an agent keeps rewriting during the run. You wrap your PyTorch
+optimizer in one line. Every so often the agent (Claude Code) reads what the run reports and decides whether to
+rewrite two small programs: the optimizer program, which turns gradients into updates at every step, and an analysis
+program, which measures whatever the agent wants to look at.
+
+The agent can change anything that can be written as optimizer code: the update rule of each parameter group, the
+learning rates and their schedules, momentum and β₂, preconditioning, clipping, guards against loss spikes. It is
+asked not to touch your model, data, loss, batch size, number of steps or evaluation. Its programs run inside your
+training process, so this is a rule, not a sandbox (see [Safety](docs/GUIDE.md#safety)). Until the agent changes
+something, the wrapped run is bit-for-bit the same as the plain one.
+
+## Start with your coding agent
+
+Clone this repository, open your own project in a coding agent (Claude Code, Codex, Cursor or similar) and paste this
+prompt. The agent installs OPAL, wires it into your training script, asks you what it cannot know, and checks that
+nothing changed before anything costs money.
+
+```text
+I want to train my model with OPAL, a reactive optimizer: a coding agent that rewrites the optimizer while the
+model trains. OPAL is cloned at <PATH TO OPAL>. Please set it up for this project:
+
+1. Read <PATH TO OPAL>/README.md and <PATH TO OPAL>/skills/train-with-agent/SKILL.md, and follow the skill. Do not
+   edit any file inside <PATH TO OPAL>; configure everything through opal.wrap arguments.
+2. Install OPAL into the Python environment this project trains with (pip install -e <PATH TO OPAL>), and
+   run `opal doctor` (free, offline) to check that torch and Claude Code are ready on the machine that will run
+   training; run `opal doctor --live` (one tiny paid agent call) only once I approve an agent run. If Claude Code is
+   missing or not logged in there, tell me what to run; do not log in for me.
+3. Find my training script and loop. Tell me what you found (optimizer, scheduler, number of steps, single GPU or
+   DDP, gradient clipping, mixed precision, checkpoints) and anything OPAL does not support.
+4. Ask me for the goal sentence: what the run trains and what it is judged by at the end. Do not invent the metric.
+5. Wrap the optimizer and show me the diff before running anything.
+6. Smoke test: about 100 steps unwrapped and 100 steps wrapped with backend="keep" (no agent, no cost); the losses
+   must match step for step. Show me both. If I only asked for a dry run, stop here.
+7. Before the real run, time an update in the smoke test and run `opal estimate --total-steps N --sec-per-step S`;
+   show me what it prints (how long training will wait for the agent, also as a multiple of the run's own time, and
+   the cost). Ask me for a cost cap (max_cost_usd) and how many times the agent should decide, and wait for my
+   go-ahead; then give me the exact command to launch it, and how to follow it (opal show, opal report).
+```
+
+## Start by hand
+
+```bash
+pip install opal-optimizer           # or: git clone, then pip install -e ".[examples]"
+opal doctor                          # torch and Claude Code ready?
+```
+
+The package is called `opal-optimizer` on PyPI, because `opal` there is an unrelated web framework. Both install as `import opal`, so do not install both.
+
+```python
+import torch, opal
+
+opt = torch.optim.AdamW(model.parameters(), lr=3e-4)                  # your optimizer, unchanged
+sched = torch.optim.lr_scheduler.CosineAnnealingLR(opt, T_max=steps)  # your scheduler, unchanged
+opt = opal.wrap(opt, model, scheduler=sched, total_steps=steps,
+                goal="ResNet-18 on CIFAR-10; judged by test accuracy after the last update",
+                backend="keep")    # a dry run: no agent, no cost. For the agent run, use max_cost_usd=20 instead.
+
+for step in range(steps):
+    loss = criterion(model(x), y)
+    loss.backward()
+    opt.step(loss=loss)                     # pass the loss so the agent sees it
+    opt.zero_grad()
+    sched.step()
+    if step % 500 == 0:
+        opt.log(test_acc=evaluate(model))   # recorded for you, not shown to the agent
+opt.close()
+```
+
+`goal` is one sentence: what you train and how it is judged. Then:
+
+```bash
+python train.py                                  # backend="keep": must match the plain run exactly
+opal doctor --live                               # one tiny agent call to check the setup
+opal estimate --total-steps 10000 --sec-per-step 0.05   # waiting time and cost, before you launch
+python train.py                                  # with max_cost_usd=20: the agent rewrites the optimizer
+opal show   opal_runs/<folder>                   # one line per decision
+opal report opal_runs/<folder>                   # one HTML page: loss, learning rates, rationales, code diffs
+```
+
+The guide shows how to check the keep run against your plain run byte for byte, and how to use the Hugging Face
+Trainer: [Try it without an agent](docs/GUIDE.md#try-it-without-an-agent).
+
+## Prerequisites
+
+- **A PyTorch training script** that uses `torch.optim` optimizers, on CPU, one GPU or several GPUs of one node (DDP).
+  Python 3.10 or newer, PyTorch 2.5 or newer (2.6 on Python 3.13).
+- **For an agent run, Claude Code, logged in on the machine that runs rank 0.** Install
+  [Claude Code](https://docs.claude.com/en/docs/claude-code), run `claude` once and log in with a Claude subscription
+  or an API key. The agent's usage is billed to that account. `max_cost_usd` caps it; there is no cap by default.
+  The short summaries of code changes in the report are not counted (`summarize=False` turns them off). A dry run
+  with `backend="keep"` needs neither and makes no model calls.
+- **No internet or no login on the GPU machine?** Run the agent on your laptop or a login node and connect it to the
+  training job through a shared folder (see [the mailbox broker](docs/GUIDE.md#gpu-machines-without-an-agent)).
+
+## Results
+
+Each number is one run, and each agent started from the task's own recipe:
+
+| Example | Measure | Official recipe | Reactive optimizer |
+|---|---|---|---|
+| SiT-B/2, ImageNet 256, 400K updates | FID-50K ↓ | 35.7 (our evaluator) | 23.6 |
+| RAEv2-B, ImageNet 256, 20 epochs | FID-50K ↓ | 3.39 | 3.10 (prompt asked for efficiency), 3.46 (neutral prompt); rerun on OPAL 0.3: 3.19 |
+| Goldfish 125M GPT, Swahili | FLORES-200 bits ↓ | 79.37 | 77.60; rerun on OPAL 0.3: 77.25 |
+| modded-nanogpt record #36 | validation loss ↓ | 3.2781 | 3.2749 |
+| LightningDiT-B/1, ImageNet 256, 160 epochs | FID-50K ↓ (with guidance) | 3.22 | rerun on OPAL 0.3: 2.31 |
+
+It does not always help: a run of modded-nanogpt on OPAL 0.2.0 ended at 3.2878, worse than record #36. Your
+numbers may also differ from ours, because the agent can choose differently from one run to the next. The
+[examples page](examples/README.md) has every number with its version, hardware, time and cost, the small CPU and
+one-GPU scripts, and how to rerun each setting.
+
+Our run records and final weights are on Hugging Face: [snow-leopard/opal-results](https://huggingface.co/datasets/snow-leopard/opal-results).
+
+## How it works
+
+```
+ training script ──grads──▶ updater.py ──▶ parameters        (every step, every rank)
+        │                      ▲
+        └──observations──▶ analysis.py ──reports──▶ agent    (rank 0, every `every` steps / at decisions)
+                               ▲                      │
+                               └──── new programs ◀───┘      (at decision points)
+```
+
+- **Two programs.** `updater.py` starts as a call to your own optimizer and scheduler. `analysis.py` starts with a few
+  statistics of the loss and the gradients. The agent edits both in `opal_runs/<folder>/workspace/`.
+- **One conversation for the whole run.** The agent remembers what it tried, what it predicted and what happened. Each
+  decision ends with a short rationale: what it saw, what it changed and what it expects.
+- **Safe swaps.** A new optimizer program takes over at the next step, on every GPU at once, and runs on trial for 20
+  steps. If it raises an error, the run goes back to the previous program. A failure at its first step is undone
+  exactly when a copy of the parameters and optimizer state fits in `snapshot_limit_gb` (default 2); a later failure
+  is not undone, and the agent is told. Every version is kept in `programs/`.
+- **Training waits for the agent by default.** With `blocking=False` training keeps going while the agent thinks, and
+  `"auto"` waits only when an edit would land too late. Both are faster, and noisier.
+- **What the agent sees.** Your goal sentence, the names and shapes of the parameters, the training losses, its own
+  analysis reports, and read-only copies of your training script and model code (`share_code=False` keeps them out).
+  Values you log are only recorded, unless you pass `show_agent=True`. With `validation=N` it also sees the
+  development-set values you report with `opt.report_dev(...)`.
+
+## Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `decisions` | see right | How many times the agent is asked. Each time it may also keep everything as it is. If you do not set it, a run that waits for the agent asks at most as many times as keep the waiting under 4× the run's own training time (`opal estimate` shows the number), and at most 50. If you set it, that cap is off. A fifth of the decisions fall in the first 5% of the run; `schedule="uniform"` spaces them evenly. More in the [guide](docs/GUIDE.md#cost-and-limits). |
+| `every` | 50 | Steps between checks: losses are read, a non-finite loss is caught, the analysis program runs. |
+| `blocking` | `True` | `False` or `"auto"` to keep training while the agent thinks. |
+| `max_cost_usd` | none | Stop asking the agent once it has spent this much. |
+| `backend_options` | `{}` | `model=` (default `claude-opus-5-5`), `effort=` (default `high`) and `timeout=`. A failed agent turn is retried with growing pauses; an agent that is unavailable (login, usage limit, outage) is waited for, with no deadline unless you set `unavailable_timeout=`. Details in the [guide](docs/GUIDE.md#cost-and-limits). |
+| `prompt` | `"neutral"` | The agent's instructions: the facts of the run and the protocol, with no recommended values. `"aggressive"` adds a review of every group's hyperparameters at each decision. You can also pass the path of your own template. |
+| `validation` | none | `N`: your script evaluates a held-out development set about every N updates, at times it does not announce, and reports it with `opt.report_dev(loss=..., accuracy=...)`. The agent sees each result. See the [guide](docs/GUIDE.md#what-it-can-and-cannot-change). |
+| `eval_integrity` | on with `validation` | Flags a run whose program moves the parameters somewhere else for an evaluation and back afterwards. The agent is not told. |
+
+Gradient accumulation, GradScaler, checkpoints and resume, DDP, GPU machines without internet, privacy and cost are
+covered in the [guide](docs/GUIDE.md).
+
+### Experimental Codex backend
+
+Claude is the default. To use Codex, pass `backend="codex", backend_options=dict(model="gpt-6.1-sol", effort="high")`
+(`xhigh` works too), or run `opal broker <box> --backend codex --model gpt-6.1-sol --effort high`. Log in separately
+with `CODEX_HOME=~/.codex-opal codex login --device-auth`, and do not copy or link the `auth.json` of your default
+Codex home. `max_cost_usd` does not cap Codex; `backend_options=dict(max_tokens=N)` is a soft token cap that a turn
+in progress can exceed. The run stops with an error if Codex compacts the conversation (around 450k tokens of context
+with Codex CLI 0.160.1).
+
+## Tests
+
+The whole test suite runs on CPU with no agent and no cost: `pip install -e ".[examples,test,hf]"`, then `pytest -q`. It
+takes a few minutes on a laptop. Three tests are skipped unless you set `OPAL_REAL_CLI=1`; they start the real Claude
+Code CLI against a local mock.
+
+## Status and limitations
+
+v0.3.5, under active development. Tested on one GPU and on DDP within one node (NCCL, eager and `torch.compile`).
+Multi-node, FSDP and DeepSpeed are not supported. Accelerate works if you wrap after `accelerator.prepare`, without
+fp16 GradScaler or Accelerate's gradient accumulation; the HF Trainer works through `opal.hf.OpalTrainer`. Both are
+tested on CPU. Lightning should work through `opt.observe(loss)` but we have not tried it. The agent can make a run
+worse: it cannot restart or roll back training, it can only fix its programs at the next decision.
+
+## Citation
+
+```bibtex
+@misc{bai2026reactive,
+  title  = {Reactive Optimizers},
+  author = {Bai, Xingjian and Liang, Jia-Hao and Teoh, Jayden and Sitzmann, Vincent},
+  year   = {2026},
+  month  = {oct},
+  note   = {Blog post}
+}
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).
+
+*The name:* OPAL stands for OPtimizer with an Agent in the Loop.