Skip to content

README.md

Latest commit

 

History

History
147 lines (112 loc) · 4.38 KB

README.md

File metadata and controls

147 lines (112 loc) · 4.38 KB
Raw

Kotaemon Telegram Bridge

English Русский

Python Vibecoded with Codex 5.3 License Stars Issues Last commit

Telegram bridge for Kotaemon with production-focused UX: document selection, clean citations, cited-page PDF delivery, PNG album, ACL, local storage ingest and systemd deploy.

What changed recently

  • /start now opens file picker immediately (no command wall)
  • Dedicated /cmd help command
  • Cited-pages one-file PDF flow (📄 PDF откуда Инфо)
  • 🧩 PNG album action (media-group in one message)
  • citsrc sends quote in image caption (single message per image)
  • Local storage ingest pipeline (/ingest) with persistent page artifacts
  • Better Telegram timeout handling, retries, and verbose diagnostics
  • Optional HTTP proxy via systemd drop-in

Architecture (high-level)

flowchart LR
  TG[Telegram User] --> BOT[Kotaemon Telegram Bridge]
  BOT --> KOT[Kotaemon / Gradio API]
  BOT --> DB[(SQLite state.db\nACL + user state)]
  BOT --> ST[(storage/\nincoming + rendered pages + bundles)]

  ST --> PDF[One-file cited PDF]
  ST --> PNG[PNG album by cited pages]

  BOT -->|sendDocument / sendMediaGroup| TG
Loading

Quickstart

1) Local run

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# edit .env
python bot.py

2) Server deploy (Ubuntu + systemd)

chmod +x deploy.sh
./deploy.sh <linux-user>

Service logs:

journalctl -u kotaemon-telegram-bridge -f

3) First Telegram flow

  1. /start
  2. Select files in /files
  3. Ask a question (/ask ... or plain text)
  4. Use inline actions:
    • 📄 PDF откуда Инфо — one-file cited-pages PDF
    • 🧩 PNG альбом — cited PNG pages as one album
    • 📎 Цитаты + PDF — quote + matching page image

Commands

  • /start — greeting + immediate file picker
  • /cmd — full command help
  • /files — inline file picker
  • /use <name|id> — select file by name/id
  • /clearuse — clear selected files
  • /selected — show selected file ids
  • /ask <question> — ask Kotaemon
  • /citations — cleaned citations
  • /sources — cited-pages PDF sources flow
  • /citsrc — citation + matching page image
  • /mindmap — mindmap image
  • /relogin — relogin to Kotaemon

Admin:

  • /adduser <telegram_id>
  • /deluser <telegram_id>
  • /users
  • /prepdf <pdf_url_or_path>
  • /prepdfid <file_id>
  • /ingest [file_id|name|path]

Local storage mode (fastest)

Put PDFs into:

  • storage/incoming/<file_id>.pdf or storage/incoming/<name>.pdf

Then run (admin):

  • /ingest <file_id|name|path> for one file
  • /ingest to process all PDFs in storage/incoming

Generated artifacts:

  • storage/rendered/pdf_pages/<key>/page-XXXX.pdf
  • storage/rendered/png_pages/<key>/page-XXXX.png
  • storage/rendered/bundles/<key>.pdf

How it works:

  • bot resolves selected file_id against local index
  • extracts cited pages
  • builds one compact PDF from cited pages (up to 10)
  • sends one file (with background retry fallback)

Proxy (optional, systemd drop-in)

/etc/systemd/system/kotaemon-telegram-bridge.service.d/proxy.conf

[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7080"
Environment="HTTPS_PROXY=http://127.0.0.1:7080"
Environment="NO_PROXY=localhost,127.0.0.1,kotaemon.example.com,.example.com"

Apply:

sudo systemctl daemon-reload
sudo systemctl restart kotaemon-telegram-bridge
sudo systemctl show kotaemon-telegram-bridge --property=Environment --no-pager

Security

  • Keep .env private
  • Use strict whitelist
  • Prefer dedicated Kotaemon account instead of admin

License

Apache-2.0