Update README.md

README.md

@@ -1,15 +1,156 @@
 ---
-title: Streaming Bot
-emoji: 💬
-colorFrom: yellow
-colorTo: purple
+title: Reem — Virtual Call Centre Voice Bot
+emoji: 📞
+colorFrom: green
+colorTo: yellow
 sdk: gradio
-sdk_version: 6.5.1
-app_file: app.py
 pinned: false
-hf_oauth: true
-hf_oauth_scopes:
-- inference-api
+license: mit
 ---
 
-An example chatbot using [Gradio](https://gradio.app), [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub/v0.22.2/en/index), and the [Hugging Face Inference API](https://huggingface.co/docs/api-inference/index).
+# 📞 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 (Docker SDK)
+
+1. Create a new Space → **Docker** SDK
+2. Push all files:
+   ```
+   app.py
+   requirements.txt
+   Dockerfile
+   README.md
+   ```
+3. Add secrets (`GROQ_API_KEY`, `DEEPGRAM_API_KEY`)
+4. Space auto-builds and launches on port **7860**
+
+---
+
+## 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
+├── Dockerfile
+├── README.md
+├── 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 |