ai4scientist/nano-scientist

🔥 News

• [2026. 05] 🎉 Major Release! 87 modular skills, CrossRef citation recovery, multi-model quality gate via REVIEWER_MODEL, and MCP server injection. Full BibTeX stub fallback ensures zero undefined citations.
• [2026. 01] 🚀 Nano-scientist public launch — budget-first autonomous research pipeline producing LaTeX + BibTeX + PDF in a single python main.py call.

---

✨ Why Nano-scientist

---

🧪 Showcases

Sample reports generated by Nano-scientist at --budget 1:

• What techniques bridge the performance gap between small language models and LLMs in automated bug fixing?
• Challenge taxonomy for the Lean 4 theorem prover: clustering, labeling, and trend analysis across GitHub issues.
• Comparative analysis of five AI coding agents across 933k pull requests (AIDev).
• Survey of on-policy distillation techniques.

---

🧠 How it works

flowchart TD
    I([Initializer\nzero LLM calls]) -->|literature| LIT

    subgraph LIT_LOOP["  Literature Loop  "]
        LIT[LiteratureReviewLoop\ndecide → skill → quality gate]
        LIT -->|"next iter"| LIT
    end

    LIT -->|"goal met · budget low"| EXP

    subgraph EXP_LOOP["  Experiment Loop  "]
        EXP[ExperimentationLoop\ndecide → skill → quality gate]
        EXP -->|"next iter"| EXP
    end

    EXP -->|"goal met · budget low"| WR

    subgraph WRITE_LOOP["  Writing Loop  "]
        WR[WritingLoop\nwrite sections → review pass → fix]
    end

    WR -->|compile| CT

    subgraph COMPILE["  Compiling Loop  "]
        CT[CompileTeX\npdflatex + bibtex]
        FT[FixTeX\npatch errors]
        CT -->|fix| FT
        FT -->|compile| CT
    end

    CT -->|done| F([Finisher\ncost_log · summary])
    FT -->|done| F

Stage breakdown

---

🚀 Quickstart

# 1) Clone
git clone https://github.com/AI4Scientist/nano-scientist
cd nano-scientist

# 2) Install dependencies
pip install -r requirements.txt

# 3) Add API keys
cp .env.example .env
# edit .env — minimum: OPENROUTER_API_KEY

# 4) Run
python main.py "CRISPR off-target effects in primary T cells" --budget 2.00

# Or pass a research proposal .md file
python main.py proposal.md --budget 0.50

Output lands in outputs//:

outputs/
└── /
    ├── report.tex         # assembled LaTeX source
    ├── report.pdf         # final PDF (if pdflatex installed)
    ├── references.bib     # deduplicated BibTeX
    ├── artifacts/         # per-skill markdown outputs
    ├── figures/           # generated plots / images
    ├── data/              # collected CSV / JSON data
    ├── scripts/           # executed code blocks
    ├── traj.txt           # full stdout trace
    ├── history.json       # step-by-step execution log
    ├── cost_log.json      # per-step token costs
    └── summary.json       # final run summary

---

🖥️ CLI reference

python main.py [topic] [options]

Arguments:
  topic                 Research topic — a plain string or path to a .md file.
                        Optional when using --list-skills.

Options:
  -b, --budget FLOAT    Spend limit in USD  (default: $1.00)
  -o, --output DIR      Output directory    (default: outputs/)
  -e, --env FILE        Path to .env file   (default: .env)
  --list-skills         Print available skills and exit

python main.py "CRISPR off-target effects in primary T cells" --budget 1.00
python main.py proposal.md --budget 1.00
python main.py --list-skills

Budget

Every run targets a full 8-section paper. Budget controls depth, not report type — more budget means more skill calls, more citations, and more revision rounds. Loops terminate when estimated remaining LLM calls drop below a threshold, so the agent always spends as much as it can usefully spend.

---

🧩 Skills

Each skill is a folder under skills/ with a single SKILL.md (lazy-loaded at runtime). Skills with allowed-tools: Bash get a real tool-calling loop with bash execution and error feedback.

Add a skill

1. Create skills/my-skill/SKILL.md with YAML frontmatter:

---
id: my-skill
description: One-line description shown in the planner.
allowed-tools: Bash        # grants bash tool-calling with error feedback
required-keys: [HF_TOKEN]  # optional; skill is filtered out if key missing
---

Your skill instructions here.

2. Register in skills/skills.json:

{ "id": "my-skill", "description": "One-line description shown in the planner." }

---

🔐 Environment variables

Required

Skill-gated (optional)

Missing skill keys automatically filter out dependent skills at startup.

Tuning (all optional)

---

🗂️ Project layout

nano-scientist/
├── main.py              # CLI entry point
├── src/
│   ├── flow.py          # PocketFlow wiring (3 loops + compile/fix)
│   ├── nodes.py         # 7 nodes + helpers
│   └── utils.py         # LLM client, cost tracking, BibTeX utils
├── skills/              # 87 modular research skills
│   ├── skills.json      # skill index (id + description)
│   └── /
│       └── SKILL.md     # instructions + YAML frontmatter
├── outputs/             # generated reports (git-ignored)
└── .env                 # API keys (git-ignored)

---

🤝 Join the Community

• Open an issue — bug reports, feature requests, skill ideas
• Submit a PR — new skills are one SKILL.md file

---

📌 Citation

If you use Nano-scientist in your research, please cite:

@software{nano_scientist2026,
  title  = {Nano-scientist: Autonomous Research Agent for Budget-Constrained Scientific Reports},
  author = {{AI4Scientist Team}},
  year   = {2026},
  url    = {https://github.com/AI4Scientist/nano-scientist}
}