AI-powered Telegram bot for Indian government exam preparation — SSC, IBPS, RRB
Millions of students in India prepare for highly competitive government exams (SSC CGL, IBPS PO, RRB NTPC) with limited access to personalised practice tools. This bot solves that — it runs entirely inside Telegram, generates unique MCQ quizzes on demand via LLM, tracks performance per topic, and shows the student exactly where they're weak.
No app to install. No subscription. Just /start and go.
| Onboarding | Quiz in progress | Quiz result | Progress dashboard |
|---|---|---|---|
| Feature | Command | Description |
|---|---|---|
| Exam selection | /start |
Choose SSC, IBPS, or RRB — personalises all subsequent quizzes |
| AI Quiz | /quiz |
10 MCQs generated by LLM, with instant feedback and explanations per question |
| Current Affairs | /currentaffairs |
5 daily questions on recent news relevant to exam syllabus |
| Progress Stats | /stats |
Accuracy by topic, weak areas, streak tracking |
Telegram Bot python-telegram-bot v21.9 (async/await, ConversationHandler)
AI / LLM Groq API — LLaMA 3.1 8B Instant (fast inference, free tier available)
Anthropic Claude — optional fallback
Database Supabase (PostgreSQL) — users, attempts, streaks
REST API FastAPI + Uvicorn — for future web dashboard integration
Deployment Docker + Railway / Render
The bot supports both Groq and Anthropic — whichever key you provide, it uses that. Groq gives ~2s quiz generation vs ~3-4s with Claude.
exam-prep-bot/
├── bot/
│ ├── handlers/
│ │ ├── onboarding.py # /start, exam selection flow
│ │ ├── quiz.py # /quiz, question delivery, answer handling
│ │ ├── current_affairs.py # /currentaffairs
│ │ └── stats.py # /stats, progress dashboard
│ ├── keyboards.py # Inline keyboard builders
│ └── messages.py # All user-facing strings
├── core/
│ ├── quiz_engine.py # Quiz generation logic
│ ├── ai_client.py # Groq / Anthropic wrapper (dual support)
│ ├── stats.py # Accuracy calculation, weak topic detection
│ └── prompts.py # LLM prompts for quiz and current affairs
├── db/
│ ├── client.py # Supabase client
│ ├── models.py # Data classes
│ └── migrations/001_init.sql # Full schema
├── api/
│ ├── main.py # FastAPI app
│ └── routes.py # REST endpoints
├── main.py # Bot entrypoint
├── Dockerfile
└── railway.toml
- Python 3.11+
- Telegram bot token — create one via @BotFather
- Groq API key (free) or Anthropic API key
- Supabase project (free tier works)
git clone https://github.com/YOUR_USERNAME/exam-prep-bot.git
cd exam-prep-bot
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txtcp .env.example .envEdit .env:
TELEGRAM_BOT_TOKEN=your_token_here
GROQ_API_KEY=your_groq_key_here # get free at console.groq.com
ANTHROPIC_API_KEY= # optional fallback
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_KEY=eyJ...
PORT=8000
ENV=developmentIn your Supabase project → SQL Editor → paste and run db/migrations/001_init.sql.
python main.pyBot starts polling. Open Telegram, find your bot, send /start.
docker build -t exam-prep-bot .
docker run -d \
-e TELEGRAM_BOT_TOKEN=your_token \
-e GROQ_API_KEY=your_key \
-e SUPABASE_URL=your_url \
-e SUPABASE_KEY=your_key \
exam-prep-bot- Push to GitHub
- Connect repo at railway.app
- Add environment variables in Railway dashboard
- Deploy —
railway.tomlhandles the rest
Health check endpoint: GET /api/v1/health
All endpoints under /api/v1:
| Method | Endpoint | Description |
|---|---|---|
| GET | /health |
Health check |
| GET | /users/{telegram_id}/stats |
User statistics |
| POST | /users/{telegram_id}/quiz/start |
Start quiz session |
| POST | /users/{telegram_id}/current-affairs/start |
Start current affairs |
| GET | /users/{telegram_id}/history |
Attempt history |
Example response from /stats:
{
"overall_accuracy": 75.5,
"quiz_accuracy": 75.5,
"current_affairs_accuracy": 80.0,
"streak_days": 5,
"topic_wise_accuracy": {
"Quantitative Aptitude": 70.0,
"Reasoning": 85.0
},
"weak_topics": [
["Quantitative Aptitude", 70.0],
["English", 65.0]
]
}| Table | Purpose |
|---|---|
users |
telegram_id, username, exam_type, created_at |
quiz_attempts |
per-question records with topic, subtopic, correctness |
current_affairs_attempts |
same structure for current affairs |
daily_streaks |
date-level streak tracking per user |
Full schema in db/migrations/001_init.sql.
| Variable | Required | Description |
|---|---|---|
TELEGRAM_BOT_TOKEN |
✅ | From @BotFather |
GROQ_API_KEY |
✅ or Anthropic | LLaMA 3.1 via Groq |
ANTHROPIC_API_KEY |
✅ or Groq | Claude via Anthropic |
SUPABASE_URL |
✅ | Your Supabase project URL |
SUPABASE_KEY |
✅ | Supabase anon/public key |
GROQ_MODEL |
optional | Default: llama-3.1-8b-instant |
PORT |
optional | Default: 8000 |
ENV |
optional | development / production |
| Operation | Time |
|---|---|
| Quiz generation (Groq) | ~1-2 seconds |
| Quiz generation (Claude) | ~3-4 seconds |
| Stats calculation | <100ms |
| Database queries | ~100-200ms |
MIT