1 line
108 KiB
JSON
1 line
108 KiB
JSON
{"repo": "acharnite/deepresearch", "files": {"README.md": {"ec9e9cf0a452339a7e94c4eb74b43f16ee48aced": {"t": 1785747280.1489332, "n": 9644, "h": "3e649c0817783568", "c": "# DeepeResearch — Multi-Agent AI Research System\n\n[](https://github.com/Acharnite/deepresearch/actions/workflows/ci.yml)\n[](https://www.python.org/)\n[](https://github.com/Acharnite/deepresearch/actions/workflows/ci.yml)\n[](LICENSE)\n\n> Six AI agents with distinct personalities collaborate to research any topic and produce a comprehensive, multi-perspective PDF paper.\n\n---\n\n## What is DeepeResearch?\n\nDeepeResearch 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.\n\nThe 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.\n\nThe result is a nuanced, multi-perspective research paper that no single-prompt system could produce.\n\n```\n Topic\n │\n ▼\n┌──────────────┐\n│ Orchestrator │ assigns models, manages rounds\n└──────┬───────┘\n │\n ├── Round 1 (6 agents parallel, with web search)\n ├── Collaboration Bus (shared knowledge)\n ├── Follow-up Questions → Refinement\n ├── Round 2 (agents refine, if budget allows)\n └── Scribe Agent → PDF Paper\n```\n\n---\n\n## Quick Install\n\n```bash\n# Clone the repo\ngit clone https://github.com/Acharnite/deepresearch.git\ncd deepresearch\n\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate # Linux/macOS\n# .venv\\Scripts\\activate # Windows\n\n# Install\npip install -e \".[dev]\"\n\n# Set your API key (at least one)\nexport OPENCODE_API_KEY=\"your-key-here\"\n# or: export OPENAI_API_KEY=\"your-key-here\"\n\n# Run\ndeepresearch run \"The future of renewable energy\" --web\n```\n\n**Prerequisites:**\n- Python 3.11+\n- Git\n- WeasyPrint system deps (Linux only): `sudo apt install libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-dev`\n\n**No API key?** Run a dry test without LLM calls:\n```bash\ndeepresearch run \"Test topic\" --dry-run\n```\n\n---\n\n## Agent Personalities\n\n| Agent | Emoji | Temperature | Approach |\n|-------|-------|:-----------:|----------|\n| Curious Teenager | 🔍 | 0.90 | Naive curiosity, explores tangents, pop culture |\n| Skeptical Academic | 📚 | 0.30 | Demands evidence, challenges assumptions |\n| Creative Artist | 🎨 | 0.95 | Metaphors, unexpected connections, storytelling |\n| Pragmatic Engineer | ⚙️ | 0.40 | Implementation, trade-offs, feasibility |\n| Philosophical Thinker | 🤔 | 0.85 | Ethics, first principles, deeper meaning |\n| Data-Driven Analyst | 📊 | 0.20 | Metrics, statistics, quantitative evidence |\n\nThe **Scribe** has no personality — neutral academic tone at temperature 0.3, acting as an impartial compiler.\n\n---\n\n## Model Selection\n\nDeepeResearch supports three modes: **Same Model** (default), **Random Models**, and **Manual Selection**. The default model is `opencode/go` (Opencode AI, free tier).\n\n### Provider Prefix Routing\n\nModel IDs auto-route to the correct provider. No manual configuration needed.\n\n| Prefix | Provider | Env Variable |\n|--------|----------|-------------|\n| `opencode/` | Opencode AI | `OPENCODE_API_KEY` |\n| `openrouter/` | OpenRouter | `OPENROUTER_API_KEY` |\n| `groq/` | Groq | `GROQ_API_KEY` |\n| `together/` | Together | `TOGETHER_API_KEY` |\n| `deepseek/` | DeepSeek | `DEEPSEEK_API_KEY` |\n| `cohere/` | Cohere | `COHERE_API_KEY` |\n| `google/` | Google | `GOOGLE_API_KEY` |\n| `anthropic/` | Anthropic | `ANTHROPIC_API_KEY` |\n| `ollama/` | Ollama (local) | — |\n\n### Local LLM Backends\n\nDeepeResearch supports local inference via Ollama (auto-discovered on localhost:11434) and configurable endpoints for llama.cpp, vLLM, and SGLang. See **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)** for the auto-install and auto-discovery design.\n\n---\n\n## Tool Calling (Web Search)\n\nResearch 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.\n\n- **Rate limiter**: 1 search per 5 seconds (global)\n- **Result cache**: 200 entries with LRU eviction\n- **Health tracking**: `/api/system/search` endpoint\n- **Fallback**: DuckDuckGo via ddgs (optional extra, deprecated)\n\n---\n\n## CLI Usage\n\n```bash\n# Quick research\ndeepresearch run \"Quantum computing\" --quick\n\n# Deep research with web dashboard\ndeepresearch run \"Renewable energy\" --deep --web\n\n# Start dashboard standalone\ndeepresearch serve\n```\n\n### All Options\n\n```\ndeepresearch run <topic> \\\n [--quick | --deep] \\\n [--time <minutes>] \\\n [--same | --random-models | --manual-models] \\\n [--output ./path.pdf] \\\n [--web] [--web-host 0.0.0.0] [--web-port 8080] \\\n [--dry-run]\n\ndeepresearch serve [--host 0.0.0.0] [--port 8080]\ndeepresearch profiles list\ndeepresearch models list\n```\n\n---\n\n## Web Dashboard\n\nReal-time web dashboard built with FastAPI + SSE streaming.\n\n```bash\ndeepresearch serve # Start dashboard at http://localhost:8080/\ndeepresearch run \"Topic\" --web # Run session with dashboard\n```\n\n### Features\n\n- **Pipeline visualization** — see current phase at a glance\n- **Agent progress cards** — real-time status badges (idle, researching, compiling, done)\n- **Live streaming output** — per-agent text panels showing LLM generation in real-time\n- **Event log** — timestamped phase transitions, agent completions, clarification rounds\n- **Model selector** — dropdown for \"same\" mode, per-agent selectors for \"manual\" mode\n- **Q&A visualization** — graph showing agent interactions and clarification flows\n- **Scribe output panel** — watch the scribe compile the final paper live\n- **Cancel / Delete sessions** — stop running sessions or clear completed ones\n- **Download PDF/HTML** — one-click download when research completes\n- **Settings tab** — manage API keys (9 providers) and local model endpoints\n- **System Log tab** — in-browser log viewer with level filtering\n- **Dark-themed UI** — GitHub-dark aesthetic, color-coded state badges\n\n---\n\n## Project Structure\n\n```\nworkspaces/deepresearch/\n├── pyproject.toml\n├── src/deepresearch/\n│ ├── main.py # CLI entry point\n│ ├── models.py # Pydantic data models\n│ ├── config.py # YAML config loading\n│ ├── orchestrator.py # Session lifecycle FSM\n│ ├── agents/\n│ │ ├── research_agent.py # 6 personality research agents\n│ │ ├── scribe_agent.py # Compilation and synthesis agent\n│ │ └── registry.py # Agent factory and dispatch\n│ ├── collaboration/bus.py # In-memory shared knowledge bus\n│ ├── llm/client.py # LiteLLM async wrapper with retry + streaming\n│ ├── output/pdf_generator.py # WeasyPrint PDF rendering\n│ ├── tools/web_search.py # SearXNG web search (with ddgs fallback)\n│ ├── prompts/ # Research, scribe, collaboration prompts\n│ └── web/\n│ ├── server.py # FastAPI server (REST + SSE)\n│ ├── dashboard.html # Single-page dark-themed UI\n│ ├── sessions.py # MultiSessionManager\n│ └── settings_manager.py # API key & local endpoint management\n├── src/profiles/default.yaml # 6 agent personality profiles\n├── src/config/models.yaml # LLM model definitions\n└── tests/ # 311 tests\n```\n\n---\n\n## Testing\n\n```bash\ncd workspaces/deepresearch\npytest tests/ -v # Run all tests\npytest tests/ -v --cov=deepresearch # With coverage\n```\n\n---\n\n## Design Documents\n\n- **Design doc**: `docs/design/README.md`\n- **[ADR-0001](docs/adr/ADR-0001-multi-agent-research-architecture.md)**: Multi-Agent Research Architecture\n- **[ADR-0002](docs/adr/ADR-0002-agent-personality-and-model-selection.md)**: Agent Personality and Model Selection\n- **[ADR-0003](docs/adr/ADR-0003-web-frontend-and-multi-session.md)**: Web Frontend and Multi-Session\n- **[ADR-0004](docs/adr/ADR-0004-test-findings-and-architecture-fixes.md)**: Test Findings and Architecture Fixes\n- **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)**: Auto-Install and Auto-Discover Local LLM Backends\n- **[ADR-0006](docs/adr/ADR-0006-web-search-and-tool-calling.md)**: Web Search and Tool Calling\n- **[ADR-0007](docs/adr/ADR-0007-clarification-protocol-and-refinement.md)**: Clarification Protocol and Refinement\n- **[ADR-0008](docs/adr/ADR-0008-dashboard-enhancements.md)**: Dashboard Enhancements\n- **[ADR-0009](docs/adr/ADR-0009-cicd-pipeline-and-distribution.md)**: CI/CD Pipeline and Distribution\n- **[ADR-0010](docs/adr/ADR-0010-dynamic-research-rounds.md)**: Dynamic Research Rounds\n- **[ADR-0011](docs/adr/ADR-0011-concurrency-limits-and-web-search-throttling.md)**: Session Concurrency Limits and Web Search Throttling\n- **[ADR-0012](docs/adr/ADR-0012-replace-ddgs-with-searxng.md)**: SearXNG Migration (Replace ddgs)\n- **[ADR-0013](docs/adr/ADR-0013-searxng-optimization.md)**: SearXNG Optimization and Academic Engines\n\n---\n\n## License\n\nMIT — part of the [KodeHold](https://github.com/kiffer5000/kodehold) project.\n"}, "bc70534e2637f99177617a6732f370e259dfcab7": {"t": 1785772114.7486963, "n": 9644, "h": "3e649c0817783568", "c": "# DeepeResearch — Multi-Agent AI Research System\n\n[](https://github.com/Acharnite/deepresearch/actions/workflows/ci.yml)\n[](https://www.python.org/)\n[](https://github.com/Acharnite/deepresearch/actions/workflows/ci.yml)\n[](LICENSE)\n\n> Six AI agents with distinct personalities collaborate to research any topic and produce a comprehensive, multi-perspective PDF paper.\n\n---\n\n## What is DeepeResearch?\n\nDeepeResearch 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.\n\nThe 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.\n\nThe result is a nuanced, multi-perspective research paper that no single-prompt system could produce.\n\n```\n Topic\n │\n ▼\n┌──────────────┐\n│ Orchestrator │ assigns models, manages rounds\n└──────┬───────┘\n │\n ├── Round 1 (6 agents parallel, with web search)\n ├── Collaboration Bus (shared knowledge)\n ├── Follow-up Questions → Refinement\n ├── Round 2 (agents refine, if budget allows)\n └── Scribe Agent → PDF Paper\n```\n\n---\n\n## Quick Install\n\n```bash\n# Clone the repo\ngit clone https://github.com/Acharnite/deepresearch.git\ncd deepresearch\n\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate # Linux/macOS\n# .venv\\Scripts\\activate # Windows\n\n# Install\npip install -e \".[dev]\"\n\n# Set your API key (at least one)\nexport OPENCODE_API_KEY=\"your-key-here\"\n# or: export OPENAI_API_KEY=\"your-key-here\"\n\n# Run\ndeepresearch run \"The future of renewable energy\" --web\n```\n\n**Prerequisites:**\n- Python 3.11+\n- Git\n- WeasyPrint system deps (Linux only): `sudo apt install libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-dev`\n\n**No API key?** Run a dry test without LLM calls:\n```bash\ndeepresearch run \"Test topic\" --dry-run\n```\n\n---\n\n## Agent Personalities\n\n| Agent | Emoji | Temperature | Approach |\n|-------|-------|:-----------:|----------|\n| Curious Teenager | 🔍 | 0.90 | Naive curiosity, explores tangents, pop culture |\n| Skeptical Academic | 📚 | 0.30 | Demands evidence, challenges assumptions |\n| Creative Artist | 🎨 | 0.95 | Metaphors, unexpected connections, storytelling |\n| Pragmatic Engineer | ⚙️ | 0.40 | Implementation, trade-offs, feasibility |\n| Philosophical Thinker | 🤔 | 0.85 | Ethics, first principles, deeper meaning |\n| Data-Driven Analyst | 📊 | 0.20 | Metrics, statistics, quantitative evidence |\n\nThe **Scribe** has no personality — neutral academic tone at temperature 0.3, acting as an impartial compiler.\n\n---\n\n## Model Selection\n\nDeepeResearch supports three modes: **Same Model** (default), **Random Models**, and **Manual Selection**. The default model is `opencode/go` (Opencode AI, free tier).\n\n### Provider Prefix Routing\n\nModel IDs auto-route to the correct provider. No manual configuration needed.\n\n| Prefix | Provider | Env Variable |\n|--------|----------|-------------|\n| `opencode/` | Opencode AI | `OPENCODE_API_KEY` |\n| `openrouter/` | OpenRouter | `OPENROUTER_API_KEY` |\n| `groq/` | Groq | `GROQ_API_KEY` |\n| `together/` | Together | `TOGETHER_API_KEY` |\n| `deepseek/` | DeepSeek | `DEEPSEEK_API_KEY` |\n| `cohere/` | Cohere | `COHERE_API_KEY` |\n| `google/` | Google | `GOOGLE_API_KEY` |\n| `anthropic/` | Anthropic | `ANTHROPIC_API_KEY` |\n| `ollama/` | Ollama (local) | — |\n\n### Local LLM Backends\n\nDeepeResearch supports local inference via Ollama (auto-discovered on localhost:11434) and configurable endpoints for llama.cpp, vLLM, and SGLang. See **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)** for the auto-install and auto-discovery design.\n\n---\n\n## Tool Calling (Web Search)\n\nResearch 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.\n\n- **Rate limiter**: 1 search per 5 seconds (global)\n- **Result cache**: 200 entries with LRU eviction\n- **Health tracking**: `/api/system/search` endpoint\n- **Fallback**: DuckDuckGo via ddgs (optional extra, deprecated)\n\n---\n\n## CLI Usage\n\n```bash\n# Quick research\ndeepresearch run \"Quantum computing\" --quick\n\n# Deep research with web dashboard\ndeepresearch run \"Renewable energy\" --deep --web\n\n# Start dashboard standalone\ndeepresearch serve\n```\n\n### All Options\n\n```\ndeepresearch run <topic> \\\n [--quick | --deep] \\\n [--time <minutes>] \\\n [--same | --random-models | --manual-models] \\\n [--output ./path.pdf] \\\n [--web] [--web-host 0.0.0.0] [--web-port 8080] \\\n [--dry-run]\n\ndeepresearch serve [--host 0.0.0.0] [--port 8080]\ndeepresearch profiles list\ndeepresearch models list\n```\n\n---\n\n## Web Dashboard\n\nReal-time web dashboard built with FastAPI + SSE streaming.\n\n```bash\ndeepresearch serve # Start dashboard at http://localhost:8080/\ndeepresearch run \"Topic\" --web # Run session with dashboard\n```\n\n### Features\n\n- **Pipeline visualization** — see current phase at a glance\n- **Agent progress cards** — real-time status badges (idle, researching, compiling, done)\n- **Live streaming output** — per-agent text panels showing LLM generation in real-time\n- **Event log** — timestamped phase transitions, agent completions, clarification rounds\n- **Model selector** — dropdown for \"same\" mode, per-agent selectors for \"manual\" mode\n- **Q&A visualization** — graph showing agent interactions and clarification flows\n- **Scribe output panel** — watch the scribe compile the final paper live\n- **Cancel / Delete sessions** — stop running sessions or clear completed ones\n- **Download PDF/HTML** — one-click download when research completes\n- **Settings tab** — manage API keys (9 providers) and local model endpoints\n- **System Log tab** — in-browser log viewer with level filtering\n- **Dark-themed UI** — GitHub-dark aesthetic, color-coded state badges\n\n---\n\n## Project Structure\n\n```\nworkspaces/deepresearch/\n├── pyproject.toml\n├── src/deepresearch/\n│ ├── main.py # CLI entry point\n│ ├── models.py # Pydantic data models\n│ ├── config.py # YAML config loading\n│ ├── orchestrator.py # Session lifecycle FSM\n│ ├── agents/\n│ │ ├── research_agent.py # 6 personality research agents\n│ │ ├── scribe_agent.py # Compilation and synthesis agent\n│ │ └── registry.py # Agent factory and dispatch\n│ ├── collaboration/bus.py # In-memory shared knowledge bus\n│ ├── llm/client.py # LiteLLM async wrapper with retry + streaming\n│ ├── output/pdf_generator.py # WeasyPrint PDF rendering\n│ ├── tools/web_search.py # SearXNG web search (with ddgs fallback)\n│ ├── prompts/ # Research, scribe, collaboration prompts\n│ └── web/\n│ ├── server.py # FastAPI server (REST + SSE)\n│ ├── dashboard.html # Single-page dark-themed UI\n│ ├── sessions.py # MultiSessionManager\n│ └── settings_manager.py # API key & local endpoint management\n├── src/profiles/default.yaml # 6 agent personality profiles\n├── src/config/models.yaml # LLM model definitions\n└── tests/ # 311 tests\n```\n\n---\n\n## Testing\n\n```bash\ncd workspaces/deepresearch\npytest tests/ -v # Run all tests\npytest tests/ -v --cov=deepresearch # With coverage\n```\n\n---\n\n## Design Documents\n\n- **Design doc**: `docs/design/README.md`\n- **[ADR-0001](docs/adr/ADR-0001-multi-agent-research-architecture.md)**: Multi-Agent Research Architecture\n- **[ADR-0002](docs/adr/ADR-0002-agent-personality-and-model-selection.md)**: Agent Personality and Model Selection\n- **[ADR-0003](docs/adr/ADR-0003-web-frontend-and-multi-session.md)**: Web Frontend and Multi-Session\n- **[ADR-0004](docs/adr/ADR-0004-test-findings-and-architecture-fixes.md)**: Test Findings and Architecture Fixes\n- **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)**: Auto-Install and Auto-Discover Local LLM Backends\n- **[ADR-0006](docs/adr/ADR-0006-web-search-and-tool-calling.md)**: Web Search and Tool Calling\n- **[ADR-0007](docs/adr/ADR-0007-clarification-protocol-and-refinement.md)**: Clarification Protocol and Refinement\n- **[ADR-0008](docs/adr/ADR-0008-dashboard-enhancements.md)**: Dashboard Enhancements\n- **[ADR-0009](docs/adr/ADR-0009-cicd-pipeline-and-distribution.md)**: CI/CD Pipeline and Distribution\n- **[ADR-0010](docs/adr/ADR-0010-dynamic-research-rounds.md)**: Dynamic Research Rounds\n- **[ADR-0011](docs/adr/ADR-0011-concurrency-limits-and-web-search-throttling.md)**: Session Concurrency Limits and Web Search Throttling\n- **[ADR-0012](docs/adr/ADR-0012-replace-ddgs-with-searxng.md)**: SearXNG Migration (Replace ddgs)\n- **[ADR-0013](docs/adr/ADR-0013-searxng-optimization.md)**: SearXNG Optimization and Academic Engines\n\n---\n\n## License\n\nMIT — part of the [KodeHold](https://github.com/kiffer5000/kodehold) project.\n"}, "a9f8d2e148af41191a9a848433c1d372170d7b10": {"t": 1785772116.033542, "n": 9644, "h": "cc272efe9939cc9f", "c": "# DeepeResearch — Multi-Agent AI Research System\n\n[](https://github.com/Acharnite/deepresearch/actions/workflows/ci.yml)\n[](https://www.python.org/)\n[](https://github.com/Acharnite/deepresearch/actions/workflows/ci.yml)\n[](LICENSE)\n\n> Six AI agents with distinct personalities collaborate to research any topic and produce a comprehensive, multi-perspective PDF paper.\n\n---\n\n## What is DeepeResearch?\n\nDeepeResearch 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.\n\nThe 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.\n\nThe result is a nuanced, multi-perspective research paper that no single-prompt system could produce.\n\n```\n Topic\n │\n ▼\n┌──────────────┐\n│ Orchestrator │ assigns models, manages rounds\n└──────┬───────┘\n │\n ├── Round 1 (6 agents parallel, with web search)\n ├── Collaboration Bus (shared knowledge)\n ├── Follow-up Questions → Refinement\n ├── Round 2 (agents refine, if budget allows)\n └── Scribe Agent → PDF Paper\n```\n\n---\n\n## Quick Install\n\n```bash\n# Clone the repo\ngit clone https://github.com/Acharnite/deepresearch.git\ncd deepresearch\n\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate # Linux/macOS\n# .venv\\Scripts\\activate # Windows\n\n# Install\npip install -e \".[dev]\"\n\n# Set your API key (at least one)\nexport OPENCODE_API_KEY=\"your-key-here\"\n# or: export OPENAI_API_KEY=\"your-key-here\"\n\n# Run\ndeepresearch run \"The future of renewable energy\" --web\n```\n\n**Prerequisites:**\n- Python 3.11+\n- Git\n- WeasyPrint system deps (Linux only): `sudo apt install libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-dev`\n\n**No API key?** Run a dry test without LLM calls:\n```bash\ndeepresearch run \"Test topic\" --dry-run\n```\n\n---\n\n## Agent Personalities\n\n| Agent | Emoji | Temperature | Approach |\n|-------|-------|:-----------:|----------|\n| Curious Teenager | 🔍 | 0.90 | Naive curiosity, explores tangents, pop culture |\n| Skeptical Academic | 📚 | 0.30 | Demands evidence, challenges assumptions |\n| Creative Artist | 🎨 | 0.95 | Metaphors, unexpected connections, storytelling |\n| Pragmatic Engineer | ⚙️ | 0.40 | Implementation, trade-offs, feasibility |\n| Philosophical Thinker | 🤔 | 0.85 | Ethics, first principles, deeper meaning |\n| Data-Driven Analyst | 📊 | 0.20 | Metrics, statistics, quantitative evidence |\n\nThe **Scribe** has no personality — neutral academic tone at temperature 0.3, acting as an impartial compiler.\n\n---\n\n## Model Selection\n\nDeepeResearch supports three modes: **Same Model** (default), **Random Models**, and **Manual Selection**. The default model is `opencode/go` (Opencode AI, free tier).\n\n### Provider Prefix Routing\n\nModel IDs auto-route to the correct provider. No manual configuration needed.\n\n| Prefix | Provider | Env Variable |\n|--------|----------|-------------|\n| `opencode/` | Opencode AI | `OPENCODE_API_KEY` |\n| `openrouter/` | OpenRouter | `OPENROUTER_API_KEY` |\n| `groq/` | Groq | `GROQ_API_KEY` |\n| `together/` | Together | `TOGETHER_API_KEY` |\n| `deepseek/` | DeepSeek | `DEEPSEEK_API_KEY` |\n| `cohere/` | Cohere | `COHERE_API_KEY` |\n| `google/` | Google | `GOOGLE_API_KEY` |\n| `anthropic/` | Anthropic | `ANTHROPIC_API_KEY` |\n| `ollama/` | Ollama (local) | — |\n\n### Local LLM Backends\n\nDeepeResearch supports local inference via Ollama (auto-discovered on localhost:11434) and configurable endpoints for llama.cpp, vLLM, and SGLang. See **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)** for the auto-install and auto-discovery design.\n\n---\n\n## Tool Calling (Web Search)\n\nResearch 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.\n\n- **Rate limiter**: 1 search per 5 seconds (global)\n- **Result cache**: 200 entries with LRU eviction\n- **Health tracking**: `/api/system/search` endpoint\n- **Fallback**: DuckDuckGo via ddgs (optional extra, deprecated)\n\n---\n\n## CLI Usage\n\n```bash\n# Quick research\ndeepresearch run \"Quantum computing\" --quick\n\n# Deep research with web dashboard\ndeepresearch run \"Renewable energy\" --deep --web\n\n# Start dashboard standalone\ndeepresearch serve\n```\n\n### All Options\n\n```\ndeepresearch run <topic> \\\n [--quick | --deep] \\\n [--time <minutes>] \\\n [--same | --random-models | --manual-models] \\\n [--output ./path.pdf] \\\n [--web] [--web-host 0.0.0.0] [--web-port 8080] \\\n [--dry-run]\n\ndeepresearch serve [--host 0.0.0.0] [--port 8080]\ndeepresearch profiles list\ndeepresearch models list\n```\n\n---\n\n## Web Dashboard\n\nReal-time web dashboard built with FastAPI + SSE streaming.\n\n```bash\ndeepresearch serve # Start dashboard at http://localhost:8080/\ndeepresearch run \"Topic\" --web # Run session with dashboard\n```\n\n### Features\n\n- **Pipeline visualization** — see current phase at a glance\n- **Agent progress cards** — real-time status badges (idle, researching, compiling, done)\n- **Live streaming output** — per-agent text panels showing LLM generation in real-time\n- **Event log** — timestamped phase transitions, agent completions, clarification rounds\n- **Model selector** — dropdown for \"same\" mode, per-agent selectors for \"manual\" mode\n- **Q&A visualization** — graph showing agent interactions and clarification flows\n- **Scribe output panel** — watch the scribe compile the final paper live\n- **Cancel / Delete sessions** — stop running sessions or clear completed ones\n- **Download PDF/HTML** — one-click download when research completes\n- **Settings tab** — manage API keys (9 providers) and local model endpoints\n- **System Log tab** — in-browser log viewer with level filtering\n- **Dark-themed UI** — GitHub-dark aesthetic, color-coded state badges\n\n---\n\n## Project Structure\n\n```\nworkspaces/deepresearch/\n├── pyproject.toml\n├── src/deepresearch/\n│ ├── main.py # CLI entry point\n│ ├── models.py # Pydantic data models\n│ ├── config.py # YAML config loading\n│ ├── orchestrator.py # Session lifecycle FSM\n│ ├── agents/\n│ │ ├── research_agent.py # 6 personality research agents\n│ │ ├── scribe_agent.py # Compilation and synthesis agent\n│ │ └── registry.py # Agent factory and dispatch\n│ ├── collaboration/bus.py # In-memory shared knowledge bus\n│ ├── llm/client.py # LiteLLM async wrapper with retry + streaming\n│ ├── output/pdf_generator.py # WeasyPrint PDF rendering\n│ ├── tools/web_search.py # SearXNG web search (with ddgs fallback)\n│ ├── prompts/ # Research, scribe, collaboration prompts\n│ └── web/\n│ ├── server.py # FastAPI server (REST + SSE)\n│ ├── dashboard.html # Single-page dark-themed UI\n│ ├── sessions.py # MultiSessionManager\n│ └── settings_manager.py # API key & local endpoint management\n├── src/profiles/default.yaml # 6 agent personality profiles\n├── src/config/models.yaml # LLM model definitions\n└── tests/ # 311 tests\n```\n\n---\n\n## Testing\n\n```bash\ncd workspaces/deepresearch\npytest tests/ -v # Run all tests\npytest tests/ -v --cov=deepresearch # With coverage\n```\n\n---\n\n## Design Documents\n\n- **Design doc**: `docs/design/README.md`\n- **[ADR-0001](docs/adr/ADR-0001-multi-agent-research-architecture.md)**: Multi-Agent Research Architecture\n- **[ADR-0002](docs/adr/ADR-0002-agent-personality-and-model-selection.md)**: Agent Personality and Model Selection\n- **[ADR-0003](docs/adr/ADR-0003-web-frontend-and-multi-session.md)**: Web Frontend and Multi-Session\n- **[ADR-0004](docs/adr/ADR-0004-test-findings-and-architecture-fixes.md)**: Test Findings and Architecture Fixes\n- **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)**: Auto-Install and Auto-Discover Local LLM Backends\n- **[ADR-0006](docs/adr/ADR-0006-web-search-and-tool-calling.md)**: Web Search and Tool Calling\n- **[ADR-0007](docs/adr/ADR-0007-clarification-protocol-and-refinement.md)**: Clarification Protocol and Refinement\n- **[ADR-0008](docs/adr/ADR-0008-dashboard-enhancements.md)**: Dashboard Enhancements\n- **[ADR-0009](docs/adr/ADR-0009-cicd-pipeline-and-distribution.md)**: CI/CD Pipeline and Distribution\n- **[ADR-0010](docs/adr/ADR-0010-dynamic-research-rounds.md)**: Dynamic Research Rounds\n- **[ADR-0011](docs/adr/ADR-0011-concurrency-limits-and-web-search-throttling.md)**: Session Concurrency Limits and Web Search Throttling\n- **[ADR-0012](docs/adr/ADR-0012-replace-ddgs-with-searxng.md)**: SearXNG Migration (Replace ddgs)\n- **[ADR-0013](docs/adr/ADR-0013-searxng-optimization.md)**: SearXNG Optimization and Academic Engines\n\n---\n\n## License\n\nMIT — part of the [KodeHold](https://github.com/kiffer5000/kodehold) project.\n"}, "9eae844d110bd9bfacbc3a5963a67d0ce8f77479": {"t": 1785772117.4713886, "n": 9433, "h": "4b6b7c5a6fdfa41b", "c": "# DeepeResearch — Multi-Agent AI Research System\n\n[](https://github.com/Acharnite/deepresearch/actions/workflows/ci.yml)\n[](https://www.python.org/)\n\n> Six AI agents with distinct personalities collaborate to research any topic and produce a comprehensive, multi-perspective PDF paper.\n\n---\n\n## What is DeepeResearch?\n\nDeepeResearch 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.\n\nThe 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.\n\nThe result is a nuanced, multi-perspective research paper that no single-prompt system could produce.\n\n```\n Topic\n │\n ▼\n┌──────────────┐\n│ Orchestrator │ assigns models, manages rounds\n└──────┬───────┘\n │\n ├── Round 1 (6 agents parallel, with web search)\n ├── Collaboration Bus (shared knowledge)\n ├── Follow-up Questions → Refinement\n ├── Round 2 (agents refine, if budget allows)\n └── Scribe Agent → PDF Paper\n```\n\n---\n\n## Quick Install\n\n```bash\n# Clone the repo\ngit clone https://github.com/Acharnite/deepresearch.git\ncd deepresearch\n\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate # Linux/macOS\n# .venv\\Scripts\\activate # Windows\n\n# Install\npip install -e \".[dev]\"\n\n# Set your API key (at least one)\nexport OPENCODE_API_KEY=\"your-key-here\"\n# or: export OPENAI_API_KEY=\"your-key-here\"\n\n# Run\ndeepresearch run \"The future of renewable energy\" --web\n```\n\n**Prerequisites:**\n- Python 3.11+\n- Git\n- WeasyPrint system deps (Linux only): `sudo apt install libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-dev`\n\n**No API key?** Run a dry test without LLM calls:\n```bash\ndeepresearch run \"Test topic\" --dry-run\n```\n\n---\n\n## Agent Personalities\n\n| Agent | Emoji | Temperature | Approach |\n|-------|-------|:-----------:|----------|\n| Curious Teenager | 🔍 | 0.90 | Naive curiosity, explores tangents, pop culture |\n| Skeptical Academic | 📚 | 0.30 | Demands evidence, challenges assumptions |\n| Creative Artist | 🎨 | 0.95 | Metaphors, unexpected connections, storytelling |\n| Pragmatic Engineer | ⚙️ | 0.40 | Implementation, trade-offs, feasibility |\n| Philosophical Thinker | 🤔 | 0.85 | Ethics, first principles, deeper meaning |\n| Data-Driven Analyst | 📊 | 0.20 | Metrics, statistics, quantitative evidence |\n\nThe **Scribe** has no personality — neutral academic tone at temperature 0.3, acting as an impartial compiler.\n\n---\n\n## Model Selection\n\nDeepeResearch supports three modes: **Same Model** (default), **Random Models**, and **Manual Selection**. The default model is `opencode/go` (Opencode AI, free tier).\n\n### Provider Prefix Routing\n\nModel IDs auto-route to the correct provider. No manual configuration needed.\n\n| Prefix | Provider | Env Variable |\n|--------|----------|-------------|\n| `opencode/` | Opencode AI | `OPENCODE_API_KEY` |\n| `openrouter/` | OpenRouter | `OPENROUTER_API_KEY` |\n| `groq/` | Groq | `GROQ_API_KEY` |\n| `together/` | Together | `TOGETHER_API_KEY` |\n| `deepseek/` | DeepSeek | `DEEPSEEK_API_KEY` |\n| `cohere/` | Cohere | `COHERE_API_KEY` |\n| `google/` | Google | `GOOGLE_API_KEY` |\n| `anthropic/` | Anthropic | `ANTHROPIC_API_KEY` |\n| `ollama/` | Ollama (local) | — |\n\n### Local LLM Backends\n\nDeepeResearch supports local inference via Ollama (auto-discovered on localhost:11434) and configurable endpoints for llama.cpp, vLLM, and SGLang. See **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)** for the auto-install and auto-discovery design.\n\n---\n\n## Tool Calling (Web Search)\n\nResearch 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.\n\n- **Rate limiter**: 1 search per 5 seconds (global)\n- **Result cache**: 200 entries with LRU eviction\n- **Health tracking**: `/api/system/search` endpoint\n- **Fallback**: DuckDuckGo via ddgs (optional extra, deprecated)\n\n---\n\n## CLI Usage\n\n```bash\n# Quick research\ndeepresearch run \"Quantum computing\" --quick\n\n# Deep research with web dashboard\ndeepresearch run \"Renewable energy\" --deep --web\n\n# Start dashboard standalone\ndeepresearch serve\n```\n\n### All Options\n\n```\ndeepresearch run <topic> \\\n [--quick | --deep] \\\n [--time <minutes>] \\\n [--same | --random-models | --manual-models] \\\n [--output ./path.pdf] \\\n [--web] [--web-host 0.0.0.0] [--web-port 8080] \\\n [--dry-run]\n\ndeepresearch serve [--host 0.0.0.0] [--port 8080]\ndeepresearch profiles list\ndeepresearch models list\n```\n\n---\n\n## Web Dashboard\n\nReal-time web dashboard built with FastAPI + SSE streaming.\n\n```bash\ndeepresearch serve # Start dashboard at http://localhost:8080/\ndeepresearch run \"Topic\" --web # Run session with dashboard\n```\n\n### Features\n\n- **Pipeline visualization** — see current phase at a glance\n- **Agent progress cards** — real-time status badges (idle, researching, compiling, done)\n- **Live streaming output** — per-agent text panels showing LLM generation in real-time\n- **Event log** — timestamped phase transitions, agent completions, clarification rounds\n- **Model selector** — dropdown for \"same\" mode, per-agent selectors for \"manual\" mode\n- **Q&A visualization** — graph showing agent interactions and clarification flows\n- **Scribe output panel** — watch the scribe compile the final paper live\n- **Cancel / Delete sessions** — stop running sessions or clear completed ones\n- **Download PDF/HTML** — one-click download when research completes\n- **Settings tab** — manage API keys (9 providers) and local model endpoints\n- **System Log tab** — in-browser log viewer with level filtering\n- **Dark-themed UI** — GitHub-dark aesthetic, color-coded state badges\n\n---\n\n## Project Structure\n\n```\nworkspaces/deepresearch/\n├── pyproject.toml\n├── src/deepresearch/\n│ ├── main.py # CLI entry point\n│ ├── models.py # Pydantic data models\n│ ├── config.py # YAML config loading\n│ ├── orchestrator.py # Session lifecycle FSM\n│ ├── agents/\n│ │ ├── research_agent.py # 6 personality research agents\n│ │ ├── scribe_agent.py # Compilation and synthesis agent\n│ │ └── registry.py # Agent factory and dispatch\n│ ├── collaboration/bus.py # In-memory shared knowledge bus\n│ ├── llm/client.py # LiteLLM async wrapper with retry + streaming\n│ ├── output/pdf_generator.py # WeasyPrint PDF rendering\n│ ├── tools/web_search.py # SearXNG web search (with ddgs fallback)\n│ ├── prompts/ # Research, scribe, collaboration prompts\n│ └── web/\n│ ├── server.py # FastAPI server (REST + SSE)\n│ ├── dashboard.html # Single-page dark-themed UI\n│ ├── sessions.py # MultiSessionManager\n│ └── settings_manager.py # API key & local endpoint management\n├── src/profiles/default.yaml # 6 agent personality profiles\n├── src/config/models.yaml # LLM model definitions\n└── tests/ # 311 tests\n```\n\n---\n\n## Testing\n\n```bash\ncd workspaces/deepresearch\npytest tests/ -v # Run all tests\npytest tests/ -v --cov=deepresearch # With coverage\n```\n\n---\n\n## Design Documents\n\n- **Design doc**: `docs/design/README.md`\n- **[ADR-0001](docs/adr/ADR-0001-multi-agent-research-architecture.md)**: Multi-Agent Research Architecture\n- **[ADR-0002](docs/adr/ADR-0002-agent-personality-and-model-selection.md)**: Agent Personality and Model Selection\n- **[ADR-0003](docs/adr/ADR-0003-web-frontend-and-multi-session.md)**: Web Frontend and Multi-Session\n- **[ADR-0004](docs/adr/ADR-0004-test-findings-and-architecture-fixes.md)**: Test Findings and Architecture Fixes\n- **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)**: Auto-Install and Auto-Discover Local LLM Backends\n- **[ADR-0006](docs/adr/ADR-0006-web-search-and-tool-calling.md)**: Web Search and Tool Calling\n- **[ADR-0007](docs/adr/ADR-0007-clarification-protocol-and-refinement.md)**: Clarification Protocol and Refinement\n- **[ADR-0008](docs/adr/ADR-0008-dashboard-enhancements.md)**: Dashboard Enhancements\n- **[ADR-0009](docs/adr/ADR-0009-cicd-pipeline-and-distribution.md)**: CI/CD Pipeline and Distribution\n- **[ADR-0010](docs/adr/ADR-0010-dynamic-research-rounds.md)**: Dynamic Research Rounds\n- **[ADR-0011](docs/adr/ADR-0011-concurrency-limits-and-web-search-throttling.md)**: Session Concurrency Limits and Web Search Throttling\n- **[ADR-0012](docs/adr/ADR-0012-replace-ddgs-with-searxng.md)**: SearXNG Migration (Replace ddgs)\n- **[ADR-0013](docs/adr/ADR-0013-searxng-optimization.md)**: SearXNG Optimization and Academic Engines\n\n---\n\n## License\n\nMIT — part of the [KodeHold](https://github.com/kiffer5000/kodehold) project.\n"}, "2dc13fbdcad452b013acf9e5be3d116d8365ed19": {"t": 1785772119.2506301, "n": 9185, "h": "c4cd684aaa6ab98e", "c": "# DeepeResearch — Multi-Agent AI Research System\n\n> Six AI agents with distinct personalities collaborate to research any topic and produce a comprehensive, multi-perspective PDF paper.\n\n---\n\n## What is DeepeResearch?\n\nDeepeResearch 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.\n\nThe 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.\n\nThe result is a nuanced, multi-perspective research paper that no single-prompt system could produce.\n\n```\n Topic\n │\n ▼\n┌──────────────┐\n│ Orchestrator │ assigns models, manages rounds\n└──────┬───────┘\n │\n ├── Round 1 (6 agents parallel, with web search)\n ├── Collaboration Bus (shared knowledge)\n ├── Follow-up Questions → Refinement\n ├── Round 2 (agents refine, if budget allows)\n └── Scribe Agent → PDF Paper\n```\n\n---\n\n## Quick Install\n\n```bash\n# Clone the repo\ngit clone https://github.com/Acharnite/deepresearch.git\ncd deepresearch\n\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate # Linux/macOS\n# .venv\\Scripts\\activate # Windows\n\n# Install\npip install -e \".[dev]\"\n\n# Set your API key (at least one)\nexport OPENCODE_API_KEY=\"your-key-here\"\n# or: export OPENAI_API_KEY=\"your-key-here\"\n\n# Run\ndeepresearch run \"The future of renewable energy\" --web\n```\n\n**Prerequisites:**\n- Python 3.11+\n- Git\n- WeasyPrint system deps (Linux only): `sudo apt install libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-dev`\n\n**No API key?** Run a dry test without LLM calls:\n```bash\ndeepresearch run \"Test topic\" --dry-run\n```\n\n---\n\n## Agent Personalities\n\n| Agent | Emoji | Temperature | Approach |\n|-------|-------|:-----------:|----------|\n| Curious Teenager | 🔍 | 0.90 | Naive curiosity, explores tangents, pop culture |\n| Skeptical Academic | 📚 | 0.30 | Demands evidence, challenges assumptions |\n| Creative Artist | 🎨 | 0.95 | Metaphors, unexpected connections, storytelling |\n| Pragmatic Engineer | ⚙️ | 0.40 | Implementation, trade-offs, feasibility |\n| Philosophical Thinker | 🤔 | 0.85 | Ethics, first principles, deeper meaning |\n| Data-Driven Analyst | 📊 | 0.20 | Metrics, statistics, quantitative evidence |\n\nThe **Scribe** has no personality — neutral academic tone at temperature 0.3, acting as an impartial compiler.\n\n---\n\n## Model Selection\n\nDeepeResearch supports three modes: **Same Model** (default), **Random Models**, and **Manual Selection**. The default model is `opencode/go` (Opencode AI, free tier).\n\n### Provider Prefix Routing\n\nModel IDs auto-route to the correct provider. No manual configuration needed.\n\n| Prefix | Provider | Env Variable |\n|--------|----------|-------------|\n| `opencode/` | Opencode AI | `OPENCODE_API_KEY` |\n| `openrouter/` | OpenRouter | `OPENROUTER_API_KEY` |\n| `groq/` | Groq | `GROQ_API_KEY` |\n| `together/` | Together | `TOGETHER_API_KEY` |\n| `deepseek/` | DeepSeek | `DEEPSEEK_API_KEY` |\n| `cohere/` | Cohere | `COHERE_API_KEY` |\n| `google/` | Google | `GOOGLE_API_KEY` |\n| `anthropic/` | Anthropic | `ANTHROPIC_API_KEY` |\n| `ollama/` | Ollama (local) | — |\n\n### Local LLM Backends\n\nDeepeResearch supports local inference via Ollama (auto-discovered on localhost:11434) and configurable endpoints for llama.cpp, vLLM, and SGLang. See **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)** for the auto-install and auto-discovery design.\n\n---\n\n## Tool Calling (Web Search)\n\nResearch 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.\n\n- **Rate limiter**: 1 search per 5 seconds (global)\n- **Result cache**: 200 entries with LRU eviction\n- **Health tracking**: `/api/system/search` endpoint\n- **Fallback**: DuckDuckGo via ddgs (optional extra, deprecated)\n\n---\n\n## CLI Usage\n\n```bash\n# Quick research\ndeepresearch run \"Quantum computing\" --quick\n\n# Deep research with web dashboard\ndeepresearch run \"Renewable energy\" --deep --web\n\n# Start dashboard standalone\ndeepresearch serve\n```\n\n### All Options\n\n```\ndeepresearch run <topic> \\\n [--quick | --deep] \\\n [--time <minutes>] \\\n [--same | --random-models | --manual-models] \\\n [--output ./path.pdf] \\\n [--web] [--web-host 0.0.0.0] [--web-port 8080] \\\n [--dry-run]\n\ndeepresearch serve [--host 0.0.0.0] [--port 8080]\ndeepresearch profiles list\ndeepresearch models list\n```\n\n---\n\n## Web Dashboard\n\nReal-time web dashboard built with FastAPI + SSE streaming.\n\n```bash\ndeepresearch serve # Start dashboard at http://localhost:8080/\ndeepresearch run \"Topic\" --web # Run session with dashboard\n```\n\n### Features\n\n- **Pipeline visualization** — see current phase at a glance\n- **Agent progress cards** — real-time status badges (idle, researching, compiling, done)\n- **Live streaming output** — per-agent text panels showing LLM generation in real-time\n- **Event log** — timestamped phase transitions, agent completions, clarification rounds\n- **Model selector** — dropdown for \"same\" mode, per-agent selectors for \"manual\" mode\n- **Q&A visualization** — graph showing agent interactions and clarification flows\n- **Scribe output panel** — watch the scribe compile the final paper live\n- **Cancel / Delete sessions** — stop running sessions or clear completed ones\n- **Download PDF/HTML** — one-click download when research completes\n- **Settings tab** — manage API keys (9 providers) and local model endpoints\n- **System Log tab** — in-browser log viewer with level filtering\n- **Dark-themed UI** — GitHub-dark aesthetic, color-coded state badges\n\n---\n\n## Project Structure\n\n```\nworkspaces/deepresearch/\n├── pyproject.toml\n├── src/deepresearch/\n│ ├── main.py # CLI entry point\n│ ├── models.py # Pydantic data models\n│ ├── config.py # YAML config loading\n│ ├── orchestrator.py # Session lifecycle FSM\n│ ├── agents/\n│ │ ├── research_agent.py # 6 personality research agents\n│ │ ├── scribe_agent.py # Compilation and synthesis agent\n│ │ └── registry.py # Agent factory and dispatch\n│ ├── collaboration/bus.py # In-memory shared knowledge bus\n│ ├── llm/client.py # LiteLLM async wrapper with retry + streaming\n│ ├── output/pdf_generator.py # WeasyPrint PDF rendering\n│ ├── tools/web_search.py # SearXNG web search (with ddgs fallback)\n│ ├── prompts/ # Research, scribe, collaboration prompts\n│ └── web/\n│ ├── server.py # FastAPI server (REST + SSE)\n│ ├── dashboard.html # Single-page dark-themed UI\n│ ├── sessions.py # MultiSessionManager\n│ └── settings_manager.py # API key & local endpoint management\n├── src/profiles/default.yaml # 6 agent personality profiles\n├── src/config/models.yaml # LLM model definitions\n└── tests/ # 311 tests\n```\n\n---\n\n## Testing\n\n```bash\ncd workspaces/deepresearch\npytest tests/ -v # Run all tests\npytest tests/ -v --cov=deepresearch # With coverage\n```\n\n---\n\n## Design Documents\n\n- **Design doc**: `docs/design/README.md`\n- **[ADR-0001](docs/adr/ADR-0001-multi-agent-research-architecture.md)**: Multi-Agent Research Architecture\n- **[ADR-0002](docs/adr/ADR-0002-agent-personality-and-model-selection.md)**: Agent Personality and Model Selection\n- **[ADR-0003](docs/adr/ADR-0003-web-frontend-and-multi-session.md)**: Web Frontend and Multi-Session\n- **[ADR-0004](docs/adr/ADR-0004-test-findings-and-architecture-fixes.md)**: Test Findings and Architecture Fixes\n- **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)**: Auto-Install and Auto-Discover Local LLM Backends\n- **[ADR-0006](docs/adr/ADR-0006-web-search-and-tool-calling.md)**: Web Search and Tool Calling\n- **[ADR-0007](docs/adr/ADR-0007-clarification-protocol-and-refinement.md)**: Clarification Protocol and Refinement\n- **[ADR-0008](docs/adr/ADR-0008-dashboard-enhancements.md)**: Dashboard Enhancements\n- **[ADR-0009](docs/adr/ADR-0009-cicd-pipeline-and-distribution.md)**: CI/CD Pipeline and Distribution\n- **[ADR-0010](docs/adr/ADR-0010-dynamic-research-rounds.md)**: Dynamic Research Rounds\n- **[ADR-0011](docs/adr/ADR-0011-concurrency-limits-and-web-search-throttling.md)**: Session Concurrency Limits and Web Search Throttling\n- **[ADR-0012](docs/adr/ADR-0012-replace-ddgs-with-searxng.md)**: SearXNG Migration (Replace ddgs)\n- **[ADR-0013](docs/adr/ADR-0013-searxng-optimization.md)**: SearXNG Optimization and Academic Engines\n\n---\n\n## License\n\nMIT — part of the [KodeHold](https://github.com/kiffer5000/kodehold) project.\n"}, "bbb1696e3b76ae98a464be500362d8fa9459312c": {"t": 1785772121.6255932, "n": 8091, "h": "84839b94d5ec2eaf", "c": "# DeepeResearch — Multi-Agent AI Research System\n\n> Six AI agents with distinct personalities collaborate to research any topic and produce a comprehensive, multi-perspective PDF paper.\n\n---\n\n## What is DeepeResearch?\n\nDeepeResearch 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.\n\nThe 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.\n\nThe result is a nuanced, multi-perspective research paper that no single-prompt system could produce.\n\n```\n Topic\n │\n ▼\n┌──────────────┐\n│ Orchestrator │ assigns models, manages rounds\n└──────┬───────┘\n │\n ├── Round 1 (6 agents parallel, with web search)\n ├── Collaboration Bus (shared knowledge)\n ├── Follow-up Questions → Refinement\n ├── Round 2 (agents refine, if budget allows)\n └── Scribe Agent → PDF Paper\n```\n\n---\n\n## Quick Install\n\n```bash\n# Clone the repo\ngit clone https://github.com/Acharnite/deepresearch.git\ncd deepresearch\n\n# Create virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate # Linux/macOS\n# .venv\\Scripts\\activate # Windows\n\n# Install\npip install -e \".[dev]\"\n\n# Set your API key (at least one)\nexport OPENCODE_API_KEY=\"your-key-here\"\n# or: export OPENAI_API_KEY=\"your-key-here\"\n\n# Run\ndeepresearch run \"The future of renewable energy\" --web\n```\n\n**Prerequisites:**\n- Python 3.11+\n- Git\n- WeasyPrint system deps (Linux only): `sudo apt install libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-dev`\n\n**No API key?** Run a dry test without LLM calls:\n```bash\ndeepresearch run \"Test topic\" --dry-run\n```\n\n---\n\n## Agent Personalities\n\n| Agent | Emoji | Temperature | Approach |\n|-------|-------|:-----------:|----------|\n| Curious Teenager | 🔍 | 0.90 | Naive curiosity, explores tangents, pop culture |\n| Skeptical Academic | 📚 | 0.30 | Demands evidence, challenges assumptions |\n| Creative Artist | 🎨 | 0.95 | Metaphors, unexpected connections, storytelling |\n| Pragmatic Engineer | ⚙️ | 0.40 | Implementation, trade-offs, feasibility |\n| Philosophical Thinker | 🤔 | 0.85 | Ethics, first principles, deeper meaning |\n| Data-Driven Analyst | 📊 | 0.20 | Metrics, statistics, quantitative evidence |\n\nThe **Scribe** has no personality — neutral academic tone at temperature 0.3, acting as an impartial compiler.\n\n---\n\n## Model Selection\n\nDeepeResearch supports three modes: **Same Model** (default), **Random Models**, and **Manual Selection**. The default model is `opencode/go` (Opencode AI, free tier).\n\n### Provider Prefix Routing\n\nModel IDs auto-route to the correct provider. No manual configuration needed.\n\n| Prefix | Provider | Env Variable |\n|--------|----------|-------------|\n| `opencode/` | Opencode AI | `OPENCODE_API_KEY` |\n| `openrouter/` | OpenRouter | `OPENROUTER_API_KEY` |\n| `groq/` | Groq | `GROQ_API_KEY` |\n| `together/` | Together | `TOGETHER_API_KEY` |\n| `deepseek/` | DeepSeek | `DEEPSEEK_API_KEY` |\n| `cohere/` | Cohere | `COHERE_API_KEY` |\n| `google/` | Google | `GOOGLE_API_KEY` |\n| `anthropic/` | Anthropic | `ANTHROPIC_API_KEY` |\n| `ollama/` | Ollama (local) | — |\n\n### Local LLM Backends\n\nDeepeResearch supports local inference via Ollama (auto-discovered on localhost:11434) and configurable endpoints for llama.cpp, vLLM, and SGLang. See **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)** for the auto-install and auto-discovery design.\n\n---\n\n## Tool Calling (Web Search)\n\nResearch agents search the web in real-time using DuckDuckGo via LiteLLM function calling. Agents can make up to 5 search queries per generation, refining based on initial results. Falls back gracefully if DuckDuckGo is unavailable.\n\n---\n\n## CLI Usage\n\n```bash\n# Quick research\ndeepresearch run \"Quantum computing\" --quick\n\n# Deep research with web dashboard\ndeepresearch run \"Renewable energy\" --deep --web\n\n# Start dashboard standalone\ndeepresearch serve\n```\n\n### All Options\n\n```\ndeepresearch run <topic> \\\n [--quick | --deep] \\\n [--time <minutes>] \\\n [--same | --random-models | --manual-models] \\\n [--output ./path.pdf] \\\n [--web] [--web-host 0.0.0.0] [--web-port 8080] \\\n [--dry-run]\n\ndeepresearch serve [--host 0.0.0.0] [--port 8080]\ndeepresearch profiles list\ndeepresearch models list\n```\n\n---\n\n## Web Dashboard\n\nReal-time web dashboard built with FastAPI + SSE streaming.\n\n```bash\ndeepresearch serve # Start dashboard at http://localhost:8080/\ndeepresearch run \"Topic\" --web # Run session with dashboard\n```\n\n### Features\n\n- **Pipeline visualization** — see current phase at a glance\n- **Agent progress cards** — real-time status badges (idle, researching, compiling, done)\n- **Live streaming output** — per-agent text panels showing LLM generation in real-time\n- **Event log** — timestamped phase transitions, agent completions, clarification rounds\n- **Model selector** — dropdown for \"same\" mode, per-agent selectors for \"manual\" mode\n- **Q&A visualization** — graph showing agent interactions and clarification flows\n- **Scribe output panel** — watch the scribe compile the final paper live\n- **Cancel / Delete sessions** — stop running sessions or clear completed ones\n- **Download PDF/HTML** — one-click download when research completes\n- **Settings tab** — manage API keys (9 providers) and local model endpoints\n- **System Log tab** — in-browser log viewer with level filtering\n- **Dark-themed UI** — GitHub-dark aesthetic, color-coded state badges\n\n---\n\n## Project Structure\n\n```\nworkspaces/deepresearch/\n├── pyproject.toml\n├── src/deepresearch/\n│ ├── main.py # CLI entry point\n│ ├── models.py # Pydantic data models\n│ ├── config.py # YAML config loading\n│ ├── orchestrator.py # Session lifecycle FSM\n│ ├── agents/\n│ │ ├── research_agent.py # 6 personality research agents\n│ │ ├── scribe_agent.py # Compilation and synthesis agent\n│ │ └── registry.py # Agent factory and dispatch\n│ ├── collaboration/bus.py # In-memory shared knowledge bus\n│ ├── llm/client.py # LiteLLM async wrapper with retry + streaming\n│ ├── output/pdf_generator.py # WeasyPrint PDF rendering\n│ ├── tools/web_search.py # DuckDuckGo function calling\n│ ├── prompts/ # Research, scribe, collaboration prompts\n│ └── web/\n│ ├── server.py # FastAPI server (REST + SSE)\n│ ├── dashboard.html # Single-page dark-themed UI\n│ ├── sessions.py # MultiSessionManager\n│ └── settings_manager.py # API key & local endpoint management\n├── src/profiles/default.yaml # 6 agent personality profiles\n├── src/config/models.yaml # LLM model definitions\n└── tests/ # 292 tests\n```\n\n---\n\n## Testing\n\n```bash\ncd workspaces/deepresearch\npytest tests/ -v # Run all tests\npytest tests/ -v --cov=deepresearch # With coverage\n```\n\n---\n\n## Design Documents\n\n- **Design doc**: `docs/design/README.md`\n- **[ADR-0001](docs/adr/ADR-0001-multi-agent-research-architecture.md)**: Multi-Agent Research Architecture\n- **[ADR-0002](docs/adr/ADR-0002-agent-personality-and-model-selection.md)**: Agent Personality and Model Selection\n- **[ADR-0003](docs/adr/ADR-0003-web-frontend-and-multi-session.md)**: Web Frontend and Multi-Session\n- **[ADR-0004](docs/adr/ADR-0004-test-findings-and-architecture-fixes.md)**: Test Findings and Architecture Fixes\n- **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)**: Auto-Install and Auto-Discover Local LLM Backends\n\n---\n\n## License\n\nMIT — part of the [KodeHold](https://github.com/kiffer5000/kodehold) project.\n"}, "bab80b4b0b231673872154366625ffb021506a50": {"t": 1785772124.007321, "n": 7753, "h": "915cca075ec8015d", "c": "# DeepeResearch — Multi-Agent AI Research System\n\n> Six AI agents with distinct personalities collaborate to research any topic and produce a comprehensive, multi-perspective PDF paper.\n\n---\n\n## What is DeepeResearch?\n\nDeepeResearch 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.\n\nThe 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.\n\nThe result is a nuanced, multi-perspective research paper that no single-prompt system could produce.\n\n```\n Topic\n │\n ▼\n┌──────────────┐\n│ Orchestrator │ assigns models, manages rounds\n└──────┬───────┘\n │\n ├── Round 1 (6 agents parallel, with web search)\n ├── Collaboration Bus (shared knowledge)\n ├── Follow-up Questions → Refinement\n ├── Round 2 (agents refine, if budget allows)\n └── Scribe Agent → PDF Paper\n```\n\n---\n\n## Quick Install\n\n```bash\n# Install from the KodeHold workspace\ncd workspaces/deepresearch\npip install -e \".[dev]\"\n\n# Verify\ndeepresearch --version\n```\n\n**Prerequisites:**\n- Python 3.11+\n- An API key for at least one LLM provider (see [Model Selection](#model-selection))\n- WeasyPrint system deps (Linux only): `sudo apt install libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-dev`\n\n---\n\n## Agent Personalities\n\n| Agent | Emoji | Temperature | Approach |\n|-------|-------|:-----------:|----------|\n| Curious Teenager | 🔍 | 0.90 | Naive curiosity, explores tangents, pop culture |\n| Skeptical Academic | 📚 | 0.30 | Demands evidence, challenges assumptions |\n| Creative Artist | 🎨 | 0.95 | Metaphors, unexpected connections, storytelling |\n| Pragmatic Engineer | ⚙️ | 0.40 | Implementation, trade-offs, feasibility |\n| Philosophical Thinker | 🤔 | 0.85 | Ethics, first principles, deeper meaning |\n| Data-Driven Analyst | 📊 | 0.20 | Metrics, statistics, quantitative evidence |\n\nThe **Scribe** has no personality — neutral academic tone at temperature 0.3, acting as an impartial compiler.\n\n---\n\n## Model Selection\n\nDeepeResearch supports three modes: **Same Model** (default), **Random Models**, and **Manual Selection**. The default model is `opencode/go` (Opencode AI, free tier).\n\n### Provider Prefix Routing\n\nModel IDs auto-route to the correct provider. No manual configuration needed.\n\n| Prefix | Provider | Env Variable |\n|--------|----------|-------------|\n| `opencode/` | Opencode AI | `OPENCODE_API_KEY` |\n| `openrouter/` | OpenRouter | `OPENROUTER_API_KEY` |\n| `groq/` | Groq | `GROQ_API_KEY` |\n| `together/` | Together | `TOGETHER_API_KEY` |\n| `deepseek/` | DeepSeek | `DEEPSEEK_API_KEY` |\n| `cohere/` | Cohere | `COHERE_API_KEY` |\n| `google/` | Google | `GOOGLE_API_KEY` |\n| `anthropic/` | Anthropic | `ANTHROPIC_API_KEY` |\n| `ollama/` | Ollama (local) | — |\n\n### Local LLM Backends\n\nDeepeResearch supports local inference via Ollama (auto-discovered on localhost:11434) and configurable endpoints for llama.cpp, vLLM, and SGLang. See **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)** for the auto-install and auto-discovery design.\n\n---\n\n## Tool Calling (Web Search)\n\nResearch agents search the web in real-time using DuckDuckGo via LiteLLM function calling. Agents can make up to 5 search queries per generation, refining based on initial results. Falls back gracefully if DuckDuckGo is unavailable.\n\n---\n\n## CLI Usage\n\n```bash\n# Quick research\ndeepresearch run \"Quantum computing\" --quick\n\n# Deep research with web dashboard\ndeepresearch run \"Renewable energy\" --deep --web\n\n# Start dashboard standalone\ndeepresearch serve\n```\n\n### All Options\n\n```\ndeepresearch run <topic> \\\n [--quick | --deep] \\\n [--time <minutes>] \\\n [--same | --random-models | --manual-models] \\\n [--output ./path.pdf] \\\n [--web] [--web-host 0.0.0.0] [--web-port 8080] \\\n [--dry-run]\n\ndeepresearch serve [--host 0.0.0.0] [--port 8080]\ndeepresearch profiles list\ndeepresearch models list\n```\n\n---\n\n## Web Dashboard\n\nReal-time web dashboard built with FastAPI + SSE streaming.\n\n```bash\ndeepresearch serve # Start dashboard at http://localhost:8080/\ndeepresearch run \"Topic\" --web # Run session with dashboard\n```\n\n### Features\n\n- **Pipeline visualization** — see current phase at a glance\n- **Agent progress cards** — real-time status badges (idle, researching, compiling, done)\n- **Live streaming output** — per-agent text panels showing LLM generation in real-time\n- **Event log** — timestamped phase transitions, agent completions, clarification rounds\n- **Model selector** — dropdown for \"same\" mode, per-agent selectors for \"manual\" mode\n- **Q&A visualization** — graph showing agent interactions and clarification flows\n- **Scribe output panel** — watch the scribe compile the final paper live\n- **Cancel / Delete sessions** — stop running sessions or clear completed ones\n- **Download PDF/HTML** — one-click download when research completes\n- **Settings tab** — manage API keys (9 providers) and local model endpoints\n- **System Log tab** — in-browser log viewer with level filtering\n- **Dark-themed UI** — GitHub-dark aesthetic, color-coded state badges\n\n---\n\n## Project Structure\n\n```\nworkspaces/deepresearch/\n├── pyproject.toml\n├── src/deepresearch/\n│ ├── main.py # CLI entry point\n│ ├── models.py # Pydantic data models\n│ ├── config.py # YAML config loading\n│ ├── orchestrator.py # Session lifecycle FSM\n│ ├── agents/\n│ │ ├── research_agent.py # 6 personality research agents\n│ │ ├── scribe_agent.py # Compilation and synthesis agent\n│ │ └── registry.py # Agent factory and dispatch\n│ ├── collaboration/bus.py # In-memory shared knowledge bus\n│ ├── llm/client.py # LiteLLM async wrapper with retry + streaming\n│ ├── output/pdf_generator.py # WeasyPrint PDF rendering\n│ ├── tools/web_search.py # DuckDuckGo function calling\n│ ├── prompts/ # Research, scribe, collaboration prompts\n│ └── web/\n│ ├── server.py # FastAPI server (REST + SSE)\n│ ├── dashboard.html # Single-page dark-themed UI\n│ ├── sessions.py # MultiSessionManager\n│ └── settings_manager.py # API key & local endpoint management\n├── src/profiles/default.yaml # 6 agent personality profiles\n├── src/config/models.yaml # LLM model definitions\n└── tests/ # 292 tests\n```\n\n---\n\n## Testing\n\n```bash\ncd workspaces/deepresearch\npytest tests/ -v # Run all tests\npytest tests/ -v --cov=deepresearch # With coverage\n```\n\n---\n\n## Design Documents\n\n- **Design doc**: `docs/design/README.md`\n- **[ADR-0001](docs/adr/ADR-0001-multi-agent-research-architecture.md)**: Multi-Agent Research Architecture\n- **[ADR-0002](docs/adr/ADR-0002-agent-personality-and-model-selection.md)**: Agent Personality and Model Selection\n- **[ADR-0003](docs/adr/ADR-0003-web-frontend-and-multi-session.md)**: Web Frontend and Multi-Session\n- **[ADR-0004](docs/adr/ADR-0004-test-findings-and-architecture-fixes.md)**: Test Findings and Architecture Fixes\n- **[ADR-0005](docs/adr/ADR-0005-auto-install-and-discover-local-llm-backends.md)**: Auto-Install and Auto-Discover Local LLM Backends\n\n---\n\n## License\n\nMIT — part of the [KodeHold](https://github.com/kiffer5000/kodehold) project.\n"}, "70e737e286522e19e154b120b3ac864027608e6d": {"t": 1785772126.600772, "n": 20063, "h": "9592feed5891f4ac", "c": "# DeepeResearch — Multi-Agent AI Research System\n\n> Six AI agents with distinct personalities collaborate to research any topic and produce a comprehensive, multi-perspective PDF paper.\n\n---\n\n## What is DeepeResearch?\n\nDeepeResearch 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.\n\nThe 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.\n\nThe result is a nuanced, multi-perspective research paper that no single-prompt system could produce.\n\n```\n Topic\n │\n ▼\n┌──────────────┐\n│ Orchestrator │ ── assigns models, manages rounds\n└──────┬───────┘\n │\n ├──────────── Round 1 (parallel) ────────────┐\n │ ┌────────┐ ┌────────┐ ┌──────┐ ┌────┐ │\n ├──│ Agent 1 │ │ Agent 2 │ │ … │ │Agent6│ │\n │ └────────┘ └────────┘ └──────┘ └────┘ │\n │ │\n ├──────── Collaboration Bus ──────────────────┤\n │ Agents share findings, ask each other Qs │\n │ │\n ├──────── Round 2 (parallel, refined) ───────┤\n │ Each agent researches again, now informed │\n │ by what the others found │\n └────────────────────┬───────────────────────┘\n │\n ▼\n ┌──────────────┐\n │ Scribe Agent │ ── compiles, deduplicates, synthesizes\n └──────┬───────┘\n │\n ▼\n ┌──────────┐\n │ PDF Paper │ ── cover page, all perspectives, synthesis\n └──────────┘\n```\n\n---\n\n## Architecture Overview\n\n| Component | Role |\n|-----------|------|\n| **Orchestrator** | Manages the full session lifecycle — config validation, model assignment, round sequencing, error handling, and event logging. Runs as a finite state machine (`IDLE → CONFIGURING → ROUND1 → COLLABORATING → FOLLOWUP → ROUND2 → COMPILING → OUTPUT → COMPLETE`). |\n| **Research Agents** | Six parallel AI agents, each with a distinct personality profile (prompt + temperature). Run concurrently via `asyncio.gather()`. |\n| **Collaboration Bus** | In-memory shared knowledge store. After Round 1, the orchestrator aggregates all findings into `SharedKnowledge` (consensus points, conflicting perspectives, unanswered questions). Each agent sees this before Round 2 — preventing groupthink by design. |\n| **Scribe Agent** | Neutral, academic-tone agent (temperature 0.3) that compiles all individual reports into a coherent paper. Handles de-duplication, cross-report synthesis, and clarification queries. Uses a structured pipeline: Extract → Compare → Weave → Clarify. |\n| **PDF Generator** | Renders the final paper via Jinja2 HTML templates → WeasyPrint PDF. Falls back to HTML if PDF generation fails. |\n\n---\n\n## The 6 Agent Personalities\n\nEach agent is defined by a YAML profile that includes a full persona prompt, methodology, knowledge base description, bias mitigation instructions, voice/tone guidance, and an LLM temperature setting.\n\n| Agent | Emoji | Temperature | Approach | Voice |\n|-------|-------|:-----------:|----------|-------|\n| Curious Teenager | 🔍 | **0.90** | Naive curiosity, asks \"why\" repeatedly, explores tangents, pop culture connections | Inquisitive, enthusiastic, conversational |\n| Skeptical Academic | 📚 | **0.30** | Demands evidence, challenges assumptions, finds flaws, rigorous methodology | Precise, critical, formal |\n| Creative Artist | 🎨 | **0.95** | Metaphors, unexpected connections, visual thinking, storytelling | Expressive, metaphorical, imaginative |\n| Pragmatic Engineer | ⚙️ | **0.40** | Implementation, trade-offs, feasibility, real-world impact | Direct, practical, solution-oriented |\n| Philosophical Thinker | 🤔 | **0.85** | Ethics, first principles, deeper meaning, human significance | Contemplative, Socratic, abstract |\n| Data-Driven Analyst | 📊 | **0.20** | Metrics, statistics, quantitative evidence, patterns, trends | Factual, analytical, structured |\n\n**The Scribe has no personality** — it maintains a neutral academic tone at temperature 0.3, acting as an impartial compiler and synthesizer.\n\n---\n\n## Model Selection\n\nDeepeResearch supports three modes for assigning LLM models to agents.\n\nThe new default model is **`opencode/go`** (Opencode AI), with `opencode/zen` also available. You can also access these models via OpenRouter as `openrouter/opencode/go` and `openrouter/opencode/zen`.\n\n### Provider Prefix Routing\n\nThe LLMClient auto-detects the provider from the model ID prefix. For example, `opencode/go` routes to `https://api.opencode.ai/v1` using `OPENCODE_API_KEY`, while `openrouter/opencode/go` routes to OpenRouter. This means you can mix models from different providers by simply using their prefixed model IDs.\n\n| Prefix | API Base | Env Variable |\n|--------|----------|-------------|\n| `opencode/` | `https://api.opencode.ai/v1` | `OPENCODE_API_KEY` |\n| `openrouter/` | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` |\n| `groq/` | `https://api.groq.com/openai/v1` | `GROQ_API_KEY` |\n| `together/` | `https://api.together.xyz/v1` | `TOGETHER_API_KEY` |\n| `deepseek/` | `https://api.deepseek.com/v1` | `DEEPSEEK_API_KEY` |\n| `cohere/` | `https://api.cohere.ai/v1` | `COHERE_API_KEY` |\n| `google/` | `https://generativelanguage.googleapis.com/v1` | `GOOGLE_API_KEY` |\n| `anthropic/` | `https://api.anthropic.com/v1` | `ANTHROPIC_API_KEY` |\n| `ollama/` | (local) | — |\n\n### Same Model (default)\nAll 6 agents use the same underlying LLM. Personality differentiation comes entirely from the prompt instructions and temperature settings. This is the cheapest and fastest option, and works well for most use cases.\n\n```bash\ndeepresearch run \"Topic\" --same\n# or just omit the flag — same model is default\ndeepresearch run \"Topic\"\n```\n\n### Random Models\nEach agent gets a randomly assigned model from your configured pool. The random seed is derived from the topic string, making assignments **deterministic and reproducible** — same topic always gets the same model distribution.\n\n```bash\ndeepresearch run \"Topic\" --random-models\n```\n\n### Manual Selection\nThe system prompts you to choose a model for each agent interactively before the session starts.\n\n```bash\ndeepresearch run \"Topic\" --manual-models\n```\n\n### Model Selector (Web UI)\n\nWhen using the web dashboard, you can pick models visually:\n- **\"Same\" mode** — single model dropdown for all agents\n- **\"Manual\" mode** — per-agent model selectors\n- **\"Random\" mode** — info text explaining random assignment from pool\n\nThe `/api/models` endpoint auto-discovers models from ALL configured providers (OpenAI, OpenRouter, Anthropic, Groq, Together, DeepSeek, Google, Cohere) via their respective APIs, merged with curated `models.yaml` definitions and locally-discovered Ollama models. Results are cached for 60 seconds.\n\n---\n\n## Tool Calling (Web Search)\n\nResearch agents can search the web in real-time using DuckDuckGo via LiteLLM function calling — enabling them to access current information, recent developments, and external sources during research.\n\n### How It Works\n\n1. **`LLMClient.generate_with_tools()`** handles the multi-turn tool calling loop:\n - Calls LiteLLM `acompletion()` with streaming and tools enabled\n - If the LLM requests a tool call, the tool is executed and results are fed back\n - The loop continues (up to **5 rounds**) until the LLM produces a final text response\n - Falls back gracefully: streaming+tool failure → non-streaming retry → no-tools retry\n\n2. **`WEB_SEARCH_TOOL`** is a LiteLLM-compatible function-calling schema defined in `tools/web_search.py`:\n - Name: `web_search`\n - Required parameter: `query` (string)\n - Optional parameter: `max_results` (integer, default 5)\n\n3. **`web_search()`** queries DuckDuckGo via `duckduckgo_search.DDGS`:\n - Runs in a thread (`asyncio.to_thread()`) to avoid blocking the event loop\n - Returns structured results: `[{title, snippet, url}, ...]`\n - Returns an error dict on failure — never raises\n\n### Which Agents Use It\n\n- **ResearchAgent.research_round_1()** — the initial research pass now calls `generate_with_tools()` with `WEB_SEARCH_TOOL`. If the tool call fails, the agent falls back to generating without tools.\n- All 6 personality agents benefit: Curious Teenager, Skeptical Academic, Creative Artist, Pragmatic Engineer, Philosophical Thinker, and Data-Driven Analyst all search the web during Round 1.\n\n### Benefits\n\n- **Live facts** — agents access current information instead of relying solely on training data\n- **Graceful degradation** — if DuckDuckGo is unavailable or tool calling isn't supported by the model, research continues without errors\n- **Multiple queries** — the 5-round loop lets agents refine their search queries based on initial results\n\n---\n\n## Installation\n\nDeepeResearch is part of the KodeHold project. You run it from the workspace directory.\n\n```bash\n# Navigate to the workspace\ncd workspaces/deepresearch\n\n# Create and activate a virtual environment (recommended)\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Verify it works\ndeepresearch --version\n```\n\n### Prerequisites\n\n- **Python 3.11+**\n- **API key** for at least one LLM provider:\n - `OPENAI_API_KEY` — OpenAI (GPT-4o, GPT-4o Mini)\n - `ANTHROPIC_API_KEY` — Anthropic (Claude Sonnet 4, Claude Haiku 3.5)\n - `OPENCODE_API_KEY` — Opencode AI (Opencode Go, Opencode Zen)\n - `OPENROUTER_API_KEY` — OpenRouter (access to 100+ models)\n - Or configure **Ollama** locally for Llama 3.1, Mixtral, etc.\n- **WeasyPrint system dependencies** (Linux only):\n ```bash\n sudo apt install libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-dev\n ```\n\n---\n\n## CLI Usage\n\n### Quick Start\n\n```bash\n# See available agent profiles and their personalities\ndeepresearch profiles list\n\n# See which LLM models are configured\ndeepresearch models list\n\n# Dry-run — validates config without making any API calls\ndeepresearch run \"Quantum computing\" --quick --dry-run\n\n# Full research session\ndeepresearch run \"The future of renewable energy\" --quick\n\n# Balanced research with random model assignment\ndeepresearch run \"Consciousness in AI\" --random-models\n\n# Deep research with web dashboard\ndeepresearch run \"Geopolitics of rare earth minerals\" --deep --web\n```\n\n### All Options\n\n```\ndeepresearch run <topic> \\\n [--quick | --deep] \\\n [--time <minutes>] \\\n [--same | --random-models | --manual-models] \\\n [--output ./path.pdf] \\\n [--web] [--web-host 0.0.0.0] [--web-port 8080] \\\n [--dry-run]\n\ndeepresearch serve [--host 0.0.0.0] [--port 8080]\ndeepresearch profiles list\ndeepresearch models list\n```\n\n### Time Budget\n\n| Mode | Duration | Rounds | Use Case |\n|------|:--------:|:------:|----------|\n| `--quick` | ~5 min | 1 round | Quick overview or exploratory research |\n| `--time 15` (medium) | ~15 min | 2 rounds | Balanced depth and breadth (default-style) |\n| `--deep` or `--time 30` | ~30 min | 2 rounds | Thorough, comprehensive research |\n| `--time 60` | ~60 min | 2 rounds | Exhaustive deep-dive |\n\nThe time budget controls how much the agents write — shorter budgets produce more concise findings, longer budgets allow deeper exploration and more extensive analysis. Use `--time <N>` for fine-grained control between the presets.\n\n---\n\n## Web Dashboard\n\nDeepeResearch includes a real-time web dashboard built with FastAPI + SSE streaming.\n\n```bash\n# Start the dashboard server standalone\ndeepresearch serve\n# Open http://localhost:8080/\n\n# Run a session with the dashboard\ndeepresearch run \"Topic\" --web\n# Opens http://localhost:8080/ automatically\n\n# Custom host/port\ndeepresearch serve --host 127.0.0.1 --port 9090\ndeepresearch run \"Topic\" --web --web-host 127.0.0.1 --web-port 9090\n```\n\n### Dashboard Features\n\n- **Topic input** field with time budget and model mode selectors\n- **\"Start Research\"** button to launch a session\n- **Model dropdown selector** — for \"same\" mode, a single dropdown; for \"manual\" mode, per-agent model selectors; info text for \"random\" mode\n- **Provider model auto-discovery** — the model dropdown fetches from `/api/models`, which discovers models from ALL configured providers (OpenAI, OpenRouter, Anthropic, Groq, Together, DeepSeek, Google, Cohere) plus Ollama local models, all merged with the curated `models.yaml` definitions (60s cache)\n- **Real-time agent progress bars** via SSE streaming — see each agent's status update as it works\n- **Live event log** with timestamps showing every phase transition, agent completion, and clarification round\n- **Cancel button** to gracefully stop a running session\n- **Delete session / Clear All buttons** — delete individual sessions via the `DELETE /api/sessions/{id}` endpoint, or clear all completed/errored sessions with one click. Session output files are cleaned up on deletion.\n- **Download PDF / Download HTML** buttons when the research completes\n- **Settings tab** — manage API keys (9 supported providers including Opencode AI) and local model endpoints (Ollama, llama.cpp, vLLM) through the UI without touching the terminal\n- **Dark-themed UI** with GitHub-dark aesthetic, color-coded state badges, and agent emoji indicators\n\nThe dashboard shows a status bar at the top with the current orchestrator state (idle, configuring, round 1, collaborating, follow-up, round 2, compiling, complete, error) and a grid layout with agent progress cards on the left and a scrolling event log on the right.\n\n---\n\n## Output\n\nThe final output is a professionally formatted research paper.\n\n**PDF paper** (primary output):\n- Cover page with title and generation timestamp\n- Abstract summarizing the research\n- Per-agent findings — each personality's unique perspective in its own section\n- Synthesis section — where the scribe weaves perspectives together\n- Key takeaways — actionable conclusions distilled from all agents\n- Conclusion — final synthesis\n\n**HTML fallback**: If PDF generation fails (e.g., missing WeasyPrint deps), the paper is saved as HTML with the same structure.\n\nFiles are written to `./output/` by default (configurable with `--output`):\n```\n./output/paper.pdf # Final research paper\n./output/paper.html # HTML version (fallback or paired output)\n```\n\nDownload both from the web dashboard when running with `--web`.\n\n---\n\n## Configuration\n\n### Agent Profiles\n\nThe six built-in agent personalities are defined in:\n\n```\nsrc/profiles/default.yaml\n```\n\nEach profile contains: `id`, `name`, `emoji`, `temperature`, `persona_prompt`, `methodology`, `knowledge_base`, `bias_mitigation`, and `voice`.\n\nYou can create custom profiles:\n```\n~/.deepresearch/profiles/custom.yaml\n```\n\n### Model Definitions\n\nAvailable LLM models are configured in:\n\n```\nsrc/config/models.yaml\n```\n\nDefault models are now **`opencode/go`** (default) and **`opencode/zen`**, both routed via Opencode AI. OpenRouter alternatives (`openrouter/opencode/go`, `openrouter/opencode/zen`) are also included. Curated models also cover GPT-4o, GPT-4o Mini, Claude Sonnet 4, Claude Haiku 3.5, Llama 3.1 (Ollama), and Mixtral (Ollama).\n\n**Provider prefix routing** — the LLMClient maps model ID prefixes to API base URLs and API key environment variables. This means any model ID like `anthropic/claude-sonnet-4-20250514` or `groq/llama3-70b` routes to the correct provider automatically.\n\n**Model auto-discovery** — the `/api/models` endpoint goes beyond `models.yaml`. It also:\n- Fetches model lists from ALL configured providers (OpenAI, OpenRouter, Anthropic, Groq, Together, DeepSeek, Google, Cohere) via their REST APIs\n- Auto-discovers Ollama models from `http://localhost:11434/api/tags`\n- Merges locally-configured endpoints (llama.cpp, vLLM)\n- Caches results for 60 seconds\n\n**Model cost tracking** — per-model input/output cost rates are defined in `llm/client.py`. Costs are roughly calibrated based on published pricing. Add any model supported by LiteLLM.\n\n---\n\n## Project Structure\n\n```\nworkspaces/deepresearch/\n├── pyproject.toml # Package config, dependencies, entry point\n├── src/\n│ └── deepresearch/\n│ ├── __init__.py\n│ ├── __main__.py # Entry: python -m deepresearch\n│ ├── main.py # CLI entry point (argparse + rich)\n│ ├── models.py # Pydantic data models\n│ ├── config.py # YAML config loading and validation\n│ ├── orchestrator.py # Session lifecycle FSM\n│ │\n│ ├── agents/\n│ │ ├── base_agent.py # Abstract ResearchAgent base class\n│ │ ├── research_agent.py # 6 personality research agents\n│ │ ├── scribe_agent.py # Compilation and synthesis agent\n│ │ └── registry.py # Agent factory and profile registry\n│ │\n│ ├── collaboration/\n│ │ └── bus.py # In-memory shared knowledge bus\n│ │\n│ ├── llm/\n│ │ └── client.py # LiteLLM async wrapper with retry\n│ │\n│ ├── output/\n│ │ ├── pdf_generator.py # WeasyPrint PDF rendering\n│ │ └── templates/ # Jinja2 HTML + CSS templates\n│ │\n│ ├── tools/\n│ │ └── web_search.py # DuckDuckGo web search tool (function calling)\n│ │\n│ ├── prompts/\n│ │ ├── research.py # Research round prompt templates\n│ │ ├── scribe.py # Scribe compilation prompts\n│ │ └── collaboration.py # Collaboration/sharing prompts\n│ │\n│ ├── utils/\n│ │ ├── token_tracker.py # Token usage tracking\n│ │ └── cost_estimator.py # Cost estimation logic\n│ │\n│ └── web/\n│ ├── server.py # FastAPI server (REST + SSE)\n│ ├── dashboard.html # Single-page dark-themed UI\n│ ├── event_bus.py # SSE event bus\n│ ├── sessions.py # MultiSessionManager, SessionInfo\n│ ├── session_manager.py # Legacy singleton session manager\n│ ├── settings_manager.py # API key & local endpoint management\n│ └── state.py # Shared session state\n│\n├── src/profiles/default.yaml # 6 agent personality profiles\n├── src/config/models.yaml # LLM model definitions\n│\n└── tests/\n ├── conftest.py # Shared fixtures (mock LLM)\n ├── test_models.py\n ├── test_config.py\n ├── test_orchestrator.py\n ├── test_agents.py\n ├── test_collaboration.py\n ├── test_scribe.py\n ├── test_prompts.py\n └── test_integration.py # End-to-end workflow tests\n```\n\n---\n\n## Running Tests\n\n```bash\n# From the deepresearch workspace\ncd workspaces/deepresearch\n\n# Run all tests\npytest tests/ -v\n\n# Run with coverage\npytest tests/ -v --cov=deepresearch\n\n# Run a specific test file\npytest tests/test_orchestrator.py -v\n```\n\n---\n\n## Design Documents\n\n- **Design doc**: `docs/design/README.md` — full architecture, data model, component design, and implementation plan\n- **ADR-0001**: `docs/adr/ADR-0001-multi-agent-research-architecture.md` — multi-agent architecture decisions\n- **ADR-0002**: `docs/adr/ADR-0002-agent-personality-and-model-selection.md` — personality profiles and model selection modes\n- **ADR-0003**: `docs/adr/ADR-0003-web-frontend-and-multi-session.md` — web frontend, multi-session architecture, and settings management\n\n---\n\n## License\n\nMIT — part of the [KodeHold](https://github.com/kiffer5000/kodehold) project.\n"}, "2fd865c67c5190cfe4d5f4af6bde266d64bed07b": {"t": 1785772127.8557243, "n": 18000, "h": "8b610dd692c17f56", "c": "# DeepeResearch — Multi-Agent AI Research System\n\n> Six AI agents with distinct personalities collaborate to research any topic and produce a comprehensive, multi-perspective PDF paper.\n\n---\n\n## What is DeepeResearch?\n\nDeepeResearch 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.\n\nThe 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.\n\nThe result is a nuanced, multi-perspective research paper that no single-prompt system could produce.\n\n```\n Topic\n │\n ▼\n┌──────────────┐\n│ Orchestrator │ ── assigns models, manages rounds\n└──────┬───────┘\n │\n ├──────────── Round 1 (parallel) ────────────┐\n │ ┌────────┐ ┌────────┐ ┌──────┐ ┌────┐ │\n ├──│ Agent 1 │ │ Agent 2 │ │ … │ │Agent6│ │\n │ └────────┘ └────────┘ └──────┘ └────┘ │\n │ │\n ├──────── Collaboration Bus ──────────────────┤\n │ Agents share findings, ask each other Qs │\n │ │\n ├──────── Round 2 (parallel, refined) ───────┤\n │ Each agent researches again, now informed │\n │ by what the others found │\n └────────────────────┬───────────────────────┘\n │\n ▼\n ┌──────────────┐\n │ Scribe Agent │ ── compiles, deduplicates, synthesizes\n └──────┬───────┘\n │\n ▼\n ┌──────────┐\n │ PDF Paper │ ── cover page, all perspectives, synthesis\n └──────────┘\n```\n\n---\n\n## Architecture Overview\n\n| Component | Role |\n|-----------|------|\n| **Orchestrator** | Manages the full session lifecycle — config validation, model assignment, round sequencing, error handling, and event logging. Runs as a finite state machine (`IDLE → CONFIGURING → ROUND1 → COLLABORATING → FOLLOWUP → ROUND2 → COMPILING → OUTPUT → COMPLETE`). |\n| **Research Agents** | Six parallel AI agents, each with a distinct personality profile (prompt + temperature). Run concurrently via `asyncio.gather()`. |\n| **Collaboration Bus** | In-memory shared knowledge store. After Round 1, the orchestrator aggregates all findings into `SharedKnowledge` (consensus points, conflicting perspectives, unanswered questions). Each agent sees this before Round 2 — preventing groupthink by design. |\n| **Scribe Agent** | Neutral, academic-tone agent (temperature 0.3) that compiles all individual reports into a coherent paper. Handles de-duplication, cross-report synthesis, and clarification queries. Uses a structured pipeline: Extract → Compare → Weave → Clarify. |\n| **PDF Generator** | Renders the final paper via Jinja2 HTML templates → WeasyPrint PDF. Falls back to HTML if PDF generation fails. |\n\n---\n\n## The 6 Agent Personalities\n\nEach agent is defined by a YAML profile that includes a full persona prompt, methodology, knowledge base description, bias mitigation instructions, voice/tone guidance, and an LLM temperature setting.\n\n| Agent | Emoji | Temperature | Approach | Voice |\n|-------|-------|:-----------:|----------|-------|\n| Curious Teenager | 🔍 | **0.90** | Naive curiosity, asks \"why\" repeatedly, explores tangents, pop culture connections | Inquisitive, enthusiastic, conversational |\n| Skeptical Academic | 📚 | **0.30** | Demands evidence, challenges assumptions, finds flaws, rigorous methodology | Precise, critical, formal |\n| Creative Artist | 🎨 | **0.95** | Metaphors, unexpected connections, visual thinking, storytelling | Expressive, metaphorical, imaginative |\n| Pragmatic Engineer | ⚙️ | **0.40** | Implementation, trade-offs, feasibility, real-world impact | Direct, practical, solution-oriented |\n| Philosophical Thinker | 🤔 | **0.85** | Ethics, first principles, deeper meaning, human significance | Contemplative, Socratic, abstract |\n| Data-Driven Analyst | 📊 | **0.20** | Metrics, statistics, quantitative evidence, patterns, trends | Factual, analytical, structured |\n\n**The Scribe has no personality** — it maintains a neutral academic tone at temperature 0.3, acting as an impartial compiler and synthesizer.\n\n---\n\n## Model Selection\n\nDeepeResearch supports three modes for assigning LLM models to agents.\n\nThe new default model is **`opencode/go`** (Opencode AI), with `opencode/zen` also available. You can also access these models via OpenRouter as `openrouter/opencode/go` and `openrouter/opencode/zen`.\n\n### Provider Prefix Routing\n\nThe LLMClient auto-detects the provider from the model ID prefix. For example, `opencode/go` routes to `https://api.opencode.ai/v1` using `OPENCODE_API_KEY`, while `openrouter/opencode/go` routes to OpenRouter. This means you can mix models from different providers by simply using their prefixed model IDs.\n\n| Prefix | API Base | Env Variable |\n|--------|----------|-------------|\n| `opencode/` | `https://api.opencode.ai/v1` | `OPENCODE_API_KEY` |\n| `openrouter/` | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` |\n| `groq/` | `https://api.groq.com/openai/v1` | `GROQ_API_KEY` |\n| `together/` | `https://api.together.xyz/v1` | `TOGETHER_API_KEY` |\n| `deepseek/` | `https://api.deepseek.com/v1` | `DEEPSEEK_API_KEY` |\n| `cohere/` | `https://api.cohere.ai/v1` | `COHERE_API_KEY` |\n| `google/` | `https://generativelanguage.googleapis.com/v1` | `GOOGLE_API_KEY` |\n| `anthropic/` | `https://api.anthropic.com/v1` | `ANTHROPIC_API_KEY` |\n| `ollama/` | (local) | — |\n\n### Same Model (default)\nAll 6 agents use the same underlying LLM. Personality differentiation comes entirely from the prompt instructions and temperature settings. This is the cheapest and fastest option, and works well for most use cases.\n\n```bash\ndeepresearch run \"Topic\" --same\n# or just omit the flag — same model is default\ndeepresearch run \"Topic\"\n```\n\n### Random Models\nEach agent gets a randomly assigned model from your configured pool. The random seed is derived from the topic string, making assignments **deterministic and reproducible** — same topic always gets the same model distribution.\n\n```bash\ndeepresearch run \"Topic\" --random-models\n```\n\n### Manual Selection\nThe system prompts you to choose a model for each agent interactively before the session starts.\n\n```bash\ndeepresearch run \"Topic\" --manual-models\n```\n\n### Model Selector (Web UI)\n\nWhen using the web dashboard, you can pick models visually:\n- **\"Same\" mode** — single model dropdown for all agents\n- **\"Manual\" mode** — per-agent model selectors\n- **\"Random\" mode** — info text explaining random assignment from pool\n\nThe `/api/models` endpoint auto-discovers models from ALL configured providers (OpenAI, OpenRouter, Anthropic, Groq, Together, DeepSeek, Google, Cohere) via their respective APIs, merged with curated `models.yaml` definitions and locally-discovered Ollama models. Results are cached for 60 seconds.\n\n---\n\n## Installation\n\nDeepeResearch is part of the KodeHold project. You run it from the workspace directory.\n\n```bash\n# Navigate to the workspace\ncd workspaces/deepresearch\n\n# Create and activate a virtual environment (recommended)\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Verify it works\ndeepresearch --version\n```\n\n### Prerequisites\n\n- **Python 3.11+**\n- **API key** for at least one LLM provider:\n - `OPENAI_API_KEY` — OpenAI (GPT-4o, GPT-4o Mini)\n - `ANTHROPIC_API_KEY` — Anthropic (Claude Sonnet 4, Claude Haiku 3.5)\n - `OPENCODE_API_KEY` — Opencode AI (Opencode Go, Opencode Zen)\n - `OPENROUTER_API_KEY` — OpenRouter (access to 100+ models)\n - Or configure **Ollama** locally for Llama 3.1, Mixtral, etc.\n- **WeasyPrint system dependencies** (Linux only):\n ```bash\n sudo apt install libpango-1.0-0 libcairo2 libgdk-pixbuf2.0-dev\n ```\n\n---\n\n## CLI Usage\n\n### Quick Start\n\n```bash\n# See available agent profiles and their personalities\ndeepresearch profiles list\n\n# See which LLM models are configured\ndeepresearch models list\n\n# Dry-run — validates config without making any API calls\ndeepresearch run \"Quantum computing\" --quick --dry-run\n\n# Full research session\ndeepresearch run \"The future of renewable energy\" --quick\n\n# Balanced research with random model assignment\ndeepresearch run \"Consciousness in AI\" --random-models\n\n# Deep research with web dashboard\ndeepresearch run \"Geopolitics of rare earth minerals\" --deep --web\n```\n\n### All Options\n\n```\ndeepresearch run <topic> \\\n [--quick | --deep] \\\n [--time <minutes>] \\\n [--same | --random-models | --manual-models] \\\n [--output ./path.pdf] \\\n [--web] [--web-host 0.0.0.0] [--web-port 8080] \\\n [--dry-run]\n\ndeepresearch serve [--host 0.0.0.0] [--port 8080]\ndeepresearch profiles list\ndeepresearch models list\n```\n\n### Time Budget\n\n| Mode | Duration | Rounds | Use Case |\n|------|:--------:|:------:|----------|\n| `--quick` | ~5 min | 1 round | Quick overview or exploratory research |\n| `--time 15` (medium) | ~15 min | 2 rounds | Balanced depth and breadth (default-style) |\n| `--deep` or `--time 30` | ~30 min | 2 rounds | Thorough, comprehensive research |\n| `--time 60` | ~60 min | 2 rounds | Exhaustive deep-dive |\n\nThe time budget controls how much the agents write — shorter budgets produce more concise findings, longer budgets allow deeper exploration and more extensive analysis. Use `--time <N>` for fine-grained control between the presets.\n\n---\n\n## Web Dashboard\n\nDeepeResearch includes a real-time web dashboard built with FastAPI + SSE streaming.\n\n```bash\n# Start the dashboard server standalone\ndeepresearch serve\n# Open http://localhost:8080/\n\n# Run a session with the dashboard\ndeepresearch run \"Topic\" --web\n# Opens http://localhost:8080/ automatically\n\n# Custom host/port\ndeepresearch serve --host 127.0.0.1 --port 9090\ndeepresearch run \"Topic\" --web --web-host 127.0.0.1 --web-port 9090\n```\n\n### Dashboard Features\n\n- **Topic input** field with time budget and model mode selectors\n- **\"Start Research\"** button to launch a session\n- **Model dropdown selector** — for \"same\" mode, a single dropdown; for \"manual\" mode, per-agent model selectors; info text for \"random\" mode\n- **Provider model auto-discovery** — the model dropdown fetches from `/api/models`, which discovers models from ALL configured providers (OpenAI, OpenRouter, Anthropic, Groq, Together, DeepSeek, Google, Cohere) plus Ollama local models, all merged with the curated `models.yaml` definitions (60s cache)\n- **Real-time agent progress bars** via SSE streaming — see each agent's status update as it works\n- **Live event log** with timestamps showing every phase transition, agent completion, and clarification round\n- **Cancel button** to gracefully stop a running session\n- **Delete session / Clear All buttons** — delete individual sessions via the `DELETE /api/sessions/{id}` endpoint, or clear all completed/errored sessions with one click. Session output files are cleaned up on deletion.\n- **Download PDF / Download HTML** buttons when the research completes\n- **Settings tab** — manage API keys (9 supported providers including Opencode AI) and local model endpoints (Ollama, llama.cpp, vLLM) through the UI without touching the terminal\n- **Dark-themed UI** with GitHub-dark aesthetic, color-coded state badges, and agent emoji indicators\n\nThe dashboard shows a status bar at the top with the current orchestrator state (idle, configuring, round 1, collaborating, follow-up, round 2, compiling, complete, error) and a grid layout with agent progress cards on the left and a scrolling event log on the right.\n\n---\n\n## Output\n\nThe final output is a professionally formatted research paper.\n\n**PDF paper** (primary output):\n- Cover page with title and generation timestamp\n- Abstract summarizing the research\n- Per-agent findings — each personality's unique perspective in its own section\n- Synthesis section — where the scribe weaves perspectives together\n- Key takeaways — actionable conclusions distilled from all agents\n- Conclusion — final synthesis\n\n**HTML fallback**: If PDF generation fails (e.g., missing WeasyPrint deps), the paper is saved as HTML with the same structure.\n\nFiles are written to `./output/` by default (configurable with `--output`):\n```\n./output/paper.pdf # Final research paper\n./output/paper.html # HTML version (fallback or paired output)\n```\n\nDownload both from the web dashboard when running with `--web`.\n\n---\n\n## Configuration\n\n### Agent Profiles\n\nThe six built-in agent personalities are defined in:\n\n```\nsrc/profiles/default.yaml\n```\n\nEach profile contains: `id`, `name`, `emoji`, `temperature`, `persona_prompt`, `methodology`, `knowledge_base`, `bias_mitigation`, and `voice`.\n\nYou can create custom profiles:\n```\n~/.deepresearch/profiles/custom.yaml\n```\n\n### Model Definitions\n\nAvailable LLM models are configured in:\n\n```\nsrc/config/models.yaml\n```\n\nDefault models are now **`opencode/go`** (default) and **`opencode/zen`**, both routed via Opencode AI. OpenRouter alternatives (`openrouter/opencode/go`, `openrouter/opencode/zen`) are also included. Curated models also cover GPT-4o, GPT-4o Mini, Claude Sonnet 4, Claude Haiku 3.5, Llama 3.1 (Ollama), and Mixtral (Ollama).\n\n**Provider prefix routing** — the LLMClient maps model ID prefixes to API base URLs and API key environment variables. This means any model ID like `anthropic/claude-sonnet-4-20250514` or `groq/llama3-70b` routes to the correct provider automatically.\n\n**Model auto-discovery** — the `/api/models` endpoint goes beyond `models.yaml`. It also:\n- Fetches model lists from ALL configured providers (OpenAI, OpenRouter, Anthropic, Groq, Together, DeepSeek, Google, Cohere) via their REST APIs\n- Auto-discovers Ollama models from `http://localhost:11434/api/tags`\n- Merges locally-configured endpoints (llama.cpp, vLLM)\n- Caches results for 60 seconds\n\n**Model cost tracking** — per-model input/output cost rates are defined in `llm/client.py`. Costs are roughly calibrated based on published pricing. Add any model supported by LiteLLM.\n\n---\n\n## Project Structure\n\n```\nworkspaces/deepresearch/\n├── pyproject.toml # Package config, dependencies, entry point\n├── src/\n│ └── deepresearch/\n│ ├── __init__.py\n│ ├── __main__.py # Entry: python -m deepresearch\n│ ├── main.py # CLI entry point (argparse + rich)\n│ ├── models.py # Pydantic data models\n│ ├── config.py # YAML config loading and validation\n│ ├── orchestrator.py # Session lifecycle FSM\n│ │\n│ ├── agents/\n│ │ ├── base_agent.py # Abstract ResearchAgent base class\n│ │ ├── research_agent.py # 6 personality research agents\n│ │ ├── scribe_agent.py # Compilation and synthesis agent\n│ │ └── registry.py # Agent factory and profile registry\n│ │\n│ ├── collaboration/\n│ │ └── bus.py # In-memory shared knowledge bus\n│ │\n│ ├── llm/\n│ │ └── client.py # LiteLLM async wrapper with retry\n│ │\n│ ├── output/\n│ │ ├── pdf_generator.py # WeasyPrint PDF rendering\n│ │ └── templates/ # Jinja2 HTML + CSS templates\n│ │\n│ ├── prompts/\n│ │ ├── research.py # Research round prompt templates\n│ │ ├── scribe.py # Scribe compilation prompts\n│ │ └── collaboration.py # Collaboration/sharing prompts\n│ │\n│ ├── utils/\n│ │ ├── token_tracker.py # Token usage tracking\n│ │ └── cost_estimator.py # Cost estimation logic\n│ │\n│ └── web/\n│ ├── server.py # FastAPI server (REST + SSE)\n│ ├── dashboard.html # Single-page dark-themed UI\n│ ├── event_bus.py # SSE event bus\n│ ├── sessions.py # MultiSessionManager, SessionInfo\n│ ├── session_manager.py # Legacy singleton session manager\n│ ├── settings_manager.py # API key & local endpoint management\n│ └── state.py # Shared session state\n│\n├── src/profiles/default.yaml # 6 agent personality profiles\n├── src/config/models.yaml # LLM model definitions\n│\n└── tests/\n ├── conftest.py # Shared fixtures (mock LLM)\n ├── test_models.py\n ├── test_config.py\n ├── test_orchestrator.py\n ├── test_agents.py\n ├── test_collaboration.py\n ├── test_scribe.py\n ├── test_prompts.py\n └── test_integration.py # End-to-end workflow tests\n```\n\n---\n\n## Running Tests\n\n```bash\n# From the deepresearch workspace\ncd workspaces/deepresearch\n\n# Run all tests\npytest tests/ -v\n\n# Run with coverage\npytest tests/ -v --cov=deepresearch\n\n# Run a specific test file\npytest tests/test_orchestrator.py -v\n```\n\n---\n\n## Design Documents\n\n- **Design doc**: `docs/design/README.md` — full architecture, data model, component design, and implementation plan\n- **ADR-0001**: `docs/adr/ADR-0001-multi-agent-research-architecture.md` — multi-agent architecture decisions\n- **ADR-0002**: `docs/adr/ADR-0002-agent-personality-and-model-selection.md` — personality profiles and model selection modes\n- **ADR-0003**: `docs/adr/ADR-0003-web-frontend-and-multi-session.md` — web frontend, multi-session architecture, and settings management\n\n---\n\n## License\n\nMIT — part of the [KodeHold](https://github.com/kiffer5000/kodehold) project.\n"}}}} |