NanoResearch

End-to-End Autonomous AI Research Engine — From Idea to Full Paper, Fully Automated

Quick Start · Showcase · Pipeline · Claude Code · Feishu Bot

🔬 NanoResearch actually runs computational experiments — it doesn't just generate code, it submits jobs to GPU clusters, collects real results, generates figures, and outputs a complete LaTeX paper backed by real experimental data. Every number, table, and chart in the paper comes from actual experiment outputs, not LLM fabrication.

📖 Table of Contents

📊 Real-World Output Showcase
⚡ CLI Demo
📢 News
✨ Key Features
🆚 Why NanoResearch
🎯 Use Cases
🖼️ Showcase
CLI: Plain vs TUI
🔬 Pipeline
📦 Quick Start
🧩 Claude Code Mode
⚙️ Configuration
💻 CLI Reference
🍪 Examples & Demos
📂 Output Structure
💬 Feishu Bot
🏗️ Project Structure
❓ FAQ
🎯 Roadmap
📋 Requirements
🙏 Acknowledgements
🤝 Contributing
📝 Citation
📄 License

🔝 Back to top

📊 Real-World Output Showcase

Figures below are generated by NanoResearch from real experiment runs. All curves, tables, and visualizations are derived from actual training logs and execution outputs — not LLM fabrication.

_{Experimental Results}

_{Main Results & Comparison}

_{Ablation & Visualization}

Every figure is produced by the pipeline from genuine experiment artifacts; all data traces back to executed runs.

⚡ CLI Demo

The command-line interface (CLI) offers both a full-screen TUI and classic streaming logs. Below is a TUI theme and interface demo (color themes and layout). For other entry points (e.g. Claude Code, Feishu bot), see the corresponding sections in this README.

🖥️ CLI / TUI
demo_cli_tui_theme.mp4

_{TUI layout, color theme switching, and improved on-screen structure}

🔝 Back to top

📢 News

[2026-03] 📄 NanoResearch documentation and showcase overhaul — local image references and real-world output display.
[2026-03] 🚀 NanoResearch v1.0 officially released — the first end-to-end autonomous AI research engine, covering literature search through LaTeX paper output.
[2026-03] 🔬 Core capabilities: real GPU/SLURM execution, evidence-driven writing, 9-stage resumable pipeline, per-stage multi-model routing.

📜 Release History

Date	Milestone
2026-03	Feishu bot, Claude Code integration, NeurIPS/ICML/arXiv templates
2026-03	SLURM cluster auto-submission, checkpoint & resume, multi-model routing
2026-02	Core pipeline and Agent architecture

✨ Key Features

🔬 Real Experiments	🧠 Multi-Model Routing	🔄 Checkpoint & Resume	📝 Evidence-Grounded Writing
Auto-submit GPU/SLURM jobs and collect real metrics	Configure different models for each pipeline stage	Resume from any failed stage without restart	Paper data is bound to real experiment results
📊 Auto Figure Gen	🏗️ Multi-Format Templates	🤖 Multi-Interface Control	💰 Cost Efficient
Code-based charts + AI architecture diagrams	NeurIPS / ICML / arXiv one-click switch	CLI / Claude Code / Feishu Bot	As low as $0.5/paper with DeepSeek

🆚 Why NanoResearch

Feature	Traditional AI Writing Tools	NanoResearch
Literature Search	Partial	✅ OpenAlex + Semantic Scholar
Experiment Design	❌	✅ Auto-generated blueprints
Code Generation	Partial	✅ Complete runnable code
GPU Experiment Execution	❌	✅ Local / SLURM auto-training
Results Analysis	❌	✅ Parse real training logs
Paper Figures	❌	✅ From real data
Paper Writing	Outline/draft	✅ Full LaTeX paper
Checkpoint & Resume	❌	✅ Any stage recoverable
Multi-Model Collaboration	Single model	✅ Per-stage routing

🎯 Use Cases

Research Prototyping — Quickly turn a research idea into a full experiment + paper workspace
Autonomous Experiments — Let the system generate code, submit GPU training, and analyze results
Benchmark Generation — Batch-run multiple topics with reproducible experiment results
Paper Draft Assistance — Produce LaTeX drafts grounded in real experimental data
Research Audit Trail — Complete workspaces, intermediate artifacts, and logs for full traceability

🖼️ Showcase

Break free from the manual research grind

No more debugging failed experiments, wrangling data by hand, or writing papers from scratch —
NanoResearch automates the full research workflow so you can focus on real innovation.

Overview

NanoResearch is a unified research pipeline that automates the full paper-production workflow:

starts from a research topic
searches and synthesizes relevant literature
proposes an experiment blueprint
generates runnable code and scripts
executes locally or on SLURM
analyzes real outputs
generates figures
writes a LaTeX paper draft
reviews and revises the result

It is designed around resumable workspaces, multi-model routing, and grounded writing so that downstream paper content is tied to actual experiment evidence instead of free-form draft generation.

Why NanoResearch

Most "AI paper writers" stop at outlines or prose. NanoResearch is built for a deeper loop:

End-to-end pipeline: topic to exportable paper workspace
Grounded writing: writing consumes structured experiment evidence, figures, and citations
Checkpoint + resume: failed stages can be resumed from the last saved state
Execution-aware: supports local execution and SLURM-backed workflows
Multi-model by stage: route ideation, coding, writing, and review to different models
Exportable outputs: clean paper/code/figure bundles for sharing or submission prep

Use cases

Research prototyping — quickly turn a fresh idea into a full experiment-and-paper workspace
Benchmark generation — create repeatable topic-to-paper runs across multiple tasks
Autonomous experimentation — let the system generate code, execute runs, and analyze outputs
Paper drafting from evidence — produce LaTeX drafts grounded in actual experiment artifacts
Internal research tooling — use workspaces, manifests, and stage artifacts as an auditable research log

Showcase

Generated research workspace

A typical NanoResearch run produces a clean, inspectable workspace containing:

literature and planning artifacts
runnable experiment code
generated figures
LaTeX paper sources and bibliography
a final exported bundle for sharing or submission prep

Example outputs

_{Framework Overview}	_{Generated Paper Examples}
_{Main Results (Real Experiment Data)}	_{Ablation Study}

🔬 Pipeline

Research Topic
     ↓
 IDEATION → PLANNING → SETUP → CODING → EXECUTION → ANALYSIS → FIGURE_GEN → WRITING → REVIEW
     ↓
 Exported: paper.pdf / paper.tex / references.bib / figures / code / data

📋 Stage Details

Stage	What It Does
`IDEATION`	Search literature, identify gaps, propose hypotheses, collect must-cite candidates
`PLANNING`	Turn the idea into a concrete experiment blueprint (datasets, baselines, metrics, ablations)
`SETUP`	Prepare repositories, dependencies, models, and datasets
`CODING`	Generate a complete runnable experiment project (training scripts, data loading, model definition)
`EXECUTION`	Run experiments locally or on SLURM, with automatic retry and debugging
`ANALYSIS`	Parse training logs and metrics into structured evidence
`FIGURE_GEN`	Create architecture diagrams, result comparison charts, and ablation figures
`WRITING`	Write and compile the LaTeX paper from experiment evidence and citations
`REVIEW`	Multi-perspective review, issue detection, and revision

🚀 EXECUTION Stage Core Capabilities

The EXECUTION stage is NanoResearch's core differentiator:

Auto SLURM Submission — Generate sbatch scripts, submit to cluster, monitor job status
Local GPU Execution — Auto-detect available GPUs and manage training processes
Auto Debug & Retry — Analyze error logs on failure, fix code, and re-execute automatically
Real-Time Log Monitoring — Track training progress and metric changes
Hybrid Execution — Automatically switch between local and cluster based on task complexity

📦 Quick Start

Follow these steps to go from install to first run in about 5 minutes.

Step 1: Install

git clone https://github.com/OpenRaiser/NanoResearch.git
cd NanoResearch
pip install -e ".[dev]"

Step 2: Configure

Tip

Create ~/.nanobot/config.json. Replace base_url and api_key with your own OpenAI-compatible API endpoint.

View full configuration example

{
  "research": {
    "base_url": "https://your-openai-compatible-endpoint/v1/",
    "api_key": "your-api-key",
    "template_format": "neurips2025",
    "execution_profile": "local_quick",
    "writing_mode": "hybrid",
    "max_retries": 2,
    "auto_create_env": true,
    "auto_download_resources": true,
    "ideation": { "model": "your-model", "temperature": 0.5, "max_tokens": 16384, "timeout": 600.0 },
    "planning": { "model": "your-model", "temperature": 0.2, "max_tokens": 16384, "timeout": 600.0 },
    "code_gen": { "model": "your-model", "temperature": 0.1, "max_tokens": 16384, "timeout": 600.0 },
    "writing": { "model": "your-model", "temperature": 0.4, "max_tokens": 16384, "timeout": 600.0 },
    "figure_gen": {
      "model": "gemini-3.1-flash-image-preview",
      "image_backend": "gemini",
      "temperature": null,
      "timeout": 300.0
    },
    "review": { "model": "your-model", "temperature": 0.3, "max_tokens": 16384, "timeout": 300.0 }
  }
}

Environment variable overrides: NANORESEARCH_BASE_URL / NANORESEARCH_API_KEY / NANORESEARCH_TIMEOUT

Step 3: Validate & Run

# Validate config
nanoresearch run --topic "Adaptive Sparse Attention Mechanisms" --dry-run

# Run the full pipeline
nanoresearch run --topic "Adaptive Sparse Attention Mechanisms" --format neurips2025 --verbose

# Resume from checkpoint (if a stage fails)
nanoresearch resume --workspace ~/.nanobot/workspace/research/{session_id} --verbose

# Export paper
nanoresearch export --workspace ~/.nanobot/workspace/research/{session_id} --output ./my_paper

Step 4: Expected Output

After the pipeline completes, you will have paper figures and LaTeX sources backed by real experiment data.

🤖 Recommended Models

Stage	Task	Recommended	Budget-Friendly
`ideation`	Literature search + hypothesis	DeepSeek-V3.2	DeepSeek-V3.2
`planning`	Experiment design	Claude Sonnet 4.6	DeepSeek-V3.2
`code_gen`	Code generation	GPT-5.2-Codex / Claude Opus 4.6	DeepSeek-V3.2
`writing`	Paper writing	Claude Opus 4.6 / Claude Sonnet 4.6	DeepSeek-V3.2
`figure_prompt`	Figure description	GPT-5.2	DeepSeek-V3.2
`figure_code`	Chart plotting code	Claude Opus 4.6	DeepSeek-V3.2
`figure_gen`	AI architecture diagrams	Gemini 3.1 Flash (native image)	Gemini 3.1 Flash
`review`	Review + revision	Claude Sonnet 4.6 / Gemini Flash	DeepSeek-V3.2

Note: All text models are accessed through a single OpenAI-compatible endpoint. Set temperature: null for models that don't support it (e.g., Codex, o-series). The figure_gen stage uses the Gemini native image generation API and requires "image_backend": "gemini".

💰 Estimated Cost

Scenario	Models	Time	Estimated Cost
Draft only (skip experiments)	All DeepSeek-V3.2	~30 min	~$0.5 - $1
Draft only (skip experiments)	Mixed (Claude writing, DeepSeek others)	~30 min	~$3 - $8
Full pipeline (with experiments)	All DeepSeek-V3.2	2 - 5 hours	~$1 - $3
Full pipeline (with experiments)	Mixed (Claude/GPT code+writing)	2 - 5 hours	~$10 - $20

"Draft only" mode skips experiment stages via "skip_stages": ["SETUP", "CODING", "EXECUTION", "ANALYSIS"].

🧩 Claude Code Mode

In addition to the Python CLI, NanoResearch can be driven directly through Claude Code — no API keys required.

How It Works

In Claude Code integration mode, Claude Code itself is the research engine:

WebSearch replaces external APIs for literature retrieval (arXiv, Semantic Scholar, Google Scholar)
Bash runs experiment code, submits SLURM jobs, and compiles LaTeX
File read/write generates experiment code, papers, and structured artifacts

Quick Start

git clone https://github.com/OpenRaiser/NanoResearch.git
cd NanoResearch
claude
/project:research "Your Research Topic Here"

Available Commands

Command	Description
`/project:research <topic>`	Run the full 9-stage pipeline
`/project:ideation <topic>`	Stage 1: Literature search + hypothesis generation
`/project:planning`	Stage 2: Experiment blueprint design
`/project:experiment`	Stages 3-5: Setup + code generation + execution
`/project:analysis`	Stage 6: Results analysis
`/project:writing`	Stages 7-8: Figure generation + paper writing
`/project:review`	Stage 9: Multi-perspective review + revision
`/project:status`	Show current pipeline status
`/project:resume`	Resume pipeline from last checkpoint

💡 Tips

Architecture diagrams: Use the Nano Banana series of image models for high-quality architecture diagrams. In Claude Code mode, call image generation APIs via Bash in the figure_gen stage.
LaTeX compilation: Use tectonic instead of pdflatex. Install with: conda install -c conda-forge tectonic.
Checkpoint & resume: All stage artifacts are tracked in manifest.json, enabling resume from any stage.
Compatible with Python CLI: Workspaces created in Claude Code mode are fully compatible with the Python CLI, and vice versa.

Codex Integration

In addition to Claude Code, NanoResearch now exposes a project-level entrypoint for Codex. Codex does not need a second pipeline or a dedicated --mode codex flag. It should reuse the existing CLI, workspace, manifest, and PaperMode behavior already implemented in the repo.

How to use it

# 1. Clone the project
git clone https://github.com/OpenRaiser/NanoResearch.git
cd NanoResearch

# 2. Open the repo in Codex
# 3. Ask Codex to read AGENTS.md first

Codex entrypoint: AGENTS.md

How Codex should interpret the repo

Treat the repository as an end-to-end autonomous research pipeline, not a generic coding project
Prefer the existing nanoresearch CLI / workspace / orchestrator behavior
Map user intent onto the existing research, ideation, planning, experiment, analysis, writing, review, status, and resume flows
Keep outputs compatible with the existing workspaces and manifest.json

Survey and original modes

Codex should follow the same topic-prefix convention used by the CLI:

original: Topic
survey:short: Topic
survey:standard: Topic
survey:long: Topic

These prefixes already feed the repo's PaperMode parsing logic. Codex should reuse that behavior rather than introducing a new interface.

Execution profiles

Execution Profiles

Profile	Behavior
`fast_draft`	Lightweight drafting, fast iteration
`local_quick`	Prefer local execution; upgrade to SLURM when needed
`cluster_full`	Cluster-first execution for heavy workloads

Model Routing

NanoResearch routes different stages to different model configs through a unified configuration layer, letting you mix models by task instead of forcing one model to do everything.

Routable Stages

ideation — Literature search & ideas
planning — Experiment design
experiment — Experiment-related
code_gen — Code generation
writing — Paper writing
figure_prompt — Figure description
figure_code — Chart code
figure_gen — Image generation
review — Paper review
revision — Revision

Built around OpenAI-compatible endpoints with per-stage override support.

Literature Search API Keys (optional)

The IDEATION stage uses OpenAlex and Semantic Scholar. Works without API keys (anonymous), but with lower rate limits.

Service	How to Get	Config Key	Env Variable
OpenAlex	Free	`openalex_api_key`	`OPENALEX_API_KEY`
Semantic Scholar	Free	`s2_api_key`	`S2_API_KEY`

Paper Formats

Templates are auto-discovered from nanoresearch/templates/. Built-in formats:

Format	Purpose
`arxiv`	arXiv preprint
`icml`	ICML conference
`neurips`	NeurIPS conference
`neurips2025`	NeurIPS 2025

nanoresearch run --topic "Graph Foundation Models for Biology" --format neurips2025

💻 CLI Reference

Command	Purpose
`nanoresearch run --topic "..."`	Start a new pipeline run
`nanoresearch resume --workspace ...`	Resume from last checkpoint
`nanoresearch status --workspace ...`	Show per-stage status and artifacts
`nanoresearch list`	List saved research sessions
`nanoresearch export --workspace ...`	Export a clean output bundle
`nanoresearch config`	Print effective config with masked secrets
`nanoresearch inspect --workspace ...`	Inspect saved artifacts
`nanoresearch health`	Run environment/config health checks
`nanoresearch delete <session_id>`	Remove a saved session

nanoresearch --help

🍪 Examples & Demos

Official examples and advanced usage to get you started with NanoResearch:

👉 Browse Examples & Demos

Quick example commands

# Full pipeline + verbose logs
nanoresearch run --topic "Adaptive Sparse Attention" --format neurips2025 --verbose

# Export and inspect
nanoresearch export --workspace ~/.nanobot/workspace/research/{session_id} --output ./paper_out

Paper-only (skip experiments): Set "skip_stages": ["SETUP", "CODING", "EXECUTION", "ANALYSIS"] in config.

🔝 Back to top

📂 Output Structure

Exported paper directory

my_paper/
├── paper.pdf
├── paper.tex
├── references.bib
├── figures/
├── code/
├── data/
└── manifest.json

Full workspace (with intermediate artifacts)

~/.nanobot/workspace/research/{session_id}/
├── manifest.json          # Pipeline state tracker
├── papers/                # Literature search artifacts
├── plans/                 # Experiment blueprints and analysis
├── experiment/            # Generated experiment code + results
├── figures/               # Generated paper figures
├── drafts/                # Paper drafts and review feedback
├── output/                # Final export (main.tex / main.pdf)
└── logs/                  # Run logs

💬 Feishu Bot

NanoResearch includes a built-in Feishu (Lark) bot for triggering pipelines, checking status, and receiving papers directly in chat — no terminal needed.

Setup & Launch

1. Install dependency

pip install lark-oapi

2. Configure

Create a custom app at open.feishu.cn and obtain App ID and App Secret:

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Or add to ~/.nanobot/config.json:

{
  "feishu": {
    "app_id": "cli_xxx",
    "app_secret": "xxx"
  }
}

3. Launch

nanoresearch feishu          # Start the bot
nanoresearch feishu -v       # Verbose logging

Connects via WebSocket (no public server or webhook URL required). Press Ctrl+C to stop.

Supported Commands

Command	Description
`/run <topic>`	Start a research pipeline for the given topic
`/status`	Check current task progress
`/list`	List all historical research sessions
`/stop`	Stop the currently running pipeline
`/export`	Re-export the most recent completed research
`/new`	Clear conversation memory, start fresh
`/help`	Show help message

You can also chat naturally — the bot acts as an AI research assistant with conversation memory. When the pipeline finishes, it automatically sends the compiled paper.pdf to the chat.

🏗️ Project Structure

nanoresearch/
├── nanoresearch/
│   ├── cli.py              # 🖥️ CLI entry point
│   ├── config.py           # ⚙️ Configuration management
│   ├── agents/             # 🧠 Stage-specific agents
│   │   ├── ideation.py     #    Literature search & hypothesis
│   │   ├── planning.py     #    Experiment blueprint
│   │   ├── coding.py       #    Code generation
│   │   ├── execution/      #    Local/cluster execution
│   │   ├── analysis/       #    Results analysis
│   │   ├── figure_gen/     #    Figure generation
│   │   ├── writing/        #    Paper writing
│   │   └── review/         #    Review & revision
│   ├── pipeline/           # 🔄 Orchestrators & state machine
│   ├── schemas/            # 📋 Pydantic data models
│   ├── prompts/            # 💬 YAML prompt templates
│   ├── templates/          # 📄 LaTeX Jinja2 templates
│   └── latex/              # 🔧 LaTeX auto-fixer
├── mcp_server/             # 🔌 MCP tool server
├── skills/                 # 🎯 Claude Code skills
└── pyproject.toml

❓ FAQ

Does NanoResearch run real experiments?

Yes. The pipeline generates runnable code, executes it locally or on SLURM, and feeds resulting artifacts into analysis, figure generation, and writing stages. Paper data comes from real experiments, not model fabrication.

Can I resume a failed run?

Yes. Workspaces are checkpointed by stage. nanoresearch resume --workspace ... continues from the last incomplete or failed stage.

Do I need one model for every stage?

No. NanoResearch supports per-stage model routing, but you can also use a single model for all stages.

Is the generated paper submission-ready?

Treat it as a high-quality draft, not a final submission. The system generates a complete paper workspace and compiled PDF, but human review and revision are still necessary.

What LaTeX compiler is recommended?

Use tectonic. Conda's texlive may be missing pdflatex.fmt, causing hard-to-fix compilation failures. tectonic auto-downloads all required TeX packages.

conda install -c conda-forge tectonic

🎯 Roadmap

🔝 Back to top

🤝 Contributing

We welcome contributions from developers and researchers.

👥 Community

Join our WeChat group for discussion, Q&A, and collaboration. Scan to join:

🔝 Back to top

📋 Requirements

Python 3.10+
OpenAI-compatible API endpoint (for text model stages)
Optional: image model access (for some figure generation)
tectonic or pdflatex (for PDF compilation)

🙏 Acknowledgements

claude-scholar — Scientific research skills for Claude Code

⭐ Star History

📝 Citation

@software{nanoresearch2026,
  title = {NanoResearch},
  author = {OpenRaiser},
  year = {2026},
  url = {https://github.com/OpenRaiser/NanoResearch}
}

📄 License

MIT

_{NanoResearch is for educational, research, and technical exchange purposes only.}

FilesExpand file tree

README_en.md

Latest commit

History

README_en.md

File metadata and controls

NanoResearch

📖 Table of Contents

📊 Real-World Output Showcase

⚡ CLI Demo

📢 News

✨ Key Features

🆚 Why NanoResearch

🎯 Use Cases

🖼️ Showcase

Overview

Why NanoResearch

Use cases

Showcase

Generated research workspace

Example outputs

🔬 Pipeline

📦 Quick Start

Step 1: Install

Step 2: Configure

Step 3: Validate & Run

Step 4: Expected Output

🤖 Recommended Models

💰 Estimated Cost

🧩 Claude Code Mode

Quick Start

Available Commands

Codex Integration

How to use it

How Codex should interpret the repo

Survey and original modes

Execution profiles

Execution Profiles

Model Routing

Literature Search API Keys (optional)

Paper Formats

💻 CLI Reference

🍪 Examples & Demos

📂 Output Structure

💬 Feishu Bot

Supported Commands

🏗️ Project Structure

❓ FAQ

🎯 Roadmap

🤝 Contributing

👥 Community

📋 Requirements

🙏 Acknowledgements

⭐ Star History

📝 Citation

📄 License