OPAL: Rewrite PyTorch Optimizers During Training

Overview

OPAL is a PyTorch optimizer wrapper that lets Claude Code change the optimizer while a model trains. Instead of fixing the update rule before a run, a coding agent observes reported training information and can revise the optimizer and its analysis program at decision points.

It is intended for PyTorch training on CPU, one GPU, or multi-GPU DDP within one node. OPAL can be tried without an agent using backend="keep"; an agent-driven run requires Claude Code on the machine running rank 0. The project reports that adaptive changes can help on some training recipes, but can also make results worse.

Key Features

• Wraps an existing torch.optim optimizer and scheduler, with a keep mode for checking that the wrapped run matches the original.
• Lets the agent revise optimizer updates, learning rates and schedules, momentum, preconditioning, clipping, and related safeguards.
• Provides an analysis program that can collect training statistics and report selected observations to the agent.
• Supports CPU, single-GPU training, and single-node DDP; the README also describes integration paths for Hugging Face Trainer and Accelerate, with stated restrictions.
• Offers blocking and non-blocking agent decisions, plus decision-count and cost controls for supported agent runs.
• Records decisions, program versions, rationales, and run data, with CLI commands for viewing, watching, reporting, and comparing runs.

Use Cases

• A deep-learning researcher wants to test whether an optimizer can adapt its update rules during a long training run rather than rely on one fixed recipe.
• A PyTorch engineer wants to explore learning-rate schedules, clipping, or preconditioning changes while keeping the model, data, and evaluation setup fixed.
• A team wants to run a no-agent equivalence check first, then decide whether the potential value of agent-guided changes justifies the added runtime and cost.
• A researcher training on a GPU machine without agent access can use the documented mailbox broker approach to connect training with an agent on another machine.

Getting Started

Install the package and run its offline environment check:

pip install opal-optimizer
opal doctor

See the README and guide for wrapping an optimizer, testing with backend="keep", and configuring an agent run.

Considerations

• OPAL is marked as a new project and is changing quickly. Recent activity and releases indicate active development, but the small contributor base is highly concentrated in one person.
• Agent-driven use requires Python 3.10 or newer, PyTorch 2.5 or newer (PyTorch 2.6 on Python 3.13), and Claude Code logged in on the machine running rank 0. Agent usage is billed to the associated account; no cost cap is set by default.
• The agent's programs run inside the training process, so the README explicitly says this is not a sandbox. Review the safety guidance and consider what code and training information the agent can see.
• Multi-node training, FSDP, and DeepSpeed are unsupported. The README also documents limitations for Accelerate, including fp16 GradScaler and Accelerate gradient accumulation.
• Agent decisions can add substantial time, especially on short runs. Non-blocking mode avoids waiting but can make decisions noisier, and an agent change is not a guarantee of better results.