Auditable deep research for open-ended questions

DeepResearch is a local-first CLI that plans a research path, searches the web through Tavily, extracts atomic evidence with a local Ollama model, evaluates whether coverage is strong enough, and writes a final report with traceable citations.

Get Started View on GitHub
9 graph nodes Meta-planner, micro-planner, search, extraction, curation, evaluation, auditor, chapter synthesis, global synthesis.
Local-first runtime Ollama handles reasoning locally while Tavily focuses on discovery.
Flexible delivery Markdown, PDF, and optional Discord delivery from the same run. 
deepresearch "Compare web research APIs for deep analysis workflows"

meta_planner    decomposes the question into chapters
micro_planner   plans sub-topics for each chapter
source_manager  searches Tavily for candidates
extractor       turns passages into atomic evidence
context_manager curates and deduplicates evidence
evaluator       deterministic coverage assessment
auditor         devil's advocate chapter review
sub_synthesizer writes each chapter draft
global_synth    assembles the final report

What makes it auditable

  • Every final report is grounded in evidence objects, source URLs, and quotations.
  • The runtime can stop early when additional cycles no longer improve coverage.
  • Configuration is validated strictly instead of silently accepting unknown fields.

Sample Output

This PDF report shows the kind of editorial output DeepResearch can generate from a single CLI run: a structured comparison of Lightpanda versus Playwright with a final document ready to inspect or share.

Generated Report

Will OpenAI end up bankrupt?

Open the bundled PDF example to see the final layout, writing style, and report structure produced by the application.

Open sample PDF Download report.pdf
deepresearch "Will OpenAI end up bankrupt?" --pdf report.pdf

Run Configuration

Model gemma4:e4b
GPU RTX 5060 Ti
Context Window 128000 tokens
Output Mode PDF export
  • Question: The report investigates the financial, legal, and operational risks of OpenAI.
  • Generated locally: The example reflects a local Ollama-backed run rather than a hosted black-box pipeline.
  • Auditability preserved: The final document remains aligned with DeepResearch's evidence-first reporting model.

Key Features

The cards below describe the core capabilities of DeepResearch: the hierarchical LangGraph pipeline, the Map-Reduce chapter architecture, the runtime controls, and the final report behavior exposed by the CLI.

Map-Reduce Research Pipeline

A hierarchical LangGraph pipeline decomposes research into independent chapters, investigates each one, and merges the results into a final report.

Graph Nodes

meta_plannerDecomposes the question into research chapters
micro_plannerCreates sub-topics and search intents per chapter
source_managerSearches Tavily and filters candidate sources
extractorConverts passages into atomic evidence
context_managerDeduplicates evidence and updates the dossier
evaluatorDeterministic coverage check — no LLM calls
auditorDevil's advocate review; can reject chapters
sub_synthesizerWrites a chapter draft from curated evidence
global_synthesizerAssembles all chapter drafts into the final report

Traceable Evidence

The project is built for auditable outputs instead of opaque summaries.

Final Report Guarantees

EvidenceAtomic evidence units are attached to sources
SourcesURLs and quotations remain available for inspection
Executive answerThe CLI prints the executive summary to standard output
# Default behavior If you do not pass --markdown or --pdf, DeepResearch writes report.md in the current directory.

Local Ollama Runtime

Models run through Ollama locally, with CLI overrides for model name and context size.

CLI Overrides

--model NAMESwitch the active Ollama model for one run
--num-ctx NOverride the model context window
--max-iterations NSet the maximum research depth
--verbosity 0-3Control local progress logging detail

Tavily Source Discovery

Search is delegated to Tavily, then narrowed down to sources with usable raw content.

Search Controls

api_keyTavily API key in the user config
results_per_queryControls how many sources are fetched per query
max_raw_content_charsCaps extracted raw content per candidate
min_source_charsFilters unusably short pages

Strict Config Bootstrap

The runtime bootstraps an editable config tree under the user home directory on first load.

Materialized Paths

~/.deepresearch/config/config.tomlMain user-editable runtime config
~/.deepresearch/config/prompts/Editable prompt templates copied from package resources
# Validation model Unknown sections and unsupported fields are rejected instead of being silently ignored.

Multiple Delivery Paths

The same run can write files locally or optionally deliver the report through Discord.

Output Modes

--markdown PATHWrite the final report as Markdown
--pdf PATHRender a PDF through WeasyPrint
--discordSend the report to the configured Discord user

Research Pipeline

DeepResearch uses a hierarchical Map-Reduce architecture. Each chapter is researched independently through its own search-extract-evaluate loop, then all chapter drafts are merged into a single final report.

01

Decompose

The meta-planner breaks the question into independent research chapters, each covering a distinct angle.

02

Plan Chapter

The micro-planner creates focused sub-topics with search terms and intents for the current chapter.

03

Discover

The source manager searches Tavily and selects candidates with enough raw content to inspect.

04

Extract

The extractor turns passages into atomic evidence attached to source URLs and quotations.

05

Curate

The context manager deduplicates evidence, merges near-duplicates, and updates the working dossier.

06

Evaluate

A deterministic evaluator tracks coverage and stagnation signals to decide whether to continue, audit, or stop.

07

Audit

The auditor reviews chapter evidence as a devil's advocate and can reject it back to the micro-planner.

08

Chapter Synthesis

The sub-synthesizer produces a structured chapter draft from the curated evidence for each completed chapter.

09

Final Report

The global synthesizer assembles all chapter drafts into the final report with executive answer and citations.

Stop Conditions

  • CONTEXT_SATURATION when the synthesis token budget has been effectively consumed.
  • PLAN_COMPLETED when every chapter has been audited and synthesized.
  • MAX_ITERATIONS_REACHED when the run reaches the configured hard cap.
  • STUCK_NO_SOURCES when repeated cycles fail to produce new evidence or useful sources.

Operational Surface

  • Runtime safeguards include search batch size, retry attempts, and consecutive failure limits.
  • LangSmith tracing can be enabled without changing the CLI surface.
  • Test coverage in the repository targets graph flow, config loading, prompts, observability, Discord delivery, and deterministic behavior.

Configuration Surface

Default Runtime Config

[model]
model_name = "qwen3.5:9b"
base_url = "http://127.0.0.1:11434"
temperature_meta_planner = 0.3
temperature_micro_planner = 0.2
temperature_extractor = 0.0
temperature_auditor = 0.3
temperature_sub_synthesizer = 0.1
temperature_global_synthesizer = 0.1
num_ctx = 100000
num_predict = 8192

[search]
results_per_query = 5
max_raw_content_chars = 24000
min_source_chars = 300

[runtime]
max_iterations = 8
search_batch_size = 3
max_chapters = 5
max_topic_depth = 2
max_audit_rejections = 2
verbosity = 0

Optional Services

[langsmith]
enabled = false
tracing = true
project = "DeepResearch"

[discord]
token = "YOUR_BOT_TOKEN"
user_id = "YOUR_DISCORD_USER_ID"
output = "pdf"

PDF output uses WeasyPrint, so minimal Linux systems may need standard system libraries in addition to Python packages.

Getting Started

Requirements

DeepResearch expects Python 3.11 or newer, Ollama running locally, at least one local model pulled, and a Tavily API key configured in the editable runtime config.

ollama pull qwen3.5:9b
ollama serve

Install With pipx

pipx install git+https://github.com/arrase/deepresearch.git

Source Install

git clone https://github.com/arrase/deepresearch.git
cd deepresearch
python -m venv .venv
source .venv/bin/activate
pip install -e .

First Config Bootstrap

The config tree is created on first load. Before a real run, set a Tavily API key in the generated config file.

[search]
api_key = "YOUR_TAVILY_API_KEY"
results_per_query = 5
max_raw_content_chars = 24000
min_source_chars = 300

First Successful Run

deepresearch "Compare web research APIs for deep analysis workflows"

Common Examples

deepresearch "Assess the current commercial readiness of fusion startups" --markdown outputs/fusion.md

deepresearch "Compare web research APIs for deep analysis workflows" --pdf outputs/research-apis.pdf

deepresearch "Track the strongest open-source coding models this quarter" --model llama3.1:8b --num-ctx 65536

deepresearch "Evaluate the current state of multimodal local models" --verbosity 2

deepresearch "Research question" --config-root .deepresearch-config