the-nexus/intelligence/deepdive/QUICKSTART.md

Deep Dive Quick Start

Issue: #830
One-page guide to running the sovereign daily intelligence pipeline.

Prerequisites

• Python 3.10+
• git and make
• Local LLM endpoint at http://localhost:4000/v1 (or update config.yaml)
• Telegram bot token in environment (TELEGRAM_BOT_TOKEN)

Install (5 minutes)

cd /root/wizards/the-nexus/intelligence/deepdive
make install

This creates a virtual environment, installs dependencies, and downloads the 80MB embeddings model.

Run a Dry-Run Test

No delivery, no audio — just aggregation + relevance + synthesis:

make test-e2e

Expected output: a JSON briefing saved to ~/.cache/deepdive/briefing_*.json

Run with Live Delivery

# 1. Copy and edit config
cp config.yaml config.local.yaml
# Edit synthesis.llm_endpoint and delivery.bot_token if needed

# 2. Run pipeline
python pipeline.py --config config.local.yaml --since 24

Enable Daily 06:00 Delivery

make install-systemd
systemctl --user status deepdive.timer

The timer will run pipeline.py --config config.yaml every day at 06:00 with a 5-minute randomized delay.

Telegram On-Demand Command

For Hermes agents, register telegram_command.py as a bot command handler:

from telegram_command import deepdive_handler

# In your Hermes Telegram gateway:
commands.register("/deepdive", deepdive_handler)

Troubleshooting

Symptom	Fix
feedparser not found	Run make install
LLM connection refused	Verify llama-server is running on port 4000
Empty briefing	arXiv RSS may be slow; increase --since 48
Telegram not sending	Check TELEGRAM_BOT_TOKEN and channel_id in config
No audio generated	Set audio.enabled: true in config; ensure piper is installed

Next Steps

1. Run make test-e2e to verify the pipeline works on your host
2. Configure config.yaml with your Telegram channel and LLM endpoint
3. Run one live delivery manually
4. Enable systemd timer for daily automation
5. Register /deepdive in your Telegram bot for on-demand requests