Doc Agent — Legal AI Assistant

A Telegram bot that analyzes legal documents and answers questions about law using a free LLM fallback chain via OpenRouter. Upload a contract, get a structured breakdown, cross-check with live web search.

Try it: @Doc_helper

---

Features

• Document analysis — upload up to 5 files (PDF, DOCX, TXT, incl. DOCX tables), ask questions about their content
• RAG for large documents — when documents don't fit the model's context, the bot combines a full-text overview with the most relevant retrieved fragments for the specific question (local embeddings, no extra API — see Document Intelligence)
• Model-aware context budget — how much document text is sent scales with the active model's real context window instead of a flat cutoff
• Scanned-PDF detection — warns you if a PDF has little/no text layer instead of silently answering from near-nothing
• Legal Q&A — works without documents too, answers questions about legislation
• Web fact-checking — auto-triggers on questions about currency/recency ("actual version", "recent amendments", specific years), plus a manual "Check online" button on every answer (Tavily search)
• Voice input — send a voice message, the bot transcribes it via Groq Whisper
• Conversation memory — 1-hour context window, reset with /new
• Free model fallback chain — if one model is rate-limited, the next one picks up automatically

Model Strategy

All models are 100% free via OpenRouter. The bot tries them in priority order — if one is unavailable or rate-limited, it falls back to the next automatically.

Mode	Primary model	Context
/fast (default)	gemma-4-31b-it:free	262K — stable
/smart	nemotron-3-super-120b-a12b:free	262K — deeper reasoning

Full fallback chain: nemotron-super → gemma-4-31b → nemotron-3.5-lightning → nemotron-3-ultra-550b → openrouter/free

Free-tier model availability on OpenRouter shifts over time — llama-3.3-70b, nemotron-3-nano-30b and gemma-3-27b were dropped from the free tier and replaced above (verified against GET /api/v1/models). If you see repeated 404s in the logs, check the current free catalog and update llm.py:FREE_MODELS.

Tech Stack

Component	Service	Cost
LLM	OpenRouter — free tier	Free
Voice STT	Groq Whisper large-v3	Free
Web search	Tavily	1000 req/mo free
Embeddings	fastembed (ONNX, local) — paraphrase-multilingual-MiniLM-L12-v2	Free, runs locally, no API key
Bot framework	aiogram 3.x	—
Doc parsing	PyMuPDF, python-docx	—

Document Intelligence (RAG)

Small document sets are sent to the model as-is — simplest and best for holistic questions ("summarize this contract"). When documents don't fit the active model's context window, the bot switches to a hybrid strategy instead of blindly truncating:

1. Overview (~65% of the budget) — the beginning of each document, in upload order, so summarize/compare-style questions still see every document's start.
2. Retrieval (~35% of the budget) — the remaining budget is filled with the chunks most relevant to the specific question, found via local embedding similarity search over the parts of the documents the overview didn't reach.

Chunking is legal-structure-aware (splits on Статья N / Глава N / § N markers first, falls back to size-based splitting with overlap). Embeddings are computed once per document at upload time (in a background thread) and cached in memory alongside the document text — no persistence, same in-memory-by-design philosophy as the rest of the bot's state. If the embedding model fails to load (e.g. no network on first run), documents still work — the bot just falls back to plain truncation.

Bot Commands

Command	Description
/start	Welcome message
/help	Full command reference
/smart	Switch to deep-reasoning model
/fast	Switch to fast stable model (default)
/model	Show current model
/new	Reset conversation context
/docs	List uploaded documents
/deldoc filename.pdf	Remove a specific document
/cleardocs	Remove all documents

---

Deploy to VPS (auto-deploy via GitHub Actions)

1. API keys you need

Key	Where to get
TELEGRAM_TOKEN	@BotFather
OPENROUTER_API_KEY	openrouter.ai/keys
GROQ_API_KEY	console.groq.com
TAVILY_API_KEY	tavily.com

2. GitHub Secrets

Go to Settings → Secrets and variables → Actions in your repo and add:

Secret	Value
VPS_HOST	IP address or hostname of your VPS
VPS_USER	SSH username (e.g. ubuntu or root)
VPS_SSH_KEY	Private SSH key, base64-encoded (see below)

To base64-encode your SSH private key:

# On Linux/Mac
cat ~/.ssh/id_rsa | base64 -w 0

# On Windows (PowerShell)
[Convert]::ToBase64String([IO.File]::ReadAllBytes("$env:USERPROFILE\.ssh\id_rsa"))

The public key must be added to ~/.ssh/authorized_keys on the VPS.

3. First-time VPS setup

SSH into your VPS and run:

# Clone the repo
git clone https://github.com/nebula387/doc-agent.git ~/doc-agent
cd ~/doc-agent

# Create virtualenv and install deps
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Create the .env file with your secrets
cat > ~/doc-agent/.env <<'EOF'
TELEGRAM_TOKEN=your_token_here
OPENROUTER_API_KEY=your_key_here
GROQ_API_KEY=your_key_here
TAVILY_API_KEY=your_key_here
EOF
chmod 600 ~/doc-agent/.env

4. Create systemd service

sudo tee /etc/systemd/system/doc-agent.service > /dev/null <<'EOF'
[Unit]
Description=Doc Agent Telegram Bot
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/doc-agent
EnvironmentFile=/home/ubuntu/doc-agent/.env
ExecStart=/home/ubuntu/doc-agent/venv/bin/python bot.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable doc-agent
sudo systemctl start doc-agent

# Check status
sudo systemctl status doc-agent

Allow the deploy user to restart the service without a password prompt:

echo "ubuntu ALL=(ALL) NOPASSWD: /bin/systemctl restart doc-agent" | sudo tee /etc/sudoers.d/doc-agent

5. How auto-deploy works

Every push to main triggers .github/workflows/deploy.yml:

1. GitHub Actions SSH-es into the VPS
2. Runs git pull origin main
3. Reinstalls/upgrades Python dependencies
4. Restarts the systemd service

The .env file on the VPS is never touched by the workflow — secrets stay safe.

Note: on first startup the bot downloads the local embedding model (~240MB, cached to disk afterward) used for document RAG — this requires outbound internet access to Hugging Face. If that download fails (no egress, etc.), the bot still runs fine; it just falls back to plain document truncation instead of retrieval-augmented context.

Useful VPS commands

# View live logs
sudo journalctl -u doc-agent -f

# Manual restart
sudo systemctl restart doc-agent

# Check status
sudo systemctl status doc-agent

---

Local Setup

git clone https://github.com/nebula387/doc-agent.git
cd doc-agent

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -r requirements.txt

export TELEGRAM_TOKEN=...
export OPENROUTER_API_KEY=...
export GROQ_API_KEY=...
export TAVILY_API_KEY=...

python bot.py

Project Structure

doc-agent/
├── bot.py            # Telegram handlers, command routing, message flow
├── llm.py            # OpenRouter client, free model fallback chain
├── documents.py      # In-memory document storage, PDF/DOCX/TXT parsing, RAG context assembly
├── rag.py            # Chunking + local embeddings (fastembed) + similarity search
├── search.py         # Tavily web search, auto-actualization heuristic
├── voice.py          # Groq Whisper speech-to-text
├── config.py         # Reads secrets from env vars (never commit real keys)
├── config.example.py # Template for local development
├── requirements.txt
├── Dockerfile        # For Hugging Face Spaces deployment
└── .github/
    └── workflows/
        └── deploy.yml  # Auto-deploy to VPS on push to main

---

⚠️ This bot provides general legal information only. It does not replace professional legal advice.

License

MIT