Skip to content
alinawazcodePublic

About

TaleemGo AI: a free multi-user WhatsApp assistant for university LMS. Attendance, assignments, grades, voice notes, lecture summaries and quizzes in English, Urdu, Roman Urdu and Sindhi.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

66 Commits

Folders and files

Repository files navigation

TaleemGo AI. Your university LMS, on WhatsApp.

Python Node.js FastAPI whatsapp-web.js LLM Status

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


✨ Overview

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.


🧩 Features

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.

🧭 How it works

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
Loading

Every incoming message passes through the same gates, in this order:

  1. Activation: an unknown number is ignored until it sends an activation phrase such as Hi TaleemGo AI.
  2. Sign-up: the email and password steps. These messages never reach a language model.
  3. Pending choices: a reply to a numbered list, such as 2 or all after a file list.
  4. Exact commands: attendance NLP, courses, and the rest.
  5. 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.
  6. 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.


🚀 Quick start

Requirements

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

1. Install

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.

2. Configure

cp .env.example .env        # Windows: copy .env.example .env

Fill 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.

3. Run

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 start

Tip

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.

4. Sign in as a student

  1. Send Hi TaleemGo AI to the bot's number.
  2. Send your LMS email.
  3. Send your LMS password. It is used once to sign in and is not stored.
  4. The bot replies Connected as ... and shows the command list.

💬 Commands

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.


🌍 Natural language

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.

Free AI providers & verified capacity

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.

⚡ AI capacity and resilience

At university exhibitions or high-traffic events, multiple students interact simultaneously. TaleemGo AI enforces multiple layers of resilience:

  1. 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)
  2. 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.
  3. 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.
  4. 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.
  5. 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).
  6. 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.
  7. Exhibition Mode: Set EXHIBITION_MODE=1 to double cache TTL and log a full startup capacity and throughput report.
  8. Multi-Key Failover & Fair Spreading: Configure multiple API keys per provider via GEMINI_API_KEYS=key1,key2,... and GROQ_API_KEYS=key1,key2,... (the single GEMINI_API_KEY or GROQ_API_KEY remains 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.
  9. 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 when EXHIBITION_MODE=1). Write operations, logins, logouts, and background monitor runs invalidate the cache immediately. Students can explicitly bypass the cache at any time using refresh / taza / تازہ (e.g. attendance refresh).
  10. Parallel Sub-Requests & Concurrency: Heavy operations like get_attendance() and get_assignments_with_status() execute independent sub-queries concurrently via worker threads. AnyIO worker thread limit is configured to WORKER_THREADS=100 on startup.
  11. Hard Time Budgets & Progress Reassurance: LLM intent resolution times out within INTENT_TIMEOUT_SECONDS=6 falling 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.

🎙️ Voice notes

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_email or awaiting_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 via STT_PROVIDERS=groq,gemini.

📚 Study helper (summaries & quizzes)

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] or quiz <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, D or 1–4). The bot gives instant feedback with explanation, presents the next question, and concludes with a total score and encouragement line. Type stop or cancel to 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 at STUDY_LIMIT_PER_HOUR=6 requests per hour per student.
  • Supported Formats: .pdf, .pptx, .docx, and .txt up 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.

What the bot will not do

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.

🔐 Privacy and security

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.


📦 Deployment

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.


🔧 Configuration

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.


🧪 Testing

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.


📁 Project layout

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

🩺 Troubleshooting

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.

🚧 Known limits

  • 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.

📄 Disclaimer

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

About

TaleemGo AI: a free multi-user WhatsApp assistant for university LMS. Attendance, assignments, grades, voice notes, lecture summaries and quizzes in English, Urdu, Roman Urdu and Sindhi.

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages