fix: add HF Spaces README configuration

README.md

@@ -1,380 +1,32 @@
-# 🎙️ MCP Voice Agent
-
-> **Production-grade, fully free** MCP-powered agentic voice assistant.
-> Built with **uv**, **LangChain**, **Groq** (free LLM + STT), **Edge-TTS** (free TTS),
-> **ChromaDB** (free RAG), and hosted on **Hugging Face Spaces** (free cloud).
-
-[![CI](https://github.com/YOUR-USERNAME/mcp-voice-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/YOUR-USERNAME/mcp-voice-agent/actions)
-[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
-[![uv](https://img.shields.io/badge/managed%20by-uv-7c3aed.svg)](https://github.com/astral-sh/uv)
-[![LangChain](https://img.shields.io/badge/LangChain-0.3-1c3c3c.svg)](https://langchain.com)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-
----
-
-## 📖 Overview
-
-This project reimplements the [OpenAI MCP-Powered Voice Agents Cookbook](https://developers.openai.com/cookbook/examples/partners/mcp_powered_voice_agents/mcp_powered_agents_cookbook.ipynb) using **entirely free components** — no OpenAI API key required.
-
-### Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        User's Machine                           │
-│                                                                 │
-│   🎤 Microphone                                                 │
-│       │                                                         │
-│       ▼                                                         │
-│  ┌─────────────┐     ┌──────────────────────────────────────┐  │
-│  │ AudioRecorder│────▶│  Groq Whisper STT (free)             │  │
-│  └─────────────┘     └──────────────┬───────────────────────┘  │
-│                                     │ transcribed text          │
-│                                     ▼                           │
-│                        ┌────────────────────────┐              │
-│                        │   LangChain ReAct Agent │              │
-│                        │   (Groq llama-3.3-70b)  │              │
-│                        └────────────┬───────────┘              │
-│                                     │ tool calls                │
-│                   ┌─────────────────┼──────────────────┐       │
-│                   ▼                 ▼                   ▼       │
-│            ┌────────────┐   ┌──────────────┐   ┌────────────┐  │
-│            │ rag_search │   │  web_search  │   │sqlite_query│  │
-│            │ (ChromaDB) │   │(DuckDuckGo)  │   │  (SQLite)  │  │
-│            └──────┬─────┘   └──────┬───────┘   └─────┬──────┘  │
-│                   │                │                  │         │
-│            ┌──────┴────────────────┴──────────────────┘         │
-│            │         MCP Server (FastMCP / SSE)                 │
-│            │   Hosted FREE on Hugging Face Spaces 🤗            │
-│            └───────────────────────────────────────────────────┘
-│                                     │ synthesised text          │
-│                                     ▼                           │
-│                        ┌────────────────────────┐              │
-│                        │   Edge-TTS (free)       │              │
-│                        │   Microsoft Neural TTS  │              │
-│                        └────────────┬───────────┘              │
-│                                     │ audio bytes               │
-│                                     ▼                           │
-│                              🔊 Speaker                         │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Free Component Map
-
-| Function | Original (Paid) | This Repo (Free) |
-|---|---|---|
-| LLM (reasoning) | GPT-4.1-mini | **Groq** — `llama-3.3-70b-versatile` |
-| STT (voice → text) | `gpt-4o-transcribe` | **Groq Whisper** — `whisper-large-v3-turbo` |
-| TTS (text → voice) | `gpt-4o-mini-tts` | **Edge-TTS** — Microsoft Neural (no key) |
-| Vector store / RAG | OpenAI Vector Stores | **ChromaDB** (local) + sentence-transformers |
-| Web search | OpenAI web_search tool | **DuckDuckGo** (no key) |
-| Agent framework | OpenAI Agents SDK | **LangChain** ReAct agent |
-| MCP server | Local only | **Hugging Face Spaces** (free Docker) |
-| Package manager | pip | **uv** (fast, lockfile-based) |
-
----
-
-## 🚀 Quickstart
-
-### Prerequisites
-
-| Tool | Install |
-|---|---|
-| Python 3.11+ | [python.org](https://python.org) |
-| **uv** | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
-| ffmpeg (audio) | macOS: `brew install ffmpeg` · Linux: `apt install ffmpeg` |
-| Groq API key | [console.groq.com](https://console.groq.com) (free, takes 30 seconds) |
-
-### 1. Clone & install
-
-```bash
-git clone https://github.com/YOUR-USERNAME/mcp-voice-agent.git
-cd mcp-voice-agent
-
-# uv creates the virtualenv and installs all deps from pyproject.toml
-uv sync
-```
-
-### 2. Configure environment
-
-```bash
-cp .env.example .env
-# Edit .env — the only required value is GROQ_API_KEY
-```
-
-### 3. Seed data
-
-```bash
-# Index your documents into ChromaDB
-uv run index-docs
-
-# (Optional) Seed SQLite with plan pricing data
-uv run python scripts/seed_sqlite.py
-```
-
-### 4. Start the MCP server
-
-```bash
-# Terminal 1
-uv run mcp-server
-# → Server running at http://localhost:8000/sse
-```
-
-### 5. Start the voice assistant
-
-```bash
-# Terminal 2
-uv run voice-agent
-# → Speak into your microphone!
-```
-
-Or use the convenience scripts:
-
-```bash
-chmod +x scripts/*.sh
-./scripts/start_server.sh   # terminal 1
-./scripts/start_agent.sh    # terminal 2
-```
-
----
-
-## 📁 Project Structure
-
-```
-mcp-voice-agent/
-│
-├── src/                          # All application source code
-│   ├── config.py                 # Centralised Pydantic settings (reads .env)
-│   ├── logger.py                 # Structured logging (structlog)
-│   │
-│   ├── agents/
-│   │   ├── planner.py            # LangChain ReAct agent + Groq LLM
-│   │   └── voice_agent.py        # Main conversation loop (CLI entry point)
-│   │
-│   ├── mcp_servers/
-│   │   └── search_server.py      # FastMCP server: rag_search, web_search, health_check
-│   │
-│   ├── rag/
-│   │   └── indexer.py            # Document loading, chunking, ChromaDB indexing
-│   │
-│   ├── voice/
-│   │   └── pipeline.py           # STT (Groq Whisper) + TTS (Edge-TTS) + audio I/O
-│   │
-│   └── tools/                    # (Extendable) standalone tool utilities
-│
-├── tests/
-│   ├── conftest.py               # Shared fixtures (mocked env vars)
-│   ├── unit/
-│   │   ├── test_planner.py       # Agent unit tests (mocked LLM/tools)
-│   │   └── test_indexer.py       # RAG indexer unit tests
-│   └── integration/
-│       └── test_mcp_server.py    # MCP tool integration tests
-│
-├── data/
-│   ├── sample_files/             # Drop your .txt / .md / .pdf docs here
-│   └── chroma_db/                # ChromaDB persisted index (git-ignored)
-│
-├── scripts/
-│   ├── start_server.sh           # One-command server startup
-│   ├── start_agent.sh            # One-command agent startup
-│   └── seed_sqlite.py            # Seed SQLite with plan data
-│
-├── docs/                         # MkDocs documentation
-│
-├── .github/
-│   └── workflows/
-│       └── ci.yml                # GitHub Actions: lint → typecheck → test → deploy to HF
-│
-├── Dockerfile                    # For Hugging Face Spaces (port 7860, non-root)
-├── pyproject.toml                # uv-managed deps, ruff, mypy, pytest config
-├── .python-version               # Pins Python 3.11
-├── .env.example                  # Template — copy to .env
-├── .pre-commit-config.yaml       # ruff + mypy + safety hooks
-├── Makefile                      # Developer convenience commands
-└── README.md
-```
-
 ---
-
-## ☁️ Deploy MCP Server to Hugging Face Spaces (Free)
-
-The MCP server (RAG + web search tools) runs as a free Docker Space on Hugging Face, giving you a persistent public SSE endpoint your local voice agent can call from anywhere.
-
-### Step 1 — Create a Space
-
-1. Go to [huggingface.co/spaces](https://huggingface.co/spaces)
-2. Click **New Space**
-3. Name it `mcp-voice-agent`
-4. Select **Docker** as the SDK
-5. Set visibility to **Public** (required for free tier) or **Private** (PRO)
-
-### Step 2 — Set secrets
-
-In your Space → **Settings → Variables and Secrets**:
-
-| Secret name | Value |
-|---|---|
-| `GROQ_API_KEY` | Your Groq API key |
-
-### Step 3 — Push via Git
-
-```bash
-# Add the HF remote (replace YOUR-HF-USERNAME)
-git remote add hf https://huggingface.co/spaces/YOUR-HF-USERNAME/mcp-voice-agent
-
-# Push — HF Spaces auto-builds the Docker image
-git push hf main
-```
-
-Your MCP server will be live at:
-
-```
-https://YOUR-HF-USERNAME-mcp-voice-agent.hf.space/sse
-```
-
-### Step 4 — Point your local voice agent at HF
-
-```bash
-# Use the hosted MCP server instead of localhost
-MCP_SERVER_URL=https://YOUR-HF-USERNAME-mcp-voice-agent.hf.space/sse \
-  ./scripts/start_agent.sh
-```
-
-Or set it permanently in your `.env`:
-
-```ini
-MCP_SERVER_HOST=YOUR-HF-USERNAME-mcp-voice-agent.hf.space
-MCP_SERVER_PORT=443
-```
-
-### Automated Deploy via GitHub Actions
-
-The included CI workflow (`.github/workflows/ci.yml`) automatically deploys to HF Spaces on every push to `main` — after lint, typecheck, and tests pass.
-
-Set these GitHub repository secrets:
-
-| Secret | Description |
-|---|---|
-| `GROQ_API_KEY` | For integration tests |
-| `HF_TOKEN` | Hugging Face write token ([settings](https://huggingface.co/settings/tokens)) |
-
-Then update the deploy step in `ci.yml`:
-
-```yaml
-git remote add hf https://YOUR-HF-USERNAME:${HF_TOKEN}@huggingface.co/spaces/YOUR-HF-USERNAME/mcp-voice-agent
-```
-
+title: MCP Voice Agent
+emoji: 🎙️
+colorFrom: blue
+colorTo: purple
+sdk: docker
+pinned: false
 ---
 
-## 🛠️ Development
-
-### Common commands (via Makefile)
-
-```bash
-make install-dev    # Install all deps including dev extras
-make lint           # Ruff linting
-make format         # Ruff auto-format
-make typecheck      # mypy strict type checking
-make test           # All tests with coverage report
-make test-unit      # Unit tests only
-make test-int       # Integration tests only
-make index-docs     # Re-index documents into ChromaDB
-make start-server   # Start MCP server
-make start-agent    # Start voice agent
-make docker-build   # Build Docker image
-make docker-run     # Run Docker image locally (mirrors HF Spaces env)
-make clean          # Remove all build/cache artifacts
-```
-
-### Adding your own documents
-
-Drop `.txt`, `.md`, or `.pdf` files into `data/sample_files/`, then re-index:
+# MCP Voice Agent
 
-```bash
-uv run index-docs --force   # --force clears the existing index first
-```
+Production-grade MCP-powered voice assistant using free LLMs.
 
-### Extending with new MCP tools
+- **LLM**: Groq `llama-3.3-70b-versatile`
+- **STT**: Groq Whisper
+- **TTS**: Edge-TTS
+- **RAG**: ChromaDB + sentence-transformers
+- **Web Search**: DuckDuckGo
+- **MCP Server**: FastMCP (SSE transport)
 
-Add a new `@mcp.tool()` function to `src/mcp_servers/search_server.py`:
+## MCP Server Endpoint
 
-```python
-@mcp.tool()
-def my_new_tool(query: str) -> str:
-    """Describe what this tool does — the LLM reads this description."""
-    ...
+Once running, the MCP SSE endpoint is available at:
 ```
-
-Then register a LangChain wrapper in `src/agents/planner.py` inside `build_langchain_tools()`.
-
-### Swapping the LLM
-
-Edit `.env`:
-
-```ini
-# Groq free-tier options (as of 2026):
-LLM_MODEL=llama-3.3-70b-versatile   # best reasoning
-LLM_MODEL=gemma2-9b-it              # fastest, lowest latency
-LLM_MODEL=mixtral-8x7b-32768        # large context window
-```
-
-No code changes needed — `ChatGroq` picks up the model from settings.
-
-### Swapping the TTS voice
-
-```ini
-# In .env — run `edge-tts --list-voices` to see all options
-TTS_VOICE=en-GB-SoniaNeural         # British English
-TTS_VOICE=en-AU-NatashaNeural       # Australian English
-TTS_VOICE=de-DE-KatjaNeural         # German
-```
-
----
-
-## ⚙️ Configuration Reference
-
-All configuration is in `.env` (see `.env.example`). Every value is validated by Pydantic on startup — bad values fail fast with a clear error message.
-
-| Variable | Default | Description |
-|---|---|---|
-| `GROQ_API_KEY` | **required** | Groq API key (free at console.groq.com) |
-| `LLM_MODEL` | `llama-3.3-70b-versatile` | Groq chat model |
-| `STT_MODEL` | `whisper-large-v3-turbo` | Groq Whisper model |
-| `TTS_VOICE` | `en-US-JennyNeural` | Edge-TTS voice |
-| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence-transformer model (local) |
-| `DOCS_DIR` | `./data/sample_files` | Directory of documents to index |
-| `CHROMA_PERSIST_DIR` | `./data/chroma_db` | ChromaDB storage path |
-| `MCP_SERVER_PORT` | `8000` | MCP server port (7860 on HF Spaces) |
-| `MCP_TRANSPORT` | `sse` | `sse` for network, `stdio` for subprocess |
-| `APP_ENV` | `development` | `development` or `production` |
-| `LOG_FORMAT` | `console` | `console` (pretty) or `json` (structured) |
-
----
-
-## 🧪 Testing
-
-```bash
-uv run pytest               # all tests
-uv run pytest tests/unit/   # unit only (no network, no API keys)
-uv run pytest -v --tb=long  # verbose output
+https://adarshds-mcp-voice-agent.hf.space/sse
 ```
 
-The test suite uses mocks for all external calls (Groq API, ChromaDB, DuckDuckGo), so tests run fully offline and require no API keys.
-
----
-
-## 📜 License
-
-MIT — see [LICENSE](LICENSE).
-
----
-
-## 🙏 Acknowledgements
+## Tools Available
 
-- [OpenAI MCP Voice Agents Cookbook](https://developers.openai.com/cookbook/examples/partners/mcp_powered_voice_agents/mcp_powered_agents_cookbook.ipynb) — original inspiration
-- [Groq](https://groq.com) — fast, free LLM + Whisper inference
-- [LangChain](https://langchain.com) — agent orchestration
-- [FastMCP](https://github.com/jlowin/fastmcp) — ergonomic MCP server framework
-- [Edge-TTS](https://github.com/rany2/edge-tts) — free Microsoft neural TTS
-- [ChromaDB](https://www.trychroma.com) — local vector database
-- [Hugging Face Spaces](https://huggingface.co/spaces) — free cloud hosting
-- [uv](https://github.com/astral-sh/uv) — blazing-fast Python package manager
+- `rag_search` — search internal insurance documents
+- `web_search` — search the web via DuckDuckGo  
+- `health_check` — check server status