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

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

@@ -1,5 +1,15 @@
 # Changelog
 
+## 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.6}/PKG-INFO

@@ -1,9 +1,12 @@
 Metadata-Version: 2.4
 Name: opal-optimizer
-Version: 0.3.5
+Version: 0.3.6
 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
 
@@ -144,7 +156,7 @@ Each number is one run, and each agent started from the task's own recipe:
 
 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.
 
 Our run records and final weights are on Hugging Face: [snow-leopard/opal-results](https://huggingface.co/datasets/snow-leopard/opal-results).
@@ -178,17 +190,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. |
 | `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 +219,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.6, 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 +239,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.6}/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
 
@@ -119,7 +128,7 @@ Each number is one run, and each agent started from the task's own recipe:
 
 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.
 
 Our run records and final weights are on Hugging Face: [snow-leopard/opal-results](https://huggingface.co/datasets/snow-leopard/opal-results).
@@ -153,17 +162,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. |
 | `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 +191,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.6, 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 +211,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.6}/docs/GUIDE.md

@@ -328,7 +328,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.
@@ -485,6 +485,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.6}/opal/_version.py

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

{opal_optimizer-0.3.5 → opal_optimizer-0.3.6}/opal/backends/mailbox.py

@@ -490,7 +490,13 @@ class _Folder:
     def _sh(self, cmd, data=None):
         # without data, give ssh an empty stdin: it would otherwise read (and forward) the broker's own stdin
         io = dict(input=data) if data is not None else dict(stdin=subprocess.DEVNULL)
-        return subprocess.run(self.base + [cmd], capture_output=True, timeout=120, **io)
+        p = subprocess.run(self.base + [cmd], capture_output=True, timeout=120, **io)
+        if p.returncode == 255 and b"Permission denied" in p.stderr:  # BatchMode: ssh cannot ask for a password
+            p.stderr = p.stderr.strip() + (
+                " (the broker's ssh cannot ask for a password: use an ssh key, or open a connection it can share "
+                f"first: ssh -fNM -o ControlPath=~/.ssh/opal-%r@%h-%p {self.ssh})"
+            ).encode()
+        return p
 
     def read(self, name):
         if not self.ssh:

{opal_optimizer-0.3.5 → opal_optimizer-0.3.6}/opal/cli.py

@@ -148,6 +148,7 @@ def doctor_mailbox(spec):
 
 
 def doctor(a):
+    import os
     import platform
     import shutil
     import subprocess
@@ -163,6 +164,13 @@ def doctor(a):
         f"torch {torch.__version__}; CUDA available: {torch.cuda.is_available()}"
         + (f" ({torch.cuda.device_count()} x {torch.cuda.get_device_name(0)})" if torch.cuda.is_available() else "")
     )
+    if not torch.cuda.is_available() and (shutil.which("nvidia-smi") or os.path.exists("/dev/nvidiactl")):
+        built = f"built for CUDA {torch.version.cuda}" if torch.version.cuda else "a CPU-only build"
+        print(
+            f"this machine has an NVIDIA GPU, but torch {torch.__version__} ({built}) cannot use it: for GPU training, "
+            "install the torch build for your driver first (https://pytorch.org/get-started/locally/), or check "
+            "CUDA_VISIBLE_DEVICES"
+        )
     for name in ("codex" if a.backend == "codex" else "claude",):
         exe = shutil.which(name)
         ver = ""
@@ -209,7 +217,9 @@ def doctor(a):
             reply = (out.get("text") or "").strip()
             ok = out.get("returncode") == 0 and "READY" in reply
             print(
-                f"live call: {'ok' if ok else 'failed'} ({out.get('seconds', 0):.0f} s; reply {reply[:80]!r}; error {out.get('error')})"
+                f"live call: {'ok' if ok else 'failed'} ({out.get('seconds', 0):.0f} s"
+                + (f", ${out['cost_usd']:.2f}" if isinstance(out.get("cost_usd"), (int, float)) else "")
+                + f"; reply {reply[:80]!r}; error {out.get('error')})"
             )
             if a.backend == "codex":
                 print(f"Codex thread: {out.get('session')}; provider rollout: {out.get('rollout')}")

{opal_optimizer-0.3.5 → opal_optimizer-0.3.6}/opal/estimate.py

@@ -102,16 +102,26 @@ def lines(total_steps, sec_per_step, decisions, blocking=True, max_lag=50, model
             f"decisions not set: {decisions} scheduled instead of {capped_from}, so that the expected waiting stays "
             f"within {MAX_WAIT_FACTOR:g}x the run's own time (set decisions= to choose)"
         )
-    if over and (decisions <= 1 or not explicit):
+    fewer = capped_decisions(decisions, run, blocking, sec_per_step, max_lag) if over else decisions
+    # a run shorter than one typical answer ends before the answer arrives when training does not wait for it
+    no_wait = (
+        "blocking=False lets training go on while the agent thinks"
+        if run >= FIRST_SECONDS[1]
+        else "blocking=False would not help: training would end before the first answer arrives"
+    )
+    if over and (
+        decisions <= 1 or not explicit or waiting(fewer, blocking, sec_per_step, max_lag) > MAX_WAIT_FACTOR * run
+    ):
+        n = decisions if not explicit and decisions > 1 else 1
         out.append(
-            f"even {'one decision' if decisions <= 1 else f'{decisions} decisions'} wait{'s' * (decisions <= 1)} more "
-            f"than {MAX_WAIT_FACTOR:g}x the run's own time; blocking=False lets training go on while the agent thinks"
+            f"even {'one decision' if n <= 1 else f'{n} decisions'} wait{'s' * (n <= 1)} more "
+            f"than {MAX_WAIT_FACTOR:g}x the run's own time; {no_wait}"
         )
     elif over:
         out.append(
             f"the expected waiting is more than {MAX_WAIT_FACTOR:g}x the run's own time: ask fewer times "
-            f"(decisions={capped_decisions(decisions, run, blocking, sec_per_step, max_lag)} keeps it within "
-            f"{MAX_WAIT_FACTOR:g}x) or let training go on while the agent thinks (blocking=False)"
+            f"(decisions={fewer} keeps it within {MAX_WAIT_FACTOR:g}x) or let training go on while the agent thinks "
+            f"(blocking=False)"
         )
     if (model, effort) != (MODEL, EFFORT):
         out.append(

{opal_optimizer-0.3.5 → opal_optimizer-0.3.6}/opal/report_privacy.py

@@ -125,7 +125,7 @@ class Privacy:
     def _path(self, match):
         path = match[0]
         # Avoid eating arithmetic such as `1 / 2`, or regex syntax such as /\w+/.
-        if path in ("/", "//"):
+        if path in ("/", "//") or not re.search(r"[A-Za-z]", path):  # also `(u-1)/1000`: no letters, no location
             return path
         for root in sorted(self.roots, key=len, reverse=True):
             if path == root:

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

@@ -1647,6 +1647,7 @@ class AgentOptimizer(
             decisions=self.worker.k if self.worker else 0,
             cost_usd=self.worker.recorded_cost if self.worker else 0,
             unknown_cost_decisions=sorted(self.worker.unknown_cost_decisions) if self.worker else [],
+            agent_wait_seconds=round(self.agent_wait_seconds, 1),  # the report's "training waiting time"
             **(dict(pending_decision=self.worker.k) if settling else {}),
             **(dict(usage=self.worker.usage) if self.worker and self.worker.usage is not None else {}),
             **(dict(eval_integrity=checked) if checked else {}),

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

@@ -1,9 +1,12 @@
 Metadata-Version: 2.4
 Name: opal-optimizer
-Version: 0.3.5
+Version: 0.3.6
 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
 
@@ -144,7 +156,7 @@ Each number is one run, and each agent started from the task's own recipe:
 
 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.
 
 Our run records and final weights are on Hugging Face: [snow-leopard/opal-results](https://huggingface.co/datasets/snow-leopard/opal-results).
@@ -178,17 +190,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. |
 | `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 +219,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.6, 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 +239,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.6}/pyproject.toml

@@ -17,6 +17,11 @@ dependencies = [
     "numpy>=1.26.4",  # torch's NumPy bridge
 ]
 
+[project.urls]
+Homepage = "https://github.com/xingjian-bai/opal"
+Documentation = "https://github.com/xingjian-bai/opal/blob/main/docs/GUIDE.md"
+"Blog post" = "https://xingjianbai.com/reactive-optimizers/"
+
 [project.optional-dependencies]
 examples = [
     "torchvision>=0.20; python_version < '3.13'",

{opal_optimizer-0.3.5 → opal_optimizer-0.3.6}/skills/train-with-agent/SKILL.md

@@ -18,11 +18,14 @@ Keep test data and labels out of the training process, evaluate the final checkp
 1. **Find the loop.** Locate the training script and the place where the optimizer and LR scheduler are built and
    where `optimizer.step()` is called. Note: number of optimizer steps in the run (`total_steps`), data-parallel setup
    (single GPU, DDP, Accelerate, HF Trainer, Lightning, FSDP/DeepSpeed), gradient clipping in the loop, GradScaler,
-   gradient accumulation, EMA, checkpoint save/load.
+   gradient accumulation, EMA, checkpoint save/load, and whether parameter groups are added during training (for
+   example layers unfrozen later).
 2. **Check it is supported.** FSDP, ZeRO/DeepSpeed, tensor or pipeline parallelism and JAX are not supported: stop
    and tell the user. With an HF Trainer, use `opal.hf.OpalTrainer` (docs/GUIDE.md, "Hugging Face Trainer").
    With Accelerate, wrap after `accelerator.prepare` (GUIDE, "Accelerate"). Lightning is untested: say so before
-   continuing.
+   continuing. All parameter groups must exist before `wrap`: for layers unfrozen later, create their group up front
+   with `requires_grad=False` and set it to True when they are unfrozen. With DDP, every rank must run the same number
+   of steps; uneven inputs under `Join` stop with an error.
 3. **Write the goal sentence with the user**: what the run trains and what it is judged by at the end (for example
    "ResNet-18 on CIFAR-10, judged by test accuracy after 30 epochs"). Ask; do not invent the metric.
 4. **Wrap.** Right after the optimizer and scheduler are created:
@@ -46,7 +49,10 @@ Keep test data and labels out of the training process, evaluate the final checkp
    machine has no agent, use `backend="mailbox:<folder on the GPU machine>"`, check it there with
    `opal doctor --backend mailbox:<folder>`, and give the user the broker command:
    `opal broker <folder> --ssh <user@gpu-host> --backend claude --model claude-opus-5-5 --effort high`. With a
-   mailbox the model and effort are set on the broker, not in `backend_options`. The broker's machine must stay awake
+   mailbox the model and effort are set on the broker, not in `backend_options`. Over ssh, the GPU host needs
+   `python3` (3.6 or newer) on its non-interactive PATH; the doctor checks it. The broker's ssh cannot answer a
+   password prompt: if the host asks for one, tell the user to log in with a key or to open a shared connection
+   first (`ssh -fNM -o ControlPath=~/.ssh/opal-%r@%h-%p <user@gpu-host>`). The broker's machine must stay awake
    for the whole run (on a Mac: `caffeinate -i opal broker ...`); while no broker answers, the run waits.
 7. **Smoke test before the real run**: run about 100 updates twice with a reduced `total_steps`, once unwrapped and
    once wrapped with `backend="keep"` (no agent, no cost), and check that the losses match step for step. Time the
@@ -55,7 +61,8 @@ Keep test data and labels out of the training process, evaluate the final checkp
    run's `total_steps` and the measured seconds per update (add `--decisions K`, `--every E`, `--no-blocking` or
    `--mailbox` as the wrap call will have them). Show the user its lines as they are: the run's time without the
    agent, the expected waiting for the agent (a range, and as a multiple of the run's own time) and the expected
-   cost. If `decisions` is not set, OPAL lowers it so that the waiting stays within 4x the run's own time; say so.
+   cost. If `decisions` is not set, OPAL lowers it so that the waiting stays within 4x the run's own time, but keeps
+   at least one decision, even when one already waits longer (short runs); say so.
    Ask for `max_cost_usd`, and give the launch command only after the user confirms. Then switch to the real
    backend, with `max_cost_usd`. The agent defaults to claude-opus-5-5 at effort high, the blog's
    setting; set `backend_options=dict(model=..., effort=...)` only if the user asks (the run then warns that the blog's