immanueln98/ussd-edu

USSD-based educational chatbot for schools in Botswana (currently) # 📚 EduBot - USSD Educational Platform > An AI-powered USSD-based educational chatbot for primary school mathematics in Botswana, delivering lessons and quizzes via SMS with cost-optimized delivery. ## 🌟 Features ### ✅ Phase 1: Core USSD Experience (Complete) - **📖 Learn Mode**: Browse math topics (Addition, Subtraction, Multiplication, Division) - **✏️ Quiz Mode**: Interactive quizzes via USSD with instant feedback - **📱 SMS Delivery**: Lessons and quiz results sent via optimized SMS - **💾 Session Management**: Redis-based state persistence for seamless conversations - **🔄 Session Summary**: Complete activity summary on exit ### ✅ Phase 2: LLM Integration (Complete) - **🤖 AI Quiz Generation**: Dynamic quiz questions using Groq's Llama 3.1 8B model - **⚡ Fast Inference**: 90 chars, truncated + SMS sent 3. ⏰ Deferred: LLM timeout, fallback message + SMS queued 4. ❌ Failed: LLM error, friendly error message displayed ### Smart Truncation Algorithm ```python # Truncation priority (preserves readability): 1. Try sentence boundary (. ! ?) 2. Try clause boundary (, ; :) 3. Try word boundary (space) 4. Hard cut with ... (last resort) ``` ### SMS Conversation Summary Format When user exits chat, they receive an SMS with full history: ``` EDUBOT SESSION SUMMARY CHAT - Addition Q1: What is 2 plus 3 A: 2 plus 3 is 5. Q2: How do I add big numbers A: Add numbers one by one, like 456 + 278: 456 + 200 = 656, then 656 + 70 = 726, then 726 + 8 = 734. Thanks for learning! Dial back anytime. ``` **Key Features**: - No emojis (GSM-7 encoding saves 56% per SMS) - Full answers (not truncated versions) - Numbered Q&A for easy reference - Typically 2-3 SMS per conversation ## 💰 SMS Cost Optimization Strategy ### Before Optimization (Quiz Results Example) ``` 📝 QUIZ RESULTS Topic: Addition Score: 3/5 (60%) 👍 Good job! Q1: What is 3 + 4? Your answer: 7 ✓ Q2: What is 5 + 8? Your answer: 10 ✗ Correct: 13 ... ``` **Cost**: ~4-5 SMS (Unicode encoding due to emojis: 70 c …