DeepScholar 🔬

A personal deep-research assistant built on Hy3 (Tencent's 295B-A21B MoE model, 256K context), inspired by the staged-agent architecture of the FARS paper (FARS: A Fully Automated Research System Deployed at Scale, arXiv:2606.31651).

You give it a research question; it clarifies scope with you, plans the investigation, searches and reads real sources, and produces a long-form report with verifiable inline citations — plus a machine-auditable trail of every artifact it produced along the way.

Question ──▶ ① Clarify ──▶ ② Plan ──▶ ③ Search ──▶ ④ Write ──▶ ⑤ Verify ──▶ report.md
                │             │           │            │            │
                └─────────────┴───────────┴────────────┴────────────┘
                        shared auditable workspace (runs/<run>/)

Why this design

From FARS (arXiv:2606.31651)

FARS concept	DeepScholar adaptation
Stage-specific agents (Ideation → Planning → Experiment → Writing)	Clarify → Plan → Search → Write → Verify, each with clear inputs/outputs
Shared workspace as persistent memory + auditable artifact store	Every stage reads/writes files under runs/<run>/; no hidden state
Machine-readable experiment contract	plan/plan.json: sections × evidence-needed × concrete queries
Three-tier knowledge base (raw text → summaries → synthesized survey)	sources/raw/ → sources/notes/ → sources/survey.md
Evidence organization before prose generation	report/blueprint.json maps every claim to source ids before drafting
Citation/numerical verification & integrity failure modes	Stage 5 audits 6 adapted failure modes (hallucinated citation, number mismatch, overstatement, …)
Boundary checks + bounded retry (circuit breaker)	Plan validation retries once; verification applies exactly one fix pass

From Hy3

• OpenAI-compatible endpoint (vLLM/SGLang) — DeepScholar is just an API client; run the model wherever you like.
• reasoning_effort switch per request — DeepScholar spends thinking budget where it matters: no_think for bulk per-source summarization, high for planning, synthesis, writing, and verification (see config.yaml).
• 256K context — whole-corpus synthesis (survey, polish, audit) in a single call.
• Anti-hallucination posture ("answer when grounded, state when evidence is missing") matches the citation-grounded writing rules.

From practitioner research workflows (reference images)

• Bounded "grill-me" clarification: at most 5 decision-relevant questions, each with a recommended default; decisions are frozen into an ADR-style record (brief/clarifications.md) and a contract brief (brief/brief.md).
• A run README as the 5-minute status summary, regenerated after every stage.
• Manifests & stage gates: manifest.json records what ran, when, and with what result, so an interrupted run can be resumed exactly where it stopped.
• Never silently rewrite old records: revision fixes only listed issues; artifacts of earlier stages stay untouched.

Quick start

1. Serve Hy3

# vLLM (8× H20-3e or similar)
vllm serve tencent/Hy3 \
  --tensor-parallel-size 8 \
  --speculative-config.method mtp \
  --speculative-config.num_speculative_tokens 2 \
  --tool-call-parser hy_v3 --reasoning-parser hy_v3 \
  --enable-auto-tool-choice --port 8000 --served-model-name hy3

(Or SGLang — see the Hy3 README. Any OpenAI-compatible endpoint works; point llm.base_url at it.)

2. Install & run

cd deepscholar
pip install -r requirements.txt

# interactive (asks up to 5 clarification questions)
python -m deepscholar.cli research "What are the current approaches to memory in LLM agents, and which are production-ready?"

# non-interactive (accept recommended defaults)
python -m deepscholar.cli research "..." --yes

# resume an interrupted run / check status
python -m deepscholar.cli resume runs/20260721-101500-what-are-...
python -m deepscholar.cli status runs/20260721-101500-what-are-...

3. Read the output

runs/<run>/
  README.md              # 5-minute status summary
  manifest.json          # stage gates + token usage
  brief/                 # question, clarification ADRs, frozen brief
  plan/plan.json|.md     # research contract
  sources/registry.json  # every source: id, url, status, content hash
  sources/raw|notes/     # tier-1 raw text, tier-2 structured notes
  sources/survey.md      # tier-3 cross-source synthesis
  report/blueprint.json  # claim → source-id map (evidence before prose)
  report/report.md       # ★ final report with [S001]-style citations + References
  audit/audit.md         # integrity audit verdict + issues

Every inline citation [S001] resolves through sources/registry.json to a URL and through sources/notes/S001.md to the exact evidence used — so you can audit any claim in seconds.

Search backends

Out of the box DeepScholar uses the free arXiv API plus direct page fetching. For general web search, point search.searxng_url in config.yaml at any SearXNG instance (self-hosted or public). No paid API keys required.

Configuration

Everything lives in config.yaml: endpoint, per-stage reasoning_effort, search limits, report language (auto/en/zh), max sections.

Limitations

• Retrieval quality is bounded by arXiv + your SearXNG instance; paywalled sources are skipped.
• The verifier audits claims against notes, not the raw source, so subtle summarization errors can pass; open sources/raw/ for anything critical.
• One fix pass only, by design (FARS-style circuit breaker) — the audit report tells you what remains.