Spaces:
Running
Running
| 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 | |