A production-minded voice support agent for low-resource customer support scenarios in West Africa.
This project demonstrates how to build a safer, grounded support workflow that accepts audio or text, retrieves evidence from a support knowledge base, generates concise responses, and escalates risky or unsupported cases to a human agent.
Many customer support environments in African markets operate under constraints that are often missing from mainstream AI demos:
- multilingual and code-switched user input
- noisy audio conditions
- informal phrasing and spelling variation
- low-bandwidth or unstable connectivity
- trust-sensitive financial and account-related issues
- limited tolerance for unsupported or risky responses
This repo is a focused demonstration of how to design a support assistant for that setting.
This system implements a narrow but realistic support pipeline:
- Accept voice or text input
- Transcribe audio locally
- Normalize the user query
- Retrieve relevant support documents
- Generate a response grounded in retrieved evidence
- Estimate confidence and detect risky cases
- Either return an evidence-backed answer or recommend escalation
The goal is not open-ended chatting. The goal is reliable support behavior in settings where grounding, fallback logic, and escalation matter.
- Top-1 retrieval accuracy: 83.3%
- Evidence recall@3: 100.0%
- Average gold coverage: 84.7%
- Escalation accuracy: 75.0%
- Average confidence: 0.771
- Unsupported answers: 0
- send money failed
- cash-out issue
- account locked
- wrong recipient
- KYC / identity verification help
- Voice and text support
- Local offline transcription with
faster-whisper - Hybrid retrieval
- domain-aware lexical retrieval
- TF-IDF retrieval
- hybrid reranking
- Grounded answer generation
- Evidence-backed responses
- Confidence-aware fallback
- Escalation for risky or unsupported cases
- Offline evaluation suite
- Modular Python backend
The system supports local offline speech transcription using faster-whisper.
POST /transcribe— upload audio and receive a transcriptPOST /voice-ask— upload audio and run the full support pipeline
- Backend:
faster-whisper - Model size:
small - Device:
cpu - Compute type:
int8
The first transcription request may take longer because the ASR model is loaded on first use.
This project is open-sourced as a prototype/community edition.
It is intended to demonstrate how a voice-first support copilot can be built for low-resource West African customer-service settings using:
- local speech transcription
- hybrid retrieval
- grounded answer generation
- ticketing and escalation
- knowledge-base management
- offline evaluation
The open-source version is suitable for learning, research, experimentation, and portfolio review. A production deployment should add authentication, secure storage, stronger access control, monitoring, database migrations, and careful handling of real customer data.
Do not upload or commit real customer data, private audio, private business documents, API keys, production databases, or personally identifiable information to this repository.
For local testing, use synthetic examples or documents you have permission to share.
Copy the example environment file:
cp .env.example .env
## Contributing
Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, contribution guidelines, and safety notes.
## Security
Please read [SECURITY.md](SECURITY.md) before using this project with any sensitive data.
## License
This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.
## System architecture
```text
User input
├─> text
└─> voice
└─> local ASR (faster-whisper)
Normalized query
└─> hybrid retrieval
├─> lexical retrieval
├─> TF-IDF retrieval
└─> reranking
Retrieved evidence
└─> grounded answer generation
└─> guardrails
├─> confidence check
├─> risky-intent detection
└─> escalation decision
Final output
├─> evidence-backed response
└─> escalation to human support