mukwak/Tijah-MVP

Engine for Africa's informal economy # Tijah - Voice-First WhatsApp Shop Manager Tijah is a WhatsApp-based shop assistant for informal traders in Nigeria. Traders send voice notes or text messages to record sales, track stock, manage credit, and monitor expenses — no app download required. ## Quick Start (Local) ```bash # 1. Clone and set up git clone && cd Tijah_MVP python -m venv venv && source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt # 2. Configure environment cp .env.example .env # Then fill in your API keys (see Environment Variables below) # 3. Run the CLI simulator (no WhatsApp needed) python test_local.py ``` ## Architecture ``` WhatsApp User | | voice note / text v Meta Cloud API (v21.0) | v FastAPI Webhook (/webhook) | +---> Audio? ---> OpenAI Whisper (STT) ---> text | v Pre-classifier (regex, fast) | +---> match? ---> Intent JSON | +---> no match ---> Gemini 2.0 Flash (NLU) ---> Intent JSON | v Handler (business logic) | v SQLite (local) / Neon Postgres (hosted) | v Response (text + optional TTS via edge-tts) | v WhatsApp reply (text message + voice note if user sent voice) ``` ## Features | Feature | Example command | |---------|----------------| | Record sales | "I sold 3 bags of rice for 5000 each" | | Batch sales | "I sold 20 coke, 15 biscuit, 10 soap" | | Buy stock | "I bought 10 bags of cement at 3000" | | Batch restock | "I bought 50 phone case, 30 charger, 20 power bank" | | Credit book | "Mama Joy owes me 5000" | | Track payments | "Mama Joy paid 2000" | | Retroactive credit | "That was on credit" (marks last sale) | | Expenses | "I spent 500 on transport" / "3k on flour and 1.5k on oil" | | Set prices | "Rice is 5000 per bag" | | Daily/weekly/monthly/all-time summary | "How did my shop do today/this week/since I started?" | | Sales list | "What did I sell this week?" | | Payment history | "How much did people pay me this week?" | | Stock check | "How much rice do I have?" | | Undo / edit | "Cancel that" / "Undo the rice sale" …