Deploy to Vercel: Add serverless functions, frontend, and deployment docs

.env.example

@@ -1,6 +1,6 @@
 # LLM API Configuration
 # Google Gemini API
-GOOGLE_API_KEY=AIzaSyBEcuYN5-xzT_kU44WL8IvQfIPIW6CaKxs
+GOOGLE_API_KEY=AIzaSyD18774cyKeznZP409LIqDFMasNgqPxfLw
 
 # Embedding Model Configuration
 EMBEDDING_MODEL=all-MiniLM-L6-v2

.gitignore

@@ -52,3 +52,6 @@ frontend/node_modules/
 frontend/dist/
 frontend/.env
 frontend/.env.local
+
+# Kiro
+.kiro/

.kiro/specs/smart-escalation-api/.config.kiro

@@ -1 +0,0 @@
-{"specId": "90ea9d74-8680-4a15-8227-fea1dfad3026", "workflowType": "requirements-first", "specType": "feature"}

.kiro/specs/smart-escalation-api/design.md

@@ -1,750 +0,0 @@
-# Design Document: Smart Escalation API
-
-## Overview
-
-The Smart Escalation API is a lightweight RAG-based customer support system designed for 2-3.5 hour implementation. The system answers customer questions about TaskFlow using retrieval-augmented generation over 5 help articles, with intelligent escalation to human agents when confidence is low.
-
-### Core Design Principles
-
-1. **Simplicity First**: In-memory vector store, single API endpoint, minimal dependencies
-2. **Escalation Over Uncertainty**: Conservative approach prioritizes accuracy over coverage
-3. **Clear Separation**: Distinct modules for retrieval, generation, and escalation logic
-4. **Free Hosting Compatible**: No external databases, deployable to Render/Railway/Vercel
-
-### Key Components
-
-- **FastAPI Backend**: Single POST endpoint handling question processing
-- **RAG System**: In-memory FAISS vector store with sentence-transformers embeddings
-- **Escalation Engine**: Rule-based decision logic using relevance scores and LLM confidence signals
-- **React Chat UI**: Minimal interface for customer interaction
-
-## Architecture
-
-### System Architecture
-
-```mermaid
-graph TB
-    Customer[Customer] --> ChatUI[React Chat UI]
-    ChatUI --> API[FastAPI Endpoint]
-    API --> Orchestrator[Request Orchestrator]
-    Orchestrator --> RAG[RAG System]
-    RAG --> Embedder[Embedding Model]
-    RAG --> VectorStore[FAISS Vector Store]
-    Orchestrator --> Escalation[Escalation Engine]
-    Escalation --> LLM[LLM API]
-    Escalation --> Response[Response Builder]
-    Response --> API
-    
-    HelpArticles[(5 Help Articles)] -.->|Load on startup| VectorStore
-```
-
-### Request Flow
-
-1. **Question Submission**: Customer submits question via Chat UI
-2. **Embedding Generation**: Question is embedded using sentence-transformers
-3. **Retrieval**: Top-k chunks retrieved from FAISS vector store
-4. **Escalation Decision**: Engine evaluates relevance scores and context quality
-5. **Response Generation**: 
-   - If confident: LLM generates grounded answer
-   - If uncertain: Return escalation message
-6. **Response Delivery**: JSON response with answer/escalation + confidence explanation
-
-### Technology Stack
-
-| Component | Technology | Rationale |
-|-----------|-----------|-----------|
-| Backend Framework | FastAPI | Fast, async, automatic OpenAPI docs |
-| Embeddings | sentence-transformers (all-MiniLM-L6-v2) | Lightweight, no API costs, good quality |
-| Vector Store | FAISS (in-memory) | Fast similarity search, no external DB |
-| LLM | Google Gemini API | Free tier available, high-quality generation |
-| Frontend | React + Vite | Fast setup, minimal boilerplate |
-| Deployment | Render/Railway | Free tier, easy Python deployment |
-
-## Components and Interfaces
-
-### 1. FastAPI Application (`main.py`)
-
-**Responsibilities**:
-- Expose POST `/ask` endpoint
-- Handle CORS configuration
-- Coordinate request processing
-- Return structured JSON responses
-
-**Interface**:
-```python
-@app.post("/ask")
-async def ask_question(request: QuestionRequest) -> QuestionResponse:
-    """
-    Process customer question and return answer or escalation.
-    
-    Args:
-        request: QuestionRequest with 'question' field
-        
-    Returns:
-        QuestionResponse with response_type, message, confidence_explanation
-    """
-```
-
-**Models**:
-```python
-class QuestionRequest(BaseModel):
-    question: str
-
-class QuestionResponse(BaseModel):
-    response_type: Literal["answer", "escalation"]
-    message: str
-    confidence_explanation: str
-    sources: Optional[List[str]] = None
-```
-
-### 2. RAG System (`rag.py`)
-
-**Responsibilities**:
-- Load and chunk help articles on startup
-- Generate embeddings for chunks and questions
-- Perform similarity search
-- Return top-k relevant chunks with scores
-
-**Interface**:
-```python
-class RAGSystem:
-    def __init__(self, articles_dir: str, chunk_size: int = 500, chunk_overlap: int = 50):
-        """Initialize RAG system with help articles."""
-        
-    def retrieve(self, question: str, top_k: int = 3) -> List[RetrievedChunk]:
-        """
-        Retrieve most relevant chunks for question.
-        
-        Args:
-            question: Customer question
-            top_k: Number of chunks to retrieve
-            
-        Returns:
-            List of RetrievedChunk with content, score, source
-        """
-
-class RetrievedChunk:
-    content: str
-    score: float  # Cosine similarity score
-    source: str   # Help article filename
-```
-
-**Chunking Strategy**:
-- Fixed-size chunks with overlap (500 chars, 50 char overlap)
-- Preserves sentence boundaries where possible
-- Metadata tracks source article for each chunk
-
-### 3. Escalation Engine (`escalation.py`)
-
-**Responsibilities**:
-- Evaluate retrieval quality (relevance scores)
-- Decide whether to answer or escalate
-- Generate confidence explanations
-- Coordinate LLM calls when answering
-
-**Interface**:
-```python
-class EscalationEngine:
-    def __init__(self, llm_client: LLMClient, relevance_threshold: float = 0.5):
-        """Initialize escalation engine with LLM client and thresholds."""
-        
-    def process_question(
-        self, 
-        question: str, 
-        retrieved_chunks: List[RetrievedChunk]
-    ) -> EscalationDecision:
-        """
-        Decide whether to answer or escalate.
-        
-        Args:
-            question: Customer question
-            retrieved_chunks: Retrieved context from RAG
-            
-        Returns:
-            EscalationDecision with action, message, explanation
-        """
-
-class EscalationDecision:
-    action: Literal["answer", "escalate"]
-    message: str
-    confidence_explanation: str
-    sources: Optional[List[str]] = None
-```
-
-**Decision Logic**:
-```python
-def should_escalate(chunks: List[RetrievedChunk]) -> bool:
-    """
-    Escalate if:
-    1. Best chunk score < 0.5 (low relevance)
-    2. All chunks from same article (narrow coverage)
-    3. LLM returns uncertainty signal in response
-    """
-```
-
-### 4. LLM Client (`llm_client.py`)
-
-**Responsibilities**:
-- Abstract LLM API calls (Google Gemini)
-- Format prompts with retrieved context
-- Parse LLM responses
-- Handle API errors gracefully
-
-**Interface**:
-```python
-class LLMClient:
-    def generate_answer(
-        self, 
-        question: str, 
-        context_chunks: List[str]
-    ) -> LLMResponse:
-        """
-        Generate answer using LLM with retrieved context.
-        
-        Args:
-            question: Customer question
-            context_chunks: Retrieved help article chunks
-            
-        Returns:
-            LLMResponse with answer text and confidence signal
-        """
-
-class LLMResponse:
-    answer: str
-    uncertain: bool  # True if LLM signals uncertainty
-```
-
-**Prompt Template**:
-```
-You are a friendly customer support agent for TaskFlow, a project management SaaS.
-
-Answer the customer's question using ONLY the information provided in the help articles below.
-
-IMPORTANT RULES:
-- Use a friendly, helpful tone
-- Ground your answer in the provided context
-- If the context doesn't contain enough information to answer confidently, respond with: "I'm not certain about this. Let me connect you with a human agent."
-- Do not make up or infer information not present in the context
-
-HELP ARTICLE CONTEXT:
-{context_chunks}
-
-CUSTOMER QUESTION:
-{question}
-
-YOUR ANSWER:
-```
-
-### 5. React Chat UI (`frontend/`)
-
-**Responsibilities**:
-- Render chat interface
-- Submit questions to API
-- Display answers and escalations
-- Show confidence explanations
-
-**Key Components**:
-```typescript
-interface Message {
-  role: 'user' | 'assistant';
-  content: string;
-  confidenceExplanation?: string;
-  responseType?: 'answer' | 'escalation';
-}
-
-function ChatInterface() {
-  const [messages, setMessages] = useState<Message[]>([]);
-  const [input, setInput] = useState('');
-  const [loading, setLoading] = useState(false);
-  
-  const handleSubmit = async () => {
-    // POST to /ask endpoint
-    // Update messages with response
-  };
-}
-```
-
-## Data Models
-
-### Help Article Structure
-
-```python
-class HelpArticle:
-    """Represents a single help article."""
-    filename: str
-    title: str
-    content: str
-    chunks: List[str]  # Generated during preprocessing
-```
-
-**Article Files** (stored as markdown in `data/articles/`):
-1. `getting-started.md` - TaskFlow basics, account setup, first project
-2. `billing.md` - Subscription plans, payment methods, billing cycles
-3. `integrations.md` - Slack, GitHub, Jira integrations
-4. `permissions.md` - Team roles, access control, admin settings
-5. `troubleshooting.md` - Common errors, login issues, performance tips
-
-### Vector Store Schema
-
-```python
-# FAISS index stores:
-# - embeddings: np.ndarray of shape (n_chunks, embedding_dim)
-# - metadata: List[ChunkMetadata]
-
-class ChunkMetadata:
-    chunk_id: int
-    source_article: str
-    chunk_text: str
-    start_char: int  # Position in original article
-```
-
-### API Request/Response Models
-
-**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 depending on the permissions you want to grant.",
-  "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
-}
-```
-
-## Correctness Properties
-
-*A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.*
-
-
-### Property 1: Invalid Request Handling
-
-*For any* malformed or invalid request (missing required fields, wrong data types, malformed JSON), the API SHALL return a 400 status code with an error message.
-
-**Validates: Requirements 1.4**
-
-### Property 2: Top-K Retrieval Behavior
-
-*For any* customer question and any positive integer k, the RAG system SHALL return exactly k chunks (or fewer if total chunks < k) ordered by descending relevance score.
-
-**Validates: Requirements 2.4**
-
-### Property 3: Chunking Semantic Coherence
-
-*For any* help article text, the chunking strategy SHALL NOT split words mid-character, SHALL maintain the specified overlap between consecutive chunks, and SHALL preserve complete tokens.
-
-**Validates: Requirements 2.6**
-
-### Property 4: Escalation on Low Confidence
-
-*For any* question where retrieved chunks have maximum relevance score below the threshold OR the LLM signals uncertainty, the escalation logic SHALL return an escalation response rather than an answer.
-
-**Validates: Requirements 3.5, 4.2, 4.4**
-
-### Property 5: Response Schema Consistency
-
-*For any* valid customer question, the API response SHALL conform to the defined JSON schema with required fields (response_type, message, confidence_explanation) having correct types, and response_type SHALL be either "answer" or "escalation".
-
-**Validates: Requirements 5.1, 6.1, 6.2, 6.3, 6.4, 6.5**
-
-### Property 6: Prompt Construction Completeness
-
-*For any* customer question and any set of retrieved chunks, the constructed LLM prompt SHALL include both the complete question text and all retrieved chunk contents.
-
-**Validates: Requirements 9.4, 9.5**
-
-## Error Handling
-
-### API-Level Errors
-
-**Invalid Request Handling**:
-- Missing `question` field → 400 with message "Missing required field: question"
-- Empty question string → 400 with message "Question cannot be empty"
-- Malformed JSON → 400 with message "Invalid JSON format"
-- Request timeout (>10s) → 504 with message "Request timeout"
-
-**LLM API Errors**:
-- API key invalid → 500 with message "Configuration error"
-- Rate limit exceeded → 429 with message "Service temporarily unavailable, please try again"
-- LLM API timeout → Fallback to escalation with explanation "Unable to generate response, connecting you with human agent"
-- Network errors → Retry once, then escalate
-
-**Embedding Errors**:
-- Embedding generation fails → Log error, return 500 with message "Unable to process question"
-- Model not loaded → Fail fast on startup with clear error message
-
-### Graceful Degradation
-
-**Retrieval Failures**:
-- No chunks retrieved (empty vector store) → Automatic escalation
-- All relevance scores = 0 → Automatic escalation
-- Vector store corruption → Fail fast with error, require restart
-
-**Response Generation**:
-- LLM returns empty response → Treat as uncertainty signal, escalate
-- LLM response exceeds length limit → Truncate with "..." and include full response in logs
-- Confidence explanation generation fails → Use default: "Unable to generate explanation"
-
-### Error Logging
-
-All errors SHALL be logged with:
-- Timestamp
-- Error type and message
-- Request context (question, retrieved chunks if available)
-- Stack trace for 500-level errors
-
-## Testing Strategy
-
-### Overview
-
-The Smart Escalation API requires a **hybrid testing approach** combining unit tests, integration tests, and property-based tests. Given the system's reliance on external services (LLM APIs, embedding models) and non-deterministic behavior, property-based testing is appropriate only for the pure logic components.
-
-### Unit Tests
-
-**Focus Areas**:
-- Chunking logic (text splitting, overlap calculation)
-- Escalation decision rules (threshold comparisons)
-- Response formatting (JSON construction)
-- Prompt template construction
-- Error handling paths
-
-**Example Test Cases**:
-```python
-def test_chunking_preserves_sentences():
-    """Verify chunks don't split mid-sentence."""
-    article = "First sentence. Second sentence. Third sentence."
-    chunks = chunk_text(article, chunk_size=20, overlap=5)
-    for chunk in chunks:
-        assert not chunk.endswith(" ")  # No trailing spaces
-        assert chunk[0].isupper() or chunk[0] in "0123456789"  # Starts properly
-
-def test_escalation_on_low_score():
-    """Verify escalation when relevance below threshold."""
-    chunks = [RetrievedChunk(content="...", score=0.3, source="test.md")]
-    decision = escalation_engine.process_question("test", chunks)
-    assert decision.action == "escalate"
-
-def test_response_schema():
-    """Verify response has required fields."""
-    response = api_client.post("/ask", json={"question": "test"})
-    assert "response_type" in response.json()
-    assert "message" in response.json()
-    assert "confidence_explanation" in response.json()
-```
-
-### Property-Based Tests
-
-**Testing Library**: Hypothesis (Python)
-
-**Configuration**: Minimum 100 iterations per property test
-
-**Property Test Cases**:
-
-```python
-from hypothesis import given, strategies as st
-
-@given(st.text(min_size=1, max_size=5000))
-def test_property_chunking_no_word_splits(article_text):
-    """
-    Property 3: Chunking Semantic Coherence
-    For any article text, chunks should not split words.
-    
-    Feature: smart-escalation-api, Property 3: Chunking preserves semantic coherence
-    """
-    chunks = chunk_text(article_text, chunk_size=500, overlap=50)
-    for chunk in chunks:
-        # No chunks should end with partial words (non-whitespace followed by cut)
-        if len(chunk) == 500:  # Full-size chunk
-            assert chunk[-1].isspace() or chunk[-1] in ".,!?;:"
-
-@given(st.integers(min_value=1, max_value=10))
-def test_property_topk_retrieval(k):
-    """
-    Property 2: Top-K Retrieval Behavior
-    For any k value, retrieval returns exactly k chunks (or fewer if not enough chunks exist).
-    
-    Feature: smart-escalation-api, Property 2: Top-k retrieval returns exactly k chunks
-    """
-    question = "How do I reset my password?"
-    chunks = rag_system.retrieve(question, top_k=k)
-    assert len(chunks) <= k
-    # Verify descending order
-    scores = [c.score for c in chunks]
-    assert scores == sorted(scores, reverse=True)
-
-@given(st.floats(min_value=0.0, max_value=0.49))
-def test_property_escalation_on_low_confidence(max_score):
-    """
-    Property 4: Escalation on Low Confidence
-    For any retrieval with max score below threshold (0.5), escalation should occur.
-    
-    Feature: smart-escalation-api, Property 4: Escalation triggered by low confidence
-    """
-    chunks = [
-        RetrievedChunk(content="test", score=max_score, source="test.md")
-    ]
-    decision = escalation_engine.process_question("test question", chunks)
-    assert decision.action == "escalate"
-
-@given(st.text(min_size=1, max_size=500))
-def test_property_response_schema(question):
-    """
-    Property 5: Response Schema Consistency
-    For any valid question, response conforms to schema.
-    
-    Feature: smart-escalation-api, Property 5: Response schema consistency
-    """
-    response = api_client.post("/ask", json={"question": question})
-    data = response.json()
-    assert "response_type" in data
-    assert data["response_type"] in ["answer", "escalation"]
-    assert "message" in data
-    assert isinstance(data["message"], str)
-    assert "confidence_explanation" in data
-    assert isinstance(data["confidence_explanation"], str)
-
-@given(
-    st.text(min_size=1, max_size=200),
-    st.lists(st.text(min_size=10, max_size=500), min_size=1, max_size=5)
-)
-def test_property_prompt_construction(question, chunks):
-    """
-    Property 6: Prompt Construction Completeness
-    For any question and chunks, prompt includes both.
-    
-    Feature: smart-escalation-api, Property 6: Prompt includes context and question
-    """
-    prompt = llm_client.build_prompt(question, chunks)
-    assert question in prompt
-    for chunk in chunks:
-        assert chunk in prompt
-```
-
-### Integration Tests
-
-**Focus Areas**:
-- End-to-end API flow (question → response)
-- LLM API integration (with mocked responses)
-- Embedding model integration
-- CORS configuration
-- Error handling with external services
-
-**Example Test Cases**:
-```python
-def test_integration_answer_flow():
-    """Test full flow for answerable question."""
-    response = api_client.post("/ask", json={
-        "question": "How do I create a new project?"
-    })
-    assert response.status_code == 200
-    data = response.json()
-    assert data["response_type"] in ["answer", "escalation"]
-
-def test_integration_cors_headers():
-    """Verify CORS headers present."""
-    response = api_client.options("/ask")
-    assert "Access-Control-Allow-Origin" in response.headers
-
-@mock.patch('llm_client.openai_client')
-def test_integration_llm_timeout(mock_llm):
-    """Verify graceful handling of LLM timeout."""
-    mock_llm.side_effect = TimeoutError()
-    response = api_client.post("/ask", json={"question": "test"})
-    data = response.json()
-    assert data["response_type"] == "escalation"
-```
-
-### Frontend Tests
-
-**Testing Library**: React Testing Library + Vitest
-
-**Focus Areas**:
-- Component rendering
-- User interactions (input, submit)
-- API response display
-- Loading states
-
-**Example Test Cases**:
-```typescript
-test('displays user question in chat history', async () => {
-  render(<ChatInterface />);
-  const input = screen.getByRole('textbox');
-  const submitButton = screen.getByRole('button', { name: /send/i });
-  
-  await userEvent.type(input, 'How do I reset my password?');
-  await userEvent.click(submitButton);
-  
-  expect(screen.getByText('How do I reset my password?')).toBeInTheDocument();
-});
-
-test('shows loading state during API call', async () => {
-  render(<ChatInterface />);
-  const input = screen.getByRole('textbox');
-  const submitButton = screen.getByRole('button', { name: /send/i });
-  
-  await userEvent.type(input, 'test question');
-  await userEvent.click(submitButton);
-  
-  expect(screen.getByText(/loading/i)).toBeInTheDocument();
-});
-```
-
-### Test Coverage Goals
-
-- **Unit Tests**: 80%+ coverage of pure logic functions
-- **Property Tests**: All 6 correctness properties implemented
-- **Integration Tests**: All API endpoints and error paths
-- **Frontend Tests**: All user interactions and state changes
-
-### Manual Testing Checklist
-
-- [ ] Deploy to Render/Railway and verify functionality
-- [ ] Test with various question types (in-scope, out-of-scope, edge cases)
-- [ ] Verify LLM responses have appropriate tone
-- [ ] Check confidence explanations are helpful
-- [ ] Test error scenarios (invalid API key, network issues)
-- [ ] Verify UI is functional on desktop and mobile browsers
-
-## Implementation Notes
-
-### Development Phases
-
-**Phase 1: Core RAG System (1 hour)**
-- Implement article loading and chunking
-- Set up FAISS vector store
-- Implement embedding generation
-- Test retrieval with sample questions
-
-**Phase 2: API and Escalation Logic (1 hour)**
-- Create FastAPI application
-- Implement escalation engine
-- Integrate LLM client
-- Add error handling
-
-**Phase 3: Frontend (0.5-1 hour)**
-- Create React chat interface
-- Implement API integration
-- Add loading states
-- Basic styling
-
-**Phase 4: Testing and Deployment (0.5 hour)**
-- Write unit and property tests
-- Deploy to hosting platform
-- End-to-end testing
-
-### Configuration Management
-
-**Environment Variables**:
-```bash
-# Required
-GOOGLE_API_KEY=AIza...
-EMBEDDING_MODEL=all-MiniLM-L6-v2
-RELEVANCE_THRESHOLD=0.5
-
-# Optional
-TOP_K_CHUNKS=3
-CHUNK_SIZE=500
-CHUNK_OVERLAP=50
-LLM_MODEL=gemini-1.5-flash
-LLM_TEMPERATURE=0.3
-```
-
-**Configuration File** (`config.py`):
-```python
-from pydantic_settings import BaseSettings
-
-class Settings(BaseSettings):
-    google_api_key: str
-    embedding_model: str = "all-MiniLM-L6-v2"
-    relevance_threshold: float = 0.5
-    top_k_chunks: int = 3
-    chunk_size: int = 500
-    chunk_overlap: int = 50
-    llm_model: str = "gemini-1.5-flash"
-    llm_temperature: float = 0.3
-    
-    class Config:
-        env_file = ".env"
-```
-
-### Performance Considerations
-
-**Startup Time**:
-- Load articles and build vector store on startup (~2-3 seconds)
-- Cache embeddings to avoid recomputation
-- Use lazy loading for embedding model
-
-**Response Time**:
-- Target: <5 seconds for 95th percentile
-- Embedding generation: ~100ms
-- Vector search: ~50ms
-- LLM API call: 2-4 seconds (main bottleneck)
-- Total: ~3-5 seconds
-
-**Memory Usage**:
-- FAISS index: ~10-20 MB for 5 articles
-- Embedding model: ~100 MB
-- Total: ~150 MB (well within free tier limits)
-
-### Security Considerations
-
-**API Key Management**:
-- Store LLM API keys in environment variables
-- Never commit keys to version control
-- Use `.env` file for local development
-- Use platform secrets for deployment
-
-**Input Validation**:
-- Sanitize user input to prevent injection attacks
-- Limit question length (max 500 characters)
-- Rate limiting (if needed): 10 requests/minute per IP
-
-**CORS Configuration**:
-- Allow only specific frontend origins in production
-- Use wildcard (`*`) only for development
-
-### Deployment Instructions
-
-**Render Deployment**:
-1. Create new Web Service
-2. Connect GitHub repository
-3. Set build command: `pip install -r requirements.txt`
-4. Set start command: `uvicorn main:app --host 0.0.0.0 --port $PORT`
-5. Add environment variables (API keys)
-6. Deploy
-
-**Frontend Deployment** (Vercel):
-1. Create new project
-2. Connect GitHub repository
-3. Set framework preset: React
-4. Set build command: `npm run build`
-5. Set output directory: `dist`
-6. Add environment variable: `VITE_API_URL=<backend-url>`
-7. Deploy
-
-### Future Enhancements
-
-**Potential Improvements** (out of scope for initial implementation):
-- Conversation history tracking
-- Multi-turn dialogue support
-- Feedback collection (thumbs up/down)
-- Analytics dashboard for escalation rates
-- A/B testing different escalation thresholds
-- Persistent vector store (PostgreSQL with pgvector)
-- Streaming LLM responses
-- Multi-language support

.kiro/specs/smart-escalation-api/requirements.md

@@ -1,144 +0,0 @@
-# Requirements Document
-
-## Introduction
-
-The Smart Escalation API is 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 5 help articles to ground responses and includes a minimal React chat UI for interaction.
-
-## Glossary
-
-- **API**: The FastAPI backend service that processes customer questions
-- **RAG_System**: The Retrieval-Augmented Generation system that searches help articles using embeddings and vector store
-- **LLM**: The Large Language Model (Claude, OpenAI, etc.) that generates responses
-- **Escalation_Logic**: The decision-making component that determines whether to answer or escalate
-- **Chat_UI**: The React-based frontend interface for customer interaction
-- **Help_Article**: One of 5 TaskFlow documentation articles stored in the knowledge base
-- **Confidence_Indicator**: An explanation of why the system answered or escalated
-- **Vector_Store**: In-memory storage for document embeddings used in retrieval
-- **Chunk**: A segment of a Help_Article used for embedding and retrieval
-
-## Requirements
-
-### Requirement 1: API Endpoint
-
-**User Story:** As a customer, I want to submit questions through an API endpoint, so that I can receive support answers or escalation messages.
-
-#### Acceptance Criteria
-
-1. THE API SHALL expose a single POST endpoint that accepts customer questions
-2. WHEN a customer question is received, THE API SHALL return a JSON response within 10 seconds
-3. THE API SHALL include CORS headers to allow requests from the Chat_UI
-4. WHEN the API receives an invalid request, THE API SHALL return a 400 status code with an error message
-5. THE API SHALL be deployable to free hosting platforms (Render, Railway, or Vercel)
-
-### Requirement 2: RAG-Based Retrieval
-
-**User Story:** As the system, I want to retrieve relevant help article content, so that I can ground responses in accurate documentation.
-
-#### Acceptance Criteria
-
-1. THE RAG_System SHALL load 5 Help_Articles about TaskFlow on startup
-2. THE RAG_System SHALL split Help_Articles into Chunks for embedding
-3. WHEN a customer question is received, THE RAG_System SHALL generate an embedding for the question
-4. THE RAG_System SHALL retrieve the top-k most relevant Chunks from the Vector_Store
-5. THE RAG_System SHALL use an in-memory Vector_Store (no external database required)
-6. FOR ALL Help_Articles, the chunking strategy SHALL preserve semantic coherence
-
-### Requirement 3: Answer Generation
-
-**User Story:** As a customer, I want accurate answers grounded in help articles, so that I can resolve my issues quickly.
-
-#### Acceptance Criteria
-
-1. WHEN the Escalation_Logic determines confidence is sufficient, THE LLM SHALL generate an answer using retrieved Chunks
-2. THE LLM SHALL use a friendly customer support tone in all responses
-3. THE LLM SHALL ground all answers in the retrieved Help_Article content
-4. THE LLM SHALL NOT hallucinate information not present in the Help_Articles
-5. WHEN no relevant information is found, THE Escalation_Logic SHALL trigger escalation
-
-### Requirement 4: Escalation Decision
-
-**User Story:** As a support manager, I want the system to escalate uncertain questions to human agents, so that customers receive accurate help.
-
-#### Acceptance Criteria
-
-1. THE Escalation_Logic SHALL decide whether to answer or escalate for each customer question
-2. WHEN confidence is low, THE Escalation_Logic SHALL return an escalation message
-3. WHEN the question is outside the scope of Help_Articles, THE Escalation_Logic SHALL escalate
-4. WHEN retrieved Chunks have low relevance scores, THE Escalation_Logic SHALL escalate
-5. THE Escalation_Logic SHALL prioritize escalation over providing uncertain answers
-
-### Requirement 5: Confidence Indicator
-
-**User Story:** As a support manager, I want to understand why the system answered or escalated, so that I can evaluate system performance.
-
-#### Acceptance Criteria
-
-1. THE API SHALL include a Confidence_Indicator in every response
-2. THE Confidence_Indicator SHALL explain the reasoning behind the answer or escalation decision
-3. WHEN answering, THE Confidence_Indicator SHALL reference the relevance of retrieved content
-4. WHEN escalating, THE Confidence_Indicator SHALL explain why confidence was insufficient
-5. THE Confidence_Indicator SHALL be human-readable and concise
-
-### Requirement 6: Response Format
-
-**User Story:** As a frontend developer, I want a consistent JSON response format, so that I can reliably display results in the Chat_UI.
-
-#### Acceptance Criteria
-
-1. THE API SHALL return responses with a consistent JSON schema
-2. THE API SHALL include a response_type field indicating "answer" or "escalation"
-3. THE API SHALL include a message field containing the answer or escalation text
-4. THE API SHALL include a confidence_explanation field with the Confidence_Indicator
-5. WHEN answering, THE API SHALL optionally include source references to Help_Articles
-
-### Requirement 7: Chat UI
-
-**User Story:** As a customer, I want a simple chat interface, so that I can interact with the support system.
-
-#### Acceptance Criteria
-
-1. THE Chat_UI SHALL provide a text input field for customer questions
-2. WHEN a customer submits a question, THE Chat_UI SHALL display the question in the chat history
-3. THE Chat_UI SHALL display API responses (answers or escalations) in the chat history
-4. THE Chat_UI SHALL indicate loading state while waiting for API responses
-5. THE Chat_UI SHALL be functional and deployable (visual polish is not required)
-6. THE Chat_UI SHALL display the Confidence_Indicator for each response
-
-### Requirement 8: Help Articles Knowledge Base
-
-**User Story:** As the system, I want to load TaskFlow help articles, so that I can answer customer questions accurately.
-
-#### Acceptance Criteria
-
-1. THE RAG_System SHALL load 5 Help_Articles covering TaskFlow topics
-2. THE Help_Articles SHALL include "Getting Started with TaskFlow"
-3. THE Help_Articles SHALL include "Billing and Subscription Plans"
-4. THE Help_Articles SHALL include "Integrations"
-5. THE Help_Articles SHALL include "Managing Team Permissions"
-6. THE Help_Articles SHALL include "Troubleshooting Common Issues"
-7. THE Help_Articles SHALL be stored in a format accessible to the RAG_System
-
-### Requirement 9: Prompt Design
-
-**User Story:** As a developer, I want well-designed LLM prompts, so that the system generates high-quality responses with appropriate guardrails.
-
-#### Acceptance Criteria
-
-1. THE LLM SHALL receive instructions to use a friendly customer support tone
-2. THE LLM SHALL receive instructions to ground answers only in provided context
-3. THE LLM SHALL receive instructions to avoid hallucination
-4. THE LLM SHALL receive the retrieved Chunks as context
-5. THE LLM SHALL receive the customer question
-6. THE LLM SHALL be instructed on when to indicate uncertainty
-
-### Requirement 10: Code Quality
-
-**User Story:** As a developer, I want clean and maintainable code, so that the system is easy to understand and extend.
-
-#### Acceptance Criteria
-
-1. THE API SHALL use clear function and variable names
-2. THE API SHALL include comments explaining complex logic
-3. THE API SHALL separate concerns (retrieval, generation, escalation logic)
-4. THE API SHALL include a README with setup and deployment instructions
-5. THE API SHALL use type hints (Python) or TypeScript types for clarity

.kiro/specs/smart-escalation-api/tasks.md

@@ -1,242 +0,0 @@
-# Implementation Plan: Smart Escalation API
-
-## Overview
-
-This implementation plan follows a 4-phase approach to build a RAG-based customer support system with intelligent escalation. The system uses FastAPI, FAISS vector store, sentence-transformers embeddings, and an LLM API to answer customer questions about TaskFlow or escalate to human agents when uncertain.
-
-**Total Estimated Time**: 2-3.5 hours
-
-**Key Focus**: Escalation logic is the most critical component. Property-based testing ensures correctness of core behaviors.
-
-## Tasks
-
-### Phase 1: Core RAG System (1 hour)
-
-- [x] 1. Set up project structure and dependencies
-  - Create project directory structure (`data/articles/`, `src/`, `tests/`)
-  - Create `requirements.txt` with FastAPI, FAISS, sentence-transformers, pytest, hypothesis
-  - Create `.env.example` file with required environment variables
-  - Create `README.md` with setup instructions
-  - _Requirements: 10.4_
-
-- [x] 2. Create help article knowledge base
-  - [x] 2.1 Write 5 TaskFlow help articles as markdown files
-    - Create `data/articles/getting-started.md` (TaskFlow basics, account setup, first project)
-    - Create `data/articles/billing.md` (subscription plans, payment methods, billing cycles)
-    - Create `data/articles/integrations.md` (Slack, GitHub, Jira integrations)
-    - Create `data/articles/permissions.md` (team roles, access control, admin settings)
-    - Create `data/articles/troubleshooting.md` (common errors, login issues, performance tips)
-    - _Requirements: 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7_
-
-- [x] 3. Implement article chunking logic
-  - [x] 3.1 Create `src/chunking.py` with text chunking function
-    - Implement fixed-size chunking with overlap (500 chars, 50 char overlap)
-    - Preserve sentence boundaries where possible
-    - Track source article metadata for each chunk
-    - _Requirements: 2.2, 2.6_
-  
-  - [x] 3.2 Write property test for chunking semantic coherence
-    - **Property 3: Chunking Semantic Coherence**
-    - **Validates: Requirements 2.6**
-    - Test that chunks don't split words mid-character
-    - Test that overlap is maintained between consecutive chunks
-    - Use Hypothesis to generate random article texts
-
-- [x] 4. Implement RAG system with FAISS vector store
-  - [x] 4.1 Create `src/rag.py` with RAGSystem class
-    - Implement article loading from `data/articles/` directory
-    - Initialize sentence-transformers embedding model (all-MiniLM-L6-v2)
-    - Generate embeddings for all chunks
-    - Build in-memory FAISS index
-    - Implement `retrieve()` method for similarity search
-    - _Requirements: 2.1, 2.3, 2.4, 2.5_
-  
-  - [ ]* 4.2 Write property test for top-k retrieval behavior
-    - **Property 2: Top-K Retrieval Behavior**
-    - **Validates: Requirements 2.4**
-    - Test that retrieval returns exactly k chunks (or fewer if total < k)
-    - Test that chunks are ordered by descending relevance score
-    - Use Hypothesis to generate different k values
-
-- [x] 5. Checkpoint - Test RAG system with sample questions
-  - Ensure RAG system loads articles and retrieves relevant chunks, ask the user if questions arise.
-
-### Phase 2: API and Escalation Logic (1 hour)
-
-- [x] 6. Implement LLM client
-  - [x] 6.1 Create `src/llm_client.py` with LLMClient class
-    - Implement Google Gemini API integration
-    - Create prompt template with customer support instructions
-    - Implement `generate_answer()` method
-    - Parse LLM responses for uncertainty signals
-    - Add error handling for API timeouts and rate limits
-    - _Requirements: 3.1, 3.2, 3.3, 3.4, 9.1, 9.2, 9.3, 9.4, 9.5, 9.6_
-  
-  - [ ]* 6.2 Write property test for prompt construction completeness
-    - **Property 6: Prompt Construction Completeness**
-    - **Validates: Requirements 9.4, 9.5**
-    - Test that constructed prompts include complete question text
-    - Test that all retrieved chunk contents are included in prompt
-    - Use Hypothesis to generate random questions and chunk lists
-
-- [x] 7. Implement escalation engine
-  - [x] 7.1 Create `src/escalation.py` with EscalationEngine class
-    - Implement relevance threshold checking (default 0.5)
-    - Implement escalation decision logic
-    - Generate confidence explanations for answers and escalations
-    - Coordinate LLM calls when answering
-    - _Requirements: 3.5, 4.1, 4.2, 4.3, 4.4, 4.5, 5.1, 5.2, 5.3, 5.4, 5.5_
-  
-  - [ ]* 7.2 Write property test for escalation on low confidence
-    - **Property 4: Escalation on Low Confidence**
-    - **Validates: Requirements 3.5, 4.2, 4.4**
-    - Test that escalation occurs when max relevance score < threshold
-    - Test that escalation occurs when LLM signals uncertainty
-    - Use Hypothesis to generate relevance scores below threshold
-
-- [x] 8. Create FastAPI application
-  - [x] 8.1 Create `src/main.py` with FastAPI app
-    - Define Pydantic models (QuestionRequest, QuestionResponse)
-    - Implement POST `/ask` endpoint
-    - Configure CORS for frontend access
-    - Wire together RAG system, escalation engine, and LLM client
-    - Add request validation and error handling
-    - _Requirements: 1.1, 1.2, 1.3, 1.4, 6.1, 6.2, 6.3, 6.4, 6.5_
-  
-  - [ ]* 8.2 Write property test for invalid request handling
-    - **Property 1: Invalid Request Handling**
-    - **Validates: Requirements 1.4**
-    - Test that malformed requests return 400 status code
-    - Test that missing required fields return error messages
-    - Use Hypothesis to generate invalid request payloads
-  
-  - [ ]* 8.3 Write property test for response schema consistency
-    - **Property 5: Response Schema Consistency**
-    - **Validates: Requirements 5.1, 6.1, 6.2, 6.3, 6.4, 6.5**
-    - Test that all responses conform to JSON schema
-    - Test that response_type is either "answer" or "escalation"
-    - Test that required fields have correct types
-    - Use Hypothesis to generate random valid questions
-
-- [x] 9. Implement configuration management
-  - [x] 9.1 Create `src/config.py` with Pydantic settings
-    - Define Settings class with environment variables
-    - Set default values for thresholds and parameters
-    - Load configuration from `.env` file
-    - _Requirements: 10.5_
-
-- [x] 10. Checkpoint - Test API end-to-end
-  - Ensure API accepts questions and returns valid responses, ask the user if questions arise.
-
-### Phase 3: Frontend (0.5-1 hour)
-
-- [ ] 11. Set up React frontend with Vite
-  - [ ] 11.1 Create React project structure
-    - Initialize Vite project with React and TypeScript
-    - Install dependencies (axios for API calls)
-    - Create `frontend/.env.example` with API URL
-    - _Requirements: 7.5_
-
-- [ ] 12. Implement chat interface
-  - [ ] 12.1 Create ChatInterface component
-    - Implement message state management (user and assistant messages)
-    - Create text input field for customer questions
-    - Create submit button with loading state
-    - Display chat history with user questions and API responses
-    - Show confidence explanations for each response
-    - Differentiate between answer and escalation response types
-    - _Requirements: 7.1, 7.2, 7.3, 7.4, 7.6_
-  
-  - [ ]* 12.2 Write unit tests for ChatInterface component
-    - Test that user questions appear in chat history
-    - Test loading state during API calls
-    - Test display of API responses
-    - Use React Testing Library and Vitest
-
-- [ ] 13. Integrate frontend with backend API
-  - [ ] 13.1 Implement API client
-    - Create API service function to POST questions to `/ask` endpoint
-    - Handle API errors gracefully
-    - Configure CORS and API URL from environment variables
-    - _Requirements: 1.3_
-
-- [ ] 14. Add basic styling
-  - [ ] 14.1 Style chat interface
-    - Add minimal CSS for chat layout
-    - Style message bubbles (user vs assistant)
-    - Add loading indicator
-    - Ensure mobile responsiveness
-    - _Requirements: 7.5_
-
-### Phase 4: Testing and Deployment (0.5 hour)
-
-- [ ] 15. Write unit tests for core components
-  - [ ]* 15.1 Write unit tests for chunking logic
-    - Test chunk size and overlap calculations
-    - Test sentence boundary preservation
-    - _Requirements: 2.2, 2.6_
-  
-  - [ ]* 15.2 Write unit tests for escalation decision rules
-    - Test threshold comparisons
-    - Test confidence explanation generation
-    - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5_
-  
-  - [ ]* 15.3 Write unit tests for response formatting
-    - Test JSON construction
-    - Test source reference inclusion
-    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5_
-
-- [ ]* 16. Write integration tests
-  - [ ]* 16.1 Test end-to-end API flow
-    - Test answerable questions return answer responses
-    - Test out-of-scope questions trigger escalation
-    - Mock LLM API responses
-    - _Requirements: 1.1, 1.2_
-  
-  - [ ]* 16.2 Test error handling
-    - Test LLM API timeout handling
-    - Test invalid API key handling
-    - Test network error handling
-    - _Requirements: 1.4_
-  
-  - [ ]* 16.3 Test CORS configuration
-    - Verify CORS headers are present
-    - Test OPTIONS requests
-    - _Requirements: 1.3_
-
-- [ ] 17. Create deployment documentation
-  - [ ] 17.1 Update README with deployment instructions
-    - Document Render/Railway deployment steps for backend
-    - Document Vercel deployment steps for frontend
-    - Include environment variable configuration
-    - Add troubleshooting section
-    - _Requirements: 1.5, 10.4_
-
-- [ ] 18. Deploy to hosting platforms
-  - [ ] 18.1 Deploy backend to Render or Railway
-    - Create web service
-    - Configure build and start commands
-    - Set environment variables (API keys, thresholds)
-    - Verify deployment and test with sample requests
-    - _Requirements: 1.5_
-  
-  - [ ] 18.2 Deploy frontend to Vercel
-    - Create new project
-    - Configure build settings
-    - Set API URL environment variable
-    - Verify deployment and test chat interface
-    - _Requirements: 1.5, 7.5_
-
-- [ ] 19. Final checkpoint - End-to-end testing
-  - Test deployed application with various question types (in-scope, out-of-scope, edge cases), verify LLM responses have appropriate tone, check confidence explanations are helpful, ask the user if questions arise.
-
-## Notes
-
-- Tasks marked with `*` are optional and can be skipped for faster MVP
-- Each task references specific requirements for traceability
-- Property tests validate the 6 correctness properties defined in the design
-- Unit tests validate specific examples and edge cases
-- Checkpoints ensure incremental validation at key milestones
-- Focus on escalation logic as the most critical component
-- Use Python for backend (FastAPI, FAISS, sentence-transformers)
-- Use TypeScript for frontend (React, Vite)

.vercelignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+venv/
+env/
+ENV/
+
+# Testing
+tests/
+.pytest_cache/
+.hypothesis/
+.coverage
+htmlcov/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git/
+.gitignore
+
+# Documentation
+*.md
+!README.md
+
+# Benchmarks
+.benchmarks/
+
+# Local env files
+.env
+.env.local

DEPLOYMENT.md

@@ -0,0 +1,360 @@
+# Vercel Deployment Guide
+
+This guide walks you through deploying the Smart Escalation API to Vercel as a monorepo with both frontend and backend.
+
+## Quick Start
+
+### 1. Prerequisites
+
+- GitHub account with this repository
+- Google Gemini API key ([Get one here](https://makersuite.google.com/app/apikey))
+- Vercel account ([Sign up free](https://vercel.com/signup))
+
+### 2. Deploy to Vercel
+
+Click the button below to deploy:
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/yourusername/smart-escalation-api)
+
+Or follow manual steps:
+
+#### Step 1: Import Project
+
+1. Go to [vercel.com](https://vercel.com)
+2. Click "Add New..." → "Project"
+3. Import your GitHub repository
+4. Vercel will auto-detect the configuration from `vercel.json`
+
+#### Step 2: Configure Environment Variables
+
+Add these environment variables in the Vercel dashboard:
+
+| Variable | Value | Required |
+|----------|-------|----------|
+| `GOOGLE_API_KEY` | Your Gemini API key | ✅ Yes |
+| `EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | No (has default) |
+| `RELEVANCE_THRESHOLD` | `0.5` | No (has default) |
+| `TOP_K_CHUNKS` | `3` | No (has default) |
+| `LLM_MODEL` | `gemini-1.5-flash` | No (has default) |
+| `LLM_TEMPERATURE` | `0.3` | No (has default) |
+
+**Important**: Set these for all environments (Production, Preview, Development)
+
+#### Step 3: Deploy
+
+1. Click "Deploy"
+2. Wait 2-3 minutes for build
+3. Visit your deployment URL
+
+### 3. Test Your Deployment
+
+1. Visit `https://your-app.vercel.app`
+2. Try these test questions:
+   - "How do I create a new project in TaskFlow?" (should answer)
+   - "What's the weather today?" (should escalate)
+3. Check that responses appear correctly
+
+## Architecture
+
+### Monorepo Structure
+
+```
+smart-escalation-api/
+├── api/                    # Vercel Serverless Functions (Backend)
+│   └── ask.py             # POST /api/ask endpoint
+├── frontend/              # React Frontend
+│   ├── src/
+│   └── dist/              # Built static files
+├── src/                   # Shared Python modules
+│   ├── rag.py
+│   ├── escalation.py
+│   ├── llm_client.py
+│   └── config.py
+├── data/articles/         # Help articles knowledge base
+├── vercel.json           # Vercel configuration
+└── package.json          # Monorepo configuration
+```
+
+### How It Works
+
+1. **Frontend**: React app built with Vite, served as static files
+2. **Backend**: Python serverless function at `/api/ask`
+3. **Same Origin**: Frontend calls `/api/ask` (no CORS needed)
+4. **Automatic HTTPS**: Vercel provides SSL certificates
+5. **Global CDN**: Fast access worldwide
+
+## Configuration
+
+### vercel.json
+
+The `vercel.json` file configures:
+- Python runtime for API functions
+- Static build for frontend
+- Routing rules (API vs frontend)
+
+### Environment Variables
+
+Set in Vercel Dashboard → Settings → Environment Variables
+
+**Required:**
+- `GOOGLE_API_KEY`: Your Gemini API key
+
+**Optional (with defaults):**
+- `EMBEDDING_MODEL`: Sentence transformer model
+- `RELEVANCE_THRESHOLD`: Escalation threshold (0-1)
+- `TOP_K_CHUNKS`: Number of chunks to retrieve
+- `LLM_MODEL`: Gemini model to use
+- `LLM_TEMPERATURE`: LLM temperature (0-1)
+
+## Local Development
+
+### Backend Only
+
+```bash
+# Install Python dependencies
+pip install -r requirements.txt
+
+# Run FastAPI server
+uvicorn src.main:app --reload
+```
+
+API available at: `http://localhost:8000`
+
+### Frontend Only
+
+```bash
+# Install Node dependencies
+cd frontend
+npm install
+
+# Set API URL for local backend
+echo "VITE_API_URL=http://localhost:8000" > .env
+
+# Run dev server
+npm run dev
+```
+
+Frontend available at: `http://localhost:5173`
+
+### Full Stack (Vercel Dev)
+
+```bash
+# Install Vercel CLI
+npm install -g vercel
+
+# Run local Vercel environment
+vercel dev
+```
+
+This simulates the Vercel environment locally.
+
+## Troubleshooting
+
+### Build Fails
+
+**Problem**: "Module not found" error
+
+**Solution**:
+- Ensure `requirements.txt` includes all dependencies
+- Check Python version is 3.9+ in `vercel.json`
+- Verify all files are committed to git
+
+### API Returns 500
+
+**Problem**: Serverless function crashes
+
+**Solution**:
+- Check function logs in Vercel Dashboard
+- Verify `GOOGLE_API_KEY` is set correctly
+- Ensure `data/articles/` directory exists
+- Check that help articles are valid markdown
+
+### Frontend Can't Reach API
+
+**Problem**: "Failed to fetch" errors
+
+**Solution**:
+- Verify API endpoint: `https://your-app.vercel.app/api/ask`
+- Check browser console for errors
+- Test API directly with curl:
+  ```bash
+  curl -X POST https://your-app.vercel.app/api/ask \
+    -H "Content-Type: application/json" \
+    -d '{"question":"test"}'
+  ```
+
+### Slow Response Times
+
+**Problem**: Requests take >10 seconds
+
+**Solution**:
+- First request loads embedding model (2-3s cold start)
+- Subsequent requests are faster (cached)
+- Use `gemini-1.5-flash` for faster responses
+- Consider Vercel Pro for better performance
+
+### Out of Memory
+
+**Problem**: Function crashes with memory error
+
+**Solution**:
+- Vercel free tier: 1GB memory limit
+- Reduce `TOP_K_CHUNKS` to use less memory
+- Use smaller embedding model
+- Upgrade to Pro plan for 3GB memory
+
+## Monitoring
+
+### Vercel Dashboard
+
+Monitor your deployment:
+1. Go to Vercel Dashboard → Your Project
+2. View real-time logs in Deployments tab
+3. Check function execution time and errors
+4. Monitor bandwidth usage
+
+### Enable Analytics
+
+1. Go to Analytics tab in Vercel Dashboard
+2. Enable Web Analytics (free)
+3. Enable Speed Insights for performance monitoring
+
+### Key Metrics
+
+Watch for:
+- Function execution time (should be <5s)
+- Error rate (should be <5%)
+- Cold start frequency
+- Memory usage
+
+## Updating
+
+### Update Code
+
+```bash
+# Make changes
+git add .
+git commit -m "Update feature"
+git push
+
+# Vercel automatically deploys
+```
+
+### Update Help Articles
+
+```bash
+# Edit articles
+vim data/articles/getting-started.md
+
+# Commit and push
+git add data/articles/
+git commit -m "Update help articles"
+git push
+
+# Vercel redeploys, vector store rebuilds
+```
+
+### Update Dependencies
+
+**Python:**
+```bash
+# Update requirements.txt
+pip install new-package
+pip freeze > requirements.txt
+
+# Commit and push
+git add requirements.txt
+git commit -m "Add new dependency"
+git push
+```
+
+**Node:**
+```bash
+cd frontend
+npm install new-package
+git add package.json package-lock.json
+git commit -m "Add new dependency"
+git push
+```
+
+## Cost Estimates
+
+### Vercel Free Tier
+
+- ✅ 100GB bandwidth/month
+- ✅ 100 hours function execution/month
+- ✅ 6,000 function invocations/day
+- ✅ Unlimited deployments
+- ✅ Automatic HTTPS
+- ✅ Global CDN
+
+### Expected Usage
+
+For low-medium traffic (100-500 requests/day):
+- Function time: ~1-2s per request
+- Daily usage: 100-1000s = 0.03-0.3 hours/day
+- Monthly usage: 1-9 hours/month
+- **Well within free tier limits**
+
+### When to Upgrade
+
+Upgrade to Pro ($20/month) if you need:
+- >100 hours function execution
+- >6,000 requests/day
+- 60s timeout (vs 10s)
+- 3GB memory (vs 1GB)
+- Priority support
+
+### Additional Costs
+
+- **Google Gemini API**: Free tier (15 req/min, 1500 req/day)
+- **Total**: $0-20/month depending on traffic
+
+## Security
+
+### Best Practices
+
+1. ✅ Never commit API keys to git
+2. ✅ Use Vercel environment variables for secrets
+3. ✅ Rotate API keys periodically
+4. ✅ Monitor logs for suspicious activity
+5. ✅ Keep dependencies updated
+
+### Automatic Security
+
+Vercel provides:
+- ✅ Automatic HTTPS/SSL
+- ✅ DDoS protection
+- ✅ Secure environment variables
+- ✅ Isolated function execution
+
+## Support
+
+### Resources
+
+- [Vercel Documentation](https://vercel.com/docs)
+- [Vercel Python Runtime](https://vercel.com/docs/functions/serverless-functions/runtimes/python)
+- [Vercel Community](https://github.com/vercel/vercel/discussions)
+
+### Getting Help
+
+1. Check [README.md](README.md) for detailed documentation
+2. Review [Troubleshooting](#troubleshooting) section above
+3. Check Vercel function logs for errors
+4. Open GitHub issue for bugs
+5. Contact Vercel support (Pro plan)
+
+## Next Steps
+
+After deployment:
+
+1. ✅ Test with various questions
+2. ✅ Monitor performance in Vercel Dashboard
+3. ✅ Enable Analytics for insights
+4. ✅ Set up custom domain (optional)
+5. ✅ Configure alerts for errors
+6. ✅ Share with users!
+
+---
+
+**Need help?** Open an issue on GitHub or check the [README.md](README.md) for more details.

README.md

@@ -2,6 +2,17 @@
 
 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)
+
+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!
+
+**See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions.**
+
 ## Features
 
 - **RAG-Based Retrieval**: Uses sentence-transformers and FAISS for semantic search over help articles
@@ -12,10 +23,11 @@ An AI-powered L1 customer support system that intelligently answers customer que
 
 ## Architecture
 
-- **Backend**: FastAPI + FAISS (in-memory vector store) + sentence-transformers
+- **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**: Render/Railway (backend) + Vercel (frontend)
+- **Deployment**: Vercel (monorepo with frontend + backend)
 
 ## Quick Start
 
@@ -165,40 +177,565 @@ The system escalates to human agents when:
 
 ## Deployment
 
-### Backend Deployment (Render/Railway)
-
-#### Render
-
-1. Create a new Web Service on [Render](https://render.com)
-2. Connect your GitHub repository
-3. Configure build settings:
-   - **Build Command**: `pip install -r requirements.txt`
-   - **Start Command**: `uvicorn src.main:app --host 0.0.0.0 --port $PORT`
-4. Add environment variables:
-   - `GOOGLE_API_KEY`
-   - Other configuration variables as needed
-5. Deploy
-
-#### Railway
-
-1. Create a new project on [Railway](https://railway.app)
-2. Connect your GitHub repository
-3. Add environment variables in the Variables tab
-4. Railway will auto-detect Python and deploy
-5. Set start command if needed: `uvicorn src.main:app --host 0.0.0.0 --port $PORT`
-
-### Frontend Deployment (Vercel)
-
-1. Create a new project on [Vercel](https://vercel.com)
-2. Connect your GitHub repository
-3. Configure build settings:
-   - **Framework Preset**: Vite
-   - **Root Directory**: `frontend`
-   - **Build Command**: `npm run build`
-   - **Output Directory**: `dist`
-4. Add environment variable:
-   - `VITE_API_URL`: Your backend URL (e.g., `https://your-app.onrender.com`)
-5. Deploy
+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
+```
+
+### Step 1: Create Vercel Configuration
+
+Create `vercel.json` in the project root:
+
+```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();
+}
+```
+
+### 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:
+
+```json
+{
+  "name": "smart-escalation-api",
+  "version": "1.0.0",
+  "scripts": {
+    "build": "cd frontend && npm install && npm run build"
+  },
+  "workspaces": [
+    "frontend"
+  ]
+}
+```
+
+#### 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)
 
 ## Testing
 

VERCEL_SETUP.md

@@ -0,0 +1,220 @@
+# Vercel Setup - Quick Reference
+
+## 📋 Pre-Deployment Checklist
+
+- [ ] GitHub repository with code
+- [ ] Google Gemini API key ([Get one](https://makersuite.google.com/app/apikey))
+- [ ] Vercel account ([Sign up free](https://vercel.com/signup))
+
+## 🚀 Deployment Steps
+
+### 1. Import Project to Vercel
+
+```
+1. Go to vercel.com
+2. Click "Add New..." → "Project"
+3. Select "Import Git Repository"
+4. Choose your GitHub repository
+5. Vercel auto-detects configuration from vercel.json
+```
+
+### 2. Configure Environment Variables
+
+Add these in Vercel Dashboard → Settings → Environment Variables:
+
+#### Required
+```
+GOOGLE_API_KEY=AIza...your-key-here
+```
+
+#### Optional (with defaults)
+```
+EMBEDDING_MODEL=all-MiniLM-L6-v2
+RELEVANCE_THRESHOLD=0.5
+TOP_K_CHUNKS=3
+LLM_MODEL=gemini-1.5-flash
+LLM_TEMPERATURE=0.3
+```
+
+**Important**: Set for all environments (Production, Preview, Development)
+
+### 3. Deploy
+
+```
+1. Click "Deploy"
+2. Wait 2-3 minutes
+3. Visit your URL: https://your-app.vercel.app
+```
+
+## ✅ Post-Deployment Testing
+
+### Test Questions
+
+**Should Answer:**
+```
+"How do I create a new project in TaskFlow?"
+"How do I add a team member?"
+"What are the subscription plans?"
+```
+
+**Should Escalate:**
+```
+"What's the weather today?"
+"Tell me a joke"
+"How do I cook pasta?"
+```
+
+### Verify
+
+- [ ] Frontend loads correctly
+- [ ] Can submit questions
+- [ ] Answers appear in chat
+- [ ] Confidence explanations show
+- [ ] Escalations work for out-of-scope questions
+
+## 🔧 Common Issues
+
+### Build Fails
+
+**Error**: "Module not found"
+```bash
+# Solution: Ensure requirements.txt includes all dependencies
+pip freeze > requirements.txt
+git add requirements.txt
+git commit -m "Update dependencies"
+git push
+```
+
+### API Returns 500
+
+**Error**: Function crashes
+```bash
+# Solution: Check Vercel function logs
+1. Go to Vercel Dashboard → Deployments
+2. Click on latest deployment
+3. View Function Logs
+4. Look for Python errors
+```
+
+### Frontend Can't Reach API
+
+**Error**: "Failed to fetch"
+```bash
+# Solution: Test API directly
+curl -X POST https://your-app.vercel.app/api/ask \
+  -H "Content-Type: application/json" \
+  -d '{"question":"test"}'
+
+# Should return JSON response
+```
+
+### Slow Responses
+
+**Issue**: First request takes 5-10 seconds
+```
+This is normal! First request loads embedding model.
+Subsequent requests are fast (1-3 seconds).
+```
+
+## 📊 Monitoring
+
+### View Logs
+
+```
+Vercel Dashboard → Your Project → Deployments → Function Logs
+```
+
+### Key Metrics
+
+- Function execution time: Should be <5s
+- Error rate: Should be <5%
+- Memory usage: Should be <1GB
+
+### Enable Analytics
+
+```
+Vercel Dashboard → Analytics → Enable Web Analytics
+```
+
+## 🔄 Updating
+
+### Update Code
+
+```bash
+git add .
+git commit -m "Update feature"
+git push
+# Vercel auto-deploys
+```
+
+### Update Help Articles
+
+```bash
+vim data/articles/getting-started.md
+git add data/articles/
+git commit -m "Update help articles"
+git push
+# Vector store rebuilds automatically
+```
+
+### Update Environment Variables
+
+```
+1. Vercel Dashboard → Settings → Environment Variables
+2. Edit variable
+3. Redeploy (automatic or manual)
+```
+
+## 💰 Cost Tracking
+
+### Free Tier Limits
+
+- 100GB bandwidth/month
+- 100 hours function execution/month
+- 6,000 function invocations/day
+
+### Monitor Usage
+
+```
+Vercel Dashboard → Usage
+```
+
+### Expected Usage (100-500 requests/day)
+
+- Function time: ~1-2s per request
+- Daily: 100-1000s = 0.03-0.3 hours
+- Monthly: 1-9 hours
+- **Well within free tier**
+
+## 🆘 Getting Help
+
+### Resources
+
+- [Full Deployment Guide](DEPLOYMENT.md)
+- [README](README.md)
+- [Vercel Docs](https://vercel.com/docs)
+- [Vercel Community](https://github.com/vercel/vercel/discussions)
+
+### Support Channels
+
+1. Check function logs in Vercel Dashboard
+2. Review [DEPLOYMENT.md](DEPLOYMENT.md) troubleshooting section
+3. Open GitHub issue
+4. Vercel support (Pro plan)
+
+## 🎯 Next Steps
+
+After successful deployment:
+
+- [ ] Test with various questions
+- [ ] Enable Vercel Analytics
+- [ ] Set up custom domain (optional)
+- [ ] Monitor performance
+- [ ] Share with users!
+
+---
+
+**Quick Links:**
+- [Vercel Dashboard](https://vercel.com/dashboard)
+- [Google AI Studio](https://makersuite.google.com/app/apikey)
+- [Full Documentation](DEPLOYMENT.md)

api/ask.py

@@ -0,0 +1,128 @@
+"""
+Vercel Serverless Function for handling customer support questions.
+Endpoint: POST /api/ask
+"""
+
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+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 = None
+llm_client = None
+escalation_engine = None
+
+def initialize_components():
+    """Initialize RAG system, LLM client, and escalation engine."""
+    global rag_system, llm_client, escalation_engine
+    
+    if rag_system is None:
+        articles_dir = os.path.join(
+            os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+            "data",
+            "articles"
+        )
+        rag_system = RAGSystem(articles_dir=articles_dir)
+        llm_client = LLMClient(api_key=settings.google_api_key, model=settings.llm_model)
+        escalation_engine = EscalationEngine(
+            llm_client=llm_client,
+            relevance_threshold=settings.relevance_threshold
+        )
+
+app = FastAPI(title="Smart Escalation API")
+
+# Configure CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],  # In production, restrict to your domain
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+class QuestionRequest(BaseModel):
+    question: str
+
+class QuestionResponse(BaseModel):
+    response_type: str
+    message: str
+    confidence_explanation: str
+    sources: list = None
+
+@app.post("/api/ask", response_model=QuestionResponse)
+async def ask_question(request: QuestionRequest):
+    """
+    Process customer question and return answer or escalation.
+    
+    Args:
+        request: QuestionRequest with 'question' field
+        
+    Returns:
+        QuestionResponse with response_type, message, confidence_explanation, sources
+    """
+    try:
+        # Initialize components on first request
+        initialize_components()
+        
+        # Validate question
+        if not request.question or len(request.question.strip()) == 0:
+            return JSONResponse(
+                status_code=400,
+                content={
+                    "response_type": "error",
+                    "message": "Question cannot be empty",
+                    "confidence_explanation": "Invalid request",
+                    "sources": None
+                }
+            )
+        
+        # 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 {
+            "response_type": decision.action,
+            "message": decision.message,
+            "confidence_explanation": decision.confidence_explanation,
+            "sources": decision.sources
+        }
+        
+    except Exception as e:
+        # Log error and return escalation response
+        print(f"Error processing question: {str(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"System error occurred",
+                "sources": None
+            }
+        )
+
+@app.get("/api/health")
+async def health_check():
+    """Health check endpoint."""
+    return {
+        "status": "healthy",
+        "vector_store_loaded": rag_system is not None
+    }
+
+# Vercel serverless function handler
+def handler(request: Request):
+    """Main handler for Vercel serverless function."""
+    return app(request)

frontend/.env.example

@@ -0,0 +1,9 @@
+# API Configuration
+# For local development with separate backend server, use:
+# VITE_API_URL=http://localhost:8000
+
+# For Vercel deployment (monorepo with serverless functions), leave empty or use:
+# VITE_API_URL=/api
+
+# The default is /api which works for Vercel deployment
+VITE_API_URL=/api

frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

frontend/README.md

@@ -0,0 +1,73 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+
+```js
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+
+      // Remove tseslint.configs.recommended and replace with this
+      tseslint.configs.recommendedTypeChecked,
+      // Alternatively, use this for stricter rules
+      tseslint.configs.strictTypeChecked,
+      // Optionally, add this for stylistic rules
+      tseslint.configs.stylisticTypeChecked,
+
+      // Other configs...
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```
+
+You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+
+```js
+// eslint.config.js
+import reactX from 'eslint-plugin-react-x'
+import reactDom from 'eslint-plugin-react-dom'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      // Other configs...
+      // Enable lint rules for React
+      reactX.configs['recommended-typescript'],
+      // Enable lint rules for React DOM
+      reactDom.configs.recommended,
+    ],
+    languageOptions: {
+      parserOptions: {
+        project: ['./tsconfig.node.json', './tsconfig.app.json'],
+        tsconfigRootDir: import.meta.dirname,
+      },
+      // other options...
+    },
+  },
+])
+```

frontend/eslint.config.js

@@ -0,0 +1,23 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>frontend</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "axios": "^1.15.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^24.12.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^9.39.4",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.2",
+    "globals": "^17.4.0",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.58.0",
+    "vite": "^8.0.4"
+  }
+}

frontend/src/App.css

@@ -0,0 +1,246 @@
+/* Chat Container */
+.chat-container {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+  max-width: 900px;
+  margin: 0 auto;
+  background: var(--bg);
+}
+
+/* Chat Header */
+.chat-header {
+  padding: 24px;
+  border-bottom: 1px solid var(--border);
+  text-align: center;
+  background: var(--bg);
+}
+
+.chat-header h1 {
+  margin: 0 0 8px 0;
+  font-size: 24px;
+  color: var(--text-h);
+}
+
+.chat-header p {
+  margin: 0;
+  font-size: 14px;
+  color: var(--text);
+  opacity: 0.8;
+}
+
+/* Chat Messages Area */
+.chat-messages {
+  flex: 1;
+  overflow-y: auto;
+  padding: 24px;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+.empty-state {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  height: 100%;
+  color: var(--text);
+  opacity: 0.6;
+  font-size: 14px;
+}
+
+/* Message Styles */
+.message {
+  display: flex;
+  flex-direction: column;
+  max-width: 80%;
+  animation: fadeIn 0.3s ease-in;
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.message.user {
+  align-self: flex-end;
+}
+
+.message.assistant {
+  align-self: flex-start;
+}
+
+.message-content {
+  padding: 12px 16px;
+  border-radius: 12px;
+  background: var(--social-bg);
+}
+
+.message.user .message-content {
+  background: var(--accent-bg);
+  border: 1px solid var(--accent-border);
+}
+
+.message.assistant .message-content {
+  background: var(--social-bg);
+  border: 1px solid var(--border);
+}
+
+.message.assistant.escalation .message-content {
+  background: #fff3cd;
+  border: 1px solid #ffc107;
+}
+
+.message-role {
+  display: block;
+  font-size: 12px;
+  font-weight: 600;
+  margin-bottom: 6px;
+  color: var(--text-h);
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+}
+
+.message-content p {
+  margin: 0;
+  font-size: 15px;
+  line-height: 1.5;
+  color: var(--text);
+}
+
+/* Confidence Indicator */
+.confidence-indicator {
+  margin-top: 12px;
+  padding-top: 12px;
+  border-top: 1px solid var(--border);
+  font-size: 13px;
+}
+
+.confidence-label {
+  font-weight: 600;
+  color: var(--text-h);
+  margin-right: 6px;
+}
+
+.confidence-text {
+  color: var(--text);
+  opacity: 0.9;
+}
+
+/* Escalation Badge */
+.escalation-badge {
+  margin-top: 8px;
+  padding: 6px 12px;
+  background: #ffc107;
+  color: #000;
+  border-radius: 6px;
+  font-size: 12px;
+  font-weight: 600;
+  display: inline-block;
+}
+
+/* Loading State */
+.message.loading .message-content {
+  opacity: 0.7;
+}
+
+.loading-text {
+  font-style: italic;
+}
+
+/* Chat Input Form */
+.chat-input-form {
+  display: flex;
+  gap: 12px;
+  padding: 24px;
+  border-top: 1px solid var(--border);
+  background: var(--bg);
+}
+
+.chat-input {
+  flex: 1;
+  padding: 12px 16px;
+  font-size: 15px;
+  border: 2px solid var(--border);
+  border-radius: 8px;
+  background: var(--bg);
+  color: var(--text);
+  transition: border-color 0.3s;
+}
+
+.chat-input:focus {
+  outline: none;
+  border-color: var(--accent);
+}
+
+.chat-input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.chat-submit {
+  padding: 12px 24px;
+  font-size: 15px;
+  font-weight: 600;
+  border: 2px solid var(--accent-border);
+  border-radius: 8px;
+  background: var(--accent-bg);
+  color: var(--accent);
+  cursor: pointer;
+  transition: all 0.3s;
+}
+
+.chat-submit:hover:not(:disabled) {
+  border-color: var(--accent);
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
+}
+
+.chat-submit:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.chat-submit:focus-visible {
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+/* Responsive Design */
+@media (max-width: 768px) {
+  .chat-header {
+    padding: 16px;
+  }
+
+  .chat-header h1 {
+    font-size: 20px;
+  }
+
+  .chat-messages {
+    padding: 16px;
+  }
+
+  .message {
+    max-width: 90%;
+  }
+
+  .chat-input-form {
+    padding: 16px;
+    gap: 8px;
+  }
+
+  .chat-input {
+    font-size: 14px;
+  }
+
+  .chat-submit {
+    padding: 12px 16px;
+    font-size: 14px;
+  }
+}
+

frontend/src/App.tsx

@@ -0,0 +1,137 @@
+import { useState } from 'react'
+import './App.css'
+import { askQuestion, ApiError } from './services/api'
+
+interface Message {
+  role: 'user' | 'assistant';
+  content: string;
+  confidenceExplanation?: string;
+  responseType?: 'answer' | 'escalation';
+}
+
+function App() {
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [input, setInput] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    
+    if (!input.trim() || loading) return;
+
+    const userMessage: Message = {
+      role: 'user',
+      content: input.trim()
+    };
+
+    setMessages(prev => [...prev, userMessage]);
+    const questionText = input.trim();
+    setInput('');
+    setLoading(true);
+
+    try {
+      const response = await askQuestion(questionText);
+      
+      const assistantMessage: Message = {
+        role: 'assistant',
+        content: response.message,
+        confidenceExplanation: response.confidence_explanation,
+        responseType: response.response_type
+      };
+      
+      setMessages(prev => [...prev, assistantMessage]);
+    } catch (error) {
+      console.error('API Error:', error);
+      
+      let errorMessage = 'Sorry, something went wrong. Please try again.';
+      
+      if (error instanceof ApiError) {
+        errorMessage = error.message;
+      }
+      
+      const errorResponse: Message = {
+        role: 'assistant',
+        content: errorMessage,
+        confidenceExplanation: 'Error occurred while processing your request',
+        responseType: 'escalation'
+      };
+      
+      setMessages(prev => [...prev, errorResponse]);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="chat-container">
+      <header className="chat-header">
+        <h1>TaskFlow Support Chat</h1>
+        <p>Ask questions about TaskFlow features and documentation</p>
+      </header>
+
+      <div className="chat-messages">
+        {messages.length === 0 && (
+          <div className="empty-state">
+            <p>Start a conversation by asking a question below</p>
+          </div>
+        )}
+        
+        {messages.map((message, index) => (
+          <div 
+            key={index} 
+            className={`message ${message.role} ${message.responseType || ''}`}
+          >
+            <div className="message-content">
+              <strong className="message-role">
+                {message.role === 'user' ? 'You' : 'Assistant'}
+              </strong>
+              <p>{message.content}</p>
+              
+              {message.confidenceExplanation && (
+                <div className="confidence-indicator">
+                  <span className="confidence-label">Confidence:</span>
+                  <span className="confidence-text">{message.confidenceExplanation}</span>
+                </div>
+              )}
+              
+              {message.responseType === 'escalation' && (
+                <div className="escalation-badge">
+                  Escalated to Human Support
+                </div>
+              )}
+            </div>
+          </div>
+        ))}
+        
+        {loading && (
+          <div className="message assistant loading">
+            <div className="message-content">
+              <strong className="message-role">Assistant</strong>
+              <p className="loading-text">Thinking...</p>
+            </div>
+          </div>
+        )}
+      </div>
+
+      <form className="chat-input-form" onSubmit={handleSubmit}>
+        <input
+          type="text"
+          className="chat-input"
+          placeholder="Ask a question about TaskFlow..."
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          disabled={loading}
+        />
+        <button 
+          type="submit" 
+          className="chat-submit"
+          disabled={loading || !input.trim()}
+        >
+          {loading ? 'Sending...' : 'Send'}
+        </button>
+      </form>
+    </div>
+  )
+}
+
+export default App

frontend/src/index.css

@@ -0,0 +1,111 @@
+:root {
+  --text: #6b6375;
+  --text-h: #08060d;
+  --bg: #fff;
+  --border: #e5e4e7;
+  --code-bg: #f4f3ec;
+  --accent: #aa3bff;
+  --accent-bg: rgba(170, 59, 255, 0.1);
+  --accent-border: rgba(170, 59, 255, 0.5);
+  --social-bg: rgba(244, 243, 236, 0.5);
+  --shadow:
+    rgba(0, 0, 0, 0.1) 0 10px 15px -3px, rgba(0, 0, 0, 0.05) 0 4px 6px -2px;
+
+  --sans: system-ui, 'Segoe UI', Roboto, sans-serif;
+  --heading: system-ui, 'Segoe UI', Roboto, sans-serif;
+  --mono: ui-monospace, Consolas, monospace;
+
+  font: 18px/145% var(--sans);
+  letter-spacing: 0.18px;
+  color-scheme: light dark;
+  color: var(--text);
+  background: var(--bg);
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+
+  @media (max-width: 1024px) {
+    font-size: 16px;
+  }
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --text: #9ca3af;
+    --text-h: #f3f4f6;
+    --bg: #16171d;
+    --border: #2e303a;
+    --code-bg: #1f2028;
+    --accent: #c084fc;
+    --accent-bg: rgba(192, 132, 252, 0.15);
+    --accent-border: rgba(192, 132, 252, 0.5);
+    --social-bg: rgba(47, 48, 58, 0.5);
+    --shadow:
+      rgba(0, 0, 0, 0.4) 0 10px 15px -3px, rgba(0, 0, 0, 0.25) 0 4px 6px -2px;
+  }
+
+  #social .button-icon {
+    filter: invert(1) brightness(2);
+  }
+}
+
+#root {
+  width: 1126px;
+  max-width: 100%;
+  margin: 0 auto;
+  text-align: center;
+  border-inline: 1px solid var(--border);
+  min-height: 100svh;
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+}
+
+h1,
+h2 {
+  font-family: var(--heading);
+  font-weight: 500;
+  color: var(--text-h);
+}
+
+h1 {
+  font-size: 56px;
+  letter-spacing: -1.68px;
+  margin: 32px 0;
+  @media (max-width: 1024px) {
+    font-size: 36px;
+    margin: 20px 0;
+  }
+}
+h2 {
+  font-size: 24px;
+  line-height: 118%;
+  letter-spacing: -0.24px;
+  margin: 0 0 8px;
+  @media (max-width: 1024px) {
+    font-size: 20px;
+  }
+}
+p {
+  margin: 0;
+}
+
+code,
+.counter {
+  font-family: var(--mono);
+  display: inline-flex;
+  border-radius: 4px;
+  color: var(--text-h);
+}
+
+code {
+  font-size: 15px;
+  line-height: 135%;
+  padding: 4px 8px;
+  background: var(--code-bg);
+}

frontend/src/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

frontend/src/services/api.ts

@@ -0,0 +1,154 @@
+/**
+ * API client for Smart Escalation API
+ * Handles communication with the backend /ask endpoint
+ */
+
+// API Response Types
+export interface ApiResponse {
+  response_type: 'answer' | 'escalation';
+  message: string;
+  confidence_explanation: string;
+  sources: string[] | null;
+}
+
+// API Request Types
+export interface QuestionRequest {
+  question: string;
+}
+
+// Error Types
+export class ApiError extends Error {
+  statusCode?: number;
+  originalError?: unknown;
+
+  constructor(
+    message: string,
+    statusCode?: number,
+    originalError?: unknown
+  ) {
+    super(message);
+    this.name = 'ApiError';
+    this.statusCode = statusCode;
+    this.originalError = originalError;
+  }
+}
+
+/**
+ * Get API URL from environment variables
+ * For Vercel deployment, uses relative path /api
+ * For local development, uses localhost:8000
+ */
+const getApiUrl = (): string => {
+  // In production (Vercel), use relative path to serverless function
+  // In development, use environment variable or default to localhost
+  return import.meta.env.VITE_API_URL || '/api';
+};
+
+/**
+ * POST a question to the /ask endpoint
+ * 
+ * @param question - The customer question to submit
+ * @returns Promise resolving to the API response
+ * @throws ApiError on network errors, timeouts, or invalid responses
+ */
+export const askQuestion = async (question: string): Promise<ApiResponse> => {
+  const apiUrl = getApiUrl();
+  const endpoint = `${apiUrl}/ask`;
+
+  // Validate input
+  if (!question || question.trim().length === 0) {
+    throw new ApiError('Question cannot be empty', 400);
+  }
+
+  const requestBody: QuestionRequest = {
+    question: question.trim()
+  };
+
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 30000); // 30 second timeout
+
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(requestBody),
+      signal: controller.signal,
+    });
+
+    clearTimeout(timeoutId);
+
+    // Handle HTTP errors
+    if (!response.ok) {
+      let errorMessage = `API request failed with status ${response.status}`;
+      
+      try {
+        const errorData = await response.json();
+        errorMessage = errorData.detail || errorData.message || errorMessage;
+      } catch {
+        // If error response is not JSON, use status text
+        errorMessage = response.statusText || errorMessage;
+      }
+
+      throw new ApiError(errorMessage, response.status);
+    }
+
+    // Parse response
+    const data = await response.json();
+
+    // Validate response structure
+    if (!isValidApiResponse(data)) {
+      throw new ApiError('Invalid response format from API', 500);
+    }
+
+    return data;
+
+  } catch (error) {
+    // Handle network errors
+    if (error instanceof ApiError) {
+      throw error;
+    }
+
+    if (error instanceof Error) {
+      if (error.name === 'AbortError') {
+        throw new ApiError('Request timeout - please try again', 408, error);
+      }
+      
+      if (error.message.includes('fetch')) {
+        throw new ApiError(
+          'Unable to connect to the API. Please check your connection and try again.',
+          0,
+          error
+        );
+      }
+
+      throw new ApiError(
+        `Network error: ${error.message}`,
+        0,
+        error
+      );
+    }
+
+    throw new ApiError('An unexpected error occurred', 0, error);
+  }
+};
+
+/**
+ * Type guard to validate API response structure
+ */
+function isValidApiResponse(data: unknown): data is ApiResponse {
+  if (typeof data !== 'object' || data === null) {
+    return false;
+  }
+
+  const response = data as Record<string, unknown>;
+
+  return (
+    typeof response.response_type === 'string' &&
+    (response.response_type === 'answer' || response.response_type === 'escalation') &&
+    typeof response.message === 'string' &&
+    typeof response.confidence_explanation === 'string' &&
+    (response.sources === null || Array.isArray(response.sources))
+  );
+}

frontend/tsconfig.app.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "esnext",
+    "types": ["vite/client"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

frontend/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
+  ]
+}

frontend/tsconfig.node.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "es2023",
+    "lib": ["ES2023"],
+    "module": "esnext",
+    "types": ["node"],
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["vite.config.ts"]
+}

frontend/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react()],
+})

package.json

@@ -0,0 +1,27 @@
+{
+  "name": "smart-escalation-api",
+  "version": "1.0.0",
+  "description": "AI-powered L1 customer support system with intelligent escalation",
+  "private": true,
+  "scripts": {
+    "build": "cd frontend && npm install && npm run build",
+    "dev:frontend": "cd frontend && npm run dev",
+    "dev:backend": "uvicorn src.main:app --reload",
+    "test": "pytest -v",
+    "test:property": "pytest tests/property -v",
+    "lint": "cd frontend && npm run lint"
+  },
+  "workspaces": [
+    "frontend"
+  ],
+  "keywords": [
+    "customer-support",
+    "rag",
+    "llm",
+    "escalation",
+    "fastapi",
+    "react"
+  ],
+  "author": "",
+  "license": "MIT"
+}

src/escalation.py

@@ -223,13 +223,18 @@ class EscalationEngine:
             # If LLM call fails, escalate gracefully
             error_msg = str(e)
             
+            # Log the actual error for debugging
+            print(f"ERROR in escalation engine: {error_msg}")
+            import traceback
+            traceback.print_exc()
+            
             # Provide specific error context in explanation
             if "timeout" in error_msg.lower():
                 explanation = "Unable to generate response due to timeout, escalating to human agent"
             elif "rate limit" in error_msg.lower():
                 explanation = "Service temporarily busy, escalating to human agent"
             else:
-                explanation = "Unable to generate response, escalating to human agent"
+                explanation = f"Unable to generate response, escalating to human agent (Error: {error_msg})"
             
             return EscalationDecision(
                 action="escalation",

tests/unit/test_escalation.py

@@ -0,0 +1,408 @@
+"""
+Unit tests for the escalation engine module.
+
+Tests escalation decision rules including threshold comparisons
+and confidence explanation generation.
+
+**Validates: Requirements 4.1, 4.2, 4.3, 4.4, 4.5**
+"""
+
+import pytest
+from unittest.mock import Mock, MagicMock
+from src.escalation import EscalationEngine, EscalationDecision
+from src.rag import RetrievedChunk
+from src.llm_client import LLMClient, LLMResponse
+
+
+class TestEscalationDecisionRules:
+    """Test cases for escalation decision logic."""
+    
+    @pytest.fixture
+    def mock_llm_client(self):
+        """Create a mock LLM client."""
+        return Mock(spec=LLMClient)
+    
+    @pytest.fixture
+    def engine(self, mock_llm_client):
+        """Create escalation engine with default threshold."""
+        return EscalationEngine(
+            llm_client=mock_llm_client,
+            relevance_threshold=0.5
+        )
+    
+    def test_escalate_on_empty_chunks(self, engine):
+        """Should escalate when no chunks are retrieved."""
+        decision = engine.process_question("test question", [])
+        
+        assert decision.action == "escalation"
+        assert "no relevant information" in decision.confidence_explanation.lower()
+    
+    def test_escalate_on_low_relevance_score(self, engine):
+        """Should escalate when best relevance score is below threshold."""
+        chunks = [
+            RetrievedChunk(
+                content="Some content",
+                score=0.3,  # Below 0.5 threshold
+                source="test.md",
+                chunk_id=0,
+                position=0
+            )
+        ]
+        
+        decision = engine.process_question("test question", chunks)
+        
+        assert decision.action == "escalation"
+        assert "0.30" in decision.confidence_explanation or "0.3" in decision.confidence_explanation
+        assert decision.sources is None
+    
+    def test_escalate_on_llm_uncertainty(self, engine, mock_llm_client):
+        """Should escalate when LLM signals uncertainty."""
+        chunks = [
+            RetrievedChunk(
+                content="Relevant content",
+                score=0.8,  # High score
+                source="test.md",
+                chunk_id=0,
+                position=0
+            )
+        ]
+        
+        # Mock LLM to return uncertain response
+        mock_llm_client.generate_answer.return_value = LLMResponse(
+            answer="I'm not certain about this.",
+            uncertain=True
+        )
+        
+        decision = engine.process_question("test question", chunks)
+        
+        assert decision.action == "escalation"
+        assert "uncertainty" in decision.confidence_explanation.lower()
+        assert decision.sources is None
+    
+    def test_answer_on_high_relevance(self, engine, mock_llm_client):
+        """Should answer when relevance score is above threshold and LLM is confident."""
+        chunks = [
+            RetrievedChunk(
+                content="Relevant content",
+                score=0.8,
+                source="billing.md",
+                chunk_id=0,
+                position=0
+            )
+        ]
+        
+        # Mock LLM to return confident answer
+        mock_llm_client.generate_answer.return_value = LLMResponse(
+            answer="Here is the answer to your question.",
+            uncertain=False
+        )
+        
+        decision = engine.process_question("test question", chunks)
+        
+        assert decision.action == "answer"
+        assert decision.message == "Here is the answer to your question."
+        assert "0.8" in decision.confidence_explanation or "0.80" in decision.confidence_explanation
+        assert decision.sources == ["billing.md"]
+    
+    def test_threshold_boundary_below(self, engine):
+        """Should escalate when score is exactly at threshold (0.5)."""
+        chunks = [
+            RetrievedChunk(
+                content="Content",
+                score=0.49,  # Just below threshold
+                source="test.md",
+                chunk_id=0,
+                position=0
+            )
+        ]
+        
+        decision = engine.process_question("test question", chunks)
+        
+        assert decision.action == "escalation"
+    
+    def test_threshold_boundary_above(self, engine, mock_llm_client):
+        """Should attempt to answer when score is above threshold."""
+        chunks = [
+            RetrievedChunk(
+                content="Content",
+                score=0.51,  # Just above threshold
+                source="test.md",
+                chunk_id=0,
+                position=0
+            )
+        ]
+        
+        mock_llm_client.generate_answer.return_value = LLMResponse(
+            answer="Answer",
+            uncertain=False
+        )
+        
+        decision = engine.process_question("test question", chunks)
+        
+        assert decision.action == "answer"
+    
+    def test_custom_threshold(self, mock_llm_client):
+        """Should respect custom relevance threshold."""
+        engine = EscalationEngine(
+            llm_client=mock_llm_client,
+            relevance_threshold=0.7  # Higher threshold
+        )
+        
+        chunks = [
+            RetrievedChunk(
+                content="Content",
+                score=0.6,  # Would pass 0.5 but not 0.7
+                source="test.md",
+                chunk_id=0,
+                position=0
+            )
+        ]
+        
+        decision = engine.process_question("test question", chunks)
+        
+        assert decision.action == "escalation"
+        assert "0.7" in decision.confidence_explanation or "0.70" in decision.confidence_explanation
+
+
+class TestConfidenceExplanationGeneration:
+    """Test cases for confidence explanation generation."""
+    
+    @pytest.fixture
+    def mock_llm_client(self):
+        """Create a mock LLM client."""
+        return Mock(spec=LLMClient)
+    
+    @pytest.fixture
+    def engine(self, mock_llm_client):
+        """Create escalation engine."""
+        return EscalationEngine(llm_client=mock_llm_client)
+    
+    def test_explanation_includes_score_for_answer(self, engine, mock_llm_client):
+        """Confidence explanation for answers should include relevance score."""
+        chunks = [
+            RetrievedChunk(
+                content="Content",
+                score=0.85,
+                source="test.md",
+                chunk_id=0,
+                position=0
+            )
+        ]
+        
+        mock_llm_client.generate_answer.return_value = LLMResponse(
+            answer="Answer",
+            uncertain=False
+        )
+        
+        decision = engine.process_question("test", chunks)
+        
+        assert "0.85" in decision.confidence_explanation
+        assert "confidence" in decision.confidence_explanation.lower()
+    
+    def test_explanation_includes_source_for_answer(self, engine, mock_llm_client):
+        """Confidence explanation should mention source article."""
+        chunks = [
+            RetrievedChunk(
+                content="Content",
+                score=0.8,
+                source="billing.md",
+                chunk_id=0,
+                position=0
+            )
+        ]
+        
+        mock_llm_client.generate_answer.return_value = LLMResponse(
+            answer="Answer",
+            uncertain=False
+        )
+        
+        decision = engine.process_question("test", chunks)
+        
+        assert "billing.md" in decision.confidence_explanation
+    
+    def test_explanation_for_multiple_sources(self, engine, mock_llm_client):
+        """Should mention multiple sources in explanation."""
+        chunks = [
+            RetrievedChunk(content="C1", score=0.8, source="billing.md", chunk_id=0, position=0),
+            RetrievedChunk(content="C2", score=0.7, source="permissions.md", chunk_id=1, position=0)
+        ]
+        
+        mock_llm_client.generate_answer.return_value = LLMResponse(
+            answer="Answer",
+            uncertain=False
+        )
+        
+        decision = engine.process_question("test", chunks)
+        
+        # Should mention multiple articles
+        assert "2" in decision.confidence_explanation or "multiple" in decision.confidence_explanation.lower()
+    
+    def test_explanation_for_low_score_escalation(self, engine):
+        """Escalation explanation should mention low score."""
+        chunks = [
+            RetrievedChunk(
+                content="Content",
+                score=0.3,
+                source="test.md",
+                chunk_id=0,
+                position=0
+            )
+        ]
+        
+        decision = engine.process_question("test", chunks)
+        
+        assert decision.action == "escalation"
+        assert "0.3" in decision.confidence_explanation or "0.30" in decision.confidence_explanation
+        assert "threshold" in decision.confidence_explanation.lower()
+    
+    def test_explanation_for_llm_uncertainty(self, engine, mock_llm_client):
+        """Escalation explanation should mention LLM uncertainty."""
+        chunks = [
+            RetrievedChunk(content="Content", score=0.8, source="test.md", chunk_id=0, position=0)
+        ]
+        
+        mock_llm_client.generate_answer.return_value = LLMResponse(
+            answer="Not sure",
+            uncertain=True
+        )
+        
+        decision = engine.process_question("test", chunks)
+        
+        assert decision.action == "escalation"
+        assert "uncertainty" in decision.confidence_explanation.lower()
+    
+    def test_explanation_for_no_chunks(self, engine):
+        """Escalation explanation should mention no relevant information."""
+        decision = engine.process_question("test", [])
+        
+        assert decision.action == "escalation"
+        assert "no relevant" in decision.confidence_explanation.lower()
+
+
+class TestSourceExtraction:
+    """Test cases for source reference extraction."""
+    
+    @pytest.fixture
+    def mock_llm_client(self):
+        """Create a mock LLM client."""
+        return Mock(spec=LLMClient)
+    
+    @pytest.fixture
+    def engine(self, mock_llm_client):
+        """Create escalation engine."""
+        return EscalationEngine(llm_client=mock_llm_client)
+    
+    def test_sources_included_for_answers(self, engine, mock_llm_client):
+        """Answer responses should include source references."""
+        chunks = [
+            RetrievedChunk(content="C", score=0.8, source="billing.md", chunk_id=0, position=0)
+        ]
+        
+        mock_llm_client.generate_answer.return_value = LLMResponse(
+            answer="Answer",
+            uncertain=False
+        )
+        
+        decision = engine.process_question("test", chunks)
+        
+        assert decision.sources is not None
+        assert "billing.md" in decision.sources
+    
+    def test_sources_not_included_for_escalations(self, engine):
+        """Escalation responses should not include sources."""
+        chunks = [
+            RetrievedChunk(content="C", score=0.2, source="test.md", chunk_id=0, position=0)
+        ]
+        
+        decision = engine.process_question("test", chunks)
+        
+        assert decision.action == "escalation"
+        assert decision.sources is None
+    
+    def test_multiple_sources_deduplicated(self, engine, mock_llm_client):
+        """Should deduplicate sources from multiple chunks."""
+        chunks = [
+            RetrievedChunk(content="C1", score=0.8, source="billing.md", chunk_id=0, position=0),
+            RetrievedChunk(content="C2", score=0.7, source="billing.md", chunk_id=1, position=100),
+            RetrievedChunk(content="C3", score=0.6, source="permissions.md", chunk_id=0, position=0)
+        ]
+        
+        mock_llm_client.generate_answer.return_value = LLMResponse(
+            answer="Answer",
+            uncertain=False
+        )
+        
+        decision = engine.process_question("test", chunks)
+        
+        assert len(decision.sources) == 2
+        assert "billing.md" in decision.sources
+        assert "permissions.md" in decision.sources
+    
+    def test_sources_sorted(self, engine, mock_llm_client):
+        """Sources should be sorted alphabetically."""
+        chunks = [
+            RetrievedChunk(content="C1", score=0.8, source="permissions.md", chunk_id=0, position=0),
+            RetrievedChunk(content="C2", score=0.7, source="billing.md", chunk_id=0, position=0)
+        ]
+        
+        mock_llm_client.generate_answer.return_value = LLMResponse(
+            answer="Answer",
+            uncertain=False
+        )
+        
+        decision = engine.process_question("test", chunks)
+        
+        assert decision.sources == ["billing.md", "permissions.md"]
+
+
+class TestErrorHandling:
+    """Test cases for error handling in escalation engine."""
+    
+    @pytest.fixture
+    def mock_llm_client(self):
+        """Create a mock LLM client."""
+        return Mock(spec=LLMClient)
+    
+    @pytest.fixture
+    def engine(self, mock_llm_client):
+        """Create escalation engine."""
+        return EscalationEngine(llm_client=mock_llm_client)
+    
+    def test_escalate_on_llm_error(self, engine, mock_llm_client):
+        """Should escalate gracefully when LLM call fails."""
+        chunks = [
+            RetrievedChunk(content="C", score=0.8, source="test.md", chunk_id=0, position=0)
+        ]
+        
+        mock_llm_client.generate_answer.side_effect = Exception("API error")
+        
+        decision = engine.process_question("test", chunks)
+        
+        assert decision.action == "escalation"
+        assert decision.sources is None
+    
+    def test_escalate_on_timeout(self, engine, mock_llm_client):
+        """Should escalate with timeout message when LLM times out."""
+        chunks = [
+            RetrievedChunk(content="C", score=0.8, source="test.md", chunk_id=0, position=0)
+        ]
+        
+        mock_llm_client.generate_answer.side_effect = RuntimeError("Request timeout")
+        
+        decision = engine.process_question("test", chunks)
+        
+        assert decision.action == "escalation"
+        assert "timeout" in decision.confidence_explanation.lower()
+    
+    def test_escalate_on_rate_limit(self, engine, mock_llm_client):
+        """Should escalate with rate limit message."""
+        chunks = [
+            RetrievedChunk(content="C", score=0.8, source="test.md", chunk_id=0, position=0)
+        ]
+        
+        mock_llm_client.generate_answer.side_effect = RuntimeError("Rate limit exceeded")
+        
+        decision = engine.process_question("test", chunks)
+        
+        assert decision.action == "escalation"
+        assert "rate limit" in decision.confidence_explanation.lower() or "busy" in decision.confidence_explanation.lower()

tests/unit/test_response_formatting.py

@@ -0,0 +1,381 @@
+"""
+Unit tests for API response formatting.
+
+Tests JSON construction and source reference inclusion in API responses.
+
+**Validates: Requirements 6.1, 6.2, 6.3, 6.4, 6.5**
+"""
+
+import pytest
+from pydantic import ValidationError
+from src.main import QuestionRequest, QuestionResponse
+
+
+class TestQuestionRequestValidation:
+    """Test cases for QuestionRequest model validation."""
+    
+    def test_valid_request(self):
+        """Should accept valid question."""
+        request = QuestionRequest(question="How do I reset my password?")
+        
+        assert request.question == "How do I reset my password?"
+    
+    def test_reject_empty_question(self):
+        """Should reject empty question string."""
+        with pytest.raises(ValidationError) as exc_info:
+            QuestionRequest(question="")
+        
+        assert "question" in str(exc_info.value).lower()
+    
+    def test_reject_whitespace_only(self):
+        """Should reject whitespace-only question."""
+        with pytest.raises(ValidationError) as exc_info:
+            QuestionRequest(question="   \n\t  ")
+        
+        assert "question" in str(exc_info.value).lower()
+    
+    def test_reject_missing_question(self):
+        """Should reject request without question field."""
+        with pytest.raises(ValidationError):
+            QuestionRequest()
+    
+    def test_reject_too_long_question(self):
+        """Should reject question exceeding max length."""
+        long_question = "a" * 501  # Max is 500
+        
+        with pytest.raises(ValidationError) as exc_info:
+            QuestionRequest(question=long_question)
+        
+        assert "500" in str(exc_info.value) or "length" in str(exc_info.value).lower()
+    
+    def test_trim_whitespace(self):
+        """Should trim leading/trailing whitespace from question."""
+        request = QuestionRequest(question="  How do I reset?  ")
+        
+        assert request.question == "How do I reset?"
+        assert not request.question.startswith(" ")
+        assert not request.question.endswith(" ")
+    
+    def test_accept_max_length_question(self):
+        """Should accept question at exactly max length."""
+        question = "a" * 500
+        request = QuestionRequest(question=question)
+        
+        assert len(request.question) == 500
+
+
+class TestQuestionResponseConstruction:
+    """Test cases for QuestionResponse model construction."""
+    
+    def test_answer_response_construction(self):
+        """Should construct valid answer response."""
+        response = QuestionResponse(
+            response_type="answer",
+            message="Here is your answer.",
+            confidence_explanation="High confidence based on retrieval.",
+            sources=["billing.md"]
+        )
+        
+        assert response.response_type == "answer"
+        assert response.message == "Here is your answer."
+        assert response.confidence_explanation == "High confidence based on retrieval."
+        assert response.sources == ["billing.md"]
+    
+    def test_escalation_response_construction(self):
+        """Should construct valid escalation response."""
+        response = QuestionResponse(
+            response_type="escalation",
+            message="Let me connect you with a human agent.",
+            confidence_explanation="Low confidence - score below threshold.",
+            sources=None
+        )
+        
+        assert response.response_type == "escalation"
+        assert response.message == "Let me connect you with a human agent."
+        assert response.confidence_explanation == "Low confidence - score below threshold."
+        assert response.sources is None
+    
+    def test_sources_optional(self):
+        """Sources field should be optional."""
+        response = QuestionResponse(
+            response_type="answer",
+            message="Answer",
+            confidence_explanation="Explanation"
+        )
+        
+        assert response.sources is None
+    
+    def test_reject_invalid_response_type(self):
+        """Should reject invalid response_type values."""
+        with pytest.raises(ValidationError) as exc_info:
+            QuestionResponse(
+                response_type="invalid",
+                message="Message",
+                confidence_explanation="Explanation"
+            )
+        
+        assert "response_type" in str(exc_info.value).lower()
+    
+    def test_reject_missing_required_fields(self):
+        """Should reject response missing required fields."""
+        with pytest.raises(ValidationError):
+            QuestionResponse(response_type="answer")
+    
+    def test_multiple_sources(self):
+        """Should accept multiple source references."""
+        response = QuestionResponse(
+            response_type="answer",
+            message="Answer",
+            confidence_explanation="Explanation",
+            sources=["billing.md", "permissions.md", "troubleshooting.md"]
+        )
+        
+        assert len(response.sources) == 3
+        assert "billing.md" in response.sources
+    
+    def test_empty_sources_list(self):
+        """Should accept empty sources list."""
+        response = QuestionResponse(
+            response_type="answer",
+            message="Answer",
+            confidence_explanation="Explanation",
+            sources=[]
+        )
+        
+        assert response.sources == []
+
+
+class TestResponseJSONSerialization:
+    """Test cases for JSON serialization of responses."""
+    
+    def test_answer_json_schema(self):
+        """Answer response should serialize to correct JSON schema."""
+        response = QuestionResponse(
+            response_type="answer",
+            message="Your answer here.",
+            confidence_explanation="High confidence.",
+            sources=["billing.md"]
+        )
+        
+        json_data = response.model_dump()
+        
+        assert "response_type" in json_data
+        assert "message" in json_data
+        assert "confidence_explanation" in json_data
+        assert "sources" in json_data
+        assert json_data["response_type"] == "answer"
+        assert json_data["message"] == "Your answer here."
+        assert json_data["confidence_explanation"] == "High confidence."
+        assert json_data["sources"] == ["billing.md"]
+    
+    def test_escalation_json_schema(self):
+        """Escalation response should serialize to correct JSON schema."""
+        response = QuestionResponse(
+            response_type="escalation",
+            message="Connecting you with an agent.",
+            confidence_explanation="Low confidence.",
+            sources=None
+        )
+        
+        json_data = response.model_dump()
+        
+        assert json_data["response_type"] == "escalation"
+        assert json_data["message"] == "Connecting you with an agent."
+        assert json_data["confidence_explanation"] == "Low confidence."
+        assert json_data["sources"] is None
+    
+    def test_json_field_types(self):
+        """JSON fields should have correct types."""
+        response = QuestionResponse(
+            response_type="answer",
+            message="Answer",
+            confidence_explanation="Explanation",
+            sources=["test.md"]
+        )
+        
+        json_data = response.model_dump()
+        
+        assert isinstance(json_data["response_type"], str)
+        assert isinstance(json_data["message"], str)
+        assert isinstance(json_data["confidence_explanation"], str)
+        assert isinstance(json_data["sources"], list)
+    
+    def test_json_roundtrip(self):
+        """Should be able to serialize and deserialize."""
+        original = QuestionResponse(
+            response_type="answer",
+            message="Test answer",
+            confidence_explanation="Test explanation",
+            sources=["test.md"]
+        )
+        
+        # Serialize to dict
+        json_data = original.model_dump()
+        
+        # Deserialize back
+        restored = QuestionResponse(**json_data)
+        
+        assert restored.response_type == original.response_type
+        assert restored.message == original.message
+        assert restored.confidence_explanation == original.confidence_explanation
+        assert restored.sources == original.sources
+
+
+class TestResponseFieldContent:
+    """Test cases for response field content validation."""
+    
+    def test_message_not_empty(self):
+        """Message field should not be empty."""
+        # Pydantic doesn't enforce non-empty strings by default,
+        # but we can test that empty strings are technically allowed
+        # (business logic should prevent this)
+        response = QuestionResponse(
+            response_type="answer",
+            message="",
+            confidence_explanation="Explanation"
+        )
+        
+        assert response.message == ""
+    
+    def test_confidence_explanation_not_empty(self):
+        """Confidence explanation should not be empty."""
+        response = QuestionResponse(
+            response_type="answer",
+            message="Message",
+            confidence_explanation=""
+        )
+        
+        assert response.confidence_explanation == ""
+    
+    def test_response_type_literal_values(self):
+        """Response type should only accept 'answer' or 'escalation'."""
+        # Valid values
+        answer_response = QuestionResponse(
+            response_type="answer",
+            message="M",
+            confidence_explanation="E"
+        )
+        assert answer_response.response_type == "answer"
+        
+        escalation_response = QuestionResponse(
+            response_type="escalation",
+            message="M",
+            confidence_explanation="E"
+        )
+        assert escalation_response.response_type == "escalation"
+        
+        # Invalid value should raise error
+        with pytest.raises(ValidationError):
+            QuestionResponse(
+                response_type="unknown",
+                message="M",
+                confidence_explanation="E"
+            )
+
+
+class TestSourceReferenceFormatting:
+    """Test cases for source reference formatting."""
+    
+    def test_sources_as_list_of_strings(self):
+        """Sources should be a list of strings."""
+        response = QuestionResponse(
+            response_type="answer",
+            message="Answer",
+            confidence_explanation="Explanation",
+            sources=["billing.md", "permissions.md"]
+        )
+        
+        assert isinstance(response.sources, list)
+        assert all(isinstance(s, str) for s in response.sources)
+    
+    def test_sources_preserve_order(self):
+        """Sources list should preserve order."""
+        sources = ["c.md", "a.md", "b.md"]
+        response = QuestionResponse(
+            response_type="answer",
+            message="Answer",
+            confidence_explanation="Explanation",
+            sources=sources
+        )
+        
+        assert response.sources == sources
+    
+    def test_sources_allow_duplicates(self):
+        """Sources list should allow duplicates (though business logic may prevent this)."""
+        response = QuestionResponse(
+            response_type="answer",
+            message="Answer",
+            confidence_explanation="Explanation",
+            sources=["test.md", "test.md"]
+        )
+        
+        assert len(response.sources) == 2
+    
+    def test_escalation_typically_has_no_sources(self):
+        """Escalation responses typically have no sources."""
+        response = QuestionResponse(
+            response_type="escalation",
+            message="Escalating",
+            confidence_explanation="Low confidence",
+            sources=None
+        )
+        
+        assert response.sources is None
+    
+    def test_answer_can_have_sources(self):
+        """Answer responses can include sources."""
+        response = QuestionResponse(
+            response_type="answer",
+            message="Answer",
+            confidence_explanation="High confidence",
+            sources=["billing.md"]
+        )
+        
+        assert response.sources is not None
+        assert len(response.sources) > 0
+
+
+class TestResponseConsistency:
+    """Test cases for response schema consistency."""
+    
+    def test_all_responses_have_required_fields(self):
+        """All responses must have response_type, message, and confidence_explanation."""
+        # Answer response
+        answer = QuestionResponse(
+            response_type="answer",
+            message="A",
+            confidence_explanation="E"
+        )
+        assert hasattr(answer, "response_type")
+        assert hasattr(answer, "message")
+        assert hasattr(answer, "confidence_explanation")
+        assert hasattr(answer, "sources")
+        
+        # Escalation response
+        escalation = QuestionResponse(
+            response_type="escalation",
+            message="A",
+            confidence_explanation="E"
+        )
+        assert hasattr(escalation, "response_type")
+        assert hasattr(escalation, "message")
+        assert hasattr(escalation, "confidence_explanation")
+        assert hasattr(escalation, "sources")
+    
+    def test_response_type_determines_content(self):
+        """Response type should indicate whether it's an answer or escalation."""
+        answer = QuestionResponse(
+            response_type="answer",
+            message="Here is your answer",
+            confidence_explanation="High confidence"
+        )
+        
+        escalation = QuestionResponse(
+            response_type="escalation",
+            message="Let me connect you with an agent",
+            confidence_explanation="Low confidence"
+        )
+        
+        assert answer.response_type == "answer"
+        assert escalation.response_type == "escalation"
+        assert answer.response_type != escalation.response_type

vercel.json

@@ -0,0 +1,29 @@
+{
+  "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"
+  }
+}