behive-research

BeHive Deep Research

Run multi-source research missions that extract structured, scored claims from any topic. Returns verified intelligence — not text summaries.

Setup

BeHive must be running. Install and start:

pip install behive
cp .env.example .env  # add your LLM API key
docker compose up -d
# OR: behive api start

Verify: curl http://localhost:8091/health

Operations

1. Start Research Mission

When the user asks to research a topic, deeply investigate something, or gather intelligence:

curl -s -X POST http://localhost:8091/research \
  -H "Content-Type: application/json" \
  -d '{"topic": "<USER_TOPIC>", "scale": 30, "depth": 3}'

Scale guide:

• 15 = quick scout (2-3 min, ~50 claims)
• 30 = standard (5-10 min, ~200-500 claims)
• 100 = deep (15-30 min, ~800+ claims)
• 300 = exhaustive (45-90 min, ~2000+ claims)

Save the returned mission_id or job_id.

2. Check Progress

Poll every 30 seconds:

curl -s http://localhost:8091/research/<MISSION_ID>

Phases: scout → harvest → process → synth → done

Or stream real-time via SSE:

curl -N http://localhost:8091/research/<MISSION_ID>/events

3. Get Report

When status is done:

curl -s http://localhost:8091/research/<MISSION_ID>/report

Returns the full synthesized report with citations and quality metrics.

4. Search Knowledge

Search across all past missions:

curl -s "http://localhost:8091/search?q=<QUERY>&limit=20"

5. Knowledge Graph

Query entities and relationships:

curl -s "http://localhost:8091/graph/entities?limit=50"
curl -s "http://localhost:8091/graph/entity/<NAME>/relationships"

6. List Past Missions

curl -s http://localhost:8091/missions

Output Format

Claims are structured JSON with:

• claim — the extracted fact
• quality_score — 0.0 to 1.0 (only ≥0.55 enter the database)
• source_url — origin URL
• confidence — model confidence
• claim_type — fact, statistic, quote, prediction, etc.
• evidence — supporting context