🤖 Telegram RAG Assistant

A production-ready Telegram bot powered by Retrieval-Augmented Generation (RAG). Upload PDFs, switch context sessions, and get fast, citation-aware answers powered by a modern microservice architecture.

---

📖 Overview

This repository provides a highly scalable, containerized conversational agent tailored for document-heavy workflows. Rather than a monolithic approach, the application is divided into three purpose-built microservices:

1. Telegram Bot (apps/bot) — The user interface. Handles Telegram updates, command parsing, and file ingestion.
2. API Gateway (apps/api) — The orchestrator. Manages user states, conversation memory, and proxies complex tasks.
3. AI Engine (apps/ai) — The brain. Parses PDFs, generates embeddings, performs vector searches, and synthesizes answers via LLMs.

This separation of concerns ensures horizontal scalability, robust security, and an incredibly fast local development workflow.

---

✨ Key Features

• 📂 Document Ingestion: Upload PDF files directly in the Telegram chat. Documents are parsed, chunked, and embedded instantly.
• 🧠 Contextual RAG: Answers are generated purely based on the uploaded documents with precise page-level citations.
• 🔄 Session Management: Create isolated conversational memory sessions. Switch between tasks seamlessly without cross-contamination of context.
• 🐳 Cloud-Native Deployment: Fully orchestrated via Docker Compose for zero-headache local setup and production deployments.
• 📊 Robust Vector Search: Powered by Qdrant for blazing-fast semantic retrieval.

---

🛠️ Technology Stack

Component	Technology	Purpose
Bot Framework	grammY	Telegram Bot API integration
API Backend	Node.js + Fastify	High-performance HTTP server
Database ORM	Prisma	Type-safe PostgreSQL interactions
AI Backend	Python + FastAPI	AI model serving & ingestion logic
Vector DB	Qdrant	Semantic vector storage and retrieval
LLM & Parsing	Gemini & LlamaParse	Document parsing and answer generation

---

🚀 Getting Started

Prerequisites

• Docker Desktop or Docker Engine
• A Telegram Bot Token (from @BotFather)
• API Keys for Google Gemini and LlamaParse

1. Clone the Repository

git clone https://github.com/<your-org>/telegram-rag-bot.git
cd telegram-rag-bot

2. Configure Environment

Create a .env file in the root of the project with your credentials:

# API Keys
TELEGRAM_BOT_TOKEN="your_telegram_bot_token"
GEMINI_API_KEY="your_gemini_api_key"
LLAMA_PARSE_API_KEY="your_llamaparse_api_key"

# Database Configuration (Docker Internal)
DATABASE_URL=postgresql://postgres:kali@postgres:5432/ragdb
POSTGRES_USER=postgres
POSTGRES_PASSWORD=kali
POSTGRES_DB=ragdb

# Services
QDRANT_URL=http://qdrant:6333

3. Launch the Stack

Fire up the entire microservice architecture with a single command:

docker compose up --build

Docker will build the Node.js and Python containers, spin up PostgreSQL and Qdrant, and establish internal networking automatically.

---

💬 Bot Commands

Interact with your bot on Telegram using the following commands:

Command	Description
/start	Verify the bot is online and auto-create a "General" session
/new <name>	Create and activate a new conversation session
/list	View all your saved sessions
/current	View the currently active session
/switch <number>	Switch context to a different session by its number
/delete <number>	Delete a session by its number
/status	Check the parsing and indexing status of uploads
/clear	Wipe conversation memory for the current session
/help	Display the help menu

📸 Screenshots

---

📁 Repository Structure

telegram-rag-bot/
├── apps/
│   ├── ai/          # Python FastAPI service (Retrieval, Embeddings, LLM)
│   ├── api/         # Node.js Fastify service (Gateway, Sessions, DB)
│   └── bot/         # Node.js grammY service (Telegram Webhooks/Polling)
├── data/            # Local Docker volumes for PostgreSQL & Qdrant
├── diagram/         # Architecture diagrams and assets
├── docker-compose.yml
└── .env             # Global configuration

---

💡 Local Development (Without Docker)

If you wish to run the services individually for active development:

1. API Service (Node 24+)

cd apps/api
pnpm install
npx prisma db push
pnpm dev

2. Bot Service (Node 24+)

cd apps/bot
pnpm install
pnpm dev

3. AI Service (Python 3.12+)

cd apps/ai
uv sync
uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

(Ensure PostgreSQL and Qdrant are running locally and update the .env URLs to point to localhost instead of Docker hostnames).

---

Built with modern tools for modern document intelligence.