NanoResearch Workflow Release

NanoResearch is a personalized, self-evolving research automation workflow that turns a user-specified topic into a grounded paper artifact through ideation, planning, experiment execution, figure generation, writing, review, and continual memory/skill/policy evolution.

This repository is code-focused. It does not include benchmark replay packs, private traces, trained private router weights, API keys, or generated experiment workspaces.

Contents

• nanoresearch/: the NanoResearch runtime: CLI, orchestrators, router policy, user profile, ideation, planning, experiment/code execution, analysis, figure generation, writing, review, memory evolution, skill evolution, prompts, schemas, and templates.
• mcp_server/: local MCP-style research tools for search, paper reading, LaTeX/PDF utilities, and figure generation.
• tools/: off-policy SDPO router trace export and training scripts.
• skills/: bundled NanoResearch workflow skills.
• tests/: focused regression tests for routing, profiles, execution, planning, and writing.
• docs/case_pdfs/: five example PDFs generated by NanoResearch.
• scripts/: release hygiene and paper-claim coverage checks.

Install

python -m venv .venv
source .venv/bin/activate
pip install -e .

For development checks:

pip install -e '.[dev]'
pytest

Configure Models

NanoResearch reads configuration from ~/.nanoresearch/config.json by default, or from --config path/to/config.json.

Minimal local config:

{
  "research": {
    "base_url": "https://your-openai-compatible-endpoint/v1",
    "api_key": "<redacted>",
    "execution_profile": "local_quick",
    "template_format": "neurips",
    "same_router_hindsight_sdpo_enabled": false,
    "memory_enabled": true,
    "memory_evolution_enabled": true,
    "skill_evolution_enabled": 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-coding-model", "temperature": null, "max_tokens": 16384, "timeout": 600.0 },
    "experiment": { "model": "your-model", "temperature": 0.1, "max_tokens": 8192, "timeout": 600.0 },
    "writing": { "model": "your-model", "temperature": 0.4, "max_tokens": 16384, "timeout": 600.0 },
    "review": { "model": "your-model", "temperature": 0.3, "max_tokens": 16384, "timeout": 300.0 }
  }
}

Do not commit real API keys. Keep them in your local config or environment only.

The ReAct experiment shell tool is disabled by default in this public release. Enable it only inside a trusted sandbox/workspace:

export NANORESEARCH_ENABLE_SHELL_TOOL=1

Initialize The User Profile

The user initialization flow creates ~/.nanoresearch/profile/user_profile.json and ~/.nanoresearch/profile/user_profile.md. The profile is injected into ideation, planning, experiment, writing, and router decisions.

nanoresearch init
nanoresearch profile show
nanoresearch profile export --format markdown

The interview asks for research taste, resource budget, writing style, venue preference, figure/caption preference, and feedback priorities. Internally this builds router hints used by the adaptive planner.

Run The Full Workflow

Run an original research project from topic to exported paper artifacts:

nanoresearch run \
  --topic "Design a lightweight graph-learning method for robust node classification" \
  --format neurips \
  --profile local_quick

Useful modes:

nanoresearch run --topic "..." --dry-run
nanoresearch run --topic "..." --profile fast_draft
nanoresearch run --topic "..." --profile cluster_full --config ~/.nanoresearch/config.json

Survey-style prefixes are supported:

nanoresearch run --topic "survey:short: retrieval-augmented code agents"
nanoresearch run --topic "survey:standard: AI agents for scientific discovery"

Pipeline

The default deep workflow executes these stages:

1. IDEATION: searches literature, extracts quantitative evidence, identifies gaps, proposes and checks hypotheses.
2. PLANNING: converts the selected idea into a structured experiment blueprint and runs an LLM blueprint review/correction loop.
3. EXPERIMENT: generates code, prepares runtime, executes local or cluster experiments, repairs failures, and collects results.
4. FIGURE_GEN: builds paper-facing figures only from available evidence, with safeguards against presenting synthetic or diagnostic data as verified results.
5. WRITING: writes a grounded LaTeX paper from the blueprint, results, citations, and user profile.
6. REVIEW: reviews and revises the draft without participating in adaptive memory/skill retrieval, preserving an external-review role.

Before major stages, the router selects relevant memories and skills, emits a compact prompt plan, and logs the decision. After trajectories complete, reusable lessons are distilled into the memory store and skill bank.

Outputs

At the end of a successful run, NanoResearch exports a clean output folder and prints its path. Typical files are:

paper.pdf
paper.tex
references.bib
figures/
code/
data/
manifest.json

Raw workspaces are stored under ~/.nanoresearch/workspace/research/ unless configured otherwise.

Resume And Inspect

nanoresearch list
nanoresearch status --workspace ~/.nanoresearch/workspace/research/<session_id>
nanoresearch resume --workspace ~/.nanoresearch/workspace/research/<session_id>

Router SDPO Training

The release includes the code path for training the hindsight router policy from router traces:

python tools/export_router_sdpo_offpolicy.py \
  --input-dir runs/router_trace_dir \
  --output artifacts/router_sdpo/train_manifest.jsonl \
  --stats-output artifacts/router_sdpo/export_stats.json \
  --drop-report-output artifacts/router_sdpo/drop_reasons.json \
  --tokenizer-path <base-router-model>

torchrun --nproc_per_node=8 tools/train_router_sdpo_offpolicy.py \
  --model-path <base-router-model> \
  --manifest artifacts/router_sdpo/train_manifest.jsonl \
  --output-dir artifacts/router_sdpo/checkpoint

Enable a trained router at runtime by setting same_router_hindsight_sdpo_enabled=true and configuring either router_sdpo_model_path or router_sdpo_base_url / router_sdpo_model_name in ResearchConfig.

Release Checks

From the repository root:

bash run_smoke.sh

This runs hygiene checks and verifies that the implementation contains the mechanisms described by the paper: user/profile conditioning, router memory/skill selection, SDPO router training/export, memory evolution, skill evolution, planning review, experiment execution/repair, evidence-grounded writing, and review isolation.