AI Teaching Assistant for WhatsApp
You're not teaching alone.
Website · Research · Customization Guide · Setup
Rumi is an open-source AI teaching companion that runs on WhatsApp, giving teachers 24/7 access to classroom coaching, reading assessments, lesson plan generation, and professional development — in their own language, on the device they already have.
Across the developing world, millions of teachers work in isolation — in rural schools, multigrade classrooms, and under-resourced systems where instructional coaches simply don't exist. Traditional professional development reaches teachers once or twice a year at best. The gap between what teachers need and what the system provides is enormous.
Rumi fills that gap. By meeting teachers on WhatsApp — the world's most widely used messaging app — Rumi provides:
- Instant coaching feedback on real classroom recordings, using research-backed pedagogical frameworks
- Reading fluency assessments so teachers can measure student progress with the same rigor as standardized tests
- Evidence-based lesson plans generated from templates adapted to local curriculum and context
- Multilingual support — teachers interact in the language they think in, not just the language of instruction
The core insight: the best time to coach a teacher is right after they teach, and the best tool is the one already in their pocket.
| Feature | How It Works | Tier |
|---|---|---|
| AI Chat | Teachers ask any teaching question via text or voice; get expert responses grounded in pedagogy | Minimal |
| Registration | Automated teacher onboarding via WhatsApp — name, school, grade, language | Minimal |
| Classroom Coaching | Teacher uploads classroom audio; Rumi transcribes, analyzes against a selectable pedagogical framework (OECD, HOTS, TEACH, FICO), conducts a reflective conversation, and generates a scored PDF report with an optional classroom photo analysis | Recommended |
| Reading Assessment | Students read aloud into WhatsApp; Rumi measures fluency (WCPM), pronunciation accuracy, and comprehension against grade-level benchmarks | Recommended |
| Lesson Plans | Teacher describes a topic and grade; Rumi generates a comprehensive 9-section lesson plan as a downloadable PDF | Full |
| Voice Messages | Full voice interaction in 9 languages — teachers speak, Rumi listens, transcribes, responds in both text and voice | Full |
| AI Video Generation | Teacher requests a topic; Rumi generates an educational video with narration, images, and animations | Full |
| Attendance | Voice or text-based student attendance tracking via WhatsApp | Full |
| Exam Checker | Teacher photographs student exam papers; Rumi grades them using OCR and AI-based assessment | Full |
Teacher describes a topic and grade; Rumi generates a full lesson plan as a downloadable PDF.
lesson_plan_feature_v6_2.5x.mp4
Teacher sends classroom audio; Rumi transcribes, scores against a selectable framework (OECD / HOTS / TEACH / FICO), conducts reflective conversation, generates PDF report.
coaching_feature_compressed.mp4
Student reads aloud into WhatsApp; Rumi measures WCPM, accuracy, comprehension; compares to grade benchmarks.
reading_feature_video_2.5x.mp4
Teacher requests a topic; Rumi generates an educational video with narration and visuals.
video_generation_compressed.mp4
Teacher sets up class list, marks daily attendance via WhatsApp Flow.
attendance_feature_final_2x.mp4
- Teacher records their classroom (audio or video) and sends it to Rumi on WhatsApp
- Rumi transcribes the recording using Soniox (supporting multilingual and code-switched speech)
- Rumi analyzes the transcript against the teacher's selected pedagogical framework:
- OECD — 19 criteria across 5 goals (118 marks)
- HOTS — 16 indicators across 6 areas, aligned to PESRP/PECTAA spec (48 marks)
- TEACH — World Bank classroom observation tool
- FICO — 21 indicators across 5 domains (84 marks), with photo-aware scoring
- Optional classroom photo analysis — teacher sends a photo alongside audio; Rumi uses vision AI to score photo-aware indicators (e.g. seating arrangement, materials use)
- Rumi conducts a reflective conversation — 3 voice-delivered questions prompting the teacher to reflect on specific moments from their lesson
- Rumi generates a PDF report — with scores per goal, evidence from the transcript, growth areas, actionable recommendations, and performance charts. Ends with a personalized coaching card highlighting the single highest-leverage action.
- Prior feedback tracking — each session builds on previous ones, so recommendations evolve over time
The framework is selected per teacher (stored in their profile) and fully customizable. See docs/agent-customization.md.
- Teacher selects a student and initiates an assessment
- Rumi generates an age-appropriate reading passage (adaptive difficulty based on prior results)
- Student reads aloud into WhatsApp
- Rumi measures: Words Correct Per Minute (WCPM), reading accuracy, pronunciation quality, and comprehension (via follow-up questions)
- Results are compared against grade-level benchmarks (DIBELS/EGRA-normed, L2-adjusted for non-English readers)
- Teacher receives a detailed fluency report with diagnostic feedback and recommended next steps
Assessment methodology is customizable — teams can swap to ASER, EGRA, or custom benchmarks. See docs/agent-customization.md.
Rumi supports 9 languages for voice and text interaction:
| Language | Code | Script | Voice (TTS) | Speech Recognition |
|---|---|---|---|---|
| English | en | LTR | ElevenLabs | Soniox, Whisper |
| Urdu | ur | RTL | ElevenLabs | Soniox |
| Arabic | ar | RTL | ElevenLabs | Soniox |
| Spanish | es | LTR | ElevenLabs | Soniox |
| Balochi | bal-PK | RTL | — | Modal MMS-ASR |
| Sindhi | sd-PK | RTL | — | Modal MMS-ASR |
| Pashto | ps-PK | RTL | — | Modal MMS-ASR |
| Punjabi | pa-PK | RTL | — | Modal MMS-ASR |
| Tamil | ta-LK | LTR | — | Soniox |
Adding a new language requires updates to 7 configuration files. See docs/agent-customization.md.
# 1. Fork this repo on GitHub, then clone YOUR fork
git clone https://github.com/YOUR-ORG/rumi-platform.git
cd rumi-platform
# 2. Install dependencies
npm install && cd bot && npm install && cd ..
# 3. Set up services (see SETUP.md for details)
# - Create a Supabase database and run the schema SQL
# - Get an OpenRouter API key
# - Get WhatsApp Business credentials from Meta
# 4. Configure environment
cp .env.template .env
# Fill in SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, OPENROUTER_API_KEY,
# WHATSAPP_TOKEN, PHONE_NUMBER_ID, WABA_ID, WEBHOOK_VERIFY_TOKEN, REDIS_URL
# 5. Deploy to Railway
cd bot && railway up --service bot
# 6. Set up WhatsApp webhook pointing to your Railway URL
# 7. Send "Hi" to your bot number!| Requirement | Where to Get It |
|---|---|
| GitHub account | github.com (to fork the repo) |
| Node.js 18+ | nodejs.org |
| Supabase account | supabase.com (free tier works) |
| Railway account | railway.app (hosting + Redis) |
| OpenRouter API key | openrouter.ai/keys |
| WhatsApp Business credentials | Meta Business Manager |
See SETUP.md for the complete step-by-step guide with screenshots and troubleshooting.
rumi-platform/
├── bot/ # WhatsApp Bot (Node.js + Express)
│ ├── whatsapp-bot.js # Main entry point (webhook, message routing)
│ ├── shared/
│ │ ├── config/ # Branding, feature tiers, capabilities, languages
│ │ ├── services/ # 39+ service modules (LLM, coaching, reading, video...)
│ │ ├── handlers/ # Message handlers (text, voice, image, flow, exam, attendance)
│ │ └── constants/ # Scoring rubrics, media IDs
│ ├── workers/ # 8 background workers (coaching, video, lesson plans, exams)
│ └── scripts/ # CLI simulator, env validator, deployment helpers
├── dashboard/ # Observability Portal — analytics, session history, system health
├── portal/ # Teacher Portal — React web app for coaching/reading history
├── infrastructure/
│ ├── supabase/ # SQL schema (52+ tables), RLS policies, seed data
│ └── railway/ # Procfile for web + worker processes
├── tests/ # 158 tests across 11 suites
├── docs/ # Architecture, customization, monitoring, cost guide
└── .claude/ # Claude Code config + /setup skill
Teacher on WhatsApp
→ Meta Cloud API → POST /webhook → Express handler
→ User lookup (Supabase) → Language detection → Feature routing
→ Text | Voice | Image | Flow handler
→ LLM Service (OpenRouter) → Response generation
→ BullMQ Queue → Background workers → Reports / media
→ WhatsApp delivery back to teacher
| Tier | Features | API Keys Needed | Est. Monthly Cost |
|---|---|---|---|
| Minimal | AI Chat + Registration | 1 (OpenRouter) | ~$15 |
| Recommended | + Coaching + Reading Assessment | 2 (+ Soniox) | ~$50 |
| Full | All features (voice, video, lesson plans, attendance, exams) | 5 (+ ElevenLabs, Azure, Gamma) | ~$200+ |
Cost estimates assume 50–100 teachers, ~500 messages/day. See docs/cost-guide.md.
RUMI_TIER=minimal| Layer | Technology | Purpose |
|---|---|---|
| Runtime | Node.js 18+ | Server-side JavaScript |
| Web Framework | Express.js | Webhook handling, API routes |
| Messaging | WhatsApp Business Cloud API | Messages, media, interactive flows |
| AI/LLM | OpenRouter (500+ models) | Chat, analysis, content generation |
| Database | Supabase (PostgreSQL) | 52+ tables with Row Level Security |
| Job Queue | BullMQ (Redis) | 7 async job types with retry and checkpointing |
| Speech-to-Text | Soniox, Whisper, Modal MMS-ASR | 9-language transcription |
| Text-to-Speech | ElevenLabs | Voice responses in 4+ languages |
| PDF Generation | pdfkit, pdfmake | Coaching reports, lesson plans |
| Video Assembly | FFmpeg, Kie.ai, DALL-E | Educational video generation |
| OCR | AWS Textract, Surya | Exam paper scanning |
| Deployment | Railway | Hosting with auto-scaling |
| Monitoring | Axiom (optional) | Structured log aggregation |
BOT_NAME=MyAssistant
ORG_NAME=My School District
SUPPORT_CONTACT=help@myschool.org
LLM_MODEL=anthropic/claude-sonnet-4This repo is designed to be customized by teams using Cursor, Claude Code, or similar AI-assisted IDEs. The Agent Customization Guide maps every customization goal to exact files and step-by-step instructions:
| I want to... | Guide Section |
|---|---|
| Swap OECD coaching for Teach / Danielson / custom framework | Section 1 |
| Use ASER instead of DIBELS for reading | Section 2 |
| Change lesson plan format (5E, UbD, etc.) | Section 3 |
| Add a new language | Section 4 |
| Switch LLM provider (Claude, Gemini, local) | Section 5 |
| Add a new feature | Section 7 |
| Rebrand the entire bot | Section 11 |
npm test # All 158 tests (11 suites)
npm run test:security # No hardcoded secrets
npm run test:sprint1 # Core feature tests
npm run test:schema # Database schema validation
npm run test:setup # Setup tooling verification
npm run test:docs # Documentation completeness
npm run simulate # CLI simulator (test without WhatsApp)
npm run validate:env # Environment variable check| Doc | Description |
|---|---|
| SETUP.md | Manual setup guide (8 steps) |
| docs/architecture.md | System architecture and message flow |
| docs/agent-customization.md | Agent-first deep customization (12 sections) |
| docs/customization.md | Basic customization (branding, tiers, LLM) |
| docs/monitoring.md | Observability, dashboards, debugging |
| docs/cost-guide.md | Monthly cost estimates by tier |
| bot/docs/ | 15+ detailed feature and technical guides |
| bot/database/SCHEMA_GUIDE.md | Database schema explained (52+ tables) |
See .github/CONTRIBUTING.md for development setup, code style, testing, and PR guidelines.
Rumi is built by Taleemabad, Pakistan's leading EdTech company. The name comes from Jalaluddin Rumi, the 13th-century poet and teacher who believed that education is not the filling of a vessel but the kindling of a flame.
Website: hellorumi.ai | Research: hellorumi.ai/research
Apache License 2.0 — See LICENSE.
You are free to use, modify, and distribute this software. We encourage contributing improvements back to the community.