luchetu/pigia-shuru

# Pigia Shuru Pigia Shuru is a voice-first tax assistance backend for Kenyan taxpayers. It is designed to power phone-based tax support flows such as NIL return guidance, Turnover Tax assistance, payment help, and future KRA-integrated workflows. The current focus of the project is the backend and voice-agent platform. ## Stack - FastAPI with Python - Twilio for voice telephony - LiveKit for WebRTC transport - LiveKit Agents for session management - Gemini Realtime for conversational intelligence ## Design Principle The codebase is organized around capabilities, not vendors. Twilio, LiveKit, and Gemini are the current providers, but the folder structure is intended to stay provider-agnostic so implementations can be swapped without reshaping the app. ## Product Direction Pigia Shuru is being structured as a voice-agent system that can: - accept inbound calls from mobile or feature phones - route sessions through a voice agent - support English and Kiswahili flows - confirm critical values before action - escalate risky or unsupported cases - send SMS or WhatsApp summaries after calls ## Architecture ```mermaid flowchart LR A["Caller"] --> B["Twilio Voice"] B --> C["FastAPI Webhooks"] C --> D["Session Transport Bootstrap"] D --> E["Realtime Agent Runtime"] E --> F["AI Realtime Provider"] E --> G["Agent Flows"] G --> H["KRA Connectors"] G --> I["Notification Service"] G --> J["Audit Logs"] I --> K["SMS / WhatsApp Recap"] K --> A ``` The voice path starts at the telephony provider, enters the FastAPI backend, creates or joins a realtime transport session, and hands conversation control to the agent runtime backed by a realtime AI provider. Business flows then call integrations such as KRA connectors, notifications, and audit logging. ## High-Level Flow ```mermaid flowchart TD A["Inbound call"] --> B["Language and intent capture"] B --> C["Authenticate if required"] C --> D{"Safe to automate?"} D -->|Yes| E["Run voice-agent flow"] D -->|Needs review| F["Confir …