Add Hugging Face Spaces deployment configuration

Dockerfile

@@ -0,0 +1,34 @@
+# Hugging Face Spaces Dockerfile for Smart Escalation API
+FROM python:3.11-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Expose port 7860 (Hugging Face Spaces default)
+EXPOSE 7860
+
+# Set environment variables
+ENV PORT=7860
+ENV PYTHONUNBUFFERED=1
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:7860/health || exit 1
+
+# Run the application
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "7860"]

HUGGINGFACE_DEPLOYMENT.md

@@ -0,0 +1,340 @@
+# 🤗 Deploy to Hugging Face Spaces (FREE)
+
+Complete step-by-step guide to deploy your Smart Escalation API to Hugging Face Spaces for FREE.
+
+## Why Hugging Face Spaces?
+
+- ✅ **FREE** - No credit card required
+- ✅ **2GB RAM** - Enough for ML models (vs Render's 512MB free tier)
+- ✅ **Optimized for ML** - Built for apps like yours
+- ✅ **Easy deployment** - Push code via Git
+- ✅ **Automatic HTTPS** - Secure by default
+
+---
+
+## Step 1: Create Hugging Face Account (2 minutes)
+
+1. **Go to Hugging Face**
+   - Visit: https://huggingface.co/join
+
+2. **Sign Up**
+   - Enter your email
+   - Choose a username (e.g., `yourname`)
+   - Create password
+   - Verify email
+
+3. **Get Access Token**
+   - Go to: https://huggingface.co/settings/tokens
+   - Click **"New token"**
+   - Name: `escalation-api-deploy`
+   - Role: **Write**
+   - Click **"Generate a token"**
+   - **Copy the token** - you'll need it soon!
+
+---
+
+## Step 2: Create a New Space (3 minutes)
+
+1. **Create Space**
+   - Go to: https://huggingface.co/new-space
+   - Or click your profile → **"New Space"**
+
+2. **Configure Space**
+   - **Owner**: Your username
+   - **Space name**: `escalation-api` (or any name you like)
+   - **License**: MIT
+   - **Select the Space SDK**: Choose **"Docker"** (important!)
+   - **Space hardware**: CPU basic (free)
+   - **Visibility**: Public
+   - Click **"Create Space"**
+
+3. **Wait for Space Creation**
+   - You'll see a page with instructions
+   - Keep this page open
+
+---
+
+## Step 3: Add Required Files (5 minutes)
+
+We need to add a few files for Hugging Face Spaces:
+
+### 3.1: Create Dockerfile
+
+I'll create a Dockerfile for you:
+
+```bash
+# This will be created automatically in the next step
+```
+
+### 3.2: Create .env.example for Spaces
+
+```bash
+# This will be created automatically in the next step
+```
+
+Let me create these files now:
+
+---
+
+## Step 4: Push Code to Hugging Face (5 minutes)
+
+### 4.1: Add Hugging Face Remote
+
+Open your terminal and run:
+
+```bash
+# Add Hugging Face as a git remote
+# Replace YOUR_USERNAME with your actual Hugging Face username
+git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/escalation-api
+```
+
+Example:
+```bash
+git remote add hf https://huggingface.co/spaces/john/escalation-api
+```
+
+### 4.2: Commit New Files
+
+```bash
+# Add the new Hugging Face files
+git add Dockerfile README_SPACES.md app.py
+
+# Commit
+git commit -m "Add Hugging Face Spaces deployment files"
+```
+
+### 4.3: Push to Hugging Face
+
+```bash
+# Push to Hugging Face Spaces
+git push hf main
+```
+
+**You'll be prompted for credentials:**
+- **Username**: Your Hugging Face username
+- **Password**: Use the **access token** you created in Step 1 (NOT your password!)
+
+---
+
+## Step 5: Configure Environment Variables (3 minutes)
+
+1. **Go to Your Space**
+   - Visit: `https://huggingface.co/spaces/YOUR_USERNAME/escalation-api`
+
+2. **Open Settings**
+   - Click the **"Settings"** tab at the top
+
+3. **Add Secrets (Environment Variables)**
+   - Scroll down to **"Repository secrets"**
+   - Click **"New secret"** for each variable:
+
+   | Name | Value |
+   |------|-------|
+   | `GOOGLE_API_KEY` | Your Gemini API key from https://makersuite.google.com/app/apikey |
+   | `ARTICLES_DIR` | `data/articles` |
+   | `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` |
+   | `RELEVANCE_THRESHOLD` | `0.5` |
+   | `TOP_K_CHUNKS` | `3` |
+   | `CHUNK_SIZE` | `500` |
+   | `CHUNK_OVERLAP` | `50` |
+   | `LLM_MODEL` | `gemini-1.5-flash` |
+   | `LLM_TEMPERATURE` | `0.3` |
+   | `CORS_ORIGINS` | `https://escalation-api-frontend.vercel.app,http://localhost:5173` |
+
+4. **Save Each Secret**
+   - Click **"Add secret"** after entering each one
+
+---
+
+## Step 6: Wait for Build (10-15 minutes)
+
+1. **Go to "App" Tab**
+   - Click the **"App"** tab at the top
+
+2. **Watch Build Logs**
+   - You'll see the Docker build progress
+   - It will download ML models (~2GB)
+   - This takes 10-15 minutes on first build
+
+3. **Build Complete**
+   - When done, you'll see: **"Running"** status
+   - Your API is now live! 🎉
+
+---
+
+## Step 7: Test Your API (2 minutes)
+
+### 7.1: Get Your API URL
+
+Your API is available at:
+```
+https://YOUR_USERNAME-escalation-api.hf.space
+```
+
+Example:
+```
+https://john-escalation-api.hf.space
+```
+
+### 7.2: Test with curl
+
+```bash
+curl -X POST https://YOUR_USERNAME-escalation-api.hf.space/ask \
+  -H "Content-Type: application/json" \
+  -d '{"question": "How do I reset my password?"}'
+```
+
+### 7.3: Test in Browser
+
+Visit:
+```
+https://YOUR_USERNAME-escalation-api.hf.space/docs
+```
+
+You'll see interactive API documentation where you can test the `/ask` endpoint.
+
+---
+
+## Step 8: Connect Frontend to Backend (5 minutes)
+
+Now connect your Vercel frontend to the Hugging Face backend:
+
+### 8.1: Copy Your Backend URL
+
+```
+https://YOUR_USERNAME-escalation-api.hf.space
+```
+
+### 8.2: Add to Vercel
+
+1. Go to https://vercel.com/dashboard
+2. Open your project: `escalation-api-frontend`
+3. Go to **Settings** → **Environment Variables**
+4. Click **"Add New"**
+   - **Key**: `VITE_API_URL`
+   - **Value**: `https://YOUR_USERNAME-escalation-api.hf.space`
+   - **Environments**: Check all (Production, Preview, Development)
+5. Click **"Save"**
+
+### 8.3: Redeploy Frontend
+
+1. Go to **Deployments** tab
+2. Find the latest deployment
+3. Click **"⋯"** (three dots) → **"Redeploy"**
+4. Click **"Redeploy"** to confirm
+5. Wait 1-2 minutes
+
+---
+
+## Step 9: Test End-to-End (1 minute)
+
+1. **Visit Your Frontend**
+   - Go to: https://escalation-api-frontend.vercel.app/
+
+2. **Ask a Question**
+   - Type: "How do I reset my password?"
+   - Click **"Send"**
+
+3. **Success!** 🎉
+   - You should get an answer from your Hugging Face backend
+   - Your full-stack ML app is now live!
+
+---
+
+## 🎉 Deployment Complete!
+
+Your app is now fully deployed:
+
+- **Frontend**: https://escalation-api-frontend.vercel.app/ (Vercel - FREE)
+- **Backend**: https://YOUR_USERNAME-escalation-api.hf.space (Hugging Face - FREE)
+- **Total Cost**: $0/month 🎊
+
+---
+
+## Troubleshooting
+
+### Build fails with "Out of memory"
+
+**Solution**: Upgrade to Hugging Face Pro ($9/month) for more resources, or:
+- Use a smaller embedding model: `all-MiniLM-L6-v2` → `paraphrase-MiniLM-L3-v2`
+- Reduce dependencies in `requirements.txt`
+
+### "Application startup failed"
+
+**Solution**: Check the logs in the "App" tab:
+- Verify `GOOGLE_API_KEY` is set correctly
+- Check that all environment variables are set
+- Look for Python errors in the logs
+
+### API returns 404
+
+**Solution**: 
+- Make sure the Space is "Running" (not "Building" or "Sleeping")
+- Check the URL is correct: `https://YOUR_USERNAME-escalation-api.hf.space`
+- Visit `/docs` to see available endpoints
+
+### Frontend shows "Failed to fetch"
+
+**Solution**:
+- Verify `VITE_API_URL` is set in Vercel
+- Check backend URL is correct (no trailing slash)
+- Make sure Hugging Face Space is running
+- Check CORS_ORIGINS includes your Vercel frontend URL
+
+### Space goes to sleep
+
+**Solution**: Hugging Face Spaces on free tier sleep after inactivity:
+- First request after sleep takes 30-60 seconds (cold start)
+- Subsequent requests are fast
+- Upgrade to Pro ($9/month) for always-on instances
+
+---
+
+## Updating Your App
+
+To update your code:
+
+```bash
+# Make changes to your code
+git add .
+git commit -m "Update feature"
+
+# Push to GitHub (for version control)
+git push origin main
+
+# Push to Hugging Face (to deploy)
+git push hf main
+```
+
+Hugging Face will automatically rebuild and redeploy.
+
+---
+
+## Cost Comparison
+
+| Platform | Free Tier | Paid Tier | RAM | Notes |
+|----------|-----------|-----------|-----|-------|
+| **Hugging Face** | FREE | $9/month | 2GB | Best for ML apps |
+| **Render** | 512MB (too small) | $7/month | 512MB+ | Good for web apps |
+| **Railway** | $5 credit | $5-20/month | 512MB+ | Pay as you go |
+| **Vercel** | ❌ Can't deploy ML | ❌ Can't deploy ML | 500MB limit | Frontend only |
+
+---
+
+## Next Steps
+
+- ✅ Your app is live and working!
+- 📊 Monitor usage in Hugging Face dashboard
+- 🔧 Add more help articles in `data/articles/`
+- 🎨 Customize the frontend
+- 📈 Track API usage and performance
+
+---
+
+## Need Help?
+
+- **Hugging Face Docs**: https://huggingface.co/docs/hub/spaces
+- **Hugging Face Discord**: https://discord.gg/hugging-face
+- **Your Space Settings**: https://huggingface.co/spaces/YOUR_USERNAME/escalation-api/settings
+
+Enjoy your FREE ML-powered API! 🚀

README.md

@@ -1,767 +1,93 @@
-# Smart Escalation API
-
-An AI-powered L1 customer support system that intelligently answers customer questions about TaskFlow (a fictional project management SaaS) or escalates to human agents when uncertain. The system uses RAG-based retrieval over help articles to ground responses.
-
-## 🚀 Quick Deploy to Vercel
-
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new)
+---
+title: Smart Escalation API
+emoji: 🤖
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+license: mit
+---
 
-1. Click the button above or go to [vercel.com](https://vercel.com)
-2. Import this repository
-3. Add environment variable: `GOOGLE_API_KEY` (get from [Google AI Studio](https://makersuite.google.com/app/apikey))
-4. Deploy!
+# Smart Escalation API
 
-**See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions.**
+AI-powered L1 customer support system that intelligently answers customer questions or escalates to human agents when uncertain.
 
-## Features
+## 🚀 Features
 
 - **RAG-Based Retrieval**: Uses sentence-transformers and FAISS for semantic search over help articles
 - **Intelligent Escalation**: Automatically escalates to human agents when confidence is low
 - **FastAPI Backend**: Fast, async API with automatic OpenAPI documentation
-- **React Chat UI**: Minimal, functional chat interface for customer interaction
-- **Free Hosting Compatible**: No external databases required, deployable to free tiers
-
-## Architecture
-
-- **Backend**: Python serverless functions on Vercel
-- **Vector Store**: FAISS (in-memory) with sentence-transformers embeddings
-- **LLM**: Google Gemini API (gemini-1.5-flash)
-- **Frontend**: React + Vite + TypeScript
-- **Deployment**: Vercel (monorepo with frontend + backend)
-
-## Quick Start
-
-### Prerequisites
-
-- Python 3.9+
-- Node.js 18+ (for frontend)
-- Google Gemini API key
-
-### Backend Setup
-
-1. **Clone the repository**
-   ```bash
-   git clone <repository-url>
-   cd smart-escalation-api
-   ```
-
-2. **Create virtual environment**
-   ```bash
-   python -m venv venv
-   source venv/bin/activate  # On Windows: venv\Scripts\activate
-   ```
-
-3. **Install dependencies**
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-4. **Configure environment variables**
-   ```bash
-   cp .env.example .env
-   # Edit .env and add your API key
-   ```
-
-5. **Run the server**
-   ```bash
-   uvicorn src.main:app --reload
-   ```
-
-   The API will be available at `http://localhost:8000`
-   
-   API documentation: `http://localhost:8000/docs`
-
-### Frontend Setup
-
-1. **Navigate to frontend directory**
-   ```bash
-   cd frontend
-   ```
-
-2. **Install dependencies**
-   ```bash
-   npm install
-   ```
-
-3. **Configure environment**
-   ```bash
-   cp .env.example .env
-   # Edit .env and set VITE_API_URL to your backend URL
-   ```
-
-4. **Run development server**
-   ```bash
-   npm run dev
-   ```
-
-   The UI will be available at `http://localhost:5173`
+- **Google Gemini LLM**: Powered by gemini-1.5-flash for fast, accurate responses
 
-## Project Structure
+## 📡 API Endpoints
 
-```
-smart-escalation-api/
-├── data/
-│   └── articles/          # Help article knowledge base (markdown files)
-├── src/
-│   ├── main.py           # FastAPI application
-│   ├── rag.py            # RAG system with FAISS vector store
-│   ├── escalation.py     # Escalation decision engine
-│   ├── llm_client.py     # LLM API client (Google Gemini)
-│   ├── chunking.py       # Text chunking logic
-│   └── config.py         # Configuration management
-├── tests/
-│   ├── unit/             # Unit tests
-│   ├── integration/      # Integration tests
-│   └── property/         # Property-based tests (Hypothesis)
-├── frontend/
-│   └── src/              # React chat interface
-├── requirements.txt      # Python dependencies
-├── .env.example          # Environment variable template
-└── README.md            # This file
-```
-
-## API Usage
-
-### POST /ask
-
-Submit a customer question and receive an answer or escalation.
-
-**Request:**
-```json
-{
-  "question": "How do I add a team member to my project?"
-}
-```
-
-**Response (Answer):**
-```json
-{
-  "response_type": "answer",
-  "message": "To add a team member to your project in TaskFlow, go to Project Settings > Team Members and click 'Invite Member'. You can set their role as Viewer, Editor, or Admin.",
-  "confidence_explanation": "High confidence - retrieved relevant content from 'Managing Team Permissions' article with similarity score 0.82",
-  "sources": ["permissions.md"]
-}
-```
-
-**Response (Escalation):**
-```json
-{
-  "response_type": "escalation",
-  "message": "I'm not certain I can answer this accurately. Let me connect you with a human support agent who can help.",
-  "confidence_explanation": "Low confidence - best retrieval score was 0.42, indicating question may be outside help article scope",
-  "sources": null
-}
-```
+- `GET /` - API information
+- `GET /health` - Health check
+- `POST /ask` - Submit customer questions and get answers
 
-## Configuration
+## 🔧 Environment Variables
 
-### Environment Variables
+Configure these in your Space settings under "Repository secrets":
 
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `GOOGLE_API_KEY` | Google Gemini API key (required) | - |
-| `EMBEDDING_MODEL` | Sentence-transformers model name | `all-MiniLM-L6-v2` |
-| `RELEVANCE_THRESHOLD` | Minimum similarity score to answer (0-1) | `0.5` |
+| `ARTICLES_DIR` | Path to help articles | `data/articles` |
+| `EMBEDDING_MODEL` | Sentence transformer model | `all-MiniLM-L6-v2` |
+| `RELEVANCE_THRESHOLD` | Minimum similarity score (0-1) | `0.5` |
 | `TOP_K_CHUNKS` | Number of chunks to retrieve | `3` |
 | `CHUNK_SIZE` | Characters per chunk | `500` |
 | `CHUNK_OVERLAP` | Overlap between chunks | `50` |
-| `LLM_MODEL` | LLM model name | `gemini-1.5-flash` |
+| `LLM_MODEL` | Gemini model name | `gemini-1.5-flash` |
 | `LLM_TEMPERATURE` | LLM temperature (0-1) | `0.3` |
+| `CORS_ORIGINS` | Allowed CORS origins | `*` |
 
-### Escalation Logic
+## 📖 Usage
 
-The system escalates to human agents when:
-- Best chunk relevance score < `RELEVANCE_THRESHOLD` (default 0.5)
-- LLM signals uncertainty in its response
-- No relevant chunks are retrieved
+### Example Request
 
-## Deployment
-
-This section provides step-by-step instructions for deploying the entire Smart Escalation API (both backend and frontend) to Vercel.
-
-### Why Vercel for Everything?
-
-Vercel supports both:
-- **Frontend**: Static React apps (traditional use case)
-- **Backend**: Python serverless functions via API routes
-
-This means you can deploy the entire application to a single platform with:
-- ✅ Single deployment workflow
-- ✅ Unified environment variables
-- ✅ Automatic HTTPS
-- ✅ Global CDN
-- ✅ Free tier for both frontend and backend
-
-### Prerequisites
-
-- GitHub account with your repository
-- Google Gemini API key
-- Vercel account (free tier available at [vercel.com](https://vercel.com))
-
-### Project Structure for Vercel
-
-First, we need to restructure the project to work with Vercel's serverless functions:
-
-```
-smart-escalation-api/
-├── api/                    # Backend API (Vercel Serverless Functions)
-│   └── ask.py             # POST /api/ask endpoint
-├── frontend/              # React frontend
-│   ├── src/
-│   ├── package.json
-│   └── vite.config.ts
-├── src/                   # Shared Python modules
-│   ├── rag.py
-│   ├── escalation.py
-│   ├── llm_client.py
-│   ├── chunking.py
-│   └── config.py
-├── data/
-│   └── articles/          # Help articles
-├── requirements.txt       # Python dependencies
-├── vercel.json           # Vercel configuration
-└── package.json          # Root package.json for monorepo
+```bash
+curl -X POST https://webflow97-deployment-taskflow.hf.space/ask \
+  -H "Content-Type: application/json" \
+  -d '{"question": "How do I reset my password?"}'
 ```
 
-### Step 1: Create Vercel Configuration
-
-Create `vercel.json` in the project root:
+### Example Response (Answer)
 
 ```json
 {
-  "version": 2,
-  "builds": [
-    {
-      "src": "api/**/*.py",
-      "use": "@vercel/python"
-    },
-    {
-      "src": "frontend/package.json",
-      "use": "@vercel/static-build",
-      "config": {
-        "distDir": "frontend/dist"
-      }
-    }
-  ],
-  "routes": [
-    {
-      "src": "/api/(.*)",
-      "dest": "/api/$1"
-    },
-    {
-      "src": "/(.*)",
-      "dest": "/frontend/$1"
-    }
-  ],
-  "env": {
-    "PYTHON_VERSION": "3.9"
-  }
-}
-```
-
-### Step 2: Create API Endpoint
-
-Create `api/ask.py` to handle the `/api/ask` endpoint:
-
-```python
-from fastapi import FastAPI, Request
-from fastapi.responses import JSONResponse
-from pydantic import BaseModel
-import sys
-import os
-
-# Add parent directory to path to import src modules
-sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
-
-from src.rag import RAGSystem
-from src.escalation import EscalationEngine
-from src.llm_client import LLMClient
-from src.config import Settings
-
-# Initialize components (cached across invocations)
-settings = Settings()
-rag_system = RAGSystem(articles_dir="data/articles")
-llm_client = LLMClient(api_key=settings.google_api_key)
-escalation_engine = EscalationEngine(llm_client=llm_client)
-
-app = FastAPI()
-
-class QuestionRequest(BaseModel):
-    question: str
-
-@app.post("/api/ask")
-async def ask_question(request: QuestionRequest):
-    """Process customer question and return answer or escalation."""
-    try:
-        # Retrieve relevant chunks
-        chunks = rag_system.retrieve(request.question, top_k=settings.top_k_chunks)
-        
-        # Decide whether to answer or escalate
-        decision = escalation_engine.process_question(request.question, chunks)
-        
-        return JSONResponse(content={
-            "response_type": decision.action,
-            "message": decision.message,
-            "confidence_explanation": decision.confidence_explanation,
-            "sources": decision.sources
-        })
-    except Exception as e:
-        return JSONResponse(
-            status_code=500,
-            content={
-                "response_type": "escalation",
-                "message": "I'm experiencing technical difficulties. Let me connect you with a human agent.",
-                "confidence_explanation": f"Error: {str(e)}",
-                "sources": None
-            }
-        )
-
-# Vercel serverless function handler
-async def handler(request: Request):
-    return await app(request)
-```
-
-### Step 3: Update Frontend API URL
-
-Update `frontend/src/services/api.ts` to use relative API path:
-
-```typescript
-const API_URL = import.meta.env.VITE_API_URL || '/api';
-
-export async function askQuestion(question: string) {
-  const response = await fetch(`${API_URL}/ask`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({ question }),
-  });
-  
-  if (!response.ok) {
-    throw new Error('Failed to get response');
-  }
-  
-  return response.json();
+  "response_type": "answer",
+  "message": "To reset your password, go to the login page and click 'Forgot Password'. Enter your email address and you'll receive a reset link.",
+  "confidence_explanation": "High confidence - retrieved relevant content with similarity score 0.82",
+  "sources": ["getting-started.md"]
 }
 ```
 
-### Step 4: Deploy to Vercel
-
-#### Option A: Deploy via Vercel Dashboard (Recommended)
-
-1. **Create a Vercel Account**
-   - Go to [vercel.com](https://vercel.com)
-   - Sign up with your GitHub account
-
-2. **Import Project**
-   - Click "Add New..." → "Project"
-   - Import your GitHub repository
-   - Vercel will auto-detect the configuration
-
-3. **Configure Environment Variables**
-   
-   In the "Environment Variables" section, add:
-   
-   | Variable | Value | Notes |
-   |----------|-------|-------|
-   | `GOOGLE_API_KEY` | `AIza...` | **Required** - Your Gemini API key |
-   | `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Optional - defaults to this |
-   | `RELEVANCE_THRESHOLD` | `0.5` | Optional - adjust escalation sensitivity |
-   | `TOP_K_CHUNKS` | `3` | Optional - number of chunks to retrieve |
-   | `LLM_MODEL` | `gemini-1.5-flash` | Optional - use flash for speed |
-   | `LLM_TEMPERATURE` | `0.3` | Optional - lower = more deterministic |
-   
-   **Important**: Set these for all environments (Production, Preview, Development)
-
-4. **Deploy**
-   - Click "Deploy"
-   - Wait 2-3 minutes for build and deployment
-   - Monitor build logs for any errors
-
-5. **Verify Deployment**
-   - Visit your Vercel URL (e.g., `https://smart-escalation-api.vercel.app`)
-   - Test the chat interface
-   - Submit a test question
-   - Check browser console for any errors
-
-#### Option B: Deploy via Vercel CLI
-
-1. **Install Vercel CLI**
-   ```bash
-   npm install -g vercel
-   ```
-
-2. **Login to Vercel**
-   ```bash
-   vercel login
-   ```
-
-3. **Deploy**
-   ```bash
-   vercel
-   ```
-   
-   Follow the prompts:
-   - Set up and deploy? **Y**
-   - Which scope? Select your account
-   - Link to existing project? **N**
-   - Project name? `smart-escalation-api`
-   - In which directory is your code located? `./`
-
-4. **Add Environment Variables**
-   ```bash
-   vercel env add GOOGLE_API_KEY
-   vercel env add EMBEDDING_MODEL
-   vercel env add RELEVANCE_THRESHOLD
-   # ... add other variables
-   ```
-
-5. **Deploy to Production**
-   ```bash
-   vercel --prod
-   ```
-
-### Step 5: Configure Custom Domain (Optional)
-
-1. Go to your project in Vercel Dashboard
-2. Navigate to Settings → Domains
-3. Add your custom domain (e.g., `support.yourdomain.com`)
-4. Follow DNS configuration instructions:
-   - Add CNAME record pointing to `cname.vercel-dns.com`
-   - Or add A record pointing to Vercel's IP
-5. Wait for DNS propagation (5-30 minutes)
-6. Vercel automatically provisions SSL certificate
-
-### Deployment Troubleshooting
-
-#### Vercel Serverless Function Issues
-
-**Problem: "Module not found" in API functions**
-- **Solution**: Ensure `requirements.txt` is in project root
-- Verify Python version is 3.9+ in `vercel.json`
-- Check that `src/` modules are importable from `api/` directory
-- Add `sys.path.append()` in `api/ask.py` if needed
-
-**Problem: API function times out (10 second limit)**
-- **Solution**: Vercel serverless functions have 10s timeout on free tier
-- Optimize embedding model loading (cache between invocations)
-- Consider upgrading to Pro plan for 60s timeout
-- Use lighter embedding model if needed
-
-**Problem: "Function size exceeds limit"**
-- **Solution**: Vercel has 250MB limit for serverless functions
-- Reduce dependencies in `requirements.txt`
-- Use `.vercelignore` to exclude unnecessary files:
-  ```
-  tests/
-  .pytest_cache/
-  .hypothesis/
-  *.pyc
-  __pycache__/
-  ```
-
-**Problem: Cold start takes too long**
-- **Solution**: First request after inactivity loads embedding model (~2-3s)
-- This is normal for serverless architecture
-- Subsequent requests are fast (cached)
-- Consider keeping function warm with periodic pings
-
-**Problem: Environment variables not accessible**
-- **Solution**: Ensure variables are set in Vercel dashboard
-- Redeploy after adding new environment variables
-- Check variable names match exactly (case-sensitive)
-- Verify variables are set for correct environment (Production/Preview)
-
-#### Frontend Issues
-
-**Problem: Build fails with "Cannot find module"**
-- **Solution**: Ensure `frontend/package.json` includes all dependencies
-- Verify Node.js version (requires 18+)
-- Run `npm install` locally to test
-- Check `frontend/` is set as root directory in build settings
-
-**Problem: Frontend loads but API calls fail with 404**
-- **Solution**: Verify API routes are configured in `vercel.json`
-- Check that `api/ask.py` exists and is properly structured
-- Test API endpoint directly: `https://your-app.vercel.app/api/ask`
-- Ensure frontend is calling `/api/ask` (not `/ask`)
-
-**Problem: CORS errors in browser console**
-- **Solution**: With Vercel monorepo, CORS shouldn't be needed (same origin)
-- If using separate deployments, add CORS headers to API function
-- Verify frontend and API are on same domain
-
-**Problem: "Failed to fetch" errors**
-- **Solution**: Check browser console for detailed error
-- Verify API endpoint is accessible
-- Test with curl: `curl -X POST https://your-app.vercel.app/api/ask -H "Content-Type: application/json" -d '{"question":"test"}'`
-- Check network tab in browser dev tools
-
-#### Build and Deployment Issues
-
-**Problem: Build fails with Python errors**
-- **Solution**: Check build logs in Vercel dashboard
-- Verify all Python dependencies are in `requirements.txt`
-- Ensure Python version compatibility (3.9+)
-- Test locally: `pip install -r requirements.txt`
-
-**Problem: Build succeeds but deployment fails**
-- **Solution**: Check deployment logs for runtime errors
-- Verify `vercel.json` configuration is correct
-- Ensure all required files are committed to git
-- Check that `data/articles/` directory exists with help articles
-
-**Problem: Changes not reflecting after deployment**
-- **Solution**: Clear browser cache (Ctrl+Shift+R or Cmd+Shift+R)
-- Check that git changes are committed and pushed
-- Verify Vercel deployed the correct branch
-- Check deployment logs to confirm new version deployed
-
-**Problem: Preview deployments work but production fails**
-- **Solution**: Check environment variables are set for Production
-- Verify production branch is correct (usually `main`)
-- Compare environment variables between Preview and Production
-- Check for hardcoded URLs or environment-specific code
-
-#### Performance Issues
-
-**Problem: Slow response times (>10 seconds)**
-- **Solution**: Vercel free tier has 10s timeout for serverless functions
-- Check LLM API latency in function logs
-- Use `gemini-1.5-flash` instead of `gemini-1.5-pro`
-- Optimize embedding model loading
-- Consider upgrading to Pro plan for better performance
-
-**Problem: Out of memory errors**
-- **Solution**: Vercel serverless functions have 1GB memory limit (free tier)
-- Reduce `TOP_K_CHUNKS` to decrease memory usage
-- Use smaller embedding model
-- Optimize chunk storage and retrieval
-- Upgrade to Pro plan for 3GB memory
-
-**Problem: Rate limiting from Vercel**
-- **Solution**: Free tier has limits on function invocations
-- Monitor usage in Vercel dashboard
-- Implement client-side rate limiting
-- Upgrade to Pro plan for higher limits
-
-#### API Key and Authentication Issues
-
-**Problem: "Invalid API key" errors**
-- **Solution**: Verify `GOOGLE_API_KEY` is set correctly in Vercel
-- Check API key has proper permissions
-- Ensure quota is not exceeded
-- Test API key with direct Gemini API call
-
-**Problem: API key works locally but not on Vercel**
-- **Solution**: Ensure environment variable is set in Vercel dashboard
-- Redeploy after adding environment variables
-- Check variable name matches exactly (case-sensitive)
-- Verify no extra spaces or quotes in variable value
-
-#### Data and File Issues
-
-**Problem: Help articles not found**
-- **Solution**: Ensure `data/articles/` directory is committed to git
-- Verify file paths are correct (case-sensitive)
-- Check that markdown files exist and are readable
-- Test locally first: `ls data/articles/`
-
-**Problem: Vector store fails to build**
-- **Solution**: Check that all help articles are valid markdown
-- Verify embedding model downloads successfully
-- Check function logs for specific error messages
-- Ensure sufficient memory for vector store creation
-
-### Monitoring and Maintenance
-
-#### Vercel Analytics
-
-Enable Vercel Analytics to monitor:
-- Page views and user traffic
-- API function invocations
-- Response times and errors
-- Bandwidth usage
-
-**To enable:**
-1. Go to your project in Vercel Dashboard
-2. Navigate to Analytics tab
-3. Enable Web Analytics (free)
-4. Enable Speed Insights for performance monitoring
-
-#### Function Logs
-
-Monitor serverless function logs:
-1. Go to Vercel Dashboard → Your Project
-2. Click on Deployments → Select deployment
-3. View Function Logs for real-time monitoring
-4. Check for errors, warnings, and performance metrics
-
-**Key metrics to watch:**
-- Function execution time (should be <5s)
-- Error rate (should be <5%)
-- Cold start frequency
-- Memory usage
-
-#### Updating the Application
-
-**To update help articles:**
-1. Edit markdown files in `data/articles/`
-2. Commit and push to GitHub
-3. Vercel automatically redeploys
-4. Vector store rebuilds on next function invocation
-
-**To update code:**
-1. Make changes to Python or React code
-2. Test locally first
-3. Commit and push to GitHub
-4. Vercel automatically builds and deploys
-5. Monitor deployment logs for errors
-
-**To update dependencies:**
-1. Update `requirements.txt` (Python) or `package.json` (Node)
-2. Test locally: `pip install -r requirements.txt` or `npm install`
-3. Commit and push
-4. Vercel rebuilds with new dependencies
-
-### Cost Estimates
-
-**Vercel Free Tier Limits:**
-- 100GB bandwidth per month
-- 100 hours serverless function execution per month
-- 6,000 function invocations per day
-- 1GB function memory
-- 10s function timeout
-- Unlimited deployments
-
-**Expected Usage for Low-Medium Traffic:**
-- ~1-2s per API request
-- ~100-500 requests/day = 100-500s function time/day
-- ~3,000-15,000s function time/month = 0.8-4.2 hours/month
-- Well within free tier limits
-
-**When to Upgrade to Pro ($20/month):**
-- Need >100 hours function execution
-- Need >6,000 requests/day
-- Need 60s timeout (vs 10s)
-- Need 3GB memory (vs 1GB)
-- Need priority support
-
-**Additional Costs:**
-- **Google Gemini API**: $0-10/month (free tier: 15 req/min, 1500 req/day)
-- **Total**: $0-30/month depending on traffic
-
-### Security Best Practices
-
-1. **Environment Variables**
-   - Never commit API keys to git
-   - Use Vercel environment variables for all secrets
-   - Rotate API keys periodically
-
-2. **CORS Configuration**
-   - With Vercel monorepo, CORS is handled automatically (same origin)
-   - If using separate deployments, restrict CORS to specific domains
-
-3. **Input Validation**
-   - Already handled by Pydantic models
-   - Limit question length (max 500 characters)
-   - Sanitize user input
-
-4. **Rate Limiting**
-   - Implement client-side throttling
-   - Consider adding server-side rate limiting for production
-   - Monitor for abuse in Vercel logs
-
-5. **HTTPS**
-   - Vercel provides automatic HTTPS
-   - All traffic is encrypted by default
-   - SSL certificates auto-renewed
-
-6. **Monitoring**
-   - Enable Vercel Analytics
-   - Monitor function logs regularly
-   - Set up alerts for errors or unusual traffic
-
-### Advanced Configuration
-
-#### Custom Build Configuration
-
-Create `package.json` in project root for monorepo setup:
+### Example Response (Escalation)
 
 ```json
 {
-  "name": "smart-escalation-api",
-  "version": "1.0.0",
-  "scripts": {
-    "build": "cd frontend && npm install && npm run build"
-  },
-  "workspaces": [
-    "frontend"
-  ]
+  "response_type": "escalation",
+  "message": "I'm not certain I can answer this accurately. Let me connect you with a human support agent who can help.",
+  "confidence_explanation": "Low confidence - best retrieval score was 0.42",
+  "sources": null
 }
 ```
 
-#### Optimizing Cold Starts
-
-Add warming function to keep serverless functions active:
-
-```python
-# api/health.py
-def handler(request):
-    return {
-        "statusCode": 200,
-        "body": {"status": "healthy"}
-    }
-```
-
-Set up external monitoring (e.g., UptimeRobot) to ping `/api/health` every 5 minutes.
-
-#### Environment-Specific Configuration
-
-Use Vercel's environment system:
-- **Production**: Live environment with production API keys
-- **Preview**: Staging environment for testing (auto-created for PRs)
-- **Development**: Local development environment
-
-Set different values for each environment in Vercel dashboard.
-
-### Getting Help
-
-**Vercel Support:**
-- Documentation: [vercel.com/docs](https://vercel.com/docs)
-- Community: [github.com/vercel/vercel/discussions](https://github.com/vercel/vercel/discussions)
-- Support: Available for Pro plan users
-
-**Common Resources:**
-- [Vercel Python Runtime](https://vercel.com/docs/functions/serverless-functions/runtimes/python)
-- [Vercel Environment Variables](https://vercel.com/docs/projects/environment-variables)
-- [Vercel Monorepo Guide](https://vercel.com/docs/monorepos)
+## 📚 Interactive Documentation
 
-## Testing
+Visit `/docs` for interactive API documentation powered by Swagger UI.
 
-### Run Unit Tests
-```bash
-pytest tests/unit -v
-```
-
-### Run Property-Based Tests
-```bash
-pytest tests/property -v
-```
-
-### Run Integration Tests
-```bash
-pytest tests/integration -v
-```
+## 🏗️ Architecture
 
-### Run All Tests
-```bash
-pytest -v
-```
+- **Backend**: Python FastAPI
+- **Vector Store**: FAISS (in-memory) with sentence-transformers embeddings
+- **LLM**: Google Gemini API (gemini-1.5-flash)
+- **Deployment**: Hugging Face Spaces (Docker)
 
-## Help Articles
+## 📝 Help Articles
 
-The system includes 5 help articles about TaskFlow:
+The system includes help articles about TaskFlow (a fictional project management SaaS):
 
 1. **Getting Started** - TaskFlow basics, account setup, first project
 2. **Billing and Subscriptions** - Plans, payment methods, billing cycles
@@ -769,70 +95,12 @@ The system includes 5 help articles about TaskFlow:
 4. **Team Permissions** - Roles, access control, admin settings
 5. **Troubleshooting** - Common errors, login issues, performance tips
 
-Articles are stored as markdown files in `data/articles/`.
+## 🔗 Links
 
-## Development
+- **Frontend**: https://escalation-api-frontend.vercel.app/
+- **GitHub**: https://github.com/webflow-ai/Escalation-api
+- **API Docs**: https://webflow97-deployment-taskflow.hf.space/docs
 
-### Adding New Help Articles
-
-1. Create a new markdown file in `data/articles/`
-2. Restart the server to rebuild the vector store
-3. Test retrieval with relevant questions
-
-### Adjusting Escalation Threshold
-
-Edit `RELEVANCE_THRESHOLD` in `.env`:
-- Lower values (e.g., 0.3): Answer more questions, risk lower quality
-- Higher values (e.g., 0.7): Escalate more often, ensure high quality
-
-### Switching LLM Models
-
-**Gemini Flash (faster, cheaper):**
-```bash
-GOOGLE_API_KEY=AIza...
-LLM_MODEL=gemini-1.5-flash
-```
-
-**Gemini Pro (more capable):**
-```bash
-GOOGLE_API_KEY=AIza...
-LLM_MODEL=gemini-1.5-pro
-```
-
-## Troubleshooting
-
-### "Module not found" errors
-```bash
-# Ensure you're in the virtual environment
-source venv/bin/activate
-pip install -r requirements.txt
-```
-
-### "API key not found" errors
-```bash
-# Check .env file exists and contains valid API key
-cat .env
-```
-
-### Slow first request
-The first request loads the embedding model (~100MB), which takes 2-3 seconds. Subsequent requests are fast.
-
-### CORS errors in frontend
-Ensure `VITE_API_URL` in frontend `.env` matches your backend URL exactly (no trailing slash).
-
-## Performance
-
-- **Startup time**: 2-3 seconds (loading articles and embedding model)
-- **Response time**: 3-5 seconds (95th percentile)
-  - Embedding generation: ~100ms
-  - Vector search: ~50ms
-  - LLM API call: 2-4 seconds
-- **Memory usage**: ~150MB (embedding model + FAISS index)
-
-## License
+## 📄 License
 
 MIT
-
-## Support
-
-For questions or issues, please open a GitHub issue or contact the development team.

README_SPACES.md

@@ -0,0 +1,50 @@
+---
+title: Smart Escalation API
+emoji: 🤖
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+license: mit
+---
+
+# Smart Escalation API
+
+AI-powered L1 customer support system with intelligent escalation.
+
+## Features
+
+- RAG-based retrieval using sentence-transformers and FAISS
+- Intelligent escalation to human agents
+- Google Gemini LLM integration
+- FastAPI backend with automatic documentation
+
+## API Endpoints
+
+- `GET /` - API information
+- `GET /health` - Health check
+- `POST /ask` - Submit customer questions
+
+## Environment Variables
+
+Configure these in your Space settings:
+
+- `GOOGLE_API_KEY` - Your Google Gemini API key (required)
+- `ARTICLES_DIR` - Path to help articles (default: data/articles)
+- `EMBEDDING_MODEL` - Sentence transformer model (default: all-MiniLM-L6-v2)
+- `RELEVANCE_THRESHOLD` - Minimum similarity score (default: 0.5)
+- `TOP_K_CHUNKS` - Number of chunks to retrieve (default: 3)
+- `LLM_MODEL` - Gemini model name (default: gemini-1.5-flash)
+- `CORS_ORIGINS` - Allowed CORS origins
+
+## Usage
+
+```bash
+curl -X POST https://YOUR_USERNAME-escalation-api.hf.space/ask \
+  -H "Content-Type: application/json" \
+  -d '{"question": "How do I reset my password?"}'
+```
+
+## Documentation
+
+Visit `/docs` for interactive API documentation.

app.py

@@ -0,0 +1,13 @@
+"""
+Hugging Face Spaces entry point for Smart Escalation API.
+This file is required for Hugging Face Spaces deployment.
+"""
+
+import os
+import uvicorn
+from src.main import app
+
+if __name__ == "__main__":
+    # Hugging Face Spaces uses port 7860 by default
+    port = int(os.getenv("PORT", 7860))
+    uvicorn.run(app, host="0.0.0.0", port=port)