SakanaAI / AI-Scientist-v3

The Agentic Scientist 
 Orchestrating Coding Agents for Automated Scientific (Co-)Discovery 
 Turn a task description into experiments, ablations, and a paper, driven by coding agents. 
Agentic Scientist treats coding agents as AI scientists. Starting from a
`task.md`, the agents propose ideas, run experiments, evaluate outcomes against
the task rubric, and iterate toward stronger programs. The pipeline then runs
baselines and ablations, a sealed final evaluation, post-hoc analyses, and
writes the paper, with every stage kept under one run directory.
## Install
The recommended setup runs every agent phase inside Docker, which is the
default for `agsci run`. Install Docker,
then build the agent image:
 [code] 
If the build cannot reach package mirrors, add `--network=host` to the
`docker build` command.
> **Security note** — Agentic Scientist launches coding agents with full tool
> permissions (Headless `--allow yolo`). They can run arbitrary commands and
> inherit the API keys you give them, and the task files and papers they read
> steer what they do. Keep runs inside the Docker image rather than on your
> workstation, only run tasks and sources you trust, and review run directories
> before sharing them: agent logs can echo document contents and paths.
### Prerequisites
- **Python ≥ 3.11 with uv**. `uv sync` creates
 `.venv` and installs the `agsci` command:
 [code] 
- **API keys** in a `.env` file at the repo root (`ANTHROPIC_API_KEY`,
 `OPENAI_API_KEY`, `GEMINI_API_KEY`, ... whichever your agent
 needs). The pipeline mounts it into the agent containers. Never commit it.
- **Agent CLIs** are already inside the image. For native (non-containerized)
 runs, install the CLI of the agent you use plus Git and Node.js; versions and
 commands are in docs/install.md.
- **GPUs** are required only by the GPU task presets. The pipeline discovers
 them through `nvidia-smi` and refuses to start compute phases unless the
 visible GPUs match the preset.
- **Autoillustrate** (optional) is built into the image for concept figures.
 To use it directly on the host, follow the single-command install in the
 Autoillustrate README.
Run `agsci doctor` to check the host, or `agsci doctor examples/ preset= `
to check everything one specific run needs (CLI, credentials, image, GPUs, task
scaffold).
## Quickstart
Point `agsci run` at a task directory. This runs the default six phases
(task drafting → investigation → ablations → final evaluation → post-hoc analysis
→ paper) on the CPU-only circle-packing example:
 [code] 
Add `--dry-run` to validate the configuration and preview the exact commands
without running anything. Every option is a Hydra `key=value` override; `agsci
run --help` lists them all.
> **Note** — Agentic Scientist drives `claude`, `codex`, `cursor`, `opencode`,
> `gemini`, and `pi` through
> Headless CLI, so the same
> experiment can be repeated across agents and models: pick one with
> `agent.name= agent.model= `.
Task drafting only writes a scaffold w