Isaackjoshua/muungano-bot

A WhatsApp bot (Swahili) for a Tanzanian government-run university innovation contest about the Union of Tanganyika and Zanzibar (Muungano). It runs on FastAPI behind a Twilio WhatsApp webhook, keeps per-user state in SQLite, and answers free-text questions with Google's Gemini API (free tier) — grounded strictly in a vetted knowledge base. # Muungano WhatsApp Bot — *Elimu ya Muungano Ubunifu Challenge* A WhatsApp bot (Swahili) for a Tanzanian government-run university innovation contest about the Union of Tanganyika and Zanzibar (*Muungano*). It runs on FastAPI behind a Twilio WhatsApp webhook, keeps per-user state in SQLite, and answers free-text questions with Google's Gemini API (free tier) — grounded strictly in a vetted knowledge base. ## The three modes A user picks a mode from a numbered main menu (typing `MENU` at any time returns there): 1. **Uliza swali** — free-text Q&A. The model answers **only** from `app/knowledge_base.md`; it is instructed to decline politely rather than invent an answer, and to stay neutral on politically contested topics. 2. **Fanya Quiz** — a 5-question multiple-choice quiz (answer `A`–`D`), with a running score reported at the end. 3. **Je, Wajua?** — cycles through 10 short "did you know?" facts, one per request. ### Why not vector-search RAG? `knowledge_base.md` is a few thousand words — small enough to pass in full as the system prompt's grounding context on every request. That is simpler and more reliable than standing up embeddings and a vector DB for a corpus this size. Only revisit that if the corpus grows past comfortably fitting in context. ### Model Uses `gemini-2.5-flash` (overridable via the `GEMINI_MODEL` env var). Gemini Flash is fast, capable enough for careful instruction-following Swahili answers that respect the "only answer from the reference document, stay neutral" rules, and — critically for this project — available on Google's **free tier**. That free tier is *rate-limited* (requests per minute / per day), **not** credit-limited: there is no trial credit to exhaust and no card required. Verify the current model ID and your live quota in Google AI Studio before deploying, as free-tier Flash limits have changed more than once. > **Free-tier data note:** on Google's free Gemini tier, prompts may be used by > Google to improve their models …