DeepQuery

Open-source deep research engine. Your models, your search, your pipeline.

---

Give it a question. Get back a comprehensive, multi-source research report with citations — automatically. Think Perplexity Deep Research, but fully self-hosted, runtime-configurable, and capable of running entirely on local models with zero API keys.

# Zero-key quick start — just Ollama + DuckDuckGo, no accounts needed
ollama pull llama3.2
git clone https://github.com/yourusername/deepquery.git && cd deepquery
docker compose up

Open localhost:3000, select Ollama as your provider, and run your first research query.

Need more power? Swap in Claude, GPT-4o, or Gemini for individual pipeline phases — use a cheap model for planning, a powerful one for final writing — all from the UI at runtime.

---

Why DeepQuery?

Every existing open-source deep research tool (gpt-researcher, deep-research, STORM, open-deep-research) has the same problem: you can't even run them without paying for API keys first. They hardcode OpenAI, lock you into Tavily for search, and give you zero control over what happens between "submit query" and "here's your report."

DeepQuery was built to fix all of that:

Pain point with existing tools	How DeepQuery solves it
Requires paid API keys to start	Run entirely free with Ollama (local LLM) + DuckDuckGo (free search). Zero accounts, zero billing.
Locked to one LLM provider	6 providers (2 local, 4 cloud). Mix them in the same run — cheap model for planning, powerful one for writing.
Black-box pipeline	Visual pipeline editor in the UI. Add, remove, reorder, and disable phases. Edit system prompts inline. No code changes.
No idea what's happening during research	Terminal-style console streams every phase with timing. Token-level LLM output so you watch the report being written live.
Results disappear after the tab closes	SQLite-backed research history. Browse, re-read, and export past reports as Markdown or styled HTML.
Can't search academic sources	5 search backends including Arxiv (papers), Wikipedia (encyclopedic), and SearXNG (self-hosted meta-search) — all free.
Your data goes through third-party servers	Fully self-hosted. Docker Compose one-command deploy. Your queries and results never leave your machine.

In short: DeepQuery is the only open-source deep research tool that works out of the box with zero cost, gives you full control over every phase of the pipeline, and keeps everything local.

---

Features

Multi-Agent Research Pipeline

A LangGraph-orchestrated pipeline breaks your query into sub-questions, searches the web, synthesizes findings, and writes a polished report — all streaming in real time.

Default pipeline: Planner → Web Search → Analyst → Writer

Each phase is independently configurable. Add reflection loops for iterative deepening. Disable phases you don't need. Edit system prompts inline.

6 LLM Providers

Provider	Type	API Key
Ollama	Local	Not required
LM Studio	Local	Not required
Anthropic (Claude)	Cloud	Required
OpenAI (GPT-4o)	Cloud	Required
Google Gemini	Cloud	Required
Groq	Cloud	Required (free tier available)

5 Search Backends

Provider	API Key	Best For
DuckDuckGo	Not required	General web search (default)
Tavily	Required (free tier)	AI-optimized, higher quality results
Arxiv	Not required	Academic papers and preprints
Wikipedia	Not required	Encyclopedic knowledge
SearXNG	Not required	Self-hosted meta-search engine

Per-Phase Model Assignment

Use Groq's free Llama 3.3 70B for planning (fast, cheap), Claude for analysis (smart), and GPT-4o for writing (polished) — all in the same research run. Configure from the UI, no restarts needed.

Reflection Loops

Enable the optional Reflector phase to evaluate research quality. If gaps are found, it loops back to search for more information — up to 3 iterations. Disabled by default, one toggle to enable.

Real-Time Streaming Console

A terminal-style console shows every step of the research process:

• Phase start/completion with timing
• Live LLM token output (watch the report being written)
• Sub-query breakdown from the planner

Research History

All sessions persist to SQLite. Browse past research, view reports, export as Markdown or styled HTML. Data survives container restarts via Docker volumes.

---

Architecture

The pipeline is a LangGraph state machine. Each node (Planner, Searcher, Analyst, Writer) streams tokens via SSE as it runs. The optional Reflector node creates a loop — if it judges the research incomplete, it generates gap queries and routes back to the Searcher for another round.

Tech Stack

Layer	Technology
Agent orchestration	LangGraph + LangChain
Backend	FastAPI + SSE (sse-starlette)
Frontend	React 18 + TypeScript + Tailwind CSS + Vite
Database	SQLite via aiosqlite
Deployment	Docker Compose (multi-stage builds)

---

Getting Started

Docker (Recommended)

Prerequisites: Docker with Compose. For local-only mode, Ollama running on your host.

git clone https://github.com/yourusername/deepquery.git
cd deepquery
cp .env.example .env    # optional: add API keys for cloud providers
docker compose up

Open localhost:3000.

Docker networking: On Windows/Mac, Docker Desktop resolves host.docker.internal automatically. On Linux, the included docker-compose.yml handles it via extra_hosts.

Local Development

Prerequisites: Python 3.11+, Node.js 18+

# Backend
cd backend
pip install uv && uv pip install -e ".[dev]"
uvicorn src.main:app --reload --port 8000

# Frontend (separate terminal)
cd frontend
npm install
npm run dev

Open localhost:5173.

---

Configuration

All configuration is via environment variables. Copy .env.example to .env — all fields are optional when using Ollama + DuckDuckGo.

Variable	Description	Default
LLM_PROVIDER	Default LLM provider	anthropic
LLM_MODEL	Default model name	claude-sonnet-4-6
ANTHROPIC_API_KEY	Anthropic API key	—
OPENAI_API_KEY	OpenAI API key	—
GEMINI_API_KEY	Google Gemini API key	—
GROQ_API_KEY	Groq API key	—
OLLAMA_HOST	Ollama server hostname	localhost
LMSTUDIO_HOST	LM Studio server hostname	localhost
SEARCH_PROVIDER	Search backend (auto, tavily, duckduckgo, arxiv, wikipedia, searxng)	auto
TAVILY_API_KEY	Tavily search API key	—
SEARXNG_URL	SearXNG instance URL	—
APP_ENV	development or production	development
LOG_LEVEL	Logging level	INFO

auto search mode uses Tavily if a key is configured, otherwise falls back to DuckDuckGo.

---

API Reference

All endpoints are under /api/v1.

Research

Method	Endpoint	Description
POST	/research/stream	Stream research via SSE (token-level LLM output, phase progress, final report)
POST	/research	Run full pipeline, return complete result
GET	/research/history	List past research sessions
GET	/research/{id}	Get a specific research record
DELETE	/research/{id}	Delete a research record
GET	/research/{id}/export?format=md|html	Export report as Markdown or styled HTML

Stream request body:

{
  "query": "What is the impact of AI on software development?",
  "depth": 3,
  "max_iterations": 2,
  "provider": { "provider": "ollama", "model": "llama3.2" },
  "search_provider": "duckduckgo"
}

SSE event types: token (live LLM output), progress (phase completion with timing), result (final report + sources), saved (persistence confirmation), error, done.

Pipeline & Providers

Method	Endpoint	Description
GET	/pipeline/default	Default pipeline configuration
GET	/providers	All LLM providers with availability and models
GET	/providers/ollama/models	Live-fetch Ollama models
GET	/providers/lmstudio/models	Live-fetch LM Studio models
GET	/search-providers	Available search backends
GET	/health	Health check

---

Comparison

Feature	DeepQuery	gpt-researcher	dzhng/deep-research	STORM	open-deep-research
Zero-API-key mode	Yes	No	No	No	No
Local model support	Ollama + LM Studio	No	No	No	Limited
Per-phase model config	Yes	No	No	No	No
Runtime pipeline editor	Yes (UI)	No	No	No	No
LLM providers	6	2	1	1–2	2–3
Search providers	5	1	1	1	1
Token-level streaming	Yes (SSE)	WebSocket	No	No	SSE
Reflection loop	Yes	Yes	Yes	Yes	Yes
Research history	Yes	No	No	No	No
Web UI	Yes	Yes	No (CLI)	Yes	Yes
HTML export	Yes	No	No	No	No
Docker one-command deploy	Yes	Yes	No	No	Yes
License	MIT	Apache 2.0	MIT	Apache 2.0	MIT

---

Project Structure

deepquery/
├── backend/
│   ├── src/
│   │   ├── agents/          # LangGraph nodes (planner, searcher, analyst, writer, reflector)
│   │   ├── api/             # FastAPI routes + SSE streaming
│   │   ├── graph/           # LangGraph pipeline builder
│   │   ├── models/          # Pydantic models (state, request, config)
│   │   ├── utils/           # Defaults, config, provider helpers
│   │   ├── db.py            # SQLite persistence
│   │   └── main.py          # App entry point
│   ├── pyproject.toml
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── components/      # React UI (SearchBar, Console, PipelineEditor, etc.)
│   │   ├── hooks/           # useResearch, usePipeline, useProvider
│   │   └── lib/             # API client
│   ├── package.json
│   └── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

---

Contributing

Contributions welcome! To get started:

1. Fork the repo
2. Create a feature branch: git checkout -b feature/my-feature
3. Set up local dev (see Local Development)
4. Run tests: cd backend && pytest tests/ --cov=src
5. Lint: cd backend && ruff check src/
6. Open a PR

Please open an issue first for large changes.

---

License

MIT