Ask about attendance, deadlines, grades and lecture files in plain language. TaleemGo AI answers on WhatsApp and sends alerts when something changes.
Features | How it works | Quick start | Commands | Configuration | Privacy | Deployment | Testing
University LMS sites make you log in, pick a course and click through menus to answer simple questions. TaleemGo AI moves those questions to WhatsApp. A student signs in once with their own LMS account, then asks things the way they would ask a classmate.
Student mera NLP ka attendance kitna hai
TaleemGo NLP (DE304): 18/22 present, 81.8%, absent: 4
Student download latest lecture from NLP
TaleemGo [sends the newest lecture file]
Latest in NLP (DE304): Week 7 - Lecture 7
Student kal koi deadline hai?
TaleemGo Upcoming deadlines, soonest first, with due dates
The conversation above is illustrative. Replies come from the student's own LMS data.
Each WhatsApp number gets its own private session. One student's data never reaches another student, and the bot sends alerts without being asked.
| Area | What you get |
|---|---|
| Multi-user | Every WhatsApp number signs in with its own LMS email and password. The number of users is capped by MAX_USERS (default 5, including the admin's self-chat). |
| Natural language | English, Urdu script, Roman Urdu, Sindhi, Roman Sindhi and Hindi, including mixed messages. The model only picks an intent. It never writes a reply. |
| Commands | courses, assignments, upcoming, grades, attendance, resources, clos and download. They keep working when the AI is down. |
| Voice notes | WhatsApp voice notes in English, Urdu, or Sindhi are transcribed via Groq Whisper with Gemini fallback. The bot replies with what it heard and runs the requested command. Audio is never saved to disk. |
| Study helper | Summarize lecture slides or take an interactive quiz in English, Urdu, Roman Urdu, or Sindhi. Temporary downloads deleted immediately after text extraction. Strict untrusted input wrapping and output sanitization. |
| Smart downloads | Ask for the latest lecture, a specific week, or a title. When a week has several files, the bot lists them and you reply with a number, several numbers, or all. Supported types: PDF, PPT, PPTX, DOC, DOCX and TXT, up to 100 MB. |
| Automatic alerts | New lecture, new assignment, new or updated grade, attendance marked present or absent, and deadline reminders 3 days and 1 day before. |
| Free AI with fallback | Gemini and Groq free tiers in an ordered chain. A rate-limited or retired model is skipped automatically. An offline keyword matcher answers when every provider fails. |
| Abuse protection | Off-topic chat gets no reply. Two off-topic messages within 10 minutes start a 2-hour commands-only lockout. Jailbreak attempts lock out immediately. |
| Admin tools | users lists registered accounts and their status. llm shows provider health. llm test runs a live check of every provider. |
flowchart LR
S["Student phone"] <--> WA["WhatsApp"]
WA <--> B["Bridge<br/>whatsapp-web.js + headless Chrome<br/>127.0.0.1:3001"]
B -->|"POST /incoming"| API["FastAPI app<br/>127.0.0.1:8000"]
API --> R{"Message router"}
R --> C["Exact commands"]
R --> N["Natural language<br/>LLM chain, then offline rules"]
C --> L["LMS client"]
N --> L
L --> DB[("University LMS<br/>Supabase backend")]
M["Monitor<br/>every N minutes"] --> L
M -->|"alerts"| B
API -->|"replies and files"| B
Every incoming message passes through the same gates, in this order:
- Activation: an unknown number is ignored until it sends an activation phrase such as
Hi TaleemGo AI. - Sign-up: the email and password steps. These messages never reach a language model.
- Pending choices: a reply to a numbered list, such as
2orallafter a file list. - Exact commands:
attendance NLP,courses, and the rest. - Natural language: the model turns free text into a structured intent. Python resolves the course name and runs the same command code as step 4.
- Offline rules: used when no provider can answer.
The bridge and the app talk over localhost with a shared token. The monitor runs on a schedule (MONITOR_INTERVAL_MINUTES, default 30), compares each student's LMS data with what it saw last time, and sends only what is new. The first run for a new student records a baseline and sends nothing.
| Tool | Version |
|---|---|
| Python | 3.10 or newer (tested on 3.12) |
| Node.js | 18 or newer |
| Google Chrome | Installed locally, used headless by the bridge |
| A WhatsApp number | A dedicated one is best (see Known limits) |
| An LMS account | Backed by Supabase, with the project URL and anon key |
git clone https://github.com/alinawazcode/saathi.git
cd Saathi
pip install -r requirements.txt
cd whatsapp_bridge
npm install
cd ..Tip
npm install can stall while it downloads a bundled Chromium. Skip that download and point the bridge at your own Chrome with CHROME_PATH.
PowerShell: $env:PUPPETEER_SKIP_DOWNLOAD=1; npm install
Bash: PUPPETEER_SKIP_DOWNLOAD=1 npm install
npm install also applies a small patch to whatsapp-web.js that fixes media sending to @lid chats. The script is whatsapp_bridge/patch-wwebjs.js and it is safe to run more than once.
cp .env.example .env # Windows: copy .env.example .envFill in at least these values:
| Variable | What to put |
|---|---|
SUPABASE_URL, SUPABASE_ANON_KEY, LMS_BASE_URL |
Your LMS backend and site |
BRIDGE_TOKEN |
A long random string, for example python -c "import secrets; print(secrets.token_hex(32))" |
CHROME_PATH |
Full path to Chrome. On Linux this is usually /usr/bin/google-chrome-stable |
ADMIN_NUMBER |
Your own number, digits only, to use the self-chat and the admin commands |
GEMINI_API_KEY, GROQ_API_KEY |
Free keys, see Natural language. Optional, the bot works without them |
The full list is in Configuration.
Open two terminals in the project folder.
# Terminal 1: the app
uvicorn app.wa_bot:api --port 8000# Terminal 2: the WhatsApp bridge
cd whatsapp_bridge
npm startTip
On Windows development environments, you can run run-bridge.cmd (inside whatsapp_bridge/) instead of npm start. It automatically restarts the bridge in a loop with a 5-second delay if Chrome crashes or exits.
Scan the QR code in terminal 2 with WhatsApp on the bot's phone: Settings, Linked devices, Link a device. Wait for WhatsApp ready. The session is saved in whatsapp_bridge/.wwebjs_auth, so you scan once.
- Send
Hi TaleemGo AIto the bot's number. - Send your LMS email.
- Send your LMS password. It is used once to sign in and is not stored.
- The bot replies
Connected as ...and shows the command list.
Typed commands always work, with or without the AI.
| Command | What it does |
|---|---|
courses |
Lists your enrolled courses |
assignments [course | pending | overdue | submitted | all] |
Clean overview by default (counts per course & top 10 soonest items). Or filter by course and status |
upcoming [course] |
Pending assignments with future due dates, ordered ascending |
grades [course] |
Assignment marks as 8/10, a running total, and teacher feedback |
plan [course] [target%] [left N | miss N] |
Attendance planner: how many classes you can miss or must attend for target% (default 75%), or plan AI 80 left 3 |
digest [on [HH:MM] | off] |
Opt-in daily digest of deadlines, low attendance alerts, new lectures and grades |
calendar |
Downloads an .ics file with upcoming assignment deadlines and 1-day alarms for Google/Apple Calendar |
language [english | urdu | roman | sindhi] |
View or lock language mode (1. English, 2. Urdu, 3. Roman Urdu, 4. Sindhi) |
summarize <course> [week N | title | latest] |
Summarizes lecture document into key bullet points and terms |
quiz <course> [week N | title | latest] [n] |
Interactive multiple-choice quiz (3-10 questions, default 5) |
attendance [course] [refresh] |
Overall attendance, or one course. Add refresh to bypass cache |
resources <course> |
Lecture files grouped by week |
clos <course> |
Course learning outcomes |
download <course> [week N or title] |
Sends a lecture file. Add latest for the newest one |
help |
Shows the command list |
login |
Signs in again after a session expires |
logout |
Disconnects and deletes everything stored for that number |
Admin only, from the ADMIN_NUMBER chat: users, llm and llm test.
Students can skip the syntax. The same intent, in different languages:
| Language | Message | Result |
|---|---|---|
| English | show my grade in NLP |
NLP grades |
| English | can I miss 3 classes in HCI |
Attendance what-if calculation |
| English | summarize lecture 3 of AI |
Summary of AI lecture 3 |
| English | quiz me on week 5 of HCI |
5-question interactive quiz |
| English | send my deadlines to Google Calendar |
Sends .ics calendar file |
| Roman Urdu | HCI ke pehle hafte ki slides bhej do |
HCI week 1 files |
| Roman Urdu | mera NLP ka attendance kitna hai |
NLP attendance |
| Roman Urdu | AI me kitni classes miss kar sakta hoon |
Attendance plan for AI |
| Roman Urdu | AI ka latest lecture ka khulasa |
Summary of newest AI lecture |
| Urdu | میرا NLP کا اٹینڈنس کتنا ہے؟ |
NLP attendance |
| Sindhi | منهنجي NLP جي حاضري ڪيتري آهي؟ |
NLP attendance |
| Sindhi | ڪو اسائنمينٽ ڏيڻو آهي؟ |
Upcoming assignments |
| Mixed | Ai ky latest lecture bhejo |
Newest AI lecture |
The bot answers in the language of the current message. A very short reply such as 2 or ok keeps the language of the previous message.
Providers are tried in the order of INTENT_PROVIDERS (for intent classification), STUDY_PROVIDERS (for summaries/quizzes), and STT_PROVIDERS (for voice notes). If one is rate limited or down, the next one answers immediately.
| Provider | Free limits (Verified 2026-11-15) | Default models | Data-use terms summary |
|---|---|---|---|
| Google Gemini | 15 RPM, 1,000,000 TPM, 1,500 RPD (per project) | gemini-3.5-flash-lite, gemini-3.8-flash, gemini-3.6-flash |
Free tier inputs may be used to train Google products (no personal data in prompts). |
| Groq | 30 RPM, 8,000 TPM, 1,000 RPD, 200,000 TPD (per model) | openai/gpt-oss-20b, openai/gpt-oss-120b, qwen/qwen3.8-27b |
API data is not used to train models; 30-day retention for abuse monitoring. |
| Mistral | ~30 RPM (free trial tier) | mistral-small-latest, open-mistral-7b |
API data is not used for model training. |
| Cloudflare Workers AI | 10,000 neurons/day (~10k requests) | @cf/meta/llama-3.1-8b-instruct, @cf/meta/llama-3-8b-instruct |
Cloudflare does not train on customer inputs or logs. |
| Local LLM (Ollama) | Unmetered (depends on local GPU/CPU) | llama3.2:3b, qwen2.5:3b |
100% private and on-premise; no data ever leaves the local machine. |
| OpenRouter (optional) | 20 RPM, 50 RPD (:free models) |
meta-llama/llama-3.3-70b-instruct:free |
Varies per upstream provider. |
| Cerebras (optional) | 30 RPM (requires verified payment method) | llama3.1-8b |
API inputs not used for training. |
At university exhibitions or high-traffic events, multiple students interact simultaneously. TaleemGo AI enforces multiple layers of resilience:
- Independent Feature Chains: Configure separate provider failovers via
.env:INTENT_PROVIDERS: High-priority intent classification (default:gemini,groq)STUDY_PROVIDERS: Low-priority study helper (default:gemini,groq)STT_PROVIDERS: High-priority voice transcription (default:groq,gemini)
- Rules-First Fast Path: Short, unambiguous messages (<= 8 words) with zero negations (e.g. "attendance", "grades", "what is my schedule") execute directly with 0 provider calls and 0 tokens consumed.
- Intent Caching: Normalized LRU cache (500 entries) shared across all students. Identical intents (e.g., common exhibition queries) return in 0ms with zero provider calls. TTL is 1 hour (2 hours in exhibition mode). Never caches sign-up credentials or voice transcripts with digits.
- Token-Aware Rate Limiting & Sliding Windows: Tracks RPM, TPM, RPD, and TPD sliding windows per model. Before sending an HTTP call, the limiter checks available capacity. If a model's ceiling is reached, it skips to the next model without burning an HTTP request or encountering a 429 error.
- Provider Concurrency Cap: Caps concurrent in-flight requests per provider (
PROVIDER_CONCURRENCY=3, default 3) with a priority queue (8s wait for high-priority intent/STT, 2s wait for study). - Load Shedding: Under capacity pressure (> 80% ceiling usage across all study providers), low-priority study helper requests are shed immediately with a friendly localized message (
study_busy), preserving all remaining capacity for critical intents and voice notes. - Exhibition Mode: Set
EXHIBITION_MODE=1to double cache TTL and log a full startup capacity and throughput report. - Multi-Key Failover & Fair Spreading: Configure multiple API keys per provider via
GEMINI_API_KEYS=key1,key2,...andGROQ_API_KEYS=key1,key2,...(the singleGEMINI_API_KEYorGROQ_API_KEYremains key #1).- Terms of Service Note: Use only keys from your own accounts and follow each provider's terms of service.
- Each key is treated as its own independent entry in the provider registry with independent cooldowns, bad-key isolation, and sliding window tracking (RPM/TPM/RPD/TPD).
- Requests rotate fairly across available keys based on the lowest usage count in the current 60s sliding window, preventing early key exhaustion.
- When a key encounters HTTP 429 or hits a window ceiling, the bot automatically fails over to the next key of the same provider with zero user disruption before falling back to the next provider.
- Raw keys are never logged; logs and admin outputs identify keys securely as
gemini#1,gemini#2,groq#1, etc.
- Short-Lived LMS Read Cache: Responses for courses, assignments, and submissions are cached in-memory per user for
LMS_CACHE_TTL_SECONDS=60(doubled to 120s whenEXHIBITION_MODE=1). Write operations, logins, logouts, and background monitor runs invalidate the cache immediately. Students can explicitly bypass the cache at any time usingrefresh/taza/تازہ(e.g.attendance refresh). - Parallel Sub-Requests & Concurrency: Heavy operations like
get_attendance()andget_assignments_with_status()execute independent sub-queries concurrently via worker threads. AnyIO worker thread limit is configured toWORKER_THREADS=100on startup. - Hard Time Budgets & Progress Reassurance: LLM intent resolution times out within
INTENT_TIMEOUT_SECONDS=6falling back to rules immediately. If request processing exceeds 8 seconds, the bot sends a localised reassurance ("Still working on that, just a moment...") without abandoning the request.
Each message has a 12 second budget, with 6 seconds per request. When a model returns "not found", the bot moves to the next model in the list with no delay. When every provider fails, a student hits the hourly limit (LLM_USER_LIMIT_PER_HOUR, default 20), or LLM_ENABLED=0, the offline matcher in app/llm/rules.py handles the message.
Note
Providers retire models often. If llm shows bad model for a provider, update GEMINI_MODELS or GROQ_MODELS in .env.
Current lists: Gemini deprecations and Groq models.
Registered students can send WhatsApp voice notes instead of typing. The bot transcribes the voice note and processes it with the exact same intent router and commands.
- Audio privacy: Voice notes are processed purely in-memory as base64 bytes, never written to disk, and never stored. The transcript is never logged. Only audio duration, latency, and provider name appear in server logs.
- Transcripts: The bot's reply begins with
🎤 I heard: "..."so the student can verify what was heard. - Languages supported: Urdu, Sindhi, and English. The user's locked language mode is passed directly to the STT engine as a biasing hint. If the detected script does not match the expected language mode, the system automatically retries with the next provider. Transcripts with fewer than 2 characters prompt the student to speak slowly or type.
- Sindhi STT accuracy: Note that free speech-to-text models have lower accuracy for Sindhi than Urdu or English. Students are encouraged to check the
I heard: ...confirmation line. - Safety gates: Voice notes are accepted only from registered, active, non-locked students. Voice notes sent during sign-up (
awaiting_emailorawaiting_password) are rejected with an explicit prompt to type credentials, and the audio is discarded immediately without calling any external service. Unknown numbers are silently ignored. - Rate limits & thresholds: Voice notes have a limit of 30 seconds (
VOICE_MAX_SECONDS=30), ~2 MB raw audio (VOICE_MAX_BYTES=2000000), and 10 voice requests per hour per user (VOICE_LIMIT_PER_HOUR=10). - STT providers: Groq Whisper (
whisper-large-v3-turbo,whisper-large-v3) with automatic fallback to Gemini (gemini-3.5-flash-lite,gemini-3.8-flash,gemini-3.6-flash). Configured viaSTT_PROVIDERS=groq,gemini.
Students can ask TaleemGo AI to summarize a lecture or test their knowledge with an interactive multiple-choice quiz.
- Commands & Natural Language: Use
summarize <course> [week N | title | latest]orquiz <course> [week N | title | latest] [n](n between 3 and 10, default 5). Natural phrases like"AI ka latest lecture ka khulasa"or"quiz me on week 5 of HCI"route automatically. - Languages Supported: English, Urdu script, Roman Urdu (100% Latin characters), and Sindhi script.
- Interactive Quizzes: Quizzes run directly inside WhatsApp with single-letter answers (
A,B,C,Dor1–4). The bot gives instant feedback with explanation, presents the next question, and concludes with a total score and encouragement line. Typestoporcancelto exit. Other messages receive a one-time reminder while keeping the quiz active for up to 30 minutes. - Untrusted Input & Output Safeguards: Lecture documents are treated as untrusted input enclosed in delimiters (
=== BEGIN UNTRUSTED LECTURE DOCUMENT ===). The model is strictly instructed to ignore any instructions inside the document. Model output is sanitized plain text (markdown, HTML, URLs, emails, and phone numbers stripped; capped at 1,500 chars). Quizzes require strict JSON validation. - Summary Caching & Limits: Summaries are cached in SQLite by
(resource_id, file_size, lang)so identical requests consume zero provider quota. Quizzes are not cached. Usage is capped atSTUDY_LIMIT_PER_HOUR=6requests per hour per student. - Supported Formats:
.pdf,.pptx,.docx, and.txtup to 20 MB (STUDY_MAX_FILE_BYTES=20000000) and 20 pages (STUDY_MAX_PAGES=20). Scanned or encrypted files are safely rejected. Downloaded files are deleted immediately after text extraction.
TaleemGo AI is an LMS assistant, not a general chatbot.
- Requests about GPA, results, transcripts, timetables, fees and exams get a short "I can't do that yet" message that lists what is supported. They never count as strikes.
- Messages unrelated to university life get no reply.
- Two off-topic messages within 10 minutes (
LLM_STRIKES,LLM_STRIKE_WINDOW_MIN) lock natural language for 2 hours (LLM_LOCK_HOURS). Typed commands still work during the lockout. - A jailbreak attempt starts the lockout at once. The admin number is exempt.
| Topic | How it is handled |
|---|---|
| Passwords | Used once to sign in. Never written to disk, never logged, never sent to a model provider. |
| Voice audio | Held in memory only, never written to disk, never logged, deleted immediately after transcription. The transcript text is never logged. Sign-up states drop audio immediately. |
| Sign-up messages | Emails and passwords skip the AI entirely. |
| Model prompts | Intent classification prompts contain only the student's message text and a fixed instruction (no personal data). For explicit summarize and quiz requests only, institutional lecture document text is sent to the provider inside strict untrusted delimiters. Never any personal data (no email, name, chat id, grades, or attendance). |
| Model output | For command intents, model output is never sent to students (fixed localized templates only). For summaries and quizzes, model-written text is sanitized (plain text only, markdown/HTML stripped, URLs/emails/phone numbers removed, length capped, or strict validated JSON) and marked with an AI disclaimer. |
| Lecture file text | Downloaded temporarily to memory/disk, deleted immediately after text extraction. Institutional materials only; sent to the AI service ONLY when explicitly requested via summarize or quiz. Never sent for regular commands. |
| Session tokens | Encrypted with Fernet (data/users/<hash>/tokens.enc). The key is TALEEMGO_SECRET_KEY. |
| Isolation | Each number has its own folder, named from a hash of its chat id, and its own monitor state. |
| Stored per user | Email, status and timestamps in data/users.db, plus the encrypted tokens and the list of items already announced. |
| Deletion | logout removes all of it. |
| Local network | The bridge listens on 127.0.0.1 only and requires BRIDGE_TOKEN. |
| Secrets in git | .env, data/ and .wwebjs_auth/ are git-ignored. Keep them out of commits and screenshots. |
Free tiers of AI providers can keep request logs under their own terms. The welcome message tells students to send their password only when the bot asks for it at login.
| Option | When to use it |
|---|---|
| Your own computer | Demos and short pilots. Keep it plugged in, stop it from sleeping, and keep both terminals open. |
| Azure Ubuntu VM | Always-on use. deploy/DEPLOY.md covers the setup script, systemd services, firewall, QR scan over SSH, daily backups and cleanup. |
The deploy folder contains:
| File | Purpose |
|---|---|
setup.sh |
One-time server setup |
update.sh |
Pull new code and restart the services |
status.sh |
Service state, memory, bridge health, recent AI log lines |
backup.sh and a systemd timer |
Daily archive of .env, data/ and the WhatsApp session, keeping 7 |
taleemgo-api.service, taleemgo-bridge.service |
systemd units that restart on failure |
Important
One WhatsApp session can run in one place at a time. Stop the bot on your computer before you scan the QR code on a server, and scan a fresh code there. Do not copy .wwebjs_auth between machines.
To change the bot's WhatsApp number, stop the bridge, delete whatsapp_bridge/.wwebjs_auth, update ADMIN_NUMBER in .env, remove any ADMIN_LID line, start the bridge and scan with the new phone. Students keep their accounts and message the new number.
Every setting in .env
| Variable | Default | Meaning |
|---|---|---|
SUPABASE_URL |
none | LMS backend URL |
SUPABASE_ANON_KEY |
none | Public anon key of that backend |
LMS_BASE_URL |
none | LMS website, used for file downloads |
BRIDGE_TOKEN |
none | Shared secret between the bridge and the app |
BRIDGE_PORT |
3001 |
Bridge port on localhost |
BRIDGE_URL |
http://127.0.0.1:3001 |
Where the app finds the bridge |
PY_WEBHOOK |
http://127.0.0.1:8000/incoming |
Where the bridge sends messages |
CHROME_PATH |
Windows Chrome path | Chrome used by the bridge |
MONITOR_INTERVAL_MINUTES |
30 |
How often alerts are checked |
MAX_USERS |
5 |
Maximum registered numbers, admin included |
ACTIVATION_PHRASES |
taleemgo ai,taleem go ai,taleemgo |
Phrases that wake the bot for a new number |
ATTENDANCE_WARN |
75 |
Attendance percentage that gets a warning mark |
DIGEST_DEFAULT_TIME |
07:30 |
Default local time for the daily digest |
TIMEZONE |
Asia/Karachi |
Local timezone used for digest dispatch and timestamp formatting |
TALEEMGO_SECRET_KEY |
generated | Encryption key. Created on first run if missing. Back it up. |
ADMIN_NUMBER |
empty | Your number, digits only. Enables self-chat and admin commands |
ADMIN_LID |
empty | Your WhatsApp @lid id, only if self-chat does not reply |
DEBUG_SELF |
0 |
Set to 1 to print self-chat diagnostics |
LLM_ENABLED |
1 |
Set to 0 to run on commands and offline rules only |
LLM_PROVIDERS |
gemini,groq |
Order of the provider chain |
INTENT_PROVIDERS |
gemini,groq |
Independent provider chain for high-priority intent classification |
STUDY_PROVIDERS |
gemini,groq |
Independent provider chain for low-priority study helper |
STT_PROVIDERS |
groq,gemini |
Ordered STT providers for voice transcription |
PROVIDER_CONCURRENCY |
3 |
Max concurrent in-flight requests per provider |
EXHIBITION_MODE |
0 |
Set to 1 for 2h cache TTL and startup capacity report |
GEMINI_API_KEY, GROQ_API_KEY |
empty | Primary free keys (#1). Optional: MISTRAL_API_KEY, CLOUDFLARE_API_TOKEN, LOCAL_LLM_URL |
GEMINI_API_KEYS, GROQ_API_KEYS |
empty | Comma-separated list of additional keys for fair failover (gemini#2, groq#2, etc.) |
GEMINI_MODELS, GROQ_MODELS |
see above | Ordered model lists, comma separated |
MISTRAL_MODELS |
mistral-small-latest,open-mistral-7b |
Models for Mistral |
CLOUDFLARE_MODELS |
@cf/meta/llama-3.1-8b-instruct,... |
Models for Cloudflare Workers AI |
LOCAL_LLM_MODELS |
llama3.2:3b,qwen2.5:3b |
Models for local LLM (Ollama) |
LLM_USER_LIMIT_PER_HOUR |
20 |
AI calls per student per hour |
LLM_STRIKES |
2 |
Off-topic messages before a lockout |
LLM_STRIKE_WINDOW_MIN |
10 |
Window for counting strikes |
LLM_LOCK_HOURS |
2 |
Lockout length |
LLM_NOTIFY_ON_LOCK |
1 |
Tell the student when a lockout starts |
LLM_ADMIN_EXEMPT |
1 |
Exempt the admin from lockouts |
LLM_HELP_REPLY_INTERVAL_MIN |
2 |
Minimum gap between "I didn't understand" replies |
GREETING_REPLY |
1 |
Reply to greetings |
STT_PROVIDERS |
groq,gemini |
Ordered STT providers for voice transcription |
GROQ_STT_MODELS |
whisper-large-v3-turbo,whisper-large-v3 |
Whisper model(s) for Groq STT |
GEMINI_STT_MODELS |
gemini-3.5-flash-lite,gemini-3.8-flash,gemini-3.6-flash |
Gemini model(s) for STT fallback |
VOICE_MAX_SECONDS |
30 |
Maximum voice note duration in seconds |
VOICE_MAX_BYTES |
2000000 |
Maximum raw voice note audio bytes (~2 MB) |
VOICE_LIMIT_PER_HOUR |
10 |
Maximum voice notes per user per hour |
STUDY_LIMIT_PER_HOUR |
6 |
Maximum summary and quiz requests per student per hour |
STUDY_MAX_PAGES |
20 |
Maximum pages extracted from lecture slides/documents |
STUDY_MAX_CHARS |
24000 |
Maximum document text characters sent to AI |
STUDY_MAX_FILE_BYTES |
20000000 |
Maximum file size for study processing (~20 MB) |
SATHI_SECRET_KEY from older versions is still read. Rename it to TALEEMGO_SECRET_KEY and keep the same value, because a new key makes saved sessions unreadable and every student would have to sign in again.
The unit tests run offline with fake providers and a fake LMS. Run them from the project folder:
python -m unittest app/test_branding.py app/test_multiuser.py app/test_grades.py app/test_llm.py app/test_professional.py app/test_relogin.py app/test_helpers.py app/test_voice.py app/test_study.py app/test_capacity.py app/test_multikey.py app/test_post_demo_fixes.py app/test_llm_400.py| File | Covers |
|---|---|
test_multiuser.py |
Sign-up, isolation, user cap, self-chat detection, downloads |
test_llm.py |
Provider failover, JSON validation, privacy of prompts, lockouts, languages |
test_grades.py |
Grade maths, grade alerts, a guard that keeps sensitive LMS columns out of the code |
test_professional.py |
Conversation flow: latest lecture, follow-ups, language, empty-reply guards |
test_branding.py |
No leftover product names |
test_relogin.py |
Re-login with stale tokens and monitor/bridge resilience |
test_helpers.py |
Attendance planner, daily digest, and calendar export |
test_voice.py |
Voice note transcription, audio gates, rate limits, STT failover, privacy |
test_study.py |
Study helper: doc extraction (.txt/.pdf/.pptx/.docx), sanitization, prompt injection safety, rate limits, interactive quiz |
test_capacity.py |
Capacity ceilings, sliding windows, concurrency queue, rules-first fast path, intent cache, load shedding |
test_multikey.py |
Multi-key env parsing, fair key rotation, ordered failover, bad key isolation, admin llm key telemetry |
test_post_demo_fixes.py |
Speed under load, language mode locking, per-course assignments, attendance remaining classes |
test_llm_400.py |
No global cooldown on 400, minimal payload retry, unsupported param memory, safe error redaction, empty message rejection |
The multi-user suite includes a bridge test, so run npm install in whatsapp_bridge first. app/test_all.py is a manual smoke test against a real LMS account and is not part of the unit suite.
app/
wa_bot.py FastAPI app, message router, command handlers
users.py SQLite users, per-user folders, locks, pending choices
lms_client.py LMS access: login, refresh, data, downloads
courses.py Course matching and query cleanup
doc_text.py Document text extraction (.txt, .pdf, .pptx, .docx)
study.py Summarization and interactive quiz generator
planner.py Attendance calculator and what-if planner
calendar_gen.py ICS calendar generation
wa_monitor.py Scheduled change detection and alerts
wa_transport.py Sending messages and files through the bridge
state.py What each student has already been told
timeutils.py UTC to local time
llm/
providers.py Provider calls, cooldowns, model failover
router.py Provider chain and time budget
stt.py Voice note speech-to-text with Groq and Gemini fallback
intent.py Prompt, JSON schema, validation
rules.py Offline matcher and language detection
i18n.py Fixed replies in English, Urdu and Sindhi, with cache
lang_data.py Keywords and example phrases
bot.py, monitor.py Earlier single-user Telegram version, kept for reference
whatsapp_bridge/ whatsapp-web.js bridge (Express on localhost)
deploy/ Azure VM scripts and guide
scripts/ Developer scripts used while mapping the LMS
data/ Runtime data, git-ignored
Common problems
| Symptom | Cause and fix |
|---|---|
Bridge stops after Bridge on ... and never says WhatsApp ready |
A leftover Chrome from a previous run is holding the saved session. The bridge now cleans it up on start. Close the window, run npm start again, and read the [LOADING] lines if it repeats. |
Data passed to getter must include an id property when sending files |
The media patch is missing. Run npm install in whatsapp_bridge again. |
Attempted to use detached Frame |
The bridge's browser page died, usually after the computer slept. Restart the bridge. The saved login stays. |
| The self-chat does not reply | Set ADMIN_NUMBER. If it still fails, set DEBUG_SELF=1, send yourself a message, and copy the printed to= value into ADMIN_LID. |
llm shows bad model |
The provider retired a model. Update GEMINI_MODELS or GROQ_MODELS. |
llm shows bad key |
The API key is wrong, revoked or a placeholder. Replace it or leave it empty. |
| Alerts stop while the computer is asleep | The monitor only runs while the app runs. Disable sleep or move to a server. |
- WhatsApp has no free official bot API for this use. TaleemGo AI automates WhatsApp Web through
whatsapp-web.js, which WhatsApp does not endorse. Accounts that automate WhatsApp can be restricted, so use a dedicated number and not your personal one. - It reads assignment marks. It does not calculate GPA, weighted course grades, or letter grades, and it does not read transcripts, fees, timetables or exam schedules.
- It cannot submit assignments.
- It runs one headless Chrome and one SQLite file, which is why the default cap is 5 students.
- Free AI tiers have rate limits. The offline matcher covers the gaps with simpler understanding.
TaleemGo AI is an independent student project. It is not affiliated with, endorsed by, or sponsored by WhatsApp, Meta or any university. Each student signs in with their own LMS credentials and sees only their own data. Check that your institution allows this kind of access before you share the bot with others.
Built by Ali Nawaz