updated

DEPLOY.md

@@ -0,0 +1,198 @@
+# HuggingFace Spaces Deployment Guide
+
+## Overview
+This guide walks you through deploying the HR Report Generator API on HuggingFace Spaces using Docker.
+
+---
+
+## Prerequisites
+
+1. **HuggingFace Account**: Create a free account at [huggingface.co](https://huggingface.co)
+2. **OpenRouter API Key**: Get your key from [openrouter.ai](https://openrouter.ai)
+
+---
+
+## Step-by-Step Deployment
+
+### Step 1: Create a New Space
+
+1. Go to [huggingface.co/new-space](https://huggingface.co/new-space)
+2. Fill in the details:
+   - **Space name**: `hr-report-api` (or your preferred name)
+   - **License**: Apache 2.0 (or your preference)
+   - **SDK**: Select **Docker**
+   - **Visibility**: Private (recommended for HR data)
+3. Click **Create Space**
+
+### Step 2: Upload Files
+
+Upload all files from this folder to your Space. The structure should be:
+
+```
+your-space/
+├── api.py
+├── Dockerfile
+├── requirements.txt
+├── endpoints.txt
+├── README.md
+└── src/
+    ├── __init__.py
+    ├── config.py
+    ├── rag/
+    │   ├── __init__.py
+    │   ├── synthesizer.py
+    │   ├── retriever.py
+    │   └── prompts.py
+    ├── knowledge/
+    │   ├── __init__.py
+    │   ├── vector_store.py
+    │   └── embeddings.py
+    └── document_processor/
+        ├── __init__.py
+        └── chunker.py
+```
+
+You can upload via:
+- **Web UI**: Drag and drop files
+- **Git**: Clone the repo and push
+
+```bash
+git clone https://huggingface.co/spaces/YOUR_USERNAME/hr-report-api
+cd hr-report-api
+# Copy all files from this folder
+git add .
+git commit -m "Initial deployment"
+git push
+```
+
+### Step 3: Configure Secrets
+
+Go to **Settings → Secrets** in your Space and add:
+
+| Secret Name | Value | Description |
+|-------------|-------|-------------|
+| `OPENROUTER_API_KEY` | `sk-or-...` | Your OpenRouter API key |
+| `ALLOWED_ORIGINS` | `https://checkin.hillsideprimarycare.com,https://hsmg.netlify.app` | Comma-separated allowed origins |
+| `LLM_MODEL` | `google/gemma-2-9b-it:free` | (Optional) Override model from endpoints.txt |
+
+### Step 4: Upload FAISS Index (Optional)
+
+If you have a pre-built FAISS index with HR policies:
+
+1. Create a `data/embeddings/` folder in your Space
+2. Upload:
+   - `faiss_index.faiss` - The FAISS index file
+   - `faiss_index.chunks.json` - The chunks metadata
+
+Without this, the API will still work but report "insufficient documentation."
+
+### Step 5: Verify Deployment
+
+1. Wait for the build to complete (1-3 minutes)
+2. Your API will be available at:
+   ```
+   https://YOUR_USERNAME-hr-report-api.hf.space
+   ```
+3. Check health: `https://YOUR_USERNAME-hr-report-api.hf.space/api/health`
+
+---
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/` | GET | API info and status |
+| `/api/health` | GET | Health check |
+| `/api/generate` | POST | Generate HR document |
+| `/api/status` | GET | Knowledge base status |
+| `/api/config` | GET | Public configuration |
+
+### Generate Document Example
+
+```javascript
+fetch('https://YOUR-SPACE.hf.space/api/generate', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+        doc_type: 'Memorandum',
+        employee_name: 'John Smith',
+        date_from: '2026-02-01',
+        date_to: '2026-02-01',
+        reason: 'Tardiness',
+        additional_notes: 'Employee arrived 30 minutes late.'
+    })
+})
+```
+
+---
+
+## Updating the LLM Model
+
+1. Edit `endpoints.txt` in your Space
+2. Uncomment the model you want to use
+3. The first uncommented line will be used
+
+```txt
+# Free Models:
+google/gemma-2-9b-it:free
+# meta-llama/llama-3.2-3b-instruct:free
+
+# Paid Models:
+# openai/gpt-4o
+```
+
+---
+
+## Origin Validation
+
+The API validates the `Origin` header against `ALLOWED_ORIGINS`. Only requests from these domains are allowed:
+
+- `https://checkin.hillsideprimarycare.com`
+- `https://hsmg.netlify.app`
+- `http://localhost:3000` (for development)
+- `http://localhost:5500`
+
+To add more origins, update the `ALLOWED_ORIGINS` secret (comma-separated).
+
+---
+
+## Troubleshooting
+
+### Build Fails
+- Check Dockerfile syntax
+- Ensure all files are uploaded
+- Check the build logs for errors
+
+### CORS Errors
+- Verify `ALLOWED_ORIGINS` includes your frontend domain
+- Make sure the domain has `https://` prefix
+
+### API Returns 500
+- Check if `OPENROUTER_API_KEY` is set correctly
+- Verify the model in `endpoints.txt` is available
+- Check Space logs for detailed errors
+
+### Slow Response
+- First request may be slow due to model loading (~30s)
+- Subsequent requests should be faster
+
+---
+
+## Cost
+
+| Component | Cost |
+|-----------|------|
+| HuggingFace Space | **Free** (with cold starts) |
+| OpenRouter (free models) | **Free** |
+| Total | **$0/month** |
+
+> **Note**: Free tier has 30-60 second cold starts when the Space sleeps after inactivity.
+
+---
+
+## Next Steps
+
+1. ✅ Deploy to HuggingFace Spaces
+2. ✅ Configure secrets
+3. ⏳ Deploy frontend to Netlify (see `netlify/DEPLOY.md`)
+4. ⏳ Test end-to-end integration

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Create data directories
+RUN mkdir -p data/embeddings data/outputs data/uploads
+
+# Expose port 7860 (HuggingFace default)
+EXPOSE 7860
+
+# Run with gunicorn
+CMD ["gunicorn", "--bind", "0.0.0.0:7860", "--workers", "2", "--timeout", "120", "api:app"]

README.md

@@ -1,10 +1,30 @@
----
-title: Hrbot
-emoji: 🐠
-colorFrom: purple
-colorTo: pink
-sdk: docker
-pinned: false
----
+# HR Report Generator - API Backend (HuggingFace Spaces Docker)
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+This folder contains the API backend for the HR Report Generator, designed to run on HuggingFace Spaces using Docker.
+
+## Structure
+```
+huggingface/
+├── api.py              # Flask API server
+├── Dockerfile          # Docker configuration
+├── requirements.txt    # Python dependencies
+├── endpoints.txt       # LLM endpoints (editable)
+├── src/                # Source modules
+│   ├── config.py
+│   ├── rag/
+│   │   ├── synthesizer.py
+│   │   ├── retriever.py
+│   │   └── prompts.py
+│   ├── knowledge/
+│   │   ├── vector_store.py
+│   │   └── embeddings.py
+│   └── document_processor/
+│       └── chunker.py
+├── data/               # Data directory (create on HF)
+│   └── embeddings/
+└── DEPLOY.md           # Deployment guide
+```
+
+## Files
+- **endpoints.txt**: Configure your LLM models here
+- **api.py**: Main Flask API with CORS origin validation

api.py

@@ -0,0 +1,297 @@
+"""HR Report Generator API - HuggingFace Spaces Backend.
+
+This Flask API serves as the backend for the HR Report Generator.
+It validates origins against allowed domains stored in HF secrets.
+"""
+
+import os
+from datetime import datetime
+from pathlib import Path
+from functools import wraps
+
+from flask import Flask, request, jsonify
+from flask_cors import CORS
+from dotenv import load_dotenv
+
+# Load environment variables
+load_dotenv()
+
+# Import our modules
+from src.config import settings
+from src.knowledge.vector_store import FAISSVectorStore
+from src.rag.synthesizer import ReportSynthesizer
+
+app = Flask(__name__)
+
+# ============================================
+# CORS and Origin Validation
+# ============================================
+
+# Allowed origins from environment (set in HF Secrets)
+# Format: comma-separated list of allowed origins
+ALLOWED_ORIGINS_STR = os.getenv("ALLOWED_ORIGINS", "")
+ALLOWED_ORIGINS = [
+    origin.strip() 
+    for origin in ALLOWED_ORIGINS_STR.split(",") 
+    if origin.strip()
+]
+
+# Default allowed origins if none specified
+if not ALLOWED_ORIGINS:
+    ALLOWED_ORIGINS = [
+        "https://checkin.hillsideprimarycare.com",
+        "https://hsmg.netlify.app",
+        "http://localhost:3000",
+        "http://localhost:5500",
+        "http://127.0.0.1:5500",
+    ]
+
+# Enable CORS with specific origins
+CORS(app, resources={
+    r"/api/*": {
+        "origins": ALLOWED_ORIGINS,
+        "methods": ["GET", "POST", "OPTIONS"],
+        "allow_headers": ["Content-Type", "Authorization"],
+    }
+})
+
+
+def validate_origin(f):
+    """Decorator to validate request origin against allowed list."""
+    @wraps(f)
+    def decorated_function(*args, **kwargs):
+        origin = request.headers.get("Origin", "")
+        referer = request.headers.get("Referer", "")
+        
+        # Check if origin or referer matches allowed origins
+        is_allowed = False
+        for allowed in ALLOWED_ORIGINS:
+            if origin.startswith(allowed) or referer.startswith(allowed):
+                is_allowed = True
+                break
+        
+        if not is_allowed and origin:  # Allow requests without origin (e.g., curl)
+            return jsonify({
+                "success": False,
+                "error": "Origin not allowed"
+            }), 403
+        
+        return f(*args, **kwargs)
+    return decorated_function
+
+
+# ============================================
+# Configuration
+# ============================================
+
+def get_active_model():
+    """Read the active model from endpoints.txt."""
+    endpoints_file = Path("endpoints.txt")
+    default_model = os.getenv("LLM_MODEL", "google/gemma-2-9b-it:free")
+    
+    if not endpoints_file.exists():
+        return default_model
+    
+    try:
+        content = endpoints_file.read_text()
+        for line in content.splitlines():
+            line = line.strip()
+            # Skip comments and empty lines
+            if line and not line.startswith("#"):
+                return line
+    except Exception:
+        pass
+    
+    return default_model
+
+
+# Document type templates
+DOCUMENT_TEMPLATES = {
+    'Memorandum': {
+        'title': 'MEMORANDUM FOR PERSONNEL FILE',
+        'sections': [
+            'Purpose of Document',
+            'Incident Background',
+            'Policy References',
+            'Employee Discussion',
+            'Corrective Measures',
+            'Conclusion'
+        ]
+    },
+    'Termination Letter': {
+        'title': 'EMPLOYEE TERMINATION LETTER',
+        'sections': [
+            'Purpose of Document',
+            'Employment History',
+            'Reason for Termination',
+            'Policy Violations',
+            'Previous Warnings',
+            'Final Pay and Benefits',
+            'Return of Company Property'
+        ]
+    },
+    'Written Disciplinary Action': {
+        'title': 'WRITTEN DISCIPLINARY ACTION',
+        'sections': [
+            'Purpose of Document',
+            'Incident Details',
+            'Policy References',
+            'Previous Coaching / Warnings',
+            'Corrective Action Required',
+            'Employee Acknowledgment'
+        ]
+    },
+    '90 Day Performance Evaluation': {
+        'title': '90-DAY PERFORMANCE EVALUATION',
+        'sections': [
+            'Evaluation Period',
+            'Performance Summary',
+            'Areas of Strength',
+            'Areas for Improvement',
+            'Goals for Next Period',
+            'Recommendation'
+        ]
+    }
+}
+
+
+# ============================================
+# API Routes
+# ============================================
+
+@app.route('/')
+def index():
+    """Health check and API info."""
+    return jsonify({
+        "status": "ok",
+        "service": "HR Report Generator API",
+        "version": "1.0.0",
+        "allowed_origins": ALLOWED_ORIGINS,
+        "active_model": get_active_model(),
+    })
+
+
+@app.route('/api/health')
+def health():
+    """Health check endpoint."""
+    return jsonify({"status": "healthy"})
+
+
+@app.route('/api/generate', methods=['POST', 'OPTIONS'])
+@validate_origin
+def generate_report():
+    """Generate an HR document based on type."""
+    if request.method == 'OPTIONS':
+        return '', 204
+    
+    try:
+        data = request.json
+        
+        doc_type = data.get('doc_type', 'Memorandum')
+        employee_name = data.get('employee_name', '')
+        date_from = data.get('date_from', '')
+        date_to = data.get('date_to', '')
+        reason = data.get('reason', '')
+        additional_notes = data.get('additional_notes', '')
+        
+        if not all([employee_name, date_from, reason]):
+            return jsonify({'success': False, 'error': 'Missing required fields'}), 400
+        
+        # Format date range
+        if date_to and date_to != date_from:
+            incident_date_range = f"{date_from} to {date_to}"
+        else:
+            incident_date_range = date_from
+        
+        # Get document template info
+        template_info = DOCUMENT_TEMPLATES.get(doc_type, DOCUMENT_TEMPLATES['Memorandum'])
+        
+        # Get active model from endpoints.txt
+        model_name = get_active_model()
+        
+        # Build the synthesizer input
+        synth_input = {
+            'employee_name': employee_name,
+            'incident_date_range': incident_date_range,
+            'incident_reason': additional_notes or reason,
+            'violation_type': reason,
+            'report_date': datetime.now().strftime('%Y-%m-%d'),
+            'doc_type': doc_type,
+            'doc_title': template_info['title'],
+            'required_sections': template_info['sections'],
+        }
+        
+        # Generate the report
+        synthesizer = ReportSynthesizer(model_name=model_name)
+        result = synthesizer.synthesize_from_dict(synth_input)
+        
+        if not result.success:
+            return jsonify({'success': False, 'error': result.error}), 500
+        
+        return jsonify({
+            'success': True,
+            'markdown': result.markdown_report,
+            'validation': {
+                'is_valid': True,
+                'errors': [],
+                'warnings': [],
+            },
+            'sources': result.retrieval_context.sources_used,
+            'model_used': model_name,
+        })
+        
+    except Exception as e:
+        import traceback
+        traceback.print_exc()
+        return jsonify({'success': False, 'error': str(e)}), 500
+
+
+@app.route('/api/status')
+@validate_origin
+def get_status():
+    """Get system status."""
+    try:
+        vector_store = FAISSVectorStore()
+        loaded = vector_store.load()
+        
+        return jsonify({
+            'knowledge_base': {
+                'loaded': loaded,
+                'chunks': vector_store.size if loaded else 0,
+                'sources': vector_store.get_sources() if loaded else [],
+            },
+            'active_model': get_active_model(),
+            'allowed_origins': ALLOWED_ORIGINS,
+        })
+    except Exception as e:
+        return jsonify({
+            'knowledge_base': {'loaded': False, 'chunks': 0, 'sources': []},
+            'error': str(e),
+        })
+
+
+@app.route('/api/config')
+def get_config():
+    """Get public configuration (no secrets)."""
+    return jsonify({
+        'document_types': list(DOCUMENT_TEMPLATES.keys()),
+        'active_model': get_active_model(),
+    })
+
+
+# ============================================
+# Main
+# ============================================
+
+if __name__ == '__main__':
+    # Ensure directories exist
+    settings.ensure_directories()
+    
+    print("=" * 50)
+    print("HR Report Generator API")
+    print("=" * 50)
+    print(f"Active Model: {get_active_model()}")
+    print(f"Allowed Origins: {ALLOWED_ORIGINS}")
+    print("=" * 50)
+    
+    app.run(host='0.0.0.0', port=7860, debug=True)

endpoints.txt

@@ -0,0 +1,14 @@
+# LLM Endpoints Configuration
+# Edit this file to change the model used by the API
+# Format: model_name (one per line, first uncommented line is used)
+
+# Free OpenRouter Models:
+google/gemma-2-9b-it:free
+# meta-llama/llama-3.2-3b-instruct:free
+# mistralai/mistral-7b-instruct:free
+# google/gemini-pro-1.5-exp
+
+# Paid Models (if you have credits):
+# anthropic/claude-3.5-sonnet
+# openai/gpt-4o
+# meta-llama/llama-3.1-70b-instruct

requirements.txt

@@ -0,0 +1,21 @@
+# Flask and API
+flask>=3.0.0
+gunicorn>=21.0.0
+flask-cors>=4.0.0
+python-dotenv>=1.0.0
+requests>=2.31.0
+
+# Pydantic for data validation
+pydantic>=2.0.0
+pydantic-settings>=2.0.0
+
+# Vector store and embeddings
+faiss-cpu>=1.7.4
+sentence-transformers>=2.2.0
+numpy>=1.24.0
+
+# Document processing
+PyYAML>=6.0.0
+
+# File handling
+werkzeug>=3.0.0

src/__init__.py

@@ -0,0 +1,11 @@
+"""HR Report Generator - HuggingFace Spaces Backend."""
+
+from src.config import settings
+from src.rag import ReportSynthesizer
+from src.knowledge import FAISSVectorStore
+
+__all__ = [
+    "settings",
+    "ReportSynthesizer",
+    "FAISSVectorStore",
+]

src/config.py

@@ -0,0 +1,63 @@
+"""HR Report Generator - Configuration Module (HuggingFace Version)."""
+
+from pathlib import Path
+from typing import Literal
+import os
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # LLM Configuration (loaded from environment or endpoints.txt)
+    llm_model: str = Field(default="google/gemma-2-9b-it:free", description="LLM model name")
+    llm_temperature: float = Field(default=0.0, ge=0.0, le=1.0, description="LLM temperature")
+
+    # Embedding Configuration
+    embedding_model: str = Field(
+        default="BAAI/bge-small-en-v1.5",
+        description="HuggingFace embedding model",
+    )
+
+    # Paths (relative for Docker)
+    data_dir: Path = Field(default=Path("./data"))
+    documents_dir: Path = Field(default=Path("./data/documents"))
+    markdown_dir: Path = Field(default=Path("./data/markdown"))
+    embeddings_dir: Path = Field(default=Path("./data/embeddings"))
+    outputs_dir: Path = Field(default=Path("./data/outputs"))
+    templates_dir: Path = Field(default=Path("./templates"))
+
+    # Vector Store
+    faiss_index_path: Path = Field(default=Path("./data/embeddings/faiss_index"))
+
+    # Chunking Configuration
+    chunk_size: int = Field(default=512, description="Target chunk size in tokens")
+    chunk_overlap: int = Field(default=50, description="Overlap between chunks")
+
+    # Retrieval Configuration
+    retrieval_top_k: int = Field(default=5, description="Number of documents to retrieve")
+    retrieval_min_score: float = Field(default=0.3, description="Minimum similarity score")
+
+    def ensure_directories(self) -> None:
+        """Create all required directories if they don't exist."""
+        for path in [
+            self.data_dir,
+            self.documents_dir,
+            self.markdown_dir,
+            self.embeddings_dir,
+            self.outputs_dir,
+            self.templates_dir,
+        ]:
+            path.mkdir(parents=True, exist_ok=True)
+
+
+# Global settings instance
+settings = Settings()

src/document_processor/__init__.py

@@ -0,0 +1,8 @@
+"""Document processor module for HR Report Generator."""
+
+from src.document_processor.chunker import DocumentChunk, SemanticChunker
+
+__all__ = [
+    "DocumentChunk",
+    "SemanticChunker",
+]

src/document_processor/chunker.py

@@ -0,0 +1,209 @@
+"""Semantic document chunker for RAG processing."""
+
+import re
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel
+
+from src.config import settings
+
+
+class DocumentChunk(BaseModel):
+    """A chunk of document content with metadata."""
+
+    content: str
+    source_file: str
+    chunk_index: int
+    start_char: int
+    end_char: int
+    section_title: Optional[str] = None
+    page_hint: Optional[str] = None
+
+    @property
+    def chunk_id(self) -> str:
+        """Generate unique chunk identifier."""
+        return f"{Path(self.source_file).stem}_{self.chunk_index:04d}"
+
+
+class SemanticChunker:
+    """Chunks Markdown documents by semantic boundaries.
+
+    Respects document structure (headers, paragraphs, lists) while
+    maintaining target chunk sizes for optimal embedding performance.
+    """
+
+    def __init__(
+        self,
+        chunk_size: int = None,
+        chunk_overlap: int = None,
+    ):
+        """Initialize the chunker.
+
+        Args:
+            chunk_size: Target chunk size in characters.
+            chunk_overlap: Overlap between chunks in characters.
+        """
+        self.chunk_size = chunk_size or settings.chunk_size
+        self.chunk_overlap = chunk_overlap or settings.chunk_overlap
+
+        # Patterns for semantic splitting
+        self._header_pattern = re.compile(r"^(#{1,6})\s+(.+)$", re.MULTILINE)
+        self._section_break_pattern = re.compile(r"\n{3,}")
+        self._list_item_pattern = re.compile(r"^[\s]*[-*+]\s+", re.MULTILINE)
+
+    def _extract_frontmatter(self, content: str) -> tuple[dict, str]:
+        """Extract YAML frontmatter from markdown content."""
+        frontmatter = {}
+        body = content
+
+        if content.startswith("---"):
+            parts = content.split("---", 2)
+            if len(parts) >= 3:
+                import yaml
+
+                try:
+                    frontmatter = yaml.safe_load(parts[1]) or {}
+                except Exception:
+                    pass
+                body = parts[2].strip()
+
+        return frontmatter, body
+
+    def _find_section_boundaries(self, content: str) -> list[tuple[int, int, str]]:
+        """Find semantic section boundaries based on headers.
+
+        Returns list of (start_pos, end_pos, section_title) tuples.
+        """
+        boundaries = []
+        headers = list(self._header_pattern.finditer(content))
+
+        if not headers:
+            return [(0, len(content), "Document")]
+
+        # Add content before first header if exists
+        if headers[0].start() > 0:
+            boundaries.append((0, headers[0].start(), "Preamble"))
+
+        # Add each section
+        for i, header in enumerate(headers):
+            start = header.start()
+            end = headers[i + 1].start() if i + 1 < len(headers) else len(content)
+            title = header.group(2).strip()
+            boundaries.append((start, end, title))
+
+        return boundaries
+
+    def _split_section(self, content: str, section_title: str) -> list[str]:
+        """Split a section into smaller chunks respecting boundaries."""
+        if len(content) <= self.chunk_size:
+            return [content] if content.strip() else []
+
+        chunks = []
+        current_chunk = ""
+
+        # Split by paragraphs first
+        paragraphs = re.split(r"\n\n+", content)
+
+        for para in paragraphs:
+            para = para.strip()
+            if not para:
+                continue
+
+            # If paragraph alone exceeds chunk size, split by sentences
+            if len(para) > self.chunk_size:
+                sentences = re.split(r"(?<=[.!?])\s+", para)
+                for sentence in sentences:
+                    if len(current_chunk) + len(sentence) + 1 <= self.chunk_size:
+                        current_chunk += (" " if current_chunk else "") + sentence
+                    else:
+                        if current_chunk:
+                            chunks.append(current_chunk)
+                        current_chunk = sentence
+            elif len(current_chunk) + len(para) + 2 <= self.chunk_size:
+                current_chunk += ("\n\n" if current_chunk else "") + para
+            else:
+                if current_chunk:
+                    chunks.append(current_chunk)
+                current_chunk = para
+
+        if current_chunk.strip():
+            chunks.append(current_chunk)
+
+        return chunks
+
+    def _add_overlap(self, chunks: list[str]) -> list[str]:
+        """Add overlap between chunks for context preservation."""
+        if self.chunk_overlap <= 0 or len(chunks) <= 1:
+            return chunks
+
+        overlapped = []
+        for i, chunk in enumerate(chunks):
+            if i > 0:
+                # Add end of previous chunk as prefix
+                prev_chunk = chunks[i - 1]
+                overlap_text = prev_chunk[-self.chunk_overlap :].strip()
+                if overlap_text:
+                    chunk = f"...{overlap_text}\n\n{chunk}"
+            overlapped.append(chunk)
+
+        return overlapped
+
+    def chunk_document(self, markdown_path: Path) -> list[DocumentChunk]:
+        """Chunk a Markdown document into semantic pieces.
+
+        Args:
+            markdown_path: Path to the Markdown file.
+
+        Returns:
+            List of DocumentChunks with metadata.
+        """
+        markdown_path = Path(markdown_path)
+        content = markdown_path.read_text(encoding="utf-8")
+
+        frontmatter, body = self._extract_frontmatter(content)
+        source_file = frontmatter.get("source", markdown_path.name)
+
+        sections = self._find_section_boundaries(body)
+        all_chunks = []
+        chunk_index = 0
+
+        for start_pos, end_pos, section_title in sections:
+            section_content = body[start_pos:end_pos].strip()
+            if not section_content:
+                continue
+
+            section_chunks = self._split_section(section_content, section_title)
+            section_chunks = self._add_overlap(section_chunks)
+
+            for chunk_content in section_chunks:
+                if not chunk_content.strip():
+                    continue
+
+                chunk = DocumentChunk(
+                    content=chunk_content,
+                    source_file=str(markdown_path),
+                    chunk_index=chunk_index,
+                    start_char=start_pos,
+                    end_char=end_pos,
+                    section_title=section_title,
+                )
+                all_chunks.append(chunk)
+                chunk_index += 1
+
+        return all_chunks
+
+    def chunk_documents(self, markdown_paths: list[Path]) -> list[DocumentChunk]:
+        """Chunk multiple Markdown documents.
+
+        Args:
+            markdown_paths: List of paths to Markdown files.
+
+        Returns:
+            List of all DocumentChunks from all documents.
+        """
+        all_chunks = []
+        for path in markdown_paths:
+            chunks = self.chunk_document(path)
+            all_chunks.extend(chunks)
+        return all_chunks

src/knowledge/__init__.py

@@ -0,0 +1,10 @@
+"""Knowledge module for HR Report Generator."""
+
+from src.knowledge.vector_store import FAISSVectorStore, RetrievalResult
+from src.knowledge.embeddings import EmbeddingModel
+
+__all__ = [
+    "FAISSVectorStore",
+    "RetrievalResult",
+    "EmbeddingModel",
+]

src/knowledge/embeddings.py

@@ -0,0 +1,101 @@
+"""Embedding model wrapper for document vectorization."""
+
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+from sentence_transformers import SentenceTransformer
+
+from src.config import settings
+from src.document_processor.chunker import DocumentChunk
+
+
+class EmbeddingModel:
+    """Wrapper for sentence-transformers embedding models.
+
+    Provides efficient batch embedding with caching support.
+    """
+
+    def __init__(self, model_name: Optional[str] = None):
+        """Initialize the embedding model.
+
+        Args:
+            model_name: HuggingFace model name. Defaults to settings.embedding_model.
+        """
+        self.model_name = model_name or settings.embedding_model
+        self._model: Optional[SentenceTransformer] = None
+
+    @property
+    def model(self) -> SentenceTransformer:
+        """Lazy load the embedding model."""
+        if self._model is None:
+            self._model = SentenceTransformer(self.model_name)
+        return self._model
+
+    @property
+    def embedding_dimension(self) -> int:
+        """Get the dimension of embeddings produced by this model."""
+        return self.model.get_sentence_embedding_dimension()
+
+    def embed_text(self, text: str) -> np.ndarray:
+        """Embed a single text string.
+
+        Args:
+            text: Text to embed.
+
+        Returns:
+            Embedding vector as numpy array.
+        """
+        return self.model.encode(text, convert_to_numpy=True, normalize_embeddings=True)
+
+    def embed_texts(self, texts: list[str], batch_size: int = 32) -> np.ndarray:
+        """Embed multiple texts efficiently.
+
+        Args:
+            texts: List of texts to embed.
+            batch_size: Batch size for processing.
+
+        Returns:
+            Array of embedding vectors (num_texts x embedding_dim).
+        """
+        return self.model.encode(
+            texts,
+            batch_size=batch_size,
+            convert_to_numpy=True,
+            normalize_embeddings=True,
+            show_progress_bar=len(texts) > 100,
+        )
+
+    def embed_chunks(
+        self, chunks: list[DocumentChunk], batch_size: int = 32
+    ) -> list[tuple[DocumentChunk, np.ndarray]]:
+        """Embed document chunks with their metadata.
+
+        Args:
+            chunks: List of DocumentChunks to embed.
+            batch_size: Batch size for processing.
+
+        Returns:
+            List of (chunk, embedding) tuples.
+        """
+        texts = [chunk.content for chunk in chunks]
+        embeddings = self.embed_texts(texts, batch_size=batch_size)
+
+        return list(zip(chunks, embeddings))
+
+    def embed_query(self, query: str) -> np.ndarray:
+        """Embed a query for retrieval.
+
+        Some models use different prompting for queries vs documents.
+
+        Args:
+            query: Query text to embed.
+
+        Returns:
+            Query embedding vector.
+        """
+        # BGE models benefit from query prefixes
+        if "bge" in self.model_name.lower():
+            query = f"Represent this sentence for searching relevant passages: {query}"
+
+        return self.embed_text(query)

src/knowledge/vector_store.py

@@ -0,0 +1,205 @@
+"""FAISS vector store for document retrieval."""
+
+import json
+import pickle
+from pathlib import Path
+from typing import Optional
+
+import faiss
+import numpy as np
+from pydantic import BaseModel
+
+from src.config import settings
+from src.document_processor.chunker import DocumentChunk
+from src.knowledge.embeddings import EmbeddingModel
+
+
+class RetrievalResult(BaseModel):
+    """Result from vector store retrieval."""
+
+    chunk: DocumentChunk
+    score: float
+    rank: int
+
+    class Config:
+        arbitrary_types_allowed = True
+
+
+class FAISSVectorStore:
+    """FAISS-based vector store for efficient similarity search.
+
+    Stores document chunks with their embeddings and provides
+    fast retrieval with source tracking for citations.
+    """
+
+    def __init__(
+        self,
+        embedding_model: Optional[EmbeddingModel] = None,
+        index_path: Optional[Path] = None,
+    ):
+        """Initialize the vector store.
+
+        Args:
+            embedding_model: Model for generating embeddings.
+            index_path: Path to store/load the FAISS index.
+        """
+        self.embedding_model = embedding_model or EmbeddingModel()
+        self.index_path = Path(index_path or settings.faiss_index_path)
+
+        self._index: Optional[faiss.IndexFlatIP] = None
+        self._chunks: list[DocumentChunk] = []
+        self._is_loaded = False
+
+    def _ensure_directory(self) -> None:
+        """Ensure the index directory exists."""
+        self.index_path.parent.mkdir(parents=True, exist_ok=True)
+
+    def _create_index(self, dimension: int) -> faiss.IndexFlatIP:
+        """Create a new FAISS index.
+
+        Uses Inner Product (IP) since embeddings are normalized.
+        """
+        return faiss.IndexFlatIP(dimension)
+
+    def add_chunks(self, chunks: list[DocumentChunk]) -> int:
+        """Add document chunks to the vector store.
+
+        Args:
+            chunks: List of DocumentChunks to add.
+
+        Returns:
+            Number of chunks added.
+        """
+        if not chunks:
+            return 0
+
+        # Generate embeddings
+        chunk_embeddings = self.embedding_model.embed_chunks(chunks)
+
+        # Initialize index if needed
+        if self._index is None:
+            dimension = self.embedding_model.embedding_dimension
+            self._index = self._create_index(dimension)
+
+        # Add to index
+        embeddings_array = np.vstack([emb for _, emb in chunk_embeddings])
+        self._index.add(embeddings_array)
+
+        # Store chunks for retrieval
+        for chunk, _ in chunk_embeddings:
+            self._chunks.append(chunk)
+
+        return len(chunks)
+
+    def search(
+        self,
+        query: str,
+        top_k: int = None,
+        min_score: float = None,
+    ) -> list[RetrievalResult]:
+        """Search for relevant chunks.
+
+        Args:
+            query: Search query.
+            top_k: Number of results to return.
+            min_score: Minimum similarity score threshold.
+
+        Returns:
+            List of RetrievalResults ordered by relevance.
+        """
+        if self._index is None or self._index.ntotal == 0:
+            return []
+
+        top_k = top_k or settings.retrieval_top_k
+        min_score = min_score or settings.retrieval_min_score
+
+        # Embed query
+        query_embedding = self.embedding_model.embed_query(query)
+        query_embedding = query_embedding.reshape(1, -1)
+
+        # Search
+        scores, indices = self._index.search(query_embedding, min(top_k, self._index.ntotal))
+
+        # Build results
+        results = []
+        for rank, (score, idx) in enumerate(zip(scores[0], indices[0])):
+            if idx < 0 or score < min_score:
+                continue
+
+            chunk = self._chunks[idx]
+            results.append(
+                RetrievalResult(
+                    chunk=chunk,
+                    score=float(score),
+                    rank=rank + 1,
+                )
+            )
+
+        return results
+
+    def save(self) -> None:
+        """Save the index and chunks to disk."""
+        if self._index is None:
+            return
+
+        self._ensure_directory()
+
+        # Save FAISS index
+        index_file = self.index_path.with_suffix(".faiss")
+        faiss.write_index(self._index, str(index_file))
+
+        # Save chunks as JSON
+        chunks_file = self.index_path.with_suffix(".chunks.json")
+        chunks_data = [chunk.model_dump() for chunk in self._chunks]
+        chunks_file.write_text(json.dumps(chunks_data, indent=2), encoding="utf-8")
+
+    def load(self) -> bool:
+        """Load the index and chunks from disk.
+
+        Returns:
+            True if loaded successfully, False otherwise.
+        """
+        index_file = self.index_path.with_suffix(".faiss")
+        chunks_file = self.index_path.with_suffix(".chunks.json")
+
+        if not index_file.exists() or not chunks_file.exists():
+            return False
+
+        try:
+            # Load FAISS index
+            self._index = faiss.read_index(str(index_file))
+
+            # Load chunks
+            chunks_data = json.loads(chunks_file.read_text(encoding="utf-8"))
+            self._chunks = [DocumentChunk.model_validate(c) for c in chunks_data]
+
+            self._is_loaded = True
+            return True
+
+        except Exception as e:
+            print(f"Error loading index: {e}")
+            return False
+
+    def clear(self) -> None:
+        """Clear the index and all stored chunks."""
+        self._index = None
+        self._chunks = []
+        self._is_loaded = False
+
+        # Remove files if they exist
+        index_file = self.index_path.with_suffix(".faiss")
+        chunks_file = self.index_path.with_suffix(".chunks.json")
+
+        if index_file.exists():
+            index_file.unlink()
+        if chunks_file.exists():
+            chunks_file.unlink()
+
+    @property
+    def size(self) -> int:
+        """Get the number of chunks in the store."""
+        return len(self._chunks)
+
+    def get_sources(self) -> list[str]:
+        """Get list of unique source files in the store."""
+        return list(set(chunk.source_file for chunk in self._chunks))

src/rag/__init__.py

@@ -0,0 +1,12 @@
+"""RAG module for HR Report Generator."""
+
+from src.rag.synthesizer import ReportSynthesizer, ReportInput, SynthesisResult
+from src.rag.retriever import DocumentRetriever, RetrievalContext
+
+__all__ = [
+    "ReportSynthesizer",
+    "ReportInput", 
+    "SynthesisResult",
+    "DocumentRetriever",
+    "RetrievalContext",
+]

src/rag/prompts.py

@@ -0,0 +1,155 @@
+"""Prompt templates for HR report generation.
+
+All prompts enforce strict grounding to retrieved content with
+zero tolerance for hallucination or invention of facts.
+"""
+
+# System prompt that enforces strict RAG constraints with document type awareness
+SYSTEM_PROMPT = """You are an HR Documentation Assistant that generates professional HR documents.
+
+## CRITICAL CONSTRAINTS - FOLLOW EXACTLY
+
+1. **ONLY USE PROVIDED CONTEXT**: You may ONLY include information from the documents provided below. Do NOT invent, assume, or generalize any facts.
+
+2. **CITE EVERYTHING**: Every factual claim MUST reference its source document and section.
+
+3. **NO HALLUCINATION**: If information is not in the provided context, you MUST state "No documentation available" for that section.
+
+4. **PROFESSIONAL TONE**: Use neutral, factual HR language. No opinions, no emotional language, no speculation.
+
+5. **DETERMINISTIC**: Given the same inputs and context, produce identical outputs every time.
+
+## POLICY REFERENCE FORMAT - VERY IMPORTANT
+
+When citing policies, use this EXACT format for clarity:
+- **Policy Title**: State the exact policy name (e.g., "Attendance and Punctuality Policy")
+- **Source Document**: Reference the handbook or document name
+- **Section**: Include section number if available
+- **Relevant Text**: Quote the specific policy language in quotation marks
+
+Example:
+- Attendance and Punctuality, Hillside Medical Group Employee Handbook, Section 3.2: "Employees are considered tardy if they arrive at their work area 5 minutes after their scheduled starting time. Progressive discipline will begin with the second tardy offense within a 90-day period."
+
+## OUTPUT STRUCTURE
+
+Generate the document following this structure exactly:
+
+```markdown
+# [Document Title]
+
+**Employee Name:** [employee_name]  
+**Document Date:** [report_date]  
+**Incident Date(s):** [incident_date_range]
+**Prepared By:** Human Resources Department
+
+## Purpose of Document
+[Brief statement of why this document is being created]
+
+## Incident Background
+[Factual description of what occurred - synthesized ONLY from provided context]
+
+## Policy References
+[List specific policies with DETAILED citations. Include:
+- Full policy name
+- Source document
+- Section number (if available)
+- Exact quoted text from policy in quotation marks
+If no policies found, state "No relevant policy documentation available."]
+
+## Previous Coaching / Warnings
+[Summary of prior warnings from context with dates and specifics. If none found, state "No prior warning documentation available."]
+
+## Corrective Action Required
+[Specific actions required - ONLY if stated in context. Otherwise: "Action pending HR review."]
+
+## Employee Acknowledgment
+Employee signature: ___________________ Date: ___________
+Supervisor signature: _________________ Date: ___________
+```
+
+## VALIDATION CHECKLIST (Self-verify before outputting)
+
+- [ ] Every fact traces to a provided document
+- [ ] All policy citations include source, section, and quoted text
+- [ ] No invented dates, names, or actions
+- [ ] Professional, neutral language throughout
+"""
+
+# Template for the user message with context
+USER_MESSAGE_TEMPLATE = """## DOCUMENT INFORMATION
+
+- **Document Type:** {doc_type}
+- **Employee Name:** {employee_name}
+- **Document Date:** {report_date}
+- **Incident Date(s):** {incident_date_range}
+- **Incident Reason:** {incident_reason}
+- **Violation Type:** {violation_type}
+
+---
+
+## RETRIEVED POLICY DOCUMENTS
+
+The following policy documents contain relevant information. Use these for the Policy References section:
+
+{policy_context}
+
+---
+
+## RETRIEVED WARNING/COACHING DOCUMENTS
+
+The following documents contain prior warning/coaching records:
+
+{warnings_context}
+
+---
+
+## INSTRUCTIONS
+
+1. Generate the HR document using ONLY the information provided above.
+2. For the Policy References section:
+   - Extract and quote the EXACT policy language from the context
+   - Include the source document name
+   - Include section numbers where available
+   - Format each reference clearly with the policy title, source, and quoted text
+3. Cite specific sections for all factual claims.
+4. State "No documentation available" for any section without supporting context.
+5. Use professional, neutral HR language throughout.
+"""
+
+# Template for formatting retrieved chunks as context
+CONTEXT_CHUNK_TEMPLATE = """### Source: {source_file}
+**Section:** {section_title}
+**Relevance Score:** {score:.2f}
+
+{content}
+
+---
+"""
+
+# Refusal response for insufficient evidence
+INSUFFICIENT_EVIDENCE_RESPONSE = """# HR Incident Report
+
+**Employee Name:** {employee_name}  
+**Document Date:** {report_date}  
+**Incident Date(s):** {incident_date_range}
+**Prepared By:** Human Resources Department
+
+## Purpose of Document
+To document {incident_reason} incident(s).
+
+## Incident Background
+Insufficient documentation available to generate incident summary.
+
+## Policy References
+No relevant policy documentation available. Please ensure policy documents have been ingested into the system.
+
+## Previous Coaching / Warnings
+No prior warning documentation available.
+
+## Corrective Action Required
+Report generation incomplete. Please ingest relevant HR documentation before proceeding.
+
+---
+
+**⚠️ NOTICE:** This report could not be completed due to insufficient documentation in the knowledge base. Please add relevant HR policy documents and any prior coaching/warning records, then regenerate this report.
+"""

src/rag/retriever.py

@@ -0,0 +1,177 @@
+"""Document retriever for RAG pipeline."""
+
+from pathlib import Path
+from typing import Optional
+
+from pydantic import BaseModel
+
+from src.config import settings
+from src.knowledge.vector_store import FAISSVectorStore, RetrievalResult
+from src.rag.prompts import CONTEXT_CHUNK_TEMPLATE
+
+
+class RetrievalContext(BaseModel):
+    """Context retrieved for report generation."""
+
+    policy_results: list[RetrievalResult]
+    warning_results: list[RetrievalResult]
+    policy_context_text: str
+    warnings_context_text: str
+    has_sufficient_evidence: bool
+    sources_used: list[str]
+
+    class Config:
+        arbitrary_types_allowed = True
+
+
+class DocumentRetriever:
+    """Retrieves relevant documents for HR report generation.
+
+    Separates retrieval into policy documents and warning/coaching
+    documents to ensure proper context for each report section.
+    """
+
+    def __init__(self, vector_store: Optional[FAISSVectorStore] = None):
+        """Initialize the retriever.
+
+        Args:
+            vector_store: Vector store to search. Creates new one if not provided.
+        """
+        self.vector_store = vector_store or FAISSVectorStore()
+
+        # Try to load existing index
+        if not self.vector_store._is_loaded:
+            self.vector_store.load()
+
+    def _format_results_as_context(self, results: list[RetrievalResult]) -> str:
+        """Format retrieval results as context string for the LLM."""
+        if not results:
+            return "No relevant documents found."
+
+        context_parts = []
+        for result in results:
+            formatted = CONTEXT_CHUNK_TEMPLATE.format(
+                source_file=Path(result.chunk.source_file).name,
+                section_title=result.chunk.section_title or "General",
+                score=result.score,
+                content=result.chunk.content,
+            )
+            context_parts.append(formatted)
+
+        return "\n".join(context_parts)
+
+    def _classify_results(
+        self, results: list[RetrievalResult]
+    ) -> tuple[list[RetrievalResult], list[RetrievalResult]]:
+        """Classify results into policy and warning categories.
+
+        Uses simple heuristics based on source filename and content.
+        """
+        policy_results = []
+        warning_results = []
+
+        policy_keywords = ["policy", "handbook", "manual", "guideline", "procedure"]
+        warning_keywords = ["warning", "coaching", "counseling", "disciplinary", "incident"]
+
+        for result in results:
+            source_lower = Path(result.chunk.source_file).stem.lower()
+            content_lower = result.chunk.content.lower()
+
+            # Check if it's a warning/coaching document
+            is_warning = any(kw in source_lower for kw in warning_keywords) or any(
+                kw in content_lower[:200] for kw in warning_keywords
+            )
+
+            # Check if it's a policy document
+            is_policy = any(kw in source_lower for kw in policy_keywords) or any(
+                kw in content_lower[:200] for kw in policy_keywords
+            )
+
+            if is_warning:
+                warning_results.append(result)
+            elif is_policy:
+                policy_results.append(result)
+            else:
+                # Default to policy if unclear
+                policy_results.append(result)
+
+        return policy_results, warning_results
+
+    def retrieve(
+        self,
+        employee_name: str,
+        violation_type: str,
+        incident_reason: str,
+        top_k: int = None,
+        min_score: float = None,
+    ) -> RetrievalContext:
+        """Retrieve relevant context for report generation.
+
+        Args:
+            employee_name: Name of the employee.
+            violation_type: Type of violation (e.g., "Tardiness").
+            incident_reason: Description of the incident.
+            top_k: Number of results per query.
+            min_score: Minimum similarity score.
+
+        Returns:
+            RetrievalContext with categorized results.
+        """
+        top_k = top_k or settings.retrieval_top_k
+        min_score = min_score or settings.retrieval_min_score
+
+        # Build search queries
+        policy_query = f"{violation_type} policy procedure disciplinary action"
+        warning_query = f"{employee_name} warning coaching disciplinary {violation_type}"
+        incident_query = f"{incident_reason} {violation_type}"
+
+        # Execute searches
+        policy_results = self.vector_store.search(policy_query, top_k=top_k, min_score=min_score)
+        warning_results = self.vector_store.search(warning_query, top_k=top_k, min_score=min_score)
+        incident_results = self.vector_store.search(
+            incident_query, top_k=top_k, min_score=min_score
+        )
+
+        # Combine and deduplicate
+        all_results = {}
+        for result in policy_results + warning_results + incident_results:
+            chunk_id = result.chunk.chunk_id
+            if chunk_id not in all_results or result.score > all_results[chunk_id].score:
+                all_results[chunk_id] = result
+
+        # Re-classify all results
+        all_results_list = sorted(all_results.values(), key=lambda r: r.score, reverse=True)
+        policy_classified, warning_classified = self._classify_results(all_results_list)
+
+        # Format as context text
+        policy_context = self._format_results_as_context(policy_classified)
+        warnings_context = self._format_results_as_context(warning_classified)
+
+        # Determine if we have sufficient evidence
+        has_evidence = len(policy_classified) > 0 or len(warning_classified) > 0
+
+        # Collect unique sources
+        sources = list(
+            set(
+                Path(r.chunk.source_file).name
+                for r in policy_classified + warning_classified
+            )
+        )
+
+        return RetrievalContext(
+            policy_results=policy_classified,
+            warning_results=warning_classified,
+            policy_context_text=policy_context,
+            warnings_context_text=warnings_context,
+            has_sufficient_evidence=has_evidence,
+            sources_used=sources,
+        )
+
+    def retrieve_for_employee(
+        self, employee_name: str, top_k: int = 10
+    ) -> list[RetrievalResult]:
+        """Retrieve all documents mentioning an employee.
+
+        Useful for finding prior warnings and coaching records.
+        """
+        return self.vector_store.search(employee_name, top_k=top_k, min_score=0.2)

src/rag/synthesizer.py

@@ -0,0 +1,197 @@
+"""Report synthesizer using LLM with strict grounding."""
+
+from datetime import datetime
+from typing import Optional
+import os
+
+import requests
+from dotenv import load_dotenv
+from pydantic import BaseModel
+
+# Load environment variables
+load_dotenv()
+
+from src.config import settings
+from src.rag.prompts import (
+    INSUFFICIENT_EVIDENCE_RESPONSE,
+    SYSTEM_PROMPT,
+    USER_MESSAGE_TEMPLATE,
+)
+from src.rag.retriever import DocumentRetriever, RetrievalContext
+
+
+class ReportInput(BaseModel):
+    """Structured input for report generation."""
+
+    employee_name: str
+    incident_date_range: str
+    incident_reason: str
+    violation_type: str
+    report_date: Optional[str] = None
+    doc_type: Optional[str] = "Memorandum"
+
+    def __init__(self, **data):
+        if "report_date" not in data or data["report_date"] is None:
+            data["report_date"] = datetime.now().strftime("%Y-%m-%d")
+        super().__init__(**data)
+
+
+class SynthesisResult(BaseModel):
+    """Result of report synthesis."""
+
+    markdown_report: str
+    retrieval_context: RetrievalContext
+    model_used: str
+    generation_timestamp: str
+    success: bool
+    error: Optional[str] = None
+
+    class Config:
+        arbitrary_types_allowed = True
+
+
+class ReportSynthesizer:
+    """Synthesizes HR incident reports using RAG.
+
+    Combines retrieved context with structured inputs to generate
+    strictly grounded reports using an LLM with temperature=0.
+    """
+
+    def __init__(
+        self,
+        retriever: Optional[DocumentRetriever] = None,
+        model_name: Optional[str] = None,
+    ):
+        """Initialize the synthesizer.
+
+        Args:
+            retriever: Document retriever for context.
+            model_name: Model name for OpenRouter.
+        """
+        self.retriever = retriever or DocumentRetriever()
+        self.model_name = model_name or settings.llm_model
+        self.api_key = os.getenv("OPENROUTER_API_KEY", "")
+        self.api_base = os.getenv("OPENROUTER_API_BASE", "https://openrouter.ai/api/v1")
+
+    def _build_user_message(
+        self, report_input: ReportInput, context: RetrievalContext
+    ) -> str:
+        """Build the user message with retrieved context."""
+        return USER_MESSAGE_TEMPLATE.format(
+            doc_type=report_input.doc_type,
+            employee_name=report_input.employee_name,
+            report_date=report_input.report_date,
+            incident_date_range=report_input.incident_date_range,
+            incident_reason=report_input.incident_reason,
+            violation_type=report_input.violation_type,
+            policy_context=context.policy_context_text,
+            warnings_context=context.warnings_context_text,
+        )
+
+    def _generate_with_llm(self, user_message: str) -> str:
+        """Generate report using OpenRouter API."""
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+            "HTTP-Referer": "https://hr-report-generator.hf.space",
+            "X-Title": "HR Incident Report Generator",
+        }
+        
+        payload = {
+            "model": self.model_name,
+            "messages": [
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": user_message},
+            ],
+            "temperature": settings.llm_temperature,
+            "max_tokens": 2048,
+        }
+        
+        response = requests.post(
+            f"{self.api_base}/chat/completions",
+            headers=headers,
+            json=payload,
+            timeout=120,
+        )
+        
+        if response.status_code != 200:
+            raise Exception(f"OpenRouter API error: {response.status_code} - {response.text}")
+        
+        result = response.json()
+        return result["choices"][0]["message"]["content"]
+
+    def _generate_insufficient_evidence_report(self, report_input: ReportInput) -> str:
+        """Generate a report indicating insufficient evidence."""
+        return INSUFFICIENT_EVIDENCE_RESPONSE.format(
+            employee_name=report_input.employee_name,
+            report_date=report_input.report_date,
+            incident_date_range=report_input.incident_date_range,
+            incident_reason=report_input.incident_reason,
+            violation_type=report_input.violation_type,
+        )
+
+    def synthesize(self, report_input: ReportInput) -> SynthesisResult:
+        """Synthesize an HR incident report.
+
+        Args:
+            report_input: Structured input data.
+
+        Returns:
+            SynthesisResult with the generated report.
+        """
+        timestamp = datetime.now().isoformat()
+
+        try:
+            # Retrieve relevant context
+            context = self.retriever.retrieve(
+                employee_name=report_input.employee_name,
+                violation_type=report_input.violation_type,
+                incident_reason=report_input.incident_reason,
+            )
+
+            # Check for sufficient evidence
+            if not context.has_sufficient_evidence:
+                return SynthesisResult(
+                    markdown_report=self._generate_insufficient_evidence_report(report_input),
+                    retrieval_context=context,
+                    model_used=self.model_name,
+                    generation_timestamp=timestamp,
+                    success=True,
+                )
+
+            # Build prompt and generate
+            user_message = self._build_user_message(report_input, context)
+            markdown_report = self._generate_with_llm(user_message)
+
+            return SynthesisResult(
+                markdown_report=markdown_report,
+                retrieval_context=context,
+                model_used=self.model_name,
+                generation_timestamp=timestamp,
+                success=True,
+            )
+
+        except Exception as e:
+            return SynthesisResult(
+                markdown_report="",
+                retrieval_context=RetrievalContext(
+                    policy_results=[],
+                    warning_results=[],
+                    policy_context_text="",
+                    warnings_context_text="",
+                    has_sufficient_evidence=False,
+                    sources_used=[],
+                ),
+                model_used=self.model_name,
+                generation_timestamp=timestamp,
+                success=False,
+                error=str(e),
+            )
+
+    def synthesize_from_dict(self, data: dict) -> SynthesisResult:
+        """Synthesize a report from dictionary input.
+
+        Convenience method for CLI and API usage.
+        """
+        report_input = ReportInput(**data)
+        return self.synthesize(report_input)