<p align="center">
  <img src="demo.gif" alt="BeHive — Deep Research Engine" width="720" />
</p>

<h1 align="center">🐝 BeHive</h1>

<p align="center">
  <strong>Open-source research engine that extracts structured knowledge from any topic.</strong><br />
  Feed it a question. Get back scored claims, entity graphs, and a synthesized report — not paragraphs of slop.
</p>

<p align="center">
  <a href="https://pypi.org/project/behive"><img src="https://img.shields.io/badge/pip_install-behive-FFB300?style=flat-square&logo=pypi&logoColor=white" /></a>
  <a href="https://www.npmjs.com/package/n8n-nodes-behive"><img src="https://img.shields.io/badge/n8n-community_node-FF6D5A?style=flat-square&logo=n8n&logoColor=white" /></a>
  <img src="https://img.shields.io/badge/MCP-Live-00C853?style=flat-square" />
  <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" />
  <img src="https://img.shields.io/badge/version-0.6.0-black?style=flat-square" />
</p>

---

## The Problem

You ask an AI to research something. It hallucinates confidently or gives you a 2000-word essay that says nothing specific. No sources. No confidence scores. No way to verify.

**BeHive fixes this.** It goes out, searches real sources, extracts verifiable claims with confidence scores, and builds a knowledge graph — all through your existing AI (Claude, ChatGPT, Gemini).

---

## ⚡ Use with Claude Desktop (10 seconds)

**No install needed.** Add this to your Claude Desktop config and you're done:

**File:** `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)

```json
{
  "mcpServers": {
    "behive": {
      "url": "https://api.behive.site/mcp",
      "transport": "streamable-http"
    }
  }
}
```

Restart Claude Desktop. Ask: *"Research the EU AI Act enforcement timeline"*

That's it. Claude calls BeHive automatically.

<details>
<summary>💡 What happens under the hood</summary>

```
You ask Claude → Claude calls BeHive MCP tool → BeHive scouts 70+ APIs
→ fetches 200+ URLs via stealth drones → extracts claims with scores
→ deduplicates → returns structured report to Claude
```

**Cost:** Free. The hosted MCP server is provided by the BeHive team.  
**Privacy:** Queries are processed and discarded. No data retention.
</details>

---

## ⚡ Use with ChatGPT (Custom GPT)

1. Go to [chat.openai.com/gpts/editor](https://chat.openai.com/gpts/editor)
2. Create a new GPT
3. Under **Actions** → click **Import from URL** → paste:
   ```
   https://api.behive.site/openapi.json
   ```
4. Name it "Deep Researcher" and save

Now ask your GPT: *"Research quantum computing breakthroughs 2026"*

---

## ⚡ Use with Cursor / Windsurf / Claude Code

Add to your MCP config (`.cursor/mcp.json`, `~/.claude/settings.json`, etc.):

```json
{
  "mcpServers": {
    "behive": {
      "url": "https://api.behive.site/mcp",
      "transport": "streamable-http"
    }
  }
}
```

---

## ⚡ Use with Hermes Agent / OpenClaw

```bash
# Hermes — already has a built-in skill
hermes skill install behive-research

# OpenClaw — copy from integrations/
cp integrations/openclaw/SKILL.md ~/.openclaw/skills/behive.md
```

---

## 🛠 Self-Host (full control)

Want to run BeHive on your own machine? Three options:

### Option A: Zero-setup (DuckDB, no PostgreSQL needed)

```bash
pip install behive
export ANTHROPIC_API_KEY=***  # or OPENAI_API_KEY

behive research "NVIDIA GPU market 2026"
```

Data is stored locally in `~/.behive/research.duckdb`. No database setup needed.

### Option B: Docker Compose (recommended for teams)

```bash
git clone https://github.com/qa10devteam/behive && cd behive
echo "ANTHROPIC_API_KEY=***" > .env
docker compose up -d
# API → http://localhost:8091
# MCP → http://localhost:8090/mcp
```

### Option C: Full production (PostgreSQL + GPU)

```bash
pip install "behive[all]"
export BEHIVE_DB_URL=postgresql://user:pass@localhost:5432/behive
export ANTHROPIC_API_KEY=***
behive serve
```

---

## 🧠 Model Configuration

BeHive works with any LLM. You choose what runs each pipeline stage:

| Stage | What it does | Recommended model |
|-------|-------------|-------------------|
| **scout** | Query generation, source planning | Claude Haiku 4.5 / GPT-4.1-mini / local |
| **harvest** | Content triage, relevance filtering | Claude Haiku 4.5 / GPT-4.1-mini / local |
| **process** | Claim extraction, entity recognition | Claude Sonnet 4.6 / GPT-4.5 / Gemini 2.5 Flash |
| **synth** | Report synthesis, deduplication | Claude Opus 4.6 / GPT-4.5 / Gemini 2.5 Pro |
| **falsifier** | Cross-verification, bias detection | Claude Sonnet 5 / o4-mini |

### Quick config

```bash
behive config --preset budget     # Haiku everywhere (~$0.30/mission)
behive config --preset balanced   # Haiku scout + Sonnet synth (~$1.50)
behive config --preset deep       # Opus synth + Falsifier (~$4.00)
```

### Model presets (2026)

| Preset | Model String |
|--------|-------------|
| `claude-haiku` | anthropic/claude-haiku-4-5-20251001 |
| `claude-sonnet` | anthropic/claude-sonnet-4-6 |
| `claude-opus` | anthropic/claude-opus-4-6-v1 |
| `claude-sonnet-5` | anthropic/claude-sonnet-5 |
| `gpt-4.1-mini` | openai/gpt-4.1-mini |
| `gpt-4.5` | openai/gpt-4.5-preview |
| `o4-mini` | openai/o4-mini |
| `gemini-flash` | google/gemini-2.5-flash |
| `gemini-pro` | google/gemini-2.5-pro |
| `llama-4` | ollama/llama4-scout |
| `local` | openai/local-model (any OpenAI-compatible endpoint) |

### Environment variables

```bash
export BEHIVE_MODEL=anthropic/claude-sonnet-4-6          # one model for everything
export BEHIVE_MODEL_SCOUT=ollama/llama4-scout            # per-stage override
export BEHIVE_MODEL_SYNTH=anthropic/claude-opus-4-6-v1   # per-stage override
```

Priority: `BEHIVE_MODEL_{STAGE}` > `BEHIVE_MODEL` > config.yaml > defaults

Or pass any [litellm-compatible](https://docs.litellm.ai/docs/providers) model string directly.

---

## Benchmarks

Real results. No cherry-picking. Scale 30 (standard depth).

| Topic | Claims | Avg Quality | Duration | Sources |
|:------|-------:|:-----------:|---------:|--------:|
| NVIDIA GPU market 2026 | 290 | **0.797** | 8 min | 234 |
| OpenAI o3 capabilities | 574 | **0.789** | 12 min | 174 |
| EU AI Act enforcement | 267 | **0.759** | 6 min | 130 |
| Meta Llama 4 architecture | 568 | **0.821** | 11 min | 198 |
| SpaceX Starship timeline | 312 | **0.804** | 9 min | 187 |

**Quality scoring:**
- `0.90+` — Exceptional: specific numbers, dates, fully verifiable
- `0.82+` — Excellent: multi-source corroboration, publication-ready
- `0.75+` — Good: useful intelligence with specifics
- `0.65+` — Acceptable: general facts
- `<0.55` — Rejected: too vague, not stored

> Honest scoring. No sigmoid rescaling, no artificial inflation.

---

## Drone Arsenal

BeHive's scout phase uses **70+ APIs** across 37 categories — no single source dependency:

| Category | Examples | Method |
|----------|----------|--------|
| Web search | DuckDuckGo, Brave, SearXNG | Multi-backend fallthrough |
| Academic | arXiv, Semantic Scholar, PubMed | Direct API |
| News | Google News RSS, NewsAPI, GDELT | Real-time feeds |
| Government | EU Open Data, USPTO, SEC EDGAR | Registry APIs |
| Code | GitHub, GitLab, npm, PyPI | Package ecosystems |
| Financial | Yahoo Finance, FRED, ECB | Market data |
| Social | Reddit, HN (via Algolia), X/Twitter | Community signals |

**Stealth layer:** 8-layer drone architecture bypasses Cloudflare, DataDome, Akamai, PerimeterX. Rotating fingerprints, browser TLS profiles, residential proxy support.

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                      BeHive Pipeline                          │
└─────────────────────────────────────────────────────────────┘
                              │
    ┌───────────┬─────────────┼─────────────┬───────────┐
    ▼           ▼             ▼             ▼           ▼
┌────────┐ ┌────────┐ ┌──────────┐ ┌────────┐ ┌────────┐
│ SCOUT  │ │HARVEST │ │ PROCESS  │ │ SYNTH  │ │ GRAPH  │
│        │ │        │ │          │ │        │ │        │
│ Queen  │ │Parallel│ │ Dual-    │ │ Report │ │ Neo4j  │
│ plans  │ │ fetch  │ │ model    │ │ synth  │ │ build  │
│ 200+   │ │ drones │ │ extract  │ │ dedupe │ │ entity │
│ tasks  │ │ 70 APIs│ │ + score  │ │ FUIR   │ │ link   │
└────────┘ └────────┘ └──────────┘ └────────┘ └────────┘
```

**Key design:** The Queen plans all research tasks BEFORE any scout leaves. This means parallel execution, no redundant searches, and smart gap detection.

---

## API Reference

### REST API (port 8091)

```bash
# Start a research mission
curl -X POST http://localhost:8091/research \
  -H "Content-Type: application/json" \
  -d '{"topic": "quantum computing 2026", "depth": 3}'

# Check status
curl http://localhost:8091/research/{mission_id}

# Get report
curl http://localhost:8091/research/{mission_id}/report

# Search knowledge base
curl "http://localhost:8091/search?q=quantum+supremacy&limit=20"
```

### MCP Tools

| Tool | Description |
|------|-------------|
| `research_topic` | Start deep research on any topic |
| `mission_status` | Check progress of a running mission |
| `get_report` | Retrieve the final synthesized report |
| `search_knowledge` | Query across all previous research |
| `list_missions` | List recent research missions |

### Python SDK

```python
from behive import BeHiveClient

client = BeHiveClient()  # auto-detects local server

# Start research
mission = client.research("EU AI Act penalties", depth=3)

# Wait and get results
report = mission.wait()
print(f"Found {len(report.claims)} claims, avg quality: {report.quality:.2f}")
```

---

## Comparison

| Feature | BeHive | GPT-Researcher | Tavily | Perplexity |
|---------|--------|---------------|--------|------------|
| **Structured claims** | ✅ JSON with scores | ❌ Text only | ❌ Snippets | ❌ Text |
| **Knowledge graph** | ✅ Neo4j entities | ❌ | ❌ | ❌ |
| **Self-hosted** | ✅ MIT | ✅ | ❌ SaaS only | ❌ SaaS only |
| **MCP native** | ✅ | ❌ | ❌ | ❌ |
| **Quality scoring** | ✅ 5-dimension | ❌ | ❌ | ❌ |
| **Multi-source** | 70+ APIs | ~5 | 1 (Tavily) | Internal |
| **Cost** | Free + your LLM | Free + your LLM | $50-500/mo | $20/mo |
| **Falsifier** | ✅ Cross-verify | ❌ | ❌ | ❌ |

---

## Integrations

| Platform | Method | Difficulty |
|----------|--------|-----------|
| **Claude Desktop** | MCP (add URL) | 10 seconds |
| **ChatGPT** | Custom GPT (import URL) | 30 seconds |
| **Cursor / Windsurf** | MCP config | 10 seconds |
| **Claude Code** | MCP config | 10 seconds |
| **Hermes Agent** | Built-in skill | 1 command |
| **OpenClaw** | Skill file | 1 file copy |
| **n8n** | Community node | Install in UI |

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome.

```bash
git clone https://github.com/qa10devteam/behive
cd behive
pip install -e ".[dev]"
pytest
```

---

## License

MIT — use it however you want. Star ⭐ if it helps.

---

<p align="center">
  Built by <a href="https://qa10.io">QA10</a> · <a href="https://pypi.org/project/behive">PyPI</a> · <a href="https://github.com/qa10devteam/behive/issues">Issues</a>
</p>