Six AI agents with distinct personalities collaborate to research any topic and produce a comprehensive, multi-perspective PDF paper.
DeepeResearch is a multi-agent research system where 6 AI agents — each with a unique personality, methodology, and worldview — work together to research any topic you give them.
The agents research in parallel, share their findings with each other, refine their analysis based on what others discovered, and finally a neutral Scribe agent compiles everything into a professionally formatted PDF paper.
The result is a nuanced, multi-perspective research paper that no single-prompt system could produce.
Topic
│
▼
┌──────────────┐
│ Orchestrator │ assigns models, manages rounds
└──────┬───────┘
│
├── Round 1 (6 agents parallel, with web search)
├── Collaboration Bus (shared knowledge)
├── Follow-up Questions → Refinement
├── Round 2 (agents refine, if budget allows)
└── Scribe Agent → PDF Paper
# Clone the repo
git clone https://github.com/Acharnite/deepresearch.git
cd deepresearch
# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate # Linux/macOS
# .venv\Scripts\activate # Windows
# Install
pip install -e ".[dev]"
# Set your API key (at least one)
export OPENCODE_API_KEY="your-key-here"
# or: export OPENAI_API_KEY="your-key-here"
# Run
deepresearch run "The future of renewable energy" --webPrerequisites:
- Python 3.11+
- Git
- WeasyPrint system deps (Linux only):
sudo apt install libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-dev
No API key? Run a dry test without LLM calls:
deepresearch run "Test topic" --dry-run| Agent | Emoji | Temperature | Approach |
|---|---|---|---|
| Curious Teenager | 🔍 | 0.90 | Naive curiosity, explores tangents, pop culture |
| Skeptical Academic | 📚 | 0.30 | Demands evidence, challenges assumptions |
| Creative Artist | 🎨 | 0.95 | Metaphors, unexpected connections, storytelling |
| Pragmatic Engineer | ⚙️ | 0.40 | Implementation, trade-offs, feasibility |
| Philosophical Thinker | 🤔 | 0.85 | Ethics, first principles, deeper meaning |
| Data-Driven Analyst | 📊 | 0.20 | Metrics, statistics, quantitative evidence |
The Scribe has no personality — neutral academic tone at temperature 0.3, acting as an impartial compiler.
DeepeResearch supports three modes: Same Model (default), Random Models, and Manual Selection. The default model is opencode/go (Opencode AI, free tier).
Model IDs auto-route to the correct provider. No manual configuration needed.
| Prefix | Provider | Env Variable |
|---|---|---|
opencode/ |
Opencode AI | OPENCODE_API_KEY |
openrouter/ |
OpenRouter | OPENROUTER_API_KEY |
groq/ |
Groq | GROQ_API_KEY |
together/ |
Together | TOGETHER_API_KEY |
deepseek/ |
DeepSeek | DEEPSEEK_API_KEY |
cohere/ |
Cohere | COHERE_API_KEY |
google/ |
GOOGLE_API_KEY |
|
anthropic/ |
Anthropic | ANTHROPIC_API_KEY |
ollama/ |
Ollama (local) | — |
DeepeResearch supports local inference via Ollama (auto-discovered on localhost:11434) and configurable endpoints for llama.cpp, vLLM, and SGLang. See ADR-0005 for the auto-install and auto-discovery design.
Research agents search the web in real-time using SearXNG (self-hosted meta-search engine) with academic engines including arXiv, PubMed, Semantic Scholar, and Wikipedia. Agents can make up to 5 search queries per generation, refining based on initial results.
- Rate limiter: 1 search per 5 seconds (global)
- Result cache: 200 entries with LRU eviction
- Health tracking:
/api/system/searchendpoint - Fallback: DuckDuckGo via ddgs (optional extra, deprecated)
# Quick research
deepresearch run "Quantum computing" --quick
# Deep research with web dashboard
deepresearch run "Renewable energy" --deep --web
# Start dashboard standalone
deepresearch servedeepresearch run <topic> \
[--quick | --deep] \
[--time <minutes>] \
[--same | --random-models | --manual-models] \
[--output ./path.pdf] \
[--web] [--web-host 0.0.0.0] [--web-port 8080] \
[--dry-run]
deepresearch serve [--host 0.0.0.0] [--port 8080]
deepresearch profiles list
deepresearch models list
Real-time web dashboard built with FastAPI + SSE streaming.
deepresearch serve # Start dashboard at http://localhost:8080/
deepresearch run "Topic" --web # Run session with dashboard- Pipeline visualization — see current phase at a glance
- Agent progress cards — real-time status badges (idle, researching, compiling, done)
- Live streaming output — per-agent text panels showing LLM generation in real-time
- Event log — timestamped phase transitions, agent completions, clarification rounds
- Model selector — dropdown for "same" mode, per-agent selectors for "manual" mode
- Q&A visualization — graph showing agent interactions and clarification flows
- Scribe output panel — watch the scribe compile the final paper live
- Cancel / Delete sessions — stop running sessions or clear completed ones
- Download PDF/HTML — one-click download when research completes
- Settings tab — manage API keys (9 providers) and local model endpoints
- System Log tab — in-browser log viewer with level filtering
- Dark-themed UI — GitHub-dark aesthetic, color-coded state badges
workspaces/deepresearch/
├── pyproject.toml
├── src/deepresearch/
│ ├── main.py # CLI entry point
│ ├── models.py # Pydantic data models
│ ├── config.py # YAML config loading
│ ├── orchestrator.py # Session lifecycle FSM
│ ├── agents/
│ │ ├── research_agent.py # 6 personality research agents
│ │ ├── scribe_agent.py # Compilation and synthesis agent
│ │ └── registry.py # Agent factory and dispatch
│ ├── collaboration/bus.py # In-memory shared knowledge bus
│ ├── llm/client.py # LiteLLM async wrapper with retry + streaming
│ ├── output/pdf_generator.py # WeasyPrint PDF rendering
│ ├── tools/web_search.py # SearXNG web search (with ddgs fallback)
│ ├── prompts/ # Research, scribe, collaboration prompts
│ └── web/
│ ├── server.py # FastAPI server (REST + SSE)
│ ├── dashboard.html # Single-page dark-themed UI
│ ├── sessions.py # MultiSessionManager
│ └── settings_manager.py # API key & local endpoint management
├── src/profiles/default.yaml # 6 agent personality profiles
├── src/config/models.yaml # LLM model definitions
└── tests/ # 311 tests
cd workspaces/deepresearch
pytest tests/ -v # Run all tests
pytest tests/ -v --cov=deepresearch # With coverage- Design doc:
docs/design/README.md - ADR-0001: Multi-Agent Research Architecture
- ADR-0002: Agent Personality and Model Selection
- ADR-0003: Web Frontend and Multi-Session
- ADR-0004: Test Findings and Architecture Fixes
- ADR-0005: Auto-Install and Auto-Discover Local LLM Backends
- ADR-0006: Web Search and Tool Calling
- ADR-0007: Clarification Protocol and Refinement
- ADR-0008: Dashboard Enhancements
- ADR-0009: CI/CD Pipeline and Distribution
- ADR-0010: Dynamic Research Rounds
- ADR-0011: Session Concurrency Limits and Web Search Throttling
- ADR-0012: SearXNG Migration (Replace ddgs)
- ADR-0013: SearXNG Optimization and Academic Engines
MIT — part of the KodeHold project.