Skip to content

Deeper Research

Status: LIVE (2026-06-05) — orchestrator healthy, 3 workers running, Six Eyes scoring active Dashboard: http://localhost:8200 (SSH tunnel: ssh -L 8200:localhost:8200 vps) DNS pending: research.joaoluisbrazao.cloud → 76.13.44.83 (Vikunja #906)

Deeper Research is a recursive AI research pipeline. Given a subject, it:

  1. Explodes it into 60–100 sub-topics via LLM
  2. Searches each topic via SearXNG (Google + Bing + DuckDuckGo + Wikipedia)
  3. Fetches and parses top results
  4. Translates non-English content via LibreTranslate
  5. Interrogates entities across 18 dimensions
  6. Scores every claim through the Six Eyes critical thinking framework
  7. Auto-includes (score ≥ 6.0), queues for human review (3.0–6.0), or discards (≤ 3.0)

Architecture

CLI / Dashboard
      │
      ▼
dr_orchestrator :8200 (FastAPI)
      │
      ├─── Redis queue (infra-redis, DB index 2)
      │         │
      │    dr_worker_1 / _2 / _3 (3 parallel workers)
      │         │
      │    ┌────┴────────────────┐
      │    dr_searxng :8080      dr_libretranslate :5000
      │    (web search)          (translation)
      │         │
      └─── infra-postgres (down_rabbit_hole DB, research.* schema)
                │
           LiteLLM proxy :4000 (all AI calls — Haiku / Mistral / DeepSeek / free-OR)

All containers on infra-net. No new Redis or Postgres deployed — reuses shared infrastructure.

Key paths

Item Path
Compose file /opt/deeper_research/docker-compose.yml
Source code /opt/deeper_research/
Git bare repo /opt/git-repos/deeper-research.git
Logs /opt/deeper_research/logs/
Models config /opt/deeper_research/models.yaml
CLI script /usr/local/bin/deeper-research
Dashboard http://localhost:8200 (SSH tunnel)
DB schema down_rabbit_hole → research.* (10 tables)

Containers

Container Image Port Memory
dr_orchestrator deeper-research-orchestrator:0.1.0 127.0.0.1:8200 512MB
dr_worker_1/2/3 deeper-research-worker:0.1.0 — 512MB each
dr_searxng searxng/searxng:latest internal :8080 256MB
dr_libretranslate libretranslate/libretranslate:latest internal :5000 2GB

Workers are plain Docker Compose named containers (extends: pattern) — not Docker Swarm.

Model routing

Sensitivity classes route to different LiteLLM aliases:

Class Allowed providers Default model
LOW All (incl. CN) free_tier (OpenRouter free)
MEDIUM EU + US only standard-mistral
HIGH EU + US only standard-mistral
CRITICAL US only (Anthropic) brain-query (Claude Haiku)

Ollama is not available on this VPS (removed for memory). CRITICAL sensitivity uses Claude Haiku. Config file: /opt/deeper_research/models.yaml

Six Eyes scoring

Each claim is scored across 6 weighted dimensions:

Dimension Weight Focus
Attention 15% Facts only — what is actually stated
Emotion 10% Emotional tone in the source
Framing 20% Is the right question being asked?
Structure 25% Logical, coherent flow
Contrast 15% Alternative perspectives considered
Integrity 15% Truthfulness and accuracy

Composite score ≥ 6.0 → AUTO_INCLUDED · 3.0–6.0 → PENDING (human review) · ≤ 3.0 → DISCARDED

Entity scores are rolled up from the average of their claims after each job completes.

CLI usage

# Analyse sensitivity and pick model interactively
deeper-research "Le Mans 24h race history"

# Auto-accept recommended model and start immediately
deeper-research "Honda NSX development" --auto

# Use specific model
deeper-research "EU sanctions on Russia" --model standard-mistral

# Check status
deeper-research --status

# Scale workers
deeper-research "BMW Z1 roadster" --auto --workers 3

Dashboard is at http://localhost:8200 — counters update in real time.

Database schema

Schema research in down_rabbit_hole DB. Tables:

Table Purpose
seeds Top-level research subjects
topics 60–100 sub-topics per seed
entities Named entities extracted per topic
claims Individual claims with Six Eyes scores
relationships Entity-to-entity graph edges
sources URLs fetched (dedup)
queue Job tracking (Redis is primary queue; this is audit log)
review_queue PENDING claims awaiting human decision
agent_log Agent run log
media_assets Images/videos found

Vector columns: embedding vector(1536) on seeds, topics, entities, claims.

SSL activation (pending #906)

  1. Add DNS A record: research → 76.13.44.83 in domain registrar
  2. Run certbot: 
    docker exec infra-certbot certbot certonly --webroot \
  -w /var/www/certbot -d research.joaoluisbrazao.cloud \
  --non-interactive --agree-tos -m jbrazao@me.com
  3. Uncomment HTTPS block in /opt/infrastructure/nginx/conf.d/research.conf
  4. docker exec infra-nginx nginx -t && docker exec infra-nginx nginx -s reload

Full instructions: /opt/deeper_research/SSL_ACTIVATION.md

Operational runbook

Health check

docker compose -f /opt/deeper_research/docker-compose.yml ps
curl http://localhost:8200/api/health
curl http://localhost:8200/api/dashboard/counters

Start a research job

deeper-research "subject" --auto
# Monitor workers:
docker logs dr_worker_1 -f

Queue depth

docker exec infra-redis redis-cli -a $REDIS_PASSWORD ZCARD dr:job_queue

Restart workers after code change

cd /opt/deeper_research
docker compose build dr_orchestrator dr_worker_1
docker compose up -d --force-recreate dr_orchestrator dr_worker_1 dr_worker_2 dr_worker_3

LibreTranslate health (note: uses python3 healthcheck, no wget)

docker exec dr_libretranslate python3 -c \
  "import urllib.request; urllib.request.urlopen('http://localhost:5000/health', timeout=5); print('ok')"

Known issues / pending

Vikunja Status Description
#906 OPEN (manual) Add DNS A record for research.joaoluisbrazao.cloud
#907 BLOCKED on #906 E2E verify after SSL activation
#908 OPEN Create Forgejo repo joaobrazao/deeper-research

Code is in bare git at /opt/git-repos/deeper-research.git. Push to Forgejo when #908 is done.