README.md

---
title: PlotWeaver Voice Agent
emoji: 🗣️
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 6.12.0
app_file: app.py
pinned: true
short_description: Hausa voice AI for African banks, telecoms, and delivery
license: apache-2.0
---

# PlotWeaver Voice Agent

Hausa-first conversational AI demo. Product 7 of the PlotWeaver suite: voice bots for WhatsApp, phone, and customer support across African banks, telecoms, and delivery services.

## What it does

- **ASR**: Whisper-small transcribes your Hausa audio
- **NLU**: Hybrid — rule-based keyword matcher (fast path) + Qwen2.5-1.5B-Instruct (zero-shot fallback for paraphrases)
- **Dialogue manager**: deterministic FSM across 3 verticals (Bank, Telecom, Delivery)
- **TTS**: `facebook/mms-tts-hau` synthesizes the bot's Hausa response

## How to use

1. Pick a vertical (Bank / Telecom / Delivery)
2. Type a Hausa phrase, record with microphone, or upload audio
3. The bot's audio response autoplays

**Sample bank flow**: Type `duba ma'auni` → then `1234` → bot returns balance.

**Escalation**: Say "mutum" or "wakili" at any time to flag human handoff.

## Notes

First turn cold-starts ASR + TTS (~640 MB download). Qwen2.5-1.5B (~3 GB) only loads when rule-based NLU misses. Subsequent turns: 5-10s on CPU.

This is a POC. Production plan: fine-tuned Hausa Whisper, fine-tuned AfroXLMR NLU (replacing the LLM tier), live WhatsApp Business Cloud integration, Twilio Voice.