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

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

@@ -1,5 +1,13 @@
 # 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_optimizer-0.3.6/opal_optimizer.egg-info → opal_optimizer-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opal-optimizer
-Version: 0.3.6
+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
@@ -149,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](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
@@ -179,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
@@ -192,7 +200,7 @@ Our run records and final weights are on Hugging Face: [snow-leopard/opal-result
 |---|---|---|
 | `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](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. |
@@ -219,7 +227,7 @@ Code CLI against a local mock.
 
 ## Status and limitations
 
-v0.3.6, 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

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

@@ -121,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](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
@@ -151,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
@@ -164,7 +172,7 @@ Our run records and final weights are on Hugging Face: [snow-leopard/opal-result
 |---|---|---|
 | `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](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. |
@@ -191,7 +199,7 @@ Code CLI against a local mock.
 
 ## Status and limitations
 
-v0.3.6, 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

{opal_optimizer-0.3.6 → 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,
@@ -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`.

{opal_optimizer-0.3.6 → 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.6 → 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.6 → 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.6 → 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.6 → 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.6 → 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.6 → 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**.

{opal_optimizer-0.3.6 → opal_optimizer-0.3.7}/examples/overfit/train.py

@@ -65,7 +65,7 @@ def parse(argv=None):
     p.add_argument("--decisions", type=int, default=30)
     p.add_argument("--decision-schedule", choices=["uniform", "front"], default="uniform")  # when the agent is asked
     p.add_argument("--every", type=int, default=50, help="OPAL's check interval, in updates")
-    p.add_argument("--blocking", choices=["true", "false", "auto"], default="true")
+    p.add_argument("--blocking", choices=["true", "false"], default="true")
     p.add_argument("--prompt", default="neutral")
     p.add_argument("--no-share-code", dest="share_code", action="store_false")
     p.add_argument("--max-cost-usd", type=float, default=None, help="stop asking the agent after this much spend")

{opal_optimizer-0.3.6 → opal_optimizer-0.3.7}/examples/raev2_b/README.md

@@ -5,22 +5,15 @@ It uses representation-autoencoder latents from a DINOv3 ViT-L/16 encoder and Vi
 Training ran for 25,020 updates with batch 1,024, or 20 epochs.
 The score is FID-50K of samples from the EMA weights, without guidance.
 
-| FID-50K ↓ (one run each) | Official recipe (our run) | Reactive optimizer, asked for efficiency | Reactive optimizer, neutral prompt |
-|---|---|---|---|
-| after 25,000 updates | 3.385 | **3.101** | 3.455 (worse than official) |
+| FID-50K ↓ (one run each) | Official recipe (our run) | Reactive optimizer |
+|---|---|---|
+| after 25,000 updates | 3.385 | **3.192** |
 
 The paper's figure for this setting is 3.37 (its Table 6, B at 20 epochs).
 
-On OPAL 0.3, the rerun scored 3.192: one run, neutral prompt, 50 decisions of which 6 changed the program,
+The agent run used OPAL 0.3 with the neutral prompt: 50 decisions of which 6 changed the program,
 $13.30, 3 h 45 min on 8× 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 100 decisions every 250 updates.
-Training paused at each decision. The better run asked for efficiency:
-"Make this diffusion-model training run more efficient by designing its optimization algorithm and controlling it
-online ... The aim is a better model from the same 25,020 updates."
-That system's neutral prompt ended worse than the official recipe. OPAL defaults to a neutral prompt.
-
 ## Official code
 
 [nanovisionx/RAEv2](https://github.com/nanovisionx/RAEv2) at commit `8a0d238f8dc3b261aba98b217f6c79c0182e8e94`.
@@ -81,19 +74,18 @@ EXPERIMENT_NAME=raev2-b20-agent OPAL_MAX_COST_USD=20 \
 
 ## Our runs
 
-| | Official recipe | Asked for efficiency | Neutral prompt |
-|---|---|---|---|
-| Hardware | 8× H100 80GB | 8× H100 80GB | 8× H100 80GB |
-| Reported run time, including agent waits | 3.1 h | 4.6 h, of which 1.4 h waiting for the agent | – |
-| Agent cost | – | $15.99 | $9.94 |
-| Decisions answered / that changed code | – | 100 / 16 (the last at decision 45) | 100 / 6 |
-| FID-50K at 25,000 | 3.385 | 3.101 | 3.455 |
+| | Official recipe | Reactive optimizer |
+|---|---|---|
+| Hardware | 8× H100 80GB | 8× H100 80GB |
+| Reported run time, including agent waits | 3.21 h | 3.75 h, of which 0.49 h waiting for the agent |
+| Agent cost | – | $13.30 |
+| Decisions answered / that changed code | – | 50 / 6 |
+| FID-50K at 25,000 | 3.385 | 3.192 |
 
-The earlier summary gives 3.1 h for the official run. Its log records 3.21 h including evaluations and 2.65 h without
-them. The 4.6 h agent time above includes its 1.4 h wait.
+The official run's log records 3.21 h including evaluations and 2.65 h without them.
 
-The earlier runs used upstream code with an optimizer hook and our logging, launched as above.
-That code and the earlier training system are not in this repository.
+Both runs used upstream code with our logging, launched as above.
+That code is not in this repository.
 
 We evaluated FID-50K every 5,000 updates during training, using ImageNet validation labels, 50 Euler steps,
 no guidance and EMA weights. Scoring used torch-fidelity against `imagenet_256_fid_stats`, the default ImageNet 256

{opal_optimizer-0.3.6 → opal_optimizer-0.3.7}/examples/sit_b2/README.md

@@ -8,7 +8,7 @@ The score is FID-50K of samples from the EMA weights, without guidance.
 |---|---|---|---|
 | at 400K updates | 35.68 | 30.29 | **23.64** |
 
-Not rerun on OPAL 0.3. The numbers above come from the earlier training system OPAL grew from in October 2026.
+The numbers above come from the earlier training system OPAL grew from in October 2026.
 A training-side host connected to a broker running Claude Code, Opus 5.5 at effort `high`, with that system's prompt.
 It made 94 decisions: 19 every 1,251 updates, then every 5,004. Training paused at each decision.
 The wiring below is for OPAL 0.3.x. It has CPU checks only.

{opal_optimizer-0.3.6 → opal_optimizer-0.3.7}/opal/_version.py

@@ -1,3 +1,3 @@
 """The package, build metadata and backend clients share this version."""
 
-__version__ = "0.3.6"
+__version__ = "0.3.7"

{opal_optimizer-0.3.6 → opal_optimizer-0.3.7}/opal/wrapper.py

@@ -643,6 +643,10 @@ class AgentOptimizer(
             f"{'auto-blocking' if self._auto else 'blocking' if self.blocking else 'non-blocking'}; "
             f"backend {self._backend_label}"
         )
+        if self._auto:
+            self._notice(
+                'blocking="auto" is experimental and untested on real training runs; use True (default) or False'
+            )
         describe = getattr(self.worker.backend, "describe", None) if self.worker else None
         if describe:
             self._log(describe())

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opal-optimizer
-Version: 0.3.6
+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
@@ -149,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](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
@@ -179,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
@@ -192,7 +200,7 @@ Our run records and final weights are on Hugging Face: [snow-leopard/opal-result
 |---|---|---|
 | `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](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. |
@@ -219,7 +227,7 @@ Code CLI against a local mock.
 
 ## Status and limitations
 
-v0.3.6, 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