README.md

metadata

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
DEEPGRAM_API_KEY	✅	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:

   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

# 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