opal-optimizer 0.3.5__tar.gz → 0.3.7__tar.gz

{opal_optimizer-0.3.5 → opal_optimizer-0.3.7}/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.3.7 (2026-10-22)
+
+- Documentation and examples only, apart from one printed notice; the optimizer math, the agent prompt and the agent's tools are unchanged.
+- The README and the examples page report each task's newest OPAL run (RAEv2-B 3.19, Goldfish 77.25, LightningDiT-B/1 2.31) and no longer list older-system numbers.
+- The examples page has a section on training without waiting for the agent (`blocking=False`), with the RAEv2-B official, blocking and non-blocking runs.
+- The README says why long runs suit OPAL, with measured waiting times.
+- `blocking="auto"` is no longer documented or offered by the example scripts. Using it prints that it is experimental and untested on real training runs.
+
+## 0.3.6 (2026-10-22)
+
+- Fixes from a from-scratch test of the install and the agent prompt; the optimizer math, the agent prompt and the agent's tools are unchanged.
+- `opal doctor` says when the machine has an NVIDIA GPU that the installed torch cannot use; the README explains how to install the torch build for the driver first.
+- The ssh mailbox broker explains a "Permission denied" from a host that asks for a password, and the guide and skill show how to share one connection.
+- `opal estimate` no longer offers a decision count that still waits more than 4x, and says when training ends before the first answer.
+- The report records the training waiting time for user scripts.
+- The privacy filter keeps numbers such as `/1000`.
+- The PyPI page links to the repository, the guide and the blog post, and README links work outside GitHub.
+
 ## 0.3.5 (2026-10-21)
 
 - Reject uneven DDP inputs on every rank through the optimizer's Joinable interface instead of hanging (#2).

{opal_optimizer-0.3.5/opal_optimizer.egg-info → opal_optimizer-0.3.7}/PKG-INFO

@@ -1,9 +1,12 @@
 Metadata-Version: 2.4
 Name: opal-optimizer
-Version: 0.3.5
+Version: 0.3.7
 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
+Project-URL: Homepage, https://github.com/xingjian-bai/opal
+Project-URL: Documentation, https://github.com/xingjian-bai/opal/blob/main/docs/GUIDE.md
+Project-URL: Blog post, https://xingjianbai.com/reactive-optimizers/
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -30,9 +33,9 @@ Dynamic: license-file
 
 <p align="center">
   <a href="https://xingjianbai.com/reactive-optimizers/">Blog post</a> ·
-  <a href="docs/GUIDE.md">Guide</a> ·
+  <a href="https://github.com/xingjian-bai/opal/blob/main/docs/GUIDE.md">Guide</a> ·
   <a href="#start-with-your-coding-agent">Start with your agent</a> ·
-  <a href="examples/README.md">Examples</a>
+  <a href="https://github.com/xingjian-bai/opal/blob/main/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
@@ -44,22 +47,22 @@ 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
+training process, so this is a rule, not a sandbox (see [Safety](https://github.com/xingjian-bai/opal/blob/main/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.
+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:
+model trains. Its docs are at https://github.com/xingjian-bai/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
+1. Read the README there and skills/train-with-agent/SKILL.md, and follow the skill. Do not edit OPAL's own files;
+   configure everything through opal.wrap arguments.
+2. Install OPAL into the Python environment this project trains with (pip install opal-optimizer), 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.
@@ -71,8 +74,9 @@ model trains. OPAL is cloned at <PATH TO OPAL>. Please set it up for this projec
    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).
+   the cost). Ask me for a cost cap (max_cost_usd); leave decisions unset unless I ask, so that the waiting stays
+   within 4x the run's own time. 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
@@ -84,6 +88,11 @@ 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.
 
+On a GPU machine, install OPAL into the environment you already train with, or install the PyTorch build for your
+driver first ([pytorch.org](https://pytorch.org/get-started/locally/)). In an empty environment, `pip install
+opal-optimizer` pulls the newest torch from PyPI, which may need a newer NVIDIA driver; `opal doctor` then shows
+`CUDA available: False`.
+
 ```python
 import torch, opal
 
@@ -115,8 +124,11 @@ opal show   opal_runs/<folder>                   # one line per decision
 opal report opal_runs/<folder>                   # one HTML page: loss, learning rates, rationales, code diffs
 ```
 
+Each wrapped run prints a `profiler_start` / `profiler_stop` pair on stderr when a program starts: OPAL audits one
+update of each new program. It is harmless.
+
 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).
+Trainer: [Try it without an agent](https://github.com/xingjian-bai/opal/blob/main/docs/GUIDE.md#try-it-without-an-agent).
 
 ## Prerequisites
 
@@ -128,7 +140,7 @@ Trainer: [Try it without an agent](docs/GUIDE.md#try-it-without-an-agent).
   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)).
+  training job through a mailbox folder, over ssh or a shared filesystem (see [the mailbox broker](https://github.com/xingjian-bai/opal/blob/main/docs/GUIDE.md#gpu-machines-without-an-agent)).
 
 ## Results
 
@@ -137,16 +149,24 @@ 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 |
+| RAEv2-B, ImageNet 256, 20 epochs | FID-50K ↓ | 3.39 | 3.19 |
+| Goldfish 125M GPT, Swahili | FLORES-200 bits ↓ | 79.37 | 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 |
+| LightningDiT-B/1, ImageNet 256, 160 epochs | FID-50K ↓ (with guidance) | 3.22 | 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
+[examples page](https://github.com/xingjian-bai/opal/blob/main/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.
 
+**Long runs suit it best.** An agent decision takes about the same time in any run, about 40 s on average in ours,
+so the waiting adds up to a roughly fixed cost. In our runs of several hours it came to 0.49 h of 3.75 h on RAEv2-B,
+0.67 h of 5.65 h on Goldfish and 1.05 h of 11.2 h on SiT-B/2. In short runs it dominates: our one-GPU scripts, which
+set 50 decisions, took 27 to 31 min with the agent against 1 to 3 min without, and with `blocking=False` they ended
+before the first answer arrived. The small scripts are a quick way to try OPAL. If you have the compute, use it on runs
+of a few hours or more, where `blocking=False` also
+[kept the result](https://github.com/xingjian-bai/opal/blob/main/examples/README.md#training-without-waiting-for-the-agent).
+
 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
@@ -167,8 +187,8 @@ Our run records and final weights are on Hugging Face: [snow-leopard/opal-result
   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.
+- **Training waits for the agent by default.** With `blocking=False` training keeps going while the agent thinks. That is
+  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
@@ -178,17 +198,17 @@ Our run records and final weights are on Hugging Face: [snow-leopard/opal-result
 
 | 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). |
+| `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, but at least once, even when one decision already waits longer than that. 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](https://github.com/xingjian-bai/opal/blob/main/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. |
+| `blocking` | `True` | `False` 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). |
+| `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](https://github.com/xingjian-bai/opal/blob/main/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). |
+| `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](https://github.com/xingjian-bai/opal/blob/main/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).
+covered in the [guide](https://github.com/xingjian-bai/opal/blob/main/docs/GUIDE.md).
 
 ### Experimental Codex backend
 
@@ -207,7 +227,7 @@ 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`).
+v0.3.7, 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
@@ -227,6 +247,6 @@ worse: it cannot restart or roll back training, it can only fix its programs at
 
 ## License
 
-MIT, see [LICENSE](LICENSE).
+MIT, see [LICENSE](https://github.com/xingjian-bai/opal/blob/main/LICENSE).
 
 *The name:* OPAL stands for OPtimizer with an Agent in the Loop.

{opal_optimizer-0.3.5 → opal_optimizer-0.3.7}/README.md

@@ -5,9 +5,9 @@
 
 <p align="center">
   <a href="https://xingjianbai.com/reactive-optimizers/">Blog post</a> ·
-  <a href="docs/GUIDE.md">Guide</a> ·
+  <a href="https://github.com/xingjian-bai/opal/blob/main/docs/GUIDE.md">Guide</a> ·
   <a href="#start-with-your-coding-agent">Start with your agent</a> ·
-  <a href="examples/README.md">Examples</a>
+  <a href="https://github.com/xingjian-bai/opal/blob/main/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
@@ -19,22 +19,22 @@ 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
+training process, so this is a rule, not a sandbox (see [Safety](https://github.com/xingjian-bai/opal/blob/main/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.
+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:
+model trains. Its docs are at https://github.com/xingjian-bai/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
+1. Read the README there and skills/train-with-agent/SKILL.md, and follow the skill. Do not edit OPAL's own files;
+   configure everything through opal.wrap arguments.
+2. Install OPAL into the Python environment this project trains with (pip install opal-optimizer), 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.
@@ -46,8 +46,9 @@ model trains. OPAL is cloned at <PATH TO OPAL>. Please set it up for this projec
    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).
+   the cost). Ask me for a cost cap (max_cost_usd); leave decisions unset unless I ask, so that the waiting stays
+   within 4x the run's own time. 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
@@ -59,6 +60,11 @@ 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.
 
+On a GPU machine, install OPAL into the environment you already train with, or install the PyTorch build for your
+driver first ([pytorch.org](https://pytorch.org/get-started/locally/)). In an empty environment, `pip install
+opal-optimizer` pulls the newest torch from PyPI, which may need a newer NVIDIA driver; `opal doctor` then shows
+`CUDA available: False`.
+
 ```python
 import torch, opal
 
@@ -90,8 +96,11 @@ opal show   opal_runs/<folder>                   # one line per decision
 opal report opal_runs/<folder>                   # one HTML page: loss, learning rates, rationales, code diffs
 ```
 
+Each wrapped run prints a `profiler_start` / `profiler_stop` pair on stderr when a program starts: OPAL audits one
+update of each new program. It is harmless.
+
 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).
+Trainer: [Try it without an agent](https://github.com/xingjian-bai/opal/blob/main/docs/GUIDE.md#try-it-without-an-agent).
 
 ## Prerequisites
 
@@ -103,7 +112,7 @@ Trainer: [Try it without an agent](docs/GUIDE.md#try-it-without-an-agent).
   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)).
+  training job through a mailbox folder, over ssh or a shared filesystem (see [the mailbox broker](https://github.com/xingjian-bai/opal/blob/main/docs/GUIDE.md#gpu-machines-without-an-agent)).
 
 ## Results
 
@@ -112,16 +121,24 @@ 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 |
+| RAEv2-B, ImageNet 256, 20 epochs | FID-50K ↓ | 3.39 | 3.19 |
+| Goldfish 125M GPT, Swahili | FLORES-200 bits ↓ | 79.37 | 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 |
+| LightningDiT-B/1, ImageNet 256, 160 epochs | FID-50K ↓ (with guidance) | 3.22 | 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
+[examples page](https://github.com/xingjian-bai/opal/blob/main/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.
 
+**Long runs suit it best.** An agent decision takes about the same time in any run, about 40 s on average in ours,
+so the waiting adds up to a roughly fixed cost. In our runs of several hours it came to 0.49 h of 3.75 h on RAEv2-B,
+0.67 h of 5.65 h on Goldfish and 1.05 h of 11.2 h on SiT-B/2. In short runs it dominates: our one-GPU scripts, which
+set 50 decisions, took 27 to 31 min with the agent against 1 to 3 min without, and with `blocking=False` they ended
+before the first answer arrived. The small scripts are a quick way to try OPAL. If you have the compute, use it on runs
+of a few hours or more, where `blocking=False` also
+[kept the result](https://github.com/xingjian-bai/opal/blob/main/examples/README.md#training-without-waiting-for-the-agent).
+
 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
@@ -142,8 +159,8 @@ Our run records and final weights are on Hugging Face: [snow-leopard/opal-result
   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.
+- **Training waits for the agent by default.** With `blocking=False` training keeps going while the agent thinks. That is
+  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
@@ -153,17 +170,17 @@ Our run records and final weights are on Hugging Face: [snow-leopard/opal-result
 
 | 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). |
+| `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, but at least once, even when one decision already waits longer than that. 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](https://github.com/xingjian-bai/opal/blob/main/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. |
+| `blocking` | `True` | `False` 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). |
+| `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](https://github.com/xingjian-bai/opal/blob/main/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). |
+| `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](https://github.com/xingjian-bai/opal/blob/main/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).
+covered in the [guide](https://github.com/xingjian-bai/opal/blob/main/docs/GUIDE.md).
 
 ### Experimental Codex backend
 
@@ -182,7 +199,7 @@ 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`).
+v0.3.7, 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
@@ -202,6 +219,6 @@ worse: it cannot restart or roll back training, it can only fix its programs at
 
 ## License
 
-MIT, see [LICENSE](LICENSE).
+MIT, see [LICENSE](https://github.com/xingjian-bai/opal/blob/main/LICENSE).
 
 *The name:* OPAL stands for OPtimizer with an Agent in the Loop.

{opal_optimizer-0.3.5 → opal_optimizer-0.3.7}/docs/GUIDE.md

@@ -32,9 +32,8 @@ The picture shows `blocking=False`. With the default `blocking=True`, every rank
 - A new program takes over at the next update boundary. On one GPU this happens at once. In DDP, rank 0 announces
   it through an asynchronous broadcast every `sync_every` updates on a separate gloo group. The default is 20.
   Every rank swaps at the same update.
-- With `blocking=True`, all ranks wait at every decision, as in our published runs. With `blocking="auto"`, they wait
-  at decisions whose answers would arrive late, as described below. With `blocking=False`, they wait only once when
-  the loss turns non-finite. Waiting uses the gloo group, so a long agent turn does not trip an NCCL timeout.
+- With `blocking=True`, all ranks wait at every decision, as in most of our published runs. With `blocking=False`, they wait
+  only once when the loss turns non-finite. Waiting uses the gloo group, so a long agent turn does not trip an NCCL timeout.
 - A new updater runs on trial for `trial_steps` updates, by default 20. If it raises on any rank, every rank returns
   to the previous updater. The fallback is the last updater that passed its trial, or the starting one.
   An updater replaced during its trial does not become the fallback.
@@ -252,8 +251,7 @@ asked so far.
 | `max_cost_usd` | none | Stop asking once Claude Code reports this spend. Checked before each decision. The Claude backend also caps each decision at the remainder with `--max-budget-usd`, which can overshoot by one model call. `backend_options=dict(max_budget_usd=...)` caps each decision. |
 | `every` | 50 | Updates between checks. Decisions and the non-finite check happen at checks. |
 | `backend_options` | `{}` | `model=` defaults to `claude-opus-5-5`, `effort=` to `high`, as in the blog's runs. Another model or effort prints a warning at the start that the blog's results may differ. `timeout=` is seconds per decision, default 3600. `shell_timeout=` is seconds per agent shell command. `max_budget_usd=` caps each decision through Claude Code's `--max-budget-usd`. It can overshoot by one model call. `retries=` retries a failed turn, such as a tool crash, from the programs it started with. Pauses start at `backoff=15` s and double up to `backoff_max=600` s while `timeout` allows. `None`, the default, retries as often as that allows. `0` never retries. Each failure's error goes to the run's log, `decisions/NNN/attempts.jsonl` and the broker's log. The broker flag is `opal broker --retries N`. An unavailable agent has a separate wait, described below. `unavailable_timeout=` sets its deadline. |
-| `blocking` | True | Training waits for each decision, as in our published runs. False keeps training. "auto" waits at the first decision and when an answer would arrive more than `max_lag_updates` updates late. |
-| `max_lag_updates` | 50 | With `blocking="auto"`, the predicted lag in updates above which training waits. |
+| `blocking` | True | Training waits for each decision, as in most of our published runs. False keeps training. |
 | `share_code` | True | False keeps the training script and source files out of the agent's folder. |
 | `schedule` | "front" | When decisions are asked. The learning-rate schedule is `scheduler`. "front" puts a fifth evenly over the first 5% of training and the rest evenly over the remainder. "uniform" asks every total_steps // decisions updates. Segments such as `[(0.05, 20), (1.0, 30)]` give an end fraction and count: here 20 in the first 5%, then 30 over the rest. Update numbers such as `[500, 1000, 5000]` give the exact updates. A list sets the count: omit `decisions` or make it agree, or `wrap` raises. Each decision moves to the next check, every `every` updates. Two on one check merge. None falls in the last `every` updates. The first log line gives the remaining count. |
 | `show_next_decision` | on with the neutral and aggressive prompts | True gives the next scheduled decision's update in each message. False turns it off. |
@@ -295,15 +293,10 @@ No new decision is asked meanwhile. A failed turn, such as a crash, time limit o
 instead of the unavailable-agent wait.
 
 By default, `blocking=True` waits for the answer at each decision. Its edit takes effect from the update where the
-decision was asked, and the agent's thinking adds to wall time. `blocking=False` and `blocking="auto"` allow faster
+decision was asked, and the agent's thinking adds to wall time. `blocking=False` allows faster
 runs. Without waiting, an answer takes effect answer time / time per update updates after the state the agent saw.
 No new decision is asked while one is in progress, so fast runs may ask far fewer times.
 
-`blocking="auto"` waits when the answer would arrive more than `max_lag_updates` updates late, by default 50.
-It divides the median of the last 5 answer times by the time per update. That update time is the median over the last
-5 check intervals, excluding pauses. It always waits at the first decision.
-Each choice, its reason and its lag are in `events.jsonl` and the report.
-
 ## The report
 
 Each run keeps `report.html` in its folder. It shows the loss with a tick per decision, your `opt.log` values,
@@ -328,7 +321,7 @@ Private locations and recorded identities are omitted from messages, code and pl
 calls.
 
 Cached descriptions and tags come from Claude Opus at low effort through the Claude Code CLI, with no tools.
-One call per code change costs about a cent. It is recorded in `decisions/NNN/summary.json` and excluded from
+One call per code change costs a few cents ($0.02 to $0.06 in our checks). It is recorded in `decisions/NNN/summary.json` and excluded from
 `max_cost_usd`. A change can have any number of these tags:
 
 - `common practice`: standard recipes, such as Muon, warmup, cosine or linear decay, clipping and AdamW betas.
@@ -415,7 +408,7 @@ schedule.
   The broker keeps waiting. When `close()` returns, the final `report.html` is written.
   It waits up to 30 s for pending Claude summaries.
 - `blocking=True` is deterministic given the agent's answers. Replaying a final program with `opal.replay` is
-  deterministic too. With `blocking=False` or `"auto"`, timing decides when an edit takes effect.
+  deterministic too. With `blocking=False`, timing decides when an edit takes effect.
   Two runs with the same answers can differ.
 - To turn the agent off mid-run, resume with `backend="keep"` or start a fresh run with `opal.replay(...)`.
 - For the Hugging Face Trainer, use `opal.hf.OpalTrainer` in place of `Trainer`.
@@ -485,6 +478,8 @@ On the GPU machine, `opal doctor --backend mailbox:/scratch/me/opal-box` checks
 whether a broker serves it. That machine needs no Claude Code. Set the model and effort on the broker with
 `opal broker ... --model claude-opus-5-5 --effort high`, the defaults, rather than in the run's `backend_options`.
 The broker's machine must stay awake for the whole run. On a Mac, use `caffeinate -i opal broker ...`.
+The broker's ssh runs with `BatchMode=yes`, so it cannot ask for a password or a second factor. Log in with a key,
+or open a connection it can share before you start it: `ssh -fNM -o ControlPath=~/.ssh/opal-%r@%h-%p me@gpu-host`.
 The run waits while no broker answers, as described under "When the agent is unavailable".
 Mailbox runs do not make code-change summaries during training.
 Run `opal report <run> --summarize` where Claude Code is logged in to add them.

{opal_optimizer-0.3.5 → opal_optimizer-0.3.7}/examples/README.md

@@ -6,26 +6,39 @@ number comes from.
 
 ## Results by setting
 
-Each number is one run, and each agent started from the task's own recipe. The "Reactive optimizer" column comes
-from the harness this package grew out of (for modded-nanogpt, from OPAL 0.1.0). The last column is a rerun on OPAL
-0.3 with the neutral prompt and Opus 5.5 at effort high. In all of these runs, training paused at each decision while
-the agent answered, which is OPAL's default.
-
-| Example | Measure | Official recipe | Reactive optimizer | Made with | On OPAL 0.3 |
-|---|---|---|---|---|---|
-| [SiT-B/2](sit_b2/), ImageNet 256, 400K updates, 8× H100 | FID-50K ↓ | 35.7 with our evaluator (the SiT paper reports 33.0 with the ADM evaluator; Muon: 30.3) | 23.6 | earlier harness | not rerun |
-| [RAEv2-B](raev2_b/), ImageNet 256, 20 epochs, 8× H100 | FID-50K ↓ | 3.39 | 3.10 when asked for efficiency; 3.46 with the neutral prompt | earlier harness | 3.19 |
-| [Goldfish 125M GPT](goldfish_swahili/), 1 GB of Swahili, 1× H100 | FLORES-200 bits ↓ | 79.37 | 77.60 | earlier harness | 77.25 |
-| [modded-nanogpt record #36](modded_nanogpt/), 162M GPT, 8× H100 | validation loss ↓ | 3.2781 | 3.2749 (a small gain: the track assumes σ = 0.0013 per run) | OPAL 0.1.0 | not rerun |
-| LightningDiT-B/1, ImageNet 256, 160 epochs (200K updates), 8× H100 | FID-50K ↓, with guidance / without | 3.22 / 10.12 | – | – | 2.31 / 7.56 |
+Each number is one run, and each agent started from the task's own recipe. Runs on OPAL 0.3 used the neutral prompt
+and Opus 5.5 at effort high. SiT-B/2 comes from the harness this package grew out of. In all of these runs, training
+paused at each decision while the agent answered, which is OPAL's default.
+
+| Example | Measure | Official recipe | Reactive optimizer | Made with |
+|---|---|---|---|---|
+| [SiT-B/2](sit_b2/), ImageNet 256, 400K updates, 8× H100 | FID-50K ↓ | 35.7 with our evaluator (the SiT paper reports 33.0 with the ADM evaluator; Muon: 30.3) | 23.6 | earlier harness |
+| [RAEv2-B](raev2_b/), ImageNet 256, 20 epochs, 8× H100 | FID-50K ↓ | 3.39 | 3.19 | OPAL 0.3 |
+| [Goldfish 125M GPT](goldfish_swahili/), 1 GB of Swahili, 1× H100 | FLORES-200 bits ↓ | 79.37 | 77.25 | OPAL 0.3 |
+| [modded-nanogpt record #36](modded_nanogpt/), 162M GPT, 8× H100 | validation loss ↓ | 3.2781 | 3.2749 (a small gain: the track assumes σ = 0.0013 per run) | OPAL 0.1.0 |
+| LightningDiT-B/1, ImageNet 256, 160 epochs (200K updates), 8× H100 | FID-50K ↓, with guidance / without | 3.22 / 10.12 | 2.31 / 7.56 | OPAL 0.3 |
 
 It does not always help. On modded-nanogpt, a heavily tuned benchmark, a run on OPAL 0.2.0 with the neutral prompt
 ended at 3.2878, worse than record #36. Your numbers may also differ from ours, because the agent can make different
-choices from one run to the next and hosted models change between versions. Still, most of our reruns on OPAL 0.3
+choices from one run to the next and hosted models change between versions. Still, most of our runs on OPAL 0.3
 ended ahead of the recipe they started from. The [blog post](https://xingjianbai.com/reactive-optimizers/) has more.
 
 LightningDiT-B/1 has no folder here. Both runs used the upstream LightningDiT training code and its 64-epoch config, changed to model B/1, 200,000 updates and `use_qknorm: true` (without query-key normalization the official run diverged near update 194,000). The official recipe trains with AdamW at a constant learning rate of 2e-4. FID-50K uses 50,000 samples against the ADM reference statistics, Euler sampling with 250 steps and timestep shift 0.3; "with guidance" is the upstream setting, a guidance scale of 10 from t = 0.10 on. The LightningDiT paper reports FID-10K for this model, which is not comparable.
 
+## Training without waiting for the agent
+
+With `blocking=False`, training continues on the current programs while the agent answers, and an edit takes effect
+when its answer arrives. One run on RAEv2-B, OPAL 0.3, 8× H100:
+
+| RAEv2-B, 20 epochs | Official recipe | OPAL, training waits (default) | OPAL, `blocking=False` |
+|---|---|---|---|
+| FID-50K ↓ after 25,000 updates | 3.39 | 3.19 | 3.17 |
+| Run time, including evaluations | 3.21 h | 3.75 h, of which 0.49 h waiting for the agent | 3.22 h |
+| Decisions asked / that changed code | – | 50 / 6 | 43 / 3 |
+| Agent cost | – | $13.30 | $9.71 |
+
+Without waiting, fewer decisions are asked, because no new decision is asked while one is in progress.
+
 ## Small examples (CPU)
 
 `mnist_mlp.py` trains an MLP on MNIST with AdamW and a cosine schedule for 5 epochs. It doubles as the install

{opal_optimizer-0.3.5 → opal_optimizer-0.3.7}/examples/cifar10_resnet.py

@@ -65,9 +65,8 @@ parser.add_argument(
     nargs="?",
     const="true",
     default="true",
-    choices=["true", "false", "auto"],
-    help="true (default): training waits for each answer; false: it keeps going; auto: it waits "
-    "only when an answer would land late",
+    choices=["true", "false"],
+    help="true (default): training waits for each answer; false: it keeps going",
 )
 parser.add_argument("--max_cost_usd", type=float, default=15.0, help="stop asking the agent after this much spend")
 parser.add_argument(

{opal_optimizer-0.3.5 → opal_optimizer-0.3.7}/examples/diffusion_mnist.py

@@ -52,9 +52,8 @@ parser.add_argument(
     nargs="?",
     const="true",
     default="true",
-    choices=["true", "false", "auto"],
-    help="true (default): training waits for each answer; false: it keeps going; auto: it waits "
-    "only when an answer would land late",
+    choices=["true", "false"],
+    help="true (default): training waits for each answer; false: it keeps going",
 )  # opal
 args = parser.parse_args()
 

{opal_optimizer-0.3.5 → opal_optimizer-0.3.7}/examples/goldfish_swahili/README.md

@@ -10,17 +10,13 @@ split at the middle character. This follows upstream's `eval_code/flores_eval_go
 
 | FLORES-200 bits ↓ (one run each) | Official recipe | Reactive optimizer |
 |---|---|---|
-| after the last update | 79.37 | **77.60** |
+| after the last update | 79.37 | **77.25** |
 
-In this run the agent ended 1.77 bits below the official recipe.
+In this run the agent ended 2.12 bits below the official recipe.
 
-On OPAL 0.3, the rerun scored 77.25: one run, neutral prompt, 51 decisions of which 11 changed the program,
+The agent run used OPAL 0.3 with the neutral prompt: 51 decisions of which 11 changed the program,
 $17.41, 5 h 39 min on one H100. This wall time includes evaluations and waiting for the agent.
 
-The table above comes from the earlier training system OPAL grew from in October 2026.
-It used Claude Code, Opus 5.5 at effort `high`, with that system's neutral prompt and 100 decisions every 793 updates.
-Training paused at each decision.
-
 ## Official code and data
 
 - Training uses [tylerachang/goldfish](https://github.com/tylerachang/goldfish) at `d4a518a` with
@@ -73,9 +69,9 @@ Then run it once with `backend="keep"` for a few hundred updates: its losses mus
 | | Official recipe | Reactive optimizer |
 |---|---|---|
 | Hardware | 1× H100 80GB | 1× H100 80GB |
-| Reported run time, including agent waits | 4.8 h | 5.75 h, of which 0.77 h waiting for the agent |
-| Agent cost | – | $17.79 |
-| Decisions answered / that changed code | – | 100 / 4 (decisions 1, 2, 9 and 11) |
-| FLORES-200 bits | 79.374 | 77.600 |
+| Reported run time, including agent waits | 4.8 h | 5.65 h, of which 0.67 h waiting for the agent |
+| Agent cost | – | $17.41 |
+| Decisions answered / that changed code | – | 51 / 11 |
+| FLORES-200 bits | 79.374 | 77.250 |
 
-The official 4.8 h sums logged update windows, including evaluations. The agent time includes its 0.77 h wait.
+The official 4.8 h sums logged update windows, including evaluations. The agent time includes its 0.67 h wait.

{opal_optimizer-0.3.5 → opal_optimizer-0.3.7}/examples/gpt_small.py

@@ -70,9 +70,8 @@ parser.add_argument(
     nargs="?",
     const="true",
     default="true",
-    choices=["true", "false", "auto"],
-    help="true (default): training waits for each answer; false: it keeps going; auto: it waits "
-    "only when an answer would land late",
+    choices=["true", "false"],
+    help="true (default): training waits for each answer; false: it keeps going",
 )
 parser.add_argument("--max_cost_usd", type=float, default=15.0, help="stop asking the agent after this much spend")
 parser.add_argument(

{opal_optimizer-0.3.5 → opal_optimizer-0.3.7}/examples/mnist_mlp.py

@@ -51,9 +51,8 @@ parser.add_argument(
     nargs="?",
     const="true",
     default="true",
-    choices=["true", "false", "auto"],
-    help="true (default): training waits for each answer; false: it keeps going; auto: it waits "
-    "only when an answer would land late",
+    choices=["true", "false"],
+    help="true (default): training waits for each answer; false: it keeps going",
 )  # opal
 args = parser.parse_args()
 

{opal_optimizer-0.3.5 → opal_optimizer-0.3.7}/examples/modded_nanogpt/README.md

@@ -14,7 +14,7 @@ The gap is about 2.5 times that, from one run on each side. Record #36's publish
 It appears in row 36 of the [track README on master](https://github.com/KellerJordan/modded-nanogpt/blob/master/records/track_3_optimization/README.md).
 The README at the pinned commit below predates that row and lists only records 1 to 12.
 
-**Not rerun on OPAL 0.3 yet.** The 3.2749 run used OPAL 0.1.0 with that version's default prompt, which this release
+The 3.2749 run used OPAL 0.1.0 with that version's default prompt, which this release
 no longer ships: Claude Code (Opus 5.5, effort `high`), 100 decisions requested with checks every 10 updates (97 after
 snapping, all answered), training paused at each decision. A later run on OPAL 0.2.0 with the neutral prompt (50 evenly
 spaced decisions, 2 GPUs, a goal worded as reaching the target loss) ended at **3.2878, worse than record #36**.