Deepr

# Deepr

![Tests](https://img.shields.io/badge/tests-3000%2B%20passing-green)
![CI](https://img.shields.io/badge/CI-GitHub%20Actions-blue)
![License](https://img.shields.io/badge/license-MIT-blue)
![Python](https://img.shields.io/badge/python-3.9+-blue)

**The same deep research agents behind ChatGPT and Gemini — but scriptable.**

```bash
deepr research "What are the security implications of AWS Bedrock vs Azure OpenAI for enterprise RAG?"
```

ChatGPT and Gemini have powerful deep research, but it's trapped in a chat window. You can't script it, schedule it, or call it from your AI agents. Deepr fixes that.

## What You Can Do

- **Give your AI agents real research capabilities** — Claude Code, Cursor, VS Code can call deep research mid-task. Not hallucinations — actual research with citations. Agents can query experts, trigger research to fill knowledge gaps, and continue with accurate information.
- **Build institutional knowledge that doesn't walk out the door** — Create experts from your architecture docs, runbooks, and post-mortems. They learn, improve, and stay when people leave.
- **Weekly competitive intelligence** — Schedule research on competitor announcements, market trends, or regulatory changes. Wake up Monday with a digest.
- **Due diligence at scale** — Researching an acquisition target? Run 30 queries overnight covering their tech stack, patents, key hires, and market position.
- **Switch providers without changing code** — Same interface across OpenAI, Gemini, Grok, and Anthropic

## Why Deepr?

| If you need... | Use |
|----------------|-----|
| Occasional research | ChatGPT or Gemini web UI |
| Automated research on a schedule | **Deepr** |
| AI agents that can research and learn mid-task | **Deepr** (MCP + Skills) |
| Institutional knowledge that learns and persists | **Deepr** |
| Due diligence or competitive intel at scale | **Deepr** |

Deepr wraps the same underlying APIs (OpenAI's o3/o4-mini-deep-research, Gemini's Deep Research Agent) and adds:

- **Automation** — Run from scripts, cron jobs, CI pipelines. No browser required.
- **Domain experts** — Build persistent experts from your documents that answer questions, recognize knowledge gaps, and research autonomously to fill them.
- **MCP integration** — Your AI agents (Claude Desktop, Cursor, VS Code, Zed) can invoke deep research as a tool.
- **Multi-provider** — Same interface across OpenAI, Gemini, Grok, and Anthropic. Auto-fallback on failures.
- **Cost controls** — Per-job budgets, daily limits, cost tracking. Never get surprised by a bill.
- **Local storage** — Reports saved as markdown files you own. No vendor lock-in.

## Quick Start

```bash
pip install -e .                        # Install
cp .env.example .env                    # Add OPENAI_API_KEY=sk-...
deepr doctor && deepr budget set 5      # Verify setup, set $5 budget
deepr research "Your question here"     # Run your first research job (~$1-2)
```

That's it. Results saved to `reports/` as markdown with citations.

Optional extras:

```bash
pip install -e ".[web]"                 # Web UI and MCP server
pip install -e ".[docs]"                # Document processing for experts
pip install -e ".[full]"                # All features
```

See [docs/QUICK_START.md](docs/QUICK_START.md) for a guided setup.

## Features

### Deep Research via CLI

Submit research queries that use the same deep research agents as ChatGPT and Gemini. They search the web, synthesize sources, and produce structured reports with citations. Results saved locally as markdown.

```bash
# Architecture decisions
deepr research "Kubernetes vs ECS Fargate for multi-tenant SaaS: cost, complexity, and scaling tradeoffs"

# Compliance research
deepr check "Does SOC 2 Type II require encryption at rest for all PII?"

# Technology evaluation
deepr learn "Service mesh options for hybrid cloud" --phases 3

# Strategic decisions
deepr team "Should we build an internal ML platform or use AWS SageMaker?"

# Vendor analysis
deepr make strategy "Migrate from Snowflake to Databricks" --perspective cost
```

### Domain Experts (The Interesting Part)

This is where Deepr goes beyond "ChatGPT but CLI."

**The problem:** Your best architect leaves. Their knowledge — scattered across Confluence, Slack threads, and their head — walks out the door. Or: AWS releases 47 new services this year. Your team can't keep up.

**Traditional RAG:** Upload docs → query → get answer. Static. Never learns. Never knows what it's missing.

**Deepr experts are different:**
- **Self-aware** — They recognize when they don't know something instead of hallucinating
- **Self-improving** — They can trigger research to fill their own knowledge gaps
- **Persistent** — New knowledge integrates permanently, not just for one session
- **Portable** — Export an expert and share it across your organization

```bash
# Create an expert from your architecture docs, runbooks, ADRs
deepr expert make "Platform Team Expert" --files docs/*.md confluence-

... (truncated)