Metadata-Version: 2.4
Name: ddg-deep-research
Version: 0.2.0
Summary: 5-stage deep research pipeline using DuckDuckGo MCP — free, no API key, no rate limits
Project-URL: Homepage, https://github.com/crftsmnd/ddg-deep-research
Project-URL: Repository, https://github.com/crftsmnd/ddg-deep-research
Project-URL: Bug Tracker, https://github.com/crftsmnd/ddg-deep-research/issues
Author: crftsmnd
License: MIT
License-File: LICENSE
Keywords: agent,deep-research,duckduckgo,llm,mcp,research,web-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0
Description-Content-Type: text/markdown

# 🧠 ddg-deep-research

**5-stage deep research pipeline** using DuckDuckGo MCP — **free, no API key, no rate limits**.

```
pip install ddg-deep-research
ddg-deep-research search "your query"
```

## Why this exists

Every other deep research agent requires OpenAI / Anthropic / Google API keys — or runs expensive local models. This one uses **DuckDuckGo MCP** for both search and content extraction. Completely free. Zero API keys. Zero rate limits.

## Pipeline

```
Stage 1: Decompose  ──→ 3-6 sub-questions + search strategy
Stage 2: Gather     ──→ DuckDuckGo MCP search (parallel, unlimited)
Stage 3: Deep Read  ──→ DuckDuckGo MCP fetch_content + browser_use
Stage 4: Verify     ──→ Cross-reference claims, flag contradictions
Stage 5: Synthesize ──→ Cited brief.md + .provenance.md sidecar
```

## Quick Start

```bash
# Search the web (free, no API key!)
ddg-deep-research search "latest advances in AI reasoning"

# Fetch a webpage
ddg-deep-research fetch "https://example.com/article"
```

### Full Pipeline

```bash
# Stage 1: Break question into sub-questions (template)
ddg-deep-research decompose --question "How is RAG evolving?" --output plan.json

# Stage 2: Search
ddg-deep-research ddg_search --query "RAG architectures 2026" --output results.json

# Stage 3: Fetch content
ddg-deep-research ddg_fetch --url "https://..." --output-dir extracted/

# Stage 4: Merge results
ddg-deep-research merge --input-dir raw/ --output merged.json

# Stage 5: Clean & verify
ddg-deep-research clean --input extracted/ --output cleaned/
ddg-deep-research verify --input cleaned/cleaned.json --output verified.json

# Stage 6: Generate final brief
ddg-deep-research synthesize --verified verified.json --question "..." --output-dir outputs/ --today $(date +%Y-%m-%d)
```

### Parallel DAG Execution

```bash
ddg-deep-research dag --plan workflow.json --verbose
```

Input JSON:
```json
{
  "tasks": [
    {"id": "search_1", "depends_on": [], "command": "ddg_search --query ..."},
    {"id": "fetch_1", "depends_on": ["search_1"], "command": "ddg_fetch --url ..."},
    {"id": "synthesize", "depends_on": ["search_1", "fetch_1"], "command": "synthesize ..."}
  ]
}
```

## Python API

```python
import asyncio
from ddg_deep_research.ddg_mcp import search_web, fetch_content

async def main():
    results = await search_web("your query", max_results=10)
    for r in results:
        print(f"{r['title']}: {r['url']}")

    content = await fetch_content("https://example.com")
    print(content[:500])

asyncio.run(main())
```

## Requirements

- Python 3.10+
- `uv` installed (for duckduckgo-mcp-server): `curl -LsSf https://astral.sh/uv/install.sh | sh`
- No API keys. No subscriptions. Nothing.

## How it works

This package wraps [duckduckgo-mcp-server](https://github.com/nicholasgriffintn/duckduckgo-mcp-server) via Python's MCP stdio transport. All search and content extraction goes through DuckDuckGo's free anonymous API. The 5-stage pipeline is modeled after production research agents but without the API costs.

## Comparison

| Feature | OpenAI Deep Research | LangChain Deep Research | **ddg-deep-research** |
|---|---|---|---|
| API key needed | ✅ $200/mo | ✅ OpenAI key | **❌ Free** |
| Search engine | Bing/Browser | Custom | **DuckDuckGo** |
| Content extraction | Built-in | Built-in | **DuckDuckGo MCP** |
| Provenance tracking | ✅ | ✅ | **✅ .provenance.md** |
| DAG orchestration | ❌ | ❌ | **✅ Built-in** |
| Open source | ❌ | ✅ | **✅ MIT** |
| `pip install` | ❌ | ❌ | **✅ pip install** |

## License

MIT
