---
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 |