Skip to content
Back to search

nano-scientist

An autonomous research agent that turns a topic into a peer-reviewed technical report

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ai4scientist--nano-scientist/badge.svg)](/listings/ai4scientist--nano-scientist)

HTML

<a href="/listings/ai4scientist--nano-scientist"><img src="/api/listings/ai4scientist--nano-scientist/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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/<uuid>/`:

outputs/
└── <uuid>/
    ├── 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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 383 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img width="800" alt="ChatGPT Image Jun 3, 2026, 06_17_46 PM" src="https://github.com/user-attachments/assets/9896499d-c850-492e-be0b-40e0f86b2938" />
  3. # Nano-scientist
  4. ### *Nano. Lean. Four loops, one paper.*
  5. <p>
  6. <a href="https://github.com/AI4Scientist/nano-scientist/stargazers"><img src="https://img.shields.io/github/stars/AI4Scientist/nano-scientist?style=for-the-badge&color=FFE165&logo=github" alt="Stars" /></a>
  7. <a href="https://github.com/AI4Scientist/nano-scientist/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-111827?style=for-the-badge" alt="License" /></a>
  8. <a href="https://github.com/AI4Scientist/nano-scientist/issues"><img src="https://img.shields.io/badge/Issues-Open-2563eb?style=for-the-badge&logo=github" alt="Issues" /></a>
  9. </p>
  10. <p>
  11. <img src="https://img.shields.io/badge/Core_Files-4-111827?style=for-the-badge" alt="Core files" />
  12. <img src="https://img.shields.io/badge/Nodes-7-2563eb?style=for-the-badge" alt="Nodes" />
  13. <img src="https://img.shields.io/badge/Loops-4-dc2626?style=for-the-badge" alt="Loops" />
  14. <img src="https://img.shields.io/badge/Skills-87-059669?style=for-the-badge" alt="Skills" />
  15. <img src="https://img.shields.io/badge/Budget_Driven-Yes-7c3aed?style=for-the-badge" alt="Budget driven" />
  16. </p>
  17. **An autonomous research agent that turns a topic into a peer-reviewed technical report — within a dollar budget you set.**
  18. Built on [PocketFlow](https://github.com/The-Pocket/PocketFlow) · Inspired by [karpathy/autoresearch](https://github.com/karpathy/autoresearch)
  19. <hr />
  20. </div>
  21. ## 🔥 News
  22. - **[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.
  23. - **[2026. 01]** 🚀 Nano-scientist public launch — budget-first autonomous research pipeline producing LaTeX + BibTeX + PDF in a single `python main.py` call.
  24. ---
  25. ## ✨ Why Nano-scientist
  26. | | |
  27. |---|---|
  28. | **Budget-first control** | Fix a dollar limit; the agent adapts depth and report type automatically. Loops exit the moment estimated remaining calls fall too low — no wasted spend. |
  29. | **Four autonomous loops** | Literature → Experimentation → Writing → Compiling — each self-terminating on quality gate or budget exhaustion. No central planner. |
  30. | **87 modular skills** | From paper search and code generation to grant proposals, patent drafting, and adversarial review. Lazy-loaded; each skill is one `SKILL.md` file. |
  31. | **Research-to-PDF pipeline** | Produces LaTeX source, deduplicated BibTeX (CrossRef-verified), per-skill artifact files, figures, scripts, and a compiled PDF — all in one run. |
  32. | **Zero-drop citations** | Entries failing CrossRef verification are recovered via title lookup or kept as `@misc` stubs — never silently dropped. |
  33. ---
  34. ## 🧪 Showcases
  35. Sample reports generated by Nano-scientist at `--budget 1`:
  36. - [What techniques bridge the performance gap between small language models and LLMs in automated bug fixing?](showcases/slm/report.pdf)
  37. - [Challenge taxonomy for the Lean 4 theorem prover: clustering, labeling, and trend analysis across GitHub issues.](showcases/lean4/report.pdf)
  38. - [Comparative analysis of five AI coding agents across 933k pull requests (AIDev).](showcases/aidev/report.pdf)
  39. - [Survey of on-policy distillation techniques.](showcases/opd/report.pdf)
  40. ---
  41. ## 🧠 How it works
  42. ```mermaid
  43. flowchart TD
  44. I([Initializer\nzero LLM calls]) -->|literature| LIT
  45. subgraph LIT_LOOP[" Literature Loop "]
  46. LIT[LiteratureReviewLoop\ndecide → skill → quality gate]
  47. LIT -->|"next iter"| LIT
  48. end
  49. LIT -->|"goal met · budget low"| EXP
  50. subgraph EXP_LOOP[" Experiment Loop "]
  51. EXP[ExperimentationLoop\ndecide → skill → quality gate]
  52. EXP -->|"next iter"| EXP
  53. end
  54. EXP -->|"goal met · budget low"| WR
  55. subgraph WRITE_LOOP[" Writing Loop "]
  56. WR[WritingLoop\nwrite sections → review pass → fix]
  57. end
  58. WR -->|compile| CT
  59. subgraph COMPILE[" Compiling Loop "]
  60. CT[CompileTeX\npdflatex + bibtex]
  61. FT[FixTeX\npatch errors]
  62. CT -->|fix| FT
  63. FT -->|compile| CT
  64. end
  65. CT -->|done| F([Finisher\ncost_log · summary])
  66. FT -->|done| F
  67. ```
  68. ### Stage breakdown
  69. | Stage | What happens |
  70. |---|---|
  71. | **Initializer** | Creates `outputs/<uuid>/`, classifies topic as survey vs. experimental (`is_survey`) — zero LLM calls |
  72. | **LiteratureReviewLoop** | Each iter: LLM picks `skill\|done` → executes skill → quality gate checks goal; exits on goal met or budget low |
  73. | **ExperimentationLoop** | Survey: synthesis skills (tables, figures from literature). Experimental: `experiment-pipeline`, `experiment-craft`, etc. |
  74. | **WritingLoop** | Writes all required sections, runs a peer-review pass, addresses major comments, assembles `.tex` |
  75. | **CompilingLoop** | `pdflatex` + `bibtex`; on error or undefined citations, FixTeX patches and recompiles (up to 2 attempts) |
  76. | **Finisher** | Writes `cost_log.json` + `summary.json`, prints total cost |
  77. ---
  78. ## 🚀 Quickstart
  79. ```bash
  80. # 1) Clone
  81. git clone https://github.com/AI4Scientist/nano-scientist
  82. cd nano-scientist
  83. # 2) Install dependencies
  84. pip install -r requirements.txt
  85. # 3) Add API keys
  86. cp .env.example .env
  87. # edit .env — minimum: OPENROUTER_API_KEY
  88. # 4) Run
  89. python main.py "CRISPR off-target effects in primary T cells" --budget 2.00
  90. # Or pass a research proposal .md file
  91. python main.py proposal.md --budget 0.50
  92. ```
  93. Output lands in `outputs/<uuid>/`:
  94. ```text
  95. outputs/
  96. └── <uuid>/
  97. ├── report.tex # assembled LaTeX source
  98. ├── report.pdf # final PDF (if pdflatex installed)
  99. ├── references.bib # deduplicated BibTeX
  100. ├── artifacts/ # per-skill markdown outputs
  101. ├── figures/ # generated plots / images
  102. ├── data/ # collected CSV / JSON data
  103. ├── scripts/ # executed code blocks
  104. ├── traj.txt # full stdout trace
  105. ├── history.json # step-by-step execution log
  106. ├── cost_log.json # per-step token costs
  107. └── summary.json # final run summary
  108. ```
  109. ---
  110. ## 🖥️ CLI reference
  111. ```text
  112. python main.py [topic] [options]
  113. Arguments:
  114. topic Research topic — a plain string or path to a .md file.
  115. Optional when using --list-skills.
  116. Options:
  117. -b, --budget FLOAT Spend limit in USD (default: $1.00)
  118. -o, --output DIR Output directory (default: outputs/)
  119. -e, --env FILE Path to .env file (default: .env)
  120. --list-skills Print available skills and exit
  121. ```
  122. ```bash
  123. python main.py "CRISPR off-target effects in primary T cells" --budget 1.00
  124. python main.py proposal.md --budget 1.00
  125. python main.py --list-skills
  126. ```
  127. ### Budget
  128. 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.
  129. ---
  130. ## 🧩 Skills
  131. 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.
  132. <details>
  133. <summary><b>Core research skills (click to expand)</b></summary>
  134. | Skill | What it does |
  135. |---|---|
  136. | `paper-navigator` | Find and read academic papers: keyword search, citation traversal, arXiv monitoring, SOTA lookup |
  137. | `research-survey` | Structured literature survey: outline → draft → section expansion → final assembly with dense citations |
  138. | `research-ideation` | Multi-persona ideation → ELO tournament ranking → manuscript-quality proposal |
  139. | `paper-planning` | Story design, experiment planning, figure design, 4-week timeline |
  140. | `experiment-pipeline` | 4-stage experiment execution: baseline → hyperparameter tuning → proposed method → ablation |
  141. | `experiment-craft` | Debug and iterate on existing experiments: 5-step diagnostic flow |
  142. | `experiment-iterative-coder` | Iterative code refinement: plan → code → evaluate → refine cycles with lint/test scoring |
  143. | `paper-writing` | Academic sections: 11-step workflow with LaTeX templates and section-by-section guidance |
  144. | `paper-review` | Pre-submission self-review: 5-aspect checklist, adversarial stress-testing |
  145. | `paper-rebuttal` | Peer-review rebuttals: score diagnosis, comment prioritization, 18 tactical writing rules |
  146. | `evo-memory` | Persistent research memory: Ideation Memory + Experimentation Memory across cycles |
  147. | `study-workflow` | Publication-quality research workflow diagram as PNG via image generation |
  148. </details>
  149. <details>
  150. <summary><b>Extended skill library — 87 skills total</b></summary>
  151. | Skill | What it does |
  152. |---|---|
  153. | `ablation-planner` | Design ablations from a reviewer's perspective for paper submission |
  154. | `alphaxiv` | Quick single-paper lookup via AlphaXiv LLM-optimized summaries |
  155. | `analyze-results` | Compute statistics, generate comparison tables from ML experiment results |
  156. | `arxiv` | Search, download, and summarize papers from arXiv |
  157. | `auto-paper-improvement-loop` | Autonomously improve a generated paper via GPT review → fix → recompile |
  158. | `auto-review-loop` | Autonomous multi-round research review loop via Codex MCP |
  159. | `auto-review-loop-llm` | Same review loop using any OpenAI-compatible LLM API |
  160. | `auto-review-loop-minimax` | Same review loop using MiniMax API |
  161. | `citation-audit` | Verify every bibliographic entry is real, correctly attributed, and in context |
  162. | `claims-drafting` | Draft patent claims for an invention |
  163. | `comm-lit-review` | Communications-domain literature review (wireless, networking, satellite, cellular) |
  164. | `deepxiv` | Search and progressively read open-access papers through DeepXiv |
  165. | `dse-loop` | Autonomous design space exploration for computer architecture and EDA |
  166. | `embodiment-description` | Write detailed embodiment descriptions for patent specifications |
  167. | `exa-search` | AI-powered web search via Exa with content extraction |
  168. | `experiment-audit` | Audit experiment integrity via cross-model review before claiming results |
  169. | `experiment-bridge` | Bridge from EXPERIMENT_PLAN.md to GPU-deployed initial results |
  170. | `experiment-plan` | Turn a proposal into a claim-driven experiment roadmap |
  171. | `experiment-queue` | SSH job queue for multi-seed/multi-config ML experiments with OOM-aware retry |
  172. | `feishu-notify` | Send notifications to Feishu/Lark |
  173. | `figure-description` | Process patent figures and generate formal drawing descriptions |
  174. | `figure-spec` | Deterministic publication-quality diagrams from JSON to editable SVG |
  175. | `formula-derivation` | Structure and derive research formulas into paper-ready derivation packages |
  176. | `gemini-search` | Broad literature discovery via Gemini |
  177. | `grant-proposal` | Draft structured grant proposals (KAKENHI, NSF, NSFC, ERC, DFG, SNSF, ARC, NWO) |
  178. | `idea-creator` | Generate and rank research ideas given a broad direction |
  179. | `idea-discovery` | Full pipeline: lit review → idea generation → novelty check → critical review |
  180. | `idea-discovery-robot` | Same pipeline adapted for robotics and embodied AI |
  181. | `invention-structuring` | Structure a raw invention into a formal invention disclosure |
  182. | `jurisdiction-format` | Compile patent into CN/US/EP jurisdiction-specific filing format |
  183. | `kill-argument` | Adversarial two-thread review: strongest rejection memo → point-by-point defense |
  184. | `mermaid-diagram` | Generate Mermaid diagrams (.mmd + .md) with syntax verification |
  185. | `meta-optimize` | Analyze ARIS usage logs and propose harness optimizations |
  186. | `monitor-experiment` | Monitor running experiments, check progress, collect results |
  187. | `novelty-check` | Verify research idea novelty against recent literature |
  188. | `openalex` | Search via OpenAlex for open citation data and institutional metadata |
  189. | `overleaf-sync` | Two-way sync between local paper directory and Overleaf via Git bridge |
  190. | `paper-claim-audit` | Verify every number and comparison in the paper matches raw result files |
  191. | `paper-compile` | Compile LaTeX to PDF, fix errors, verify output |
  192. | `paper-figure` | Generate publication-quality figures and tables from experiment results |
  193. | `paper-illustration` | AI illustrations for academic papers via Gemini image generation |
  194. | `paper-illustration-image2` | Same via Codex native image generation |
  195. | `paper-plan` | Generate structured outline from review conclusions and experiment results |
  196. | `paper-poster` | Conference poster (A0/A1 PDF + editable PPTX + SVG) from a compiled paper |
  197. | `paper-slides` | Conference slides (Beamer PDF + editable PPTX) with speaker notes |
  198. | `paper-talk` | End-to-end conference talk pipeline: paper → outline → Beamer + PPTX → export |
  199. | `paper-write` | Draft LaTeX section by section from an outline |
  200. | `patent-novelty-check` | Assess patent novelty and non-obviousness against prior art |
  201. | `patent-pipeline` | Full patent drafting: CN/US/EP support, invention patents and utility models |
  202. | `patent-review` | External patent examiner review of a patent application |
  203. | `pixel-art` | Generate pixel art SVG illustrations for READMEs and docs |
  204. | `prior-art-search` | Search patent databases and academic literature for prior art |
  205. | `proof-checker` | Rigorous mathematical proof verification and fixing workflow |
  206. | `proof-writer` | Write rigorous mathematical proofs for ML/AI theory |
  207. | `qzcli` | Manage GPU compute jobs on the Qizhi (启智) platform |
  208. | `rebuttal` | Submission rebuttal pipeline with coverage enforcement and venue limits |
  209. | `research-ideation` | Multi-persona ideation → ELO ranking → manuscript-quality proposal |
  210. | `research-lit` | Search and analyze papers, find related work, summarize key ideas |
  211. | `research-pipeline` | Full pipeline: idea discovery → implementation → review → paper writing |
  212. | `research-refine` | Turn a vague direction into a problem-anchored, frontier-aware method plan |
  213. | `research-refine-pipeline` | Chain research-refine + experiment-plan in one shot |
  214. | `research-review` | Deep critical review of research via Codex MCP |
  215. | `research-wiki` | Persistent research knowledge base across the full research lifecycle |
  216. | `resubmit-pipeline` | Orchestrate text-only paper resubmission to a different venue |
  217. | `result-to-claim` | Judge what claims experiment results support before writing |
  218. | `run-experiment` | Deploy and run ML experiments on local, remote, Vast.ai, or Modal GPU |
  219. | `semantic-scholar` | Search published papers via Semantic Scholar API with citation metadata |
  220. | `serverless-modal` | Run GPU workloads on Modal — training, fine-tuning, inference |
  221. | `slides-polish` | Per-page Codex review + targeted python-pptx / Beamer fixes |
  222. | `specification-writing` | Write full patent specification from claims and invention disclosure |
  223. | `system-profile` | Profile scripts, processes, GPU, memory, interconnect — structured reports |
  224. | `training-check` | Periodic WandB metric checks to catch NaN/divergence/idle GPUs early |
  225. | `vast-gpu` | Rent, manage, and destroy GPU instances on vast.ai |
  226. | `writing-systems-papers` | Paragraph-level blueprint for 10–12 page systems papers (OSDI, SOSP, ASPLOS) |
  227. </details>
  228. ### Add a skill
  229. 1. Create `skills/my-skill/SKILL.md` with YAML frontmatter:
  230. ```markdown
  231. ---
  232. id: my-skill
  233. description: One-line description shown in the planner.
  234. allowed-tools: Bash # grants bash tool-calling with error feedback
  235. required-keys: [HF_TOKEN] # optional; skill is filtered out if key missing
  236. ---
  237. Your skill instructions here.
  238. ```
  239. 2. Register in `skills/skills.json`:
  240. ```json
  241. { "id": "my-skill", "description": "One-line description shown in the planner." }
  242. ```
  243. ---
  244. ## 🔐 Environment variables
  245. ### Required
  246. | Variable | Used for |
  247. |---|---|
  248. | `OPENROUTER_API_KEY` | Core LLM inference (all nodes) |
  249. ### Skill-gated (optional)
  250. | Variable | Skills that use it |
  251. |---|---|
  252. | `HF_TOKEN` | Skills accessing Hugging Face Hub |
  253. | `GITHUB_TOKEN` | Skills querying GitHub repos/issues |
  254. | `S2_API_KEY` | Semantic Scholar API |
  255. | `OPENAI_API_KEY` | Skills using OpenAI-compatible endpoints |
  256. Missing skill keys automatically filter out dependent skills at startup.
  257. ### Tuning (all optional)
  258. | Variable | Default | Purpose |
  259. |---|---|---|
  260. | `MODEL_NAME` | — | Override the inference model |
  261. | `INFERENCE_BASE_URL` | — | Custom OpenAI-compatible endpoint |
  262. | `REVIEWER_MODEL` | — | Second model for quality gate (e.g. `openai/gpt-4o`); falls back to `MODEL_NAME` if unset |
  263. | `INPUT_TOKEN_COST_PER_MILLION` | — | Estimate remaining LLM calls |
  264. | `OUTPUT_TOKEN_COST_PER_MILLION` | — | Estimate remaining LLM calls |
  265. | `LOOKBACK` | `3` | History steps visible per LLM call |
  266. | `MAX_REVIEW_ROUNDS` | `1` | Writing review/revision passes |
  267. | `MAX_TOOL_ROUNDS` | `16` | Max bash tool-calling rounds per skill |
  268. | `MAX_LOOP_ITERATIONS` | `20` | Max iterations per research loop |
  269. | `MIN_CALLS_TO_CONTINUE` | `3` | Stop loop when estimated remaining calls falls below this |
  270. | `OUTPUT_LANGUAGE` | auto-detect | Force output language (e.g. `"French"`); ASCII-only topics default to English |
  271. ---
  272. ## 🗂️ Project layout
  273. ```text
  274. nano-scientist/
  275. ├── main.py # CLI entry point
  276. ├── src/
  277. │ ├── flow.py # PocketFlow wiring (3 loops + compile/fix)
  278. │ ├── nodes.py # 7 nodes + helpers
  279. │ └── utils.py # LLM client, cost tracking, BibTeX utils
  280. ├── skills/ # 87 modular research skills
  281. │ ├── skills.json # skill index (id + description)
  282. │ └── <skill-name>/
  283. │ └── SKILL.md # instructions + YAML frontmatter
  284. ├── outputs/ # generated reports (git-ignored)
  285. └── .env # API keys (git-ignored)
  286. ```
  287. ---
  288. ## 🤝 Join the Community
  289. - [Open an issue](https://github.com/AI4Scientist/nano-scientist/issues) — bug reports, feature requests, skill ideas
  290. - [Submit a PR](https://github.com/AI4Scientist/nano-scientist/pulls) — new skills are one `SKILL.md` file
  291. ---
  292. ## 📌 Citation
  293. If you use Nano-scientist in your research, please cite:
  294. ```bibtex
  295. @software{nano_scientist2026,
  296. title = {Nano-scientist: Autonomous Research Agent for Budget-Constrained Scientific Reports},
  297. author = {{AI4Scientist Team}},
  298. year = {2026},
  299. url = {https://github.com/AI4Scientist/nano-scientist}
  300. }
  301. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.