# OPAL: Rewrite PyTorch Optimizers During Training This repository profile is provided by osrepos.com, an open source repository discovery platform. Source: osrepos.com Repository profile: https://osrepos.com/repo/xingjian-bai-opal Generated for open source discovery and AI-assisted research. OPAL wraps a PyTorch optimizer so Claude Code can rewrite its update and analysis programs while training runs. It is aimed at researchers and engineers experimenting with optimizer changes on CPU, a single GPU, or single-node DDP. GitHub: https://github.com/xingjian-bai/opal OSRepos URL: https://osrepos.com/repo/xingjian-bai-opal ## Summary OPAL wraps a PyTorch optimizer so Claude Code can rewrite its update and analysis programs while training runs. It is aimed at researchers and engineers experimenting with optimizer changes on CPU, a single GPU, or single-node DDP. ## Topics - python - deep-learning - ai-agents - pytorch - reactive-optimization - optimizer-search - agent-guided-training ## Repository Information Last analyzed by OSRepos: Thu Nov 05 2026 12:39:25 GMT+0000 (Western European Standard Time) Detail views: 0 GitHub clicks: 0 ## Safety Notice OSRepos shares public repositories for knowledge and discovery only. Review source code, dependencies, licenses, and security implications before running or installing anything. ## Content ## 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. ## Our Take OPAL is a distinctive and actively changing research tool for agent-guided PyTorch optimization, but its early maturity and reliance on a single dominant contributor call for a controlled trial before production use. **Good fit if:** - You train with PyTorch on CPU, one GPU, or single-node DDP and want to experiment with optimizer changes during a run. - Your runs are long enough that agent decision time is reasonable relative to training, and you can set a cost limit and evaluate results carefully. - You are comfortable trialing a new project that is receiving frequent commits and releases, with most development concentrated in one contributor. **Look elsewhere if:** - Your training depends on multi-node execution, FSDP, or DeepSpeed, which the project does not support. - You need the agent to guarantee improvements or roll back arbitrary training history; OPAL says runs can get worse and later failures are not undone. - You cannot use Claude Code for agent-driven runs, or cannot accommodate the agent's waiting time and billed usage. The keep mode remains available without agent calls. ## Project Health | Signal | Value | |---|---| | Status | **New**: less than six months old and changing fast | | Last commit | 2026-10-30 (6 days ago) | | Commits, last 90 days | 65 | | Releases, last 12 months | 6 (latest v0.3.10, 2026-11-03) | | Contributors | 2 (top contributor: 97% of commits) | | Issues closed, last 90 days | 6 (typically closed in 1 day) | | Pull requests merged, last 90 days | 2 | | Project age | 14 days | Checked on 2026-11-05 with the GitHub API. ## Project Facts - Language: Python - License: MIT - Stars: 345 - Forks: 20 - Topics: deep-learning, llm-agents, optimizer, pytorch - Website: https://xingjianbai.com/reactive-optimizers/ - Archived: no ## What You Need Detected in the repository: - Python >=3.10 (from pyproject.toml) - A test suite and automated checks on GitHub Actions ## Getting Started Install the package and run its offline environment check: ```bash pip install opal-optimizer opal doctor ``` See the [README](https://github.com/xingjian-bai/opal) and [guide](https://github.com/xingjian-bai/opal/blob/main/docs/GUIDE.md) for wrapping an optimizer, testing with `backend="keep"`, and configuring an agent run. ## License in Plain Words **MIT** (permissive). - Commercial use: yes - Modify and redistribute: yes - You must keep: the copyright and license notice - Share your changes: no A summary, not legal advice: the LICENSE file is what applies. ## 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.