Spaces:
Running
Running
File size: 4,329 Bytes
1b99a6a 106d34a 050852c b44c45c 1b99a6a 050852c 1b99a6a 050852c 5fd7d39 050852c 5fd7d39 050852c 5fd7d39 050852c 5fd7d39 050852c 5fd7d39 050852c 5fd7d39 050852c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 | ---
title: Reem — Virtual AI Interview Agent
emoji: 📞
colorFrom: green
colorTo: yellow
sdk: docker
pinned: false
license: mit
---
# 📞 Reem — Real-Time Streaming Voice RAG Bot
**XYZ Holdings Virtual Call Centre** — powered by Deepgram STT · Groq LLM · edge-tts
---
## Architecture
```
Browser mic → Gradio Audio → Deepgram STT (nova-2, multilingual)
↓
Router (sql / rag)
↙ ↘
SQLite orders FAISS + SentenceTransformer
↘ ↙
Groq LLaMA-3.3-70b (streaming)
↓
edge-tts TTS
↓
Gradio Audio (autoplay)
```
---
## Features
| Feature | Details |
|---|---|
| **STT** | Deepgram nova-2, auto language detection (EN / AR / UR) |
| **LLM** | Groq `llama-3.3-70b-versatile` with streaming |
| **TTS** | edge-tts — `en-US-AriaNeural`, `ar-SA-ZariyahNeural`, `ur-PK-UzmaNeural` |
| **Memory** | 10-turn sliding window + entity cache (order IDs, customer name) |
| **Routing** | SQL path for order tracking, RAG path for knowledge base Q&A |
| **Languages** | English · Arabic · Urdu |
---
## Environment Variables
Set these in **HF Spaces → Settings → Repository secrets**:
| Variable | Required | Description |
|---|---|---|
| `GROQ_API_KEY` | ✅ | [console.groq.com](https://console.groq.com) |
| `DEEPGRAM_API_KEY` | ✅ | [console.deepgram.com](https://console.deepgram.com) |
| `LIVEKIT_API_KEY` | ⬜ | Reserved for future WebRTC streaming |
---
## Deployment — HF Spaces (Gradio SDK)
1. Create a new Space → **Gradio** SDK
2. Push these files — no Dockerfile needed:
```
app.py
requirements.txt
README.md
```
3. Add secrets under **Settings → Repository secrets**: `GROQ_API_KEY`, `DEEPGRAM_API_KEY`
4. HF installs `requirements.txt` automatically and runs `app.py`
---
## Knowledge Base Setup
1. Open **Admin Panel** (left sidebar) after launch
2. Upload one or more `.txt` files → click **Build KB**
3. FAISS index is built in-memory and persisted to `faiss.index` + `chunks.npy`
## Orders Database Setup
1. Export your SQLite `.db` file with an `orders` table:
```sql
CREATE TABLE orders (
order_id INTEGER PRIMARY KEY,
order_date TEXT,
customer_name TEXT,
customer_city TEXT,
customer_address TEXT,
status TEXT,
delivery_date TEXT,
comments TEXT
);
```
2. Upload via **Admin Panel → Orders Database**
---
## Usage Flow
1. Page loads → **welcome message plays** in EN / AR / UR
2. Say or click your **language** → Reem confirms
3. **Speak** into mic or **type** in the text box
4. Reem routes your query:
- Order number / tracking keywords → **SQL lookup**
- General questions → **RAG knowledge base**
5. Response **streams** from Groq → TTS plays automatically
6. Reem **remembers** order IDs and customer name across turns
---
## Local Development
```bash
# Create venv
python -m venv .venv && source .venv/bin/activate
# Install
pip install -r requirements.txt
# Set env vars
export GROQ_API_KEY=gsk_...
export DEEPGRAM_API_KEY=...
# Run
python app.py
# → http://localhost:7860
```
---
## File Structure
```
├── app.py # Main Gradio app
├── requirements.txt
├── README.md # HF Spaces config frontmatter lives here
├── faiss.index # Auto-generated after KB build
├── chunks.npy # Auto-generated after KB build
├── saudi_orders_database.db # Upload via Admin Panel
└── agent_photo.jpg # Optional — replaces emoji avatar
```
---
## Differences from Streamlit Version
| Aspect | Streamlit + Railway | Gradio on HF Spaces |
|---|---|---|
| Port management | FastAPI proxy required | Single port, native |
| Streaming TTS | `st.components.v1.html` workaround | `gr.Audio(autoplay=True)` |
| STT | `streamlit-mic-recorder` | `gr.Audio(sources=["microphone"])` |
| Re-render issues | Duplicate responses on rerun | State-based, no reruns |
| Barge-in | Manual WebSocket lifecycle | Deepgram `stop_recording` event | |