Autoresearch

Autonomous AI research for accelerator optimization. An AI agent iteratively modifies an algorithm, evaluates it across random error seeds, and merges improvements — running continuous optimization campaigns with no human in the loop.

Autoresearch supports pluggable applications: bring your own simulator, evaluation script, and optimization target. It ships with applications spanning ALS-U Accumulator Ring commissioning and beam capture, PETRA-IV dynamic-aperture optimization, multi-objective Pareto first-turn threading, and an ALS injector demo. See docs/paper_scope.md for the scientific scope.

Installation

Autoresearch installs with uv sync, which resolves the exact environment locked in uv.lock. Two lanes:

git clone https://github.com/als-apg/autoresearch-commissioning.git
cd autoresearch-commissioning

# Framework only (orchestrator, dashboard, tests — no physics simulator)
uv sync --extra test --extra orchestrator

# Full physics (adds pySC + Accelerator Toolbox for the ALS-U applications)
uv sync --extra test --extra orchestrator --extra pysc

pySC is pinned to an exact revision through [tool.uv.sources] and fetched automatically — there is nothing to clone or configure. Use uv sync, not uv pip install -e . (which ignores [tool.uv.sources]).

See docs/GETTING_STARTED.md for the full walkthrough, including the developer override for a local pySC checkout and how to build your own application.

Reproducing a campaign

Export an Anthropic API key, then launch a campaign against an application and model:

export ANTHROPIC_API_KEY=sk-ant-...

uv run autoresearch \
  --tag my_first_run \
  --app applications/alsu_ar_beam_capture \
  --model anthropic/opus \
  --max-experiments 1

Progress streams to the live dashboard at http://127.0.0.1:8420. To evaluate the current algorithm directly (no agent loop), or to browse finished campaigns offline:

# Evaluate across error seeds (run from inside the application directory)
cd applications/alsu_ar_beam_capture && uv run python evaluate.py --n-seeds 4

# Browse completed campaigns
uv run autoresearch --serve

Architecture

src/autoresearch/
  orchestrator.py        — Event-driven outer loop
  agent_harness.py       — Claude Agent SDK harness (uniform AgentEvent stream)
  eval_runners.py        — Pluggable evaluation runners with registry pattern
  providers.py           — LLM provider configs (YAML-mergeable)
  report_store.py        — Textbook report cache + MCP server
  seed_worker.py         — Parallel seed evaluation (multiprocessing)
  dashboard/             — Live monitoring dashboard (SSE) + campaign health audit
applications/            — Pluggable application configs, algorithms, and prompts

Testing

# Framework lane — fast, no simulator (integration tests auto-skip)
uv run pytest tests/

# Full-physics lane runs the same command with the pysc extra installed,
# which additionally exercises the pySC integration tests.

License

License terms are pending LBNL review. See LICENSE for the current status.

Citation

If you use autoresearch in your work, please cite it using the metadata in CITATION.cff, and cite the accompanying paper as the primary reference.

Documentation

• docs/GETTING_STARTED.md — Installation, running campaigns, creating applications
• docs/paper_scope.md — Scientific scope and application pillars
• docs/architecture.html — How the outer loop, harness, and evaluation fit together