feat: Day 4 — corpus, ingest script, first 10 golden questions

- 16 curated FastAPI tutorial markdown files (~9,400 words)
with specific numbers for calculator questions (page sizes,
worker formulas, token expiry, CORS max_age, etc.)
- scripts/ingest.py: chunk → embed → store pipeline
207 chunks from 16 files into FAISS + BM25 hybrid store
- 10 golden questions: 7 positive (incl 1 calculator), 3 out-of-scope
- Pin sentence-transformers <5.0.0 for PyTorch 2.2 compat

Day 4 gate PASS: Recall@5 = 1.00 on all positive questions.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

agent_bench/evaluation/__init__.py

@@ -0,0 +1 @@
+"""Evaluation harness, metrics, and reporting."""

agent_bench/evaluation/datasets/tech_docs_golden.json

@@ -0,0 +1,92 @@
+[
+    {
+        "id": "q001",
+        "question": "How do you define a path parameter in FastAPI?",
+        "expected_answer_keywords": ["curly braces", "path", "function parameter", "URL"],
+        "expected_sources": ["fastapi_path_params.md"],
+        "category": "retrieval",
+        "difficulty": "easy",
+        "requires_calculator": false
+    },
+    {
+        "id": "q002",
+        "question": "What is the default page size for pagination in FastAPI and what is the maximum allowed?",
+        "expected_answer_keywords": ["20", "100", "default", "maximum"],
+        "expected_sources": ["fastapi_pagination.md"],
+        "category": "retrieval",
+        "difficulty": "easy",
+        "requires_calculator": false
+    },
+    {
+        "id": "q003",
+        "question": "How does FastAPI handle CORS and what is the default max_age for preflight caching?",
+        "expected_answer_keywords": ["CORSMiddleware", "600", "seconds", "preflight"],
+        "expected_sources": ["fastapi_middleware.md"],
+        "category": "retrieval",
+        "difficulty": "easy",
+        "requires_calculator": false
+    },
+    {
+        "id": "q004",
+        "question": "What algorithm and expiry time does the FastAPI security example use for JWT tokens?",
+        "expected_answer_keywords": ["HS256", "30", "minutes"],
+        "expected_sources": ["fastapi_security.md"],
+        "category": "retrieval",
+        "difficulty": "medium",
+        "requires_calculator": false
+    },
+    {
+        "id": "q005",
+        "question": "What is the recommended formula for calculating the number of Gunicorn workers for a FastAPI deployment?",
+        "expected_answer_keywords": ["2", "CPU", "cores", "1"],
+        "expected_sources": ["fastapi_deployment.md"],
+        "category": "retrieval",
+        "difficulty": "medium",
+        "requires_calculator": false
+    },
+    {
+        "id": "q006",
+        "question": "How does dependency caching work in FastAPI, and how can you disable it?",
+        "expected_answer_keywords": ["cache", "once", "use_cache", "False"],
+        "expected_sources": ["fastapi_dependencies.md"],
+        "category": "retrieval",
+        "difficulty": "medium",
+        "requires_calculator": false
+    },
+    {
+        "id": "q007",
+        "question": "If a paginated endpoint returns 20 items per page and there are 10,000 items total, how many total pages are there? And if the page size is changed to 30, how many pages would there be?",
+        "expected_answer_keywords": ["500", "334", "ceil", "pages"],
+        "expected_sources": ["fastapi_pagination.md"],
+        "category": "calculation",
+        "difficulty": "medium",
+        "requires_calculator": true
+    },
+    {
+        "id": "q008",
+        "question": "Does FastAPI support automatic Kubernetes deployment?",
+        "expected_answer_keywords": ["not", "does not contain", "no information"],
+        "expected_sources": [],
+        "category": "out_of_scope",
+        "difficulty": "easy",
+        "requires_calculator": false
+    },
+    {
+        "id": "q009",
+        "question": "How does FastAPI integrate with Apache Kafka for event streaming?",
+        "expected_answer_keywords": ["not", "does not contain", "no information"],
+        "expected_sources": [],
+        "category": "out_of_scope",
+        "difficulty": "easy",
+        "requires_calculator": false
+    },
+    {
+        "id": "q010",
+        "question": "Can FastAPI generate GraphQL schemas natively?",
+        "expected_answer_keywords": ["not", "does not contain", "no information"],
+        "expected_sources": [],
+        "category": "out_of_scope",
+        "difficulty": "easy",
+        "requires_calculator": false
+    }
+]

data/tech_docs/fastapi_background_tasks.md

@@ -0,0 +1,103 @@
+# Background Tasks in FastAPI
+
+Background tasks allow you to schedule work to run after the response has been sent to the client. This is useful for operations that do not need to complete before the user receives a response, such as sending emails, writing audit logs, or triggering data processing pipelines.
+
+## Basic Background Task
+
+```python
+from fastapi import FastAPI, BackgroundTasks
+
+app = FastAPI()
+
+def write_log(message: str):
+    with open("log.txt", "a") as f:
+        f.write(f"{message}\n")
+
+@app.post("/items/", status_code=201)
+async def create_item(name: str, background_tasks: BackgroundTasks):
+    background_tasks.add_task(write_log, f"Item created: {name}")
+    return {"name": name, "status": "created"}
+```
+
+Declare `BackgroundTasks` as a parameter in your route handler, and FastAPI injects it automatically. Call `add_task()` with the function to run and any positional or keyword arguments. The task runs after the response is sent, in the same process. The `add_task()` method accepts both synchronous and asynchronous functions -- sync functions are run in a threadpool, while async functions are awaited on the event loop.
+
+## Multiple Background Tasks
+
+You can add multiple tasks, and they execute sequentially in the order they were added:
+
+```python
+def send_email(to: str, subject: str, body: str):
+    # Simulate sending email (takes ~2 seconds)
+    import time
+    time.sleep(2)
+    print(f"Email sent to {to}: {subject}")
+
+def update_analytics(event: str, item_id: int):
+    # Record analytics event
+    print(f"Analytics: {event} for item {item_id}")
+
+@app.post("/items/{item_id}/purchase")
+async def purchase_item(item_id: int, background_tasks: BackgroundTasks):
+    # Process purchase immediately
+    result = process_purchase(item_id)
+
+    # Queue background work
+    background_tasks.add_task(
+        send_email,
+        to="buyer@example.com",
+        subject="Purchase Confirmation",
+        body=f"You purchased item {item_id}",
+    )
+    background_tasks.add_task(update_analytics, "purchase", item_id)
+
+    return {"item_id": item_id, "status": "purchased"}
+```
+
+In this example, the client receives the response immediately after purchase processing. The email and analytics tasks run sequentially in the background. If the first task takes 2 seconds, the second task starts only after the first completes.
+
+## Background Tasks in Dependencies
+
+Dependencies can also add background tasks, which is useful for cross-cutting concerns like logging:
+
+```python
+from fastapi import Depends
+
+def log_request(background_tasks: BackgroundTasks):
+    def _log(method: str, path: str):
+        with open("access.log", "a") as f:
+            f.write(f"{method} {path}\n")
+    return background_tasks, _log
+
+async def audit_dependency(
+    background_tasks: BackgroundTasks,
+    request_method: str = "GET",
+):
+    def audit_log(action: str):
+        with open("audit.log", "a") as f:
+            f.write(f"[{request_method}] {action}\n")
+    background_tasks.add_task(audit_log, "endpoint_accessed")
+
+@app.get("/items/", dependencies=[Depends(audit_dependency)])
+async def read_items(background_tasks: BackgroundTasks):
+    background_tasks.add_task(write_log, "Items listed")
+    return [{"item": "Widget"}]
+```
+
+When both the dependency and the route handler add tasks to `BackgroundTasks`, all tasks share the same task queue. Dependency tasks are added first (in the order dependencies are resolved), followed by tasks added in the route handler.
+
+## Use Cases and Limitations
+
+Common use cases for background tasks:
+
+- **Email notifications**: Send confirmation or alert emails after an action (typical send time: 1-5 seconds).
+- **Log writing**: Write detailed audit logs without adding latency to the response.
+- **Cache invalidation**: Clear or update caches after data mutations.
+- **Webhook delivery**: POST event payloads to external services with retry logic.
+- **File cleanup**: Remove temporary uploaded files after processing.
+
+Important limitations to consider:
+
+1. Background tasks run in the same process as the web server. If a task crashes, it does not affect the already-sent response, but unhandled exceptions are logged to stderr.
+2. If the server shuts down, pending background tasks are lost -- they are not persisted to a queue. For critical tasks, use a dedicated task queue like Celery (which supports up to 10,000+ tasks per second with Redis as a broker) or ARQ.
+3. Background tasks share the event loop (for async tasks) or threadpool (for sync tasks, default pool size of 40 threads). A CPU-intensive background task can degrade request handling performance.
+4. There is no built-in retry mechanism. If a background task fails, it fails silently from the client's perspective. Implement retry logic within the task function if needed.

data/tech_docs/fastapi_configuration.md

@@ -0,0 +1,144 @@
+# Configuration and Settings in FastAPI
+
+FastAPI leverages Pydantic's `BaseSettings` class to manage application configuration through environment variables, `.env` files, and secrets. This approach provides type-safe configuration with validation, default values, and automatic environment variable reading.
+
+## Pydantic Settings
+
+Install the settings extension:
+
+```bash
+pip install pydantic-settings
+```
+
+Define your settings as a Pydantic model:
+
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        env_prefix="",
+    )
+
+    app_name: str = "My FastAPI App"
+    admin_email: str = "admin@example.com"
+    debug: bool = False
+    database_url: str = "sqlite:///./app.db"
+    redis_url: str = "redis://localhost:6379/0"
+    allowed_hosts: list[str] = ["localhost", "127.0.0.1"]
+    max_connections: int = 100
+    api_v1_prefix: str = "/api/v1"
+    access_token_expire_minutes: int = 30
+    secret_key: str = "change-me-in-production"
+```
+
+Pydantic Settings reads values from these sources in the following priority order (highest priority first):
+
+1. Constructor arguments passed directly to `Settings()`
+2. Environment variables
+3. Variables from the `.env` file
+4. Default values defined in the model
+
+Setting `case_sensitive=False` (the default) means the environment variable `DATABASE_URL`, `database_url`, and `Database_Url` all map to the `database_url` field.
+
+## Environment Variables and .env Files
+
+Create a `.env` file in the project root:
+
+```
+APP_NAME=Production API
+DEBUG=false
+DATABASE_URL=postgresql://user:pass@db-host:5432/mydb
+REDIS_URL=redis://redis-host:6379/0
+MAX_CONNECTIONS=250
+SECRET_KEY=a7f3b9c1d4e8f2a6b0c5d9e3f7a1b4c8
+ACCESS_TOKEN_EXPIRE_MINUTES=60
+```
+
+The `.env` file is parsed using the `python-dotenv` library (installed automatically with `pydantic-settings`). Multiple `.env` files can be specified as a tuple:
+
+```python
+model_config = SettingsConfigDict(
+    env_file=(".env", ".env.local"),
+)
+```
+
+When multiple files are specified, later files take precedence over earlier ones. So `.env.local` overrides values from `.env`.
+
+## Settings as a Dependency
+
+Use dependency injection to provide settings to route handlers:
+
+```python
+from functools import lru_cache
+from fastapi import FastAPI, Depends
+
+app = FastAPI()
+
+@lru_cache
+def get_settings():
+    return Settings()
+
+@app.get("/info")
+async def info(settings: Settings = Depends(get_settings)):
+    return {
+        "app_name": settings.app_name,
+        "admin_email": settings.admin_email,
+        "debug": settings.debug,
+    }
+```
+
+The `@lru_cache` decorator ensures the `Settings` object is created only once and reused for all subsequent requests. Without caching, Pydantic would read and parse the `.env` file on every request, adding approximately 1-3 milliseconds of overhead per call. The cache has no size limit by default (`maxsize=128` for `lru_cache`), but since `get_settings()` takes no arguments, it effectively stores just one instance.
+
+## Nested Settings with Prefixes
+
+Organize related settings into nested models using `env_prefix`:
+
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import BaseModel
+
+class DatabaseSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="DB_")
+
+    host: str = "localhost"
+    port: int = 5432
+    name: str = "mydb"
+    user: str = "postgres"
+    password: str = ""
+    pool_min_size: int = 5
+    pool_max_size: int = 20
+    echo: bool = False
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env")
+
+    app_name: str = "My App"
+    debug: bool = False
+    db: DatabaseSettings = DatabaseSettings()
+```
+
+With `env_prefix="DB_"`, the environment variable `DB_HOST` maps to `DatabaseSettings.host`, `DB_PORT` maps to `port`, and so on. The default database pool sizes are 5 minimum and 20 maximum connections.
+
+## Secrets Management
+
+For sensitive values, Pydantic Settings supports reading from secret files (commonly used with Docker Secrets and Kubernetes Secrets):
+
+```python
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        secrets_dir="/run/secrets",
+    )
+
+    database_password: str
+    api_key: str
+    jwt_secret: str
+```
+
+When `secrets_dir` is set, Pydantic looks for files named after each field (e.g., `/run/secrets/database_password`). The file contents become the field value. Secret files take precedence over `.env` values but are overridden by environment variables.
+
+The priority order with secrets becomes: constructor arguments > environment variables > secret files > `.env` file > default values.

data/tech_docs/fastapi_dependencies.md

@@ -0,0 +1,116 @@
+# Dependency Injection in FastAPI
+
+FastAPI includes a built-in dependency injection system that allows you to share logic, enforce authentication, manage database connections, and more. Dependencies are declared using `Depends()` and are resolved automatically for each request.
+
+## Basic Dependency
+
+A dependency is any callable (function or class) that FastAPI calls before the route handler:
+
+```python
+from fastapi import FastAPI, Depends, Query
+
+app = FastAPI()
+
+async def common_parameters(
+    skip: int = Query(default=0, ge=0),
+    limit: int = Query(default=100, ge=1, le=1000),
+):
+    return {"skip": skip, "limit": limit}
+
+@app.get("/items/")
+async def read_items(commons: dict = Depends(common_parameters)):
+    return {"params": commons}
+
+@app.get("/users/")
+async def read_users(commons: dict = Depends(common_parameters)):
+    return {"params": commons}
+```
+
+Both `/items/` and `/users/` share the same pagination logic. The `common_parameters` function is called once per request, and its return value is injected into the `commons` parameter.
+
+## Class-Based Dependencies
+
+Classes work as dependencies because calling a class creates an instance (i.e., `MyClass()` is callable):
+
+```python
+class PaginationParams:
+    def __init__(
+        self,
+        skip: int = Query(default=0, ge=0),
+        limit: int = Query(default=100, ge=1, le=1000),
+    ):
+        self.skip = skip
+        self.limit = limit
+
+@app.get("/items/")
+async def read_items(pagination: PaginationParams = Depends(PaginationParams)):
+    return {"skip": pagination.skip, "limit": pagination.limit}
+```
+
+FastAPI provides a shorthand: `Depends(PaginationParams)` can also be written as `Depends()` when the type annotation already specifies the class: `pagination: PaginationParams = Depends()`.
+
+## Sub-Dependencies
+
+Dependencies can depend on other dependencies, forming a chain that FastAPI resolves automatically:
+
+```python
+def query_extractor(q: str | None = None):
+    return q
+
+def query_or_default(q: str = Depends(query_extractor)):
+    if not q:
+        return "default_query"
+    return q
+
+@app.get("/items/")
+async def read_items(query: str = Depends(query_or_default)):
+    return {"query": query}
+```
+
+FastAPI resolves the dependency tree from the leaves up. In this case, `query_extractor` runs first, then `query_or_default` receives its result. The maximum depth of the dependency chain is not explicitly limited, but in practice chains deeper than 10 levels indicate a design issue.
+
+## Dependencies with Yield (Resource Management)
+
+Use `yield` in a dependency to run setup code before and cleanup code after the route handler executes. This is ideal for managing database sessions, file handles, or locks:
+
+```python
+from sqlalchemy.orm import Session
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+@app.get("/items/")
+async def read_items(db: Session = Depends(get_db)):
+    items = db.query(Item).all()
+    return items
+```
+
+The code before `yield` runs before the handler, the yielded value is injected as the dependency, and the code after `yield` runs after the response is sent. The `finally` block ensures cleanup happens even if an exception occurs. FastAPI supports up to 32 yield dependencies per request by default.
+
+## Global Dependencies
+
+Apply dependencies to every route in the application by passing them to the `FastAPI` constructor:
+
+```python
+from fastapi import FastAPI, Depends, Header, HTTPException
+
+async def verify_api_key(x_api_key: str = Header()):
+    if x_api_key != "secret-key-123":
+        raise HTTPException(status_code=403, detail="Invalid API key")
+
+app = FastAPI(dependencies=[Depends(verify_api_key)])
+
+@app.get("/items/")
+async def read_items():
+    return [{"item": "Widget"}]
+```
+
+Every route in this application requires a valid `X-Api-Key` header. You can also scope dependencies to a specific router using `APIRouter(dependencies=[...])`.
+
+## Caching Behavior
+
+By default, if the same dependency is used multiple times within a single request (e.g., both a route and a sub-dependency use `Depends(get_db)`), FastAPI caches the result and calls the dependency only once. To disable caching and force a fresh call each time, use `Depends(get_db, use_cache=False)`.

data/tech_docs/fastapi_deployment.md

@@ -0,0 +1,149 @@
+# Deploying FastAPI Applications
+
+FastAPI applications are deployed using ASGI servers. This guide covers production deployment with Uvicorn, Gunicorn, Docker, and related infrastructure considerations.
+
+## Uvicorn (Single Process)
+
+Uvicorn is the recommended ASGI server for FastAPI. For development:
+
+```bash
+uvicorn main:app --reload --host 127.0.0.1 --port 8000
+```
+
+For production with a single process:
+
+```bash
+uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1 --log-level info
+```
+
+Key Uvicorn configuration options:
+
+| Flag              | Default       | Description                              |
+|-------------------|---------------|------------------------------------------|
+| `--host`          | `127.0.0.1`   | Bind address                             |
+| `--port`          | `8000`         | Bind port                                |
+| `--workers`       | `1`            | Number of worker processes               |
+| `--loop`          | `auto`         | Event loop (auto, asyncio, uvloop)       |
+| `--http`          | `auto`         | HTTP protocol (auto, h11, httptools)     |
+| `--ws`            | `auto`         | WebSocket protocol (auto, websockets, wsproto) |
+| `--log-level`     | `info`         | Logging level (critical, error, warning, info, debug, trace) |
+| `--access-log`    | `True`         | Enable/disable access log                |
+| `--ws-max-size`   | `16777216`     | Max WebSocket message size (16 MB)       |
+| `--timeout-keep-alive` | `5`       | Keep-alive timeout in seconds            |
+
+Using `uvloop` and `httptools` (installed automatically on Linux) provides a 20-30% performance boost over the pure-Python `asyncio` and `h11` alternatives.
+
+## Gunicorn with Uvicorn Workers
+
+For production deployments requiring multiple worker processes, use Gunicorn as the process manager with Uvicorn workers:
+
+```bash
+gunicorn main:app \
+    --workers 4 \
+    --worker-class uvicorn.workers.UvicornWorker \
+    --bind 0.0.0.0:8000 \
+    --timeout 120 \
+    --graceful-timeout 30 \
+    --keep-alive 5 \
+    --max-requests 1000 \
+    --max-requests-jitter 50 \
+    --access-logfile -
+```
+
+The recommended number of workers is `(2 * CPU_CORES) + 1`. For a server with 4 CPU cores, that is 9 workers. The `--max-requests 1000` flag restarts each worker after handling 1,000 requests, preventing memory leaks. The `--max-requests-jitter 50` adds a random offset (0-50) so workers do not all restart simultaneously.
+
+The `--timeout 120` flag sets the maximum time (in seconds) a worker can take to handle a request before being killed and restarted. The default is 30 seconds. The `--graceful-timeout 30` gives workers 30 seconds to finish current requests during shutdown.
+
+## Docker Deployment
+
+A production-ready Dockerfile:
+
+```dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install dependencies first for layer caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY ./app ./app
+
+# Create non-root user
+RUN adduser --disabled-password --gecos "" appuser
+USER appuser
+
+EXPOSE 8000
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]
+```
+
+Build and run:
+
+```bash
+docker build -t myapi:latest .
+docker run -d --name myapi -p 8000:8000 -e DATABASE_URL=postgresql://... myapi:latest
+```
+
+The `python:3.12-slim` base image is approximately 120 MB, compared to the full `python:3.12` image at approximately 890 MB. For even smaller images, use `python:3.12-alpine` (approximately 50 MB), though it may require additional build dependencies for some Python packages.
+
+## Proxy Headers and HTTPS
+
+When running behind a reverse proxy (Nginx, Traefik, AWS ALB), configure Uvicorn to trust proxy headers:
+
+```bash
+uvicorn main:app \
+    --host 0.0.0.0 \
+    --port 8000 \
+    --proxy-headers \
+    --forwarded-allow-ips="*"
+```
+
+The `--proxy-headers` flag tells Uvicorn to read `X-Forwarded-For` and `X-Forwarded-Proto` headers from the proxy. The `--forwarded-allow-ips` flag specifies which proxy IPs are trusted. Using `"*"` trusts all proxies (acceptable when the application is not directly exposed to the internet).
+
+An Nginx reverse proxy configuration:
+
+```nginx
+upstream fastapi_backend {
+    server 127.0.0.1:8000;
+}
+
+server {
+    listen 443 ssl;
+    server_name api.example.com;
+
+    ssl_certificate /etc/ssl/certs/api.example.com.pem;
+    ssl_certificate_key /etc/ssl/private/api.example.com.key;
+
+    location / {
+        proxy_pass http://fastapi_backend;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_buffering off;
+    }
+}
+```
+
+Setting `proxy_buffering off` ensures streamed responses (like SSE or large file downloads) are forwarded immediately rather than buffered by Nginx.
+
+## Health Checks
+
+Include a health check endpoint for container orchestrators:
+
+```python
+@app.get("/health", status_code=200)
+async def health_check():
+    return {"status": "healthy"}
+```
+
+Docker health check configuration:
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=10s \
+    CMD curl -f http://localhost:8000/health || exit 1
+```
+
+This checks health every 30 seconds, allows 10 seconds per check, retries 3 times before marking unhealthy, and waits 10 seconds after container start before the first check.

data/tech_docs/fastapi_error_handling.md

@@ -0,0 +1,161 @@
+# Error Handling in FastAPI
+
+FastAPI provides a structured approach to error handling using HTTP exceptions, custom exception handlers, and validation error customization. Proper error handling ensures clients receive meaningful, consistent error responses.
+
+## HTTPException
+
+The `HTTPException` class is the primary way to return error responses from route handlers:
+
+```python
+from fastapi import FastAPI, HTTPException
+
+app = FastAPI()
+
+items = {"widget": {"name": "Widget", "price": 35.99}}
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: str):
+    if item_id not in items:
+        raise HTTPException(
+            status_code=404,
+            detail="Item not found",
+            headers={"X-Error-Code": "ITEM_NOT_FOUND"},
+        )
+    return items[item_id]
+```
+
+When raised, `HTTPException` immediately terminates request processing and returns the specified status code and detail message. The `detail` parameter can be a string, list, or dictionary -- FastAPI serializes it to JSON automatically. The optional `headers` parameter adds custom HTTP headers to the error response.
+
+The default error response format is:
+
+```json
+{
+    "detail": "Item not found"
+}
+```
+
+## Custom Exception Handlers
+
+Register custom handlers for any exception type using `@app.exception_handler()`:
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+class ItemNotFoundException(Exception):
+    def __init__(self, item_id: str):
+        self.item_id = item_id
+
+app = FastAPI()
+
+@app.exception_handler(ItemNotFoundException)
+async def item_not_found_handler(request: Request, exc: ItemNotFoundException):
+    return JSONResponse(
+        status_code=404,
+        content={
+            "error": "item_not_found",
+            "message": f"Item '{exc.item_id}' does not exist",
+            "path": str(request.url),
+        },
+    )
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: str):
+    if item_id not in items_db:
+        raise ItemNotFoundException(item_id)
+    return items_db[item_id]
+```
+
+Custom exception handlers receive the `Request` object and the exception instance. They must return a `Response` object (typically `JSONResponse`). You can register handlers for any Python exception class, including built-in exceptions like `ValueError` or `RuntimeError`.
+
+## Handling Validation Errors
+
+FastAPI automatically returns a 422 Unprocessable Entity response when request validation fails. The default response includes detailed error information:
+
+```json
+{
+    "detail": [
+        {
+            "type": "int_parsing",
+            "loc": ["path", "item_id"],
+            "msg": "Input should be a valid integer, unable to parse string as an integer",
+            "input": "abc",
+            "url": "https://errors.pydantic.dev/2/v/int_parsing"
+        }
+    ]
+}
+```
+
+Each error object contains 5 fields: `type` (the error type identifier), `loc` (the location as a list like `["body", "price"]` or `["query", "limit"]`), `msg` (a human-readable message), `input` (the invalid value), and `url` (a link to Pydantic's error documentation).
+
+To customize validation error responses, override the `RequestValidationError` handler:
+
+```python
+from fastapi import FastAPI, Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+app = FastAPI()
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(
+    request: Request, exc: RequestValidationError
+):
+    error_messages = []
+    for error in exc.errors():
+        field = " -> ".join(str(loc) for loc in error["loc"])
+        error_messages.append(f"{field}: {error['msg']}")
+
+    return JSONResponse(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        content={
+            "error": "validation_error",
+            "message": "Request validation failed",
+            "details": error_messages,
+            "error_count": len(exc.errors()),
+        },
+    )
+```
+
+## Overriding Default Exception Handlers
+
+FastAPI has built-in handlers for `HTTPException` and `RequestValidationError`. You can override both:
+
+```python
+from fastapi import FastAPI
+from fastapi.exceptions import RequestValidationError
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+app = FastAPI()
+
+@app.exception_handler(StarletteHTTPException)
+async def http_exception_handler(request: Request, exc: StarletteHTTPException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "error": True,
+            "status_code": exc.status_code,
+            "message": exc.detail,
+        },
+    )
+```
+
+Note: FastAPI's `HTTPException` inherits from Starlette's `HTTPException`. To override the handler for all HTTP exceptions (including those raised by Starlette internals like 404 for missing routes), register the handler for `StarletteHTTPException` rather than FastAPI's version.
+
+## Returning the Request Body in Errors
+
+The `RequestValidationError` object contains the original request body, which can be useful for logging or debugging:
+
+```python
+@app.exception_handler(RequestValidationError)
+async def validation_handler(request: Request, exc: RequestValidationError):
+    return JSONResponse(
+        status_code=422,
+        content={
+            "detail": exc.errors(),
+            "body": exc.body,  # The raw request body that failed validation
+        },
+    )
+```
+
+The `exc.body` attribute holds the parsed request body (as a Python object) before validation was applied. This is only available for body validation errors, not for path or query parameter errors.

data/tech_docs/fastapi_intro.md

@@ -0,0 +1,71 @@
+# Introduction to FastAPI
+
+FastAPI is a modern, high-performance web framework for building APIs with Python 3.7+ based on standard Python type hints. Created by Sebastian Ramirez and first released in December 2018, it has quickly become one of the most popular Python web frameworks, with over 75,000 stars on GitHub.
+
+## Key Features
+
+FastAPI is built on top of two core libraries:
+
+- **Starlette** (version 0.27.0+) for the web framework internals, providing WebSocket support, ASGI compatibility, and background tasks.
+- **Pydantic** (version 2.0+) for data validation, serialization, and settings management using Python type annotations.
+
+The framework delivers several standout capabilities:
+
+1. **High Performance**: FastAPI achieves performance on par with Node.js and Go frameworks. Independent benchmarks from TechEmpower show it handling approximately 9,000 requests per second for JSON serialization on a single worker, compared to Flask's approximately 1,200 requests per second under comparable conditions.
+
+2. **Automatic Interactive Documentation**: Every FastAPI application automatically generates two interactive API documentation interfaces -- Swagger UI (available at `/docs`) and ReDoc (available at `/redoc`) -- with zero additional configuration.
+
+3. **Async Support**: Full native support for `async`/`await` syntax, allowing non-blocking I/O operations. Synchronous route handlers are automatically run in a threadpool with a default thread count of 40.
+
+4. **Type-Driven Development**: Leverages Python type hints for request validation, serialization, and documentation generation, reducing code duplication by an estimated 40% compared to traditional approaches.
+
+## Minimal Example
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI(
+    title="My API",
+    description="A sample API built with FastAPI",
+    version="1.0.0",
+)
+
+@app.get("/")
+async def root():
+    return {"message": "Hello, World"}
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: int, q: str = None):
+    return {"item_id": item_id, "q": q}
+```
+
+To run this application, save it as `main.py` and execute:
+
+```bash
+uvicorn main:app --reload --host 0.0.0.0 --port 8000
+```
+
+The `--reload` flag enables auto-reload on code changes and should only be used during development. By default, Uvicorn binds to `127.0.0.1` on port `8000`.
+
+## How It Works
+
+When the application starts, FastAPI performs the following steps:
+
+1. Inspects all route handler function signatures to extract parameter types.
+2. Generates a complete OpenAPI 3.1.0 schema (accessible at `/openapi.json`).
+3. Registers Pydantic models for request validation and response serialization.
+4. Mounts the Swagger UI and ReDoc documentation endpoints.
+
+Each incoming request goes through this pipeline: ASGI server receives the request, Starlette routes it to the correct handler, Pydantic validates the input data, the handler executes, and the response is serialized back through Pydantic before being sent to the client.
+
+## Installation
+
+Install FastAPI and an ASGI server:
+
+```bash
+pip install fastapi[standard]
+```
+
+This installs FastAPI along with Uvicorn (the recommended ASGI server), python-multipart for form data support, and httpx for the test client. The `[standard]` extra includes 6 additional packages beyond the base installation. If you prefer a minimal install, use `pip install fastapi` which installs only FastAPI, Starlette, and Pydantic.
+
+FastAPI requires Python 3.7 or higher, though Python 3.10+ is recommended to take advantage of modern type hint syntax such as `X | None` instead of `Optional[X]`.

data/tech_docs/fastapi_middleware.md

@@ -0,0 +1,126 @@
+# Middleware in FastAPI
+
+Middleware is a function that processes every request before it reaches a route handler and every response before it is returned to the client. FastAPI supports both ASGI middleware (from Starlette) and its own decorator-based middleware.
+
+## Custom Middleware
+
+Use the `@app.middleware("http")` decorator to create custom middleware:
+
+```python
+import time
+from fastapi import FastAPI, Request
+
+app = FastAPI()
+
+@app.middleware("http")
+async def add_process_time_header(request: Request, call_next):
+    start_time = time.perf_counter()
+    response = await call_next(request)
+    process_time = time.perf_counter() - start_time
+    response.headers["X-Process-Time"] = f"{process_time:.4f}"
+    return response
+```
+
+The middleware receives the incoming `Request` object and a `call_next` function. Calling `await call_next(request)` passes the request to the next middleware or route handler in the chain and returns the `Response`. You can modify both the request (before `call_next`) and the response (after `call_next`).
+
+## CORS Middleware
+
+Cross-Origin Resource Sharing (CORS) is configured using `CORSMiddleware` from Starlette:
+
+```python
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+app = FastAPI()
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://example.com", "https://app.example.com"],
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "DELETE"],
+    allow_headers=["Authorization", "Content-Type"],
+    expose_headers=["X-Custom-Header"],
+    max_age=600,
+)
+```
+
+The `CORSMiddleware` parameters:
+
+| Parameter            | Default | Description                                        |
+|----------------------|---------|----------------------------------------------------|
+| `allow_origins`      | `[]`    | List of allowed origin URLs                        |
+| `allow_origin_regex` | `None`  | Regex pattern for matching allowed origins         |
+| `allow_methods`      | `["GET"]` | HTTP methods allowed for cross-origin requests  |
+| `allow_headers`      | `[]`    | HTTP headers allowed in cross-origin requests      |
+| `allow_credentials`  | `False` | Whether cookies are permitted in cross-origin requests |
+| `expose_headers`     | `[]`    | Response headers accessible to the browser         |
+| `max_age`            | `600`   | Seconds the browser caches preflight results       |
+
+To allow all origins, use `allow_origins=["*"]`. However, when `allow_credentials=True`, you cannot use the wildcard `"*"` for `allow_origins` -- you must list specific origins. This is a CORS specification requirement, not a FastAPI limitation.
+
+## Middleware Ordering
+
+Middleware executes in reverse order of how it is added. The last middleware added is the first to process the request (outermost layer):
+
+```python
+app = FastAPI()
+
+@app.middleware("http")
+async def middleware_one(request: Request, call_next):
+    print("Middleware 1: before")  # Runs second
+    response = await call_next(request)
+    print("Middleware 1: after")   # Runs third
+    return response
+
+@app.middleware("http")
+async def middleware_two(request: Request, call_next):
+    print("Middleware 2: before")  # Runs first
+    response = await call_next(request)
+    print("Middleware 2: after")   # Runs fourth
+    return response
+```
+
+The output order for a request is: `Middleware 2: before`, `Middleware 1: before`, (route handler), `Middleware 1: after`, `Middleware 2: after`. This follows the standard "onion" model where each middleware wraps the next layer.
+
+## Trusted Host Middleware
+
+Protect against HTTP Host header attacks:
+
+```python
+from fastapi.middleware.trustedhost import TrustedHostMiddleware
+
+app.add_middleware(
+    TrustedHostMiddleware,
+    allowed_hosts=["example.com", "*.example.com"],
+)
+```
+
+Requests with a `Host` header not matching the allowed hosts receive a 400 Bad Request response.
+
+## GZip Middleware
+
+Compress responses automatically when the client supports it:
+
+```python
+from fastapi.middleware.gzip import GZipMiddleware
+
+app.add_middleware(GZipMiddleware, minimum_size=500)
+```
+
+The `minimum_size` parameter (default: `500` bytes) sets the minimum response body size before compression is applied. Responses smaller than this threshold are sent uncompressed. GZip compression typically reduces JSON response sizes by 60-80%.
+
+## ASGI Middleware
+
+Since FastAPI is an ASGI application, you can use any ASGI-compatible middleware:
+
+```python
+from starlette.middleware.sessions import SessionMiddleware
+
+app.add_middleware(
+    SessionMiddleware,
+    secret_key="your-session-secret",
+    max_age=14 * 24 * 60 * 60,  # 14 days in seconds = 1,209,600
+)
+```
+
+The `add_middleware()` method is the preferred way to add middleware in FastAPI, as it ensures proper integration with the application's middleware stack and exception handling.

data/tech_docs/fastapi_openapi.md

@@ -0,0 +1,210 @@
+# OpenAPI and Documentation in FastAPI
+
+FastAPI automatically generates an OpenAPI 3.1.0 schema from your code, providing interactive documentation interfaces with zero configuration. This schema drives Swagger UI and ReDoc, and can be consumed by code generators, API gateways, and testing tools.
+
+## Automatic Documentation Endpoints
+
+Every FastAPI application exposes three documentation-related endpoints by default:
+
+| Endpoint         | Description                                      |
+|------------------|--------------------------------------------------|
+| `/docs`          | Swagger UI -- interactive API explorer           |
+| `/redoc`         | ReDoc -- alternative documentation viewer        |
+| `/openapi.json`  | Raw OpenAPI schema in JSON format                |
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI(
+    title="My API",
+    description="A comprehensive API for managing items and users.",
+    version="2.1.0",
+    terms_of_service="https://example.com/terms",
+    contact={
+        "name": "API Support",
+        "url": "https://example.com/support",
+        "email": "support@example.com",
+    },
+    license_info={
+        "name": "MIT",
+        "url": "https://opensource.org/licenses/MIT",
+    },
+    openapi_url="/openapi.json",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+```
+
+To disable any documentation endpoint, set its URL to `None`:
+
+```python
+app = FastAPI(
+    docs_url=None,      # Disables Swagger UI
+    redoc_url=None,     # Disables ReDoc
+    openapi_url=None,   # Disables OpenAPI schema (also disables both UIs)
+)
+```
+
+Disabling `openapi_url` effectively disables all automatic documentation since both Swagger UI and ReDoc depend on the OpenAPI schema.
+
+## Tags and Grouping
+
+Organize endpoints into logical groups using tags:
+
+```python
+from fastapi import FastAPI
+
+tags_metadata = [
+    {
+        "name": "users",
+        "description": "Operations with users. The **login** logic is also here.",
+    },
+    {
+        "name": "items",
+        "description": "Manage items. Each item has a unique integer ID.",
+        "externalDocs": {
+            "description": "Items external docs",
+            "url": "https://example.com/items-docs",
+        },
+    },
+]
+
+app = FastAPI(openapi_tags=tags_metadata)
+
+@app.get("/users/", tags=["users"])
+async def read_users():
+    return [{"username": "alice"}]
+
+@app.get("/items/", tags=["items"])
+async def read_items():
+    return [{"name": "Widget"}]
+
+@app.post("/items/", tags=["items"])
+async def create_item(name: str):
+    return {"name": name}
+```
+
+Tags appear as collapsible sections in Swagger UI. The order of tags in `openapi_tags` determines their display order. An endpoint can have multiple tags, causing it to appear in each corresponding section.
+
+## Enriching Endpoint Documentation
+
+Add descriptions, summaries, and response documentation to individual endpoints:
+
+```python
+from fastapi import FastAPI, Path, Query
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class Item(BaseModel):
+    """An item in the inventory system."""
+    name: str
+    price: float
+    description: str | None = None
+
+    model_config = {
+        "json_schema_extra": {
+            "examples": [
+                {
+                    "name": "Premium Widget",
+                    "price": 35.99,
+                    "description": "A high-quality widget",
+                }
+            ]
+        }
+    }
+
+@app.get(
+    "/items/{item_id}",
+    summary="Get a single item",
+    description="Retrieve an item by its unique integer ID. Returns 404 if the item does not exist.",
+    response_description="The requested item with all fields populated",
+    deprecated=False,
+    operation_id="getItemById",
+)
+async def read_item(
+    item_id: int = Path(
+        title="Item ID",
+        description="The unique identifier for the item",
+        ge=1,
+        example=42,
+    ),
+):
+    return {"item_id": item_id, "name": "Widget", "price": 35.99}
+```
+
+If no `summary` is provided, FastAPI uses the function name converted to title case (e.g., `read_item` becomes "Read Item"). If no `description` is provided, FastAPI uses the function's docstring.
+
+The `operation_id` sets a unique identifier for the endpoint in the OpenAPI schema. By default, FastAPI generates operation IDs by combining the HTTP method and function name (e.g., `read_item_items__item_id__get`). Custom operation IDs are useful when generating client SDKs.
+
+## Customizing the OpenAPI Schema
+
+Override or extend the generated schema programmatically:
+
+```python
+from fastapi import FastAPI
+from fastapi.openapi.utils import get_openapi
+
+app = FastAPI()
+
+def custom_openapi():
+    if app.openapi_schema:
+        return app.openapi_schema
+
+    openapi_schema = get_openapi(
+        title="Custom API",
+        version="3.0.0",
+        summary="An API with a custom OpenAPI schema",
+        description="This schema includes additional vendor extensions.",
+        routes=app.routes,
+    )
+
+    # Add custom vendor extension
+    openapi_schema["x-api-audience"] = "public"
+
+    # Modify schema components
+    openapi_schema["info"]["x-logo"] = {
+        "url": "https://example.com/logo.png",
+        "altText": "API Logo",
+    }
+
+    app.openapi_schema = openapi_schema
+    return app.openapi_schema
+
+app.openapi = custom_openapi
+```
+
+The `get_openapi()` function generates the base schema from the application's routes. By assigning the result to `app.openapi_schema`, you cache it so it is only generated once. The cached schema is served at `/openapi.json` for all subsequent requests.
+
+## Multiple Examples
+
+Provide multiple request/response examples for a single endpoint:
+
+```python
+from fastapi import Body
+
+@app.post("/items/")
+async def create_item(
+    item: Item = Body(
+        openapi_examples={
+            "minimal": {
+                "summary": "Minimal item",
+                "description": "Only required fields",
+                "value": {"name": "Widget", "price": 9.99},
+            },
+            "complete": {
+                "summary": "Complete item",
+                "description": "All fields populated",
+                "value": {
+                    "name": "Premium Widget",
+                    "price": 35.99,
+                    "description": "A high-quality widget",
+                },
+            },
+        },
+    ),
+):
+    return item
+```
+
+These examples appear in Swagger UI as a dropdown menu, allowing API consumers to quickly test different request scenarios. Each example requires a `summary` and `value`; the `description` is optional.

data/tech_docs/fastapi_pagination.md

@@ -0,0 +1,169 @@
+# Pagination in FastAPI
+
+Pagination is essential for any API that returns collections of resources. Without pagination, endpoints serving large datasets would consume excessive memory, bandwidth, and time. FastAPI supports multiple pagination strategies, each suited to different use cases.
+
+## Offset/Limit Pagination (Skip/Limit Pattern)
+
+The most common approach uses `skip` and `limit` query parameters:
+
+```python
+from fastapi import FastAPI, Query, Depends
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class Item(BaseModel):
+    id: int
+    name: str
+    price: float
+
+# Simulated database with 10,000 items
+all_items = [Item(id=i, name=f"Item {i}", price=round(i * 1.5, 2)) for i in range(1, 10001)]
+
+class PaginationParams:
+    def __init__(
+        self,
+        skip: int = Query(default=0, ge=0, description="Number of items to skip"),
+        limit: int = Query(default=20, ge=1, le=100, description="Number of items to return"),
+    ):
+        self.skip = skip
+        self.limit = limit
+
+@app.get("/items/")
+async def list_items(pagination: PaginationParams = Depends()):
+    items = all_items[pagination.skip : pagination.skip + pagination.limit]
+    return {
+        "items": items,
+        "total": len(all_items),
+        "skip": pagination.skip,
+        "limit": pagination.limit,
+    }
+```
+
+This implementation uses a default page size of 20 items, a minimum of 1 item per page, and a maximum of 100 items per page. For a dataset of 10,000 items with the default page size of 20, there are 500 total pages. Requesting page 3 would use `skip=40&limit=20` to retrieve items 41 through 60.
+
+The offset/limit pattern is simple to implement but has performance drawbacks for large offsets. A query with `skip=9000` on a SQL database must scan and discard 9,000 rows before returning the requested 20, resulting in O(n) performance where n is the offset value.
+
+## Cursor-Based Pagination
+
+Cursor-based pagination uses an opaque token (cursor) pointing to the last item in the previous page. This avoids the performance degradation of large offsets:
+
+```python
+import base64
+from fastapi import FastAPI, Query
+
+app = FastAPI()
+
+def encode_cursor(item_id: int) -> str:
+    return base64.urlsafe_b64encode(f"id:{item_id}".encode()).decode()
+
+def decode_cursor(cursor: str) -> int:
+    decoded = base64.urlsafe_b64decode(cursor.encode()).decode()
+    return int(decoded.split(":")[1])
+
+@app.get("/items/")
+async def list_items(
+    cursor: str | None = Query(default=None, description="Pagination cursor"),
+    limit: int = Query(default=20, ge=1, le=100),
+):
+    if cursor:
+        last_id = decode_cursor(cursor)
+        # In a real DB: SELECT * FROM items WHERE id > last_id ORDER BY id LIMIT limit
+        items = [item for item in all_items if item.id > last_id][:limit]
+    else:
+        items = all_items[:limit]
+
+    next_cursor = None
+    if len(items) == limit:
+        next_cursor = encode_cursor(items[-1].id)
+
+    return {
+        "items": items,
+        "next_cursor": next_cursor,
+        "limit": limit,
+        "has_more": len(items) == limit,
+    }
+```
+
+Cursor-based pagination maintains consistent O(1) performance regardless of how deep into the dataset the client has paginated. It is the recommended approach for datasets exceeding 100,000 records or for real-time feeds where items may be inserted or deleted between page requests.
+
+## Pagination with Total Count and Link Headers
+
+Include total count metadata and RFC 5988 Link headers for discoverability:
+
+```python
+from fastapi import FastAPI, Query, Response
+from math import ceil
+
+app = FastAPI()
+
+@app.get("/items/")
+async def list_items(
+    response: Response,
+    page: int = Query(default=1, ge=1, description="Page number"),
+    per_page: int = Query(default=20, ge=1, le=100, description="Items per page"),
+):
+    total = len(all_items)
+    total_pages = ceil(total / per_page)
+    skip = (page - 1) * per_page
+    items = all_items[skip : skip + per_page]
+
+    # Build Link headers
+    base_url = "/items/"
+    links = []
+    if page > 1:
+        links.append(f'<{base_url}?page=1&per_page={per_page}>; rel="first"')
+        links.append(f'<{base_url}?page={page - 1}&per_page={per_page}>; rel="prev"')
+    if page < total_pages:
+        links.append(f'<{base_url}?page={page + 1}&per_page={per_page}>; rel="next"')
+        links.append(f'<{base_url}?page={total_pages}&per_page={per_page}>; rel="last"')
+
+    response.headers["Link"] = ", ".join(links)
+    response.headers["X-Total-Count"] = str(total)
+    response.headers["X-Total-Pages"] = str(total_pages)
+
+    return {
+        "items": items,
+        "page": page,
+        "per_page": per_page,
+        "total": total,
+        "total_pages": total_pages,
+    }
+```
+
+With 10,000 items and a default page size of 20, the `X-Total-Pages` header returns 500. At 50 items per page, there are 200 total pages. The Link header follows the RFC 5988 standard used by the GitHub API and other major REST APIs.
+
+## Pagination Response Model
+
+Standardize pagination responses across endpoints with a generic response model:
+
+```python
+from typing import Generic, TypeVar, List
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+class PaginatedResponse(BaseModel, Generic[T]):
+    items: List[T]
+    total: int
+    page: int
+    per_page: int
+    total_pages: int
+
+@app.get("/items/", response_model=PaginatedResponse[Item])
+async def list_items(
+    page: int = Query(default=1, ge=1),
+    per_page: int = Query(default=20, ge=1, le=100),
+):
+    total = len(all_items)
+    skip = (page - 1) * per_page
+    return PaginatedResponse(
+        items=all_items[skip : skip + per_page],
+        total=total,
+        page=page,
+        per_page=per_page,
+        total_pages=ceil(total / per_page),
+    )
+```
+
+This generic model ensures every paginated endpoint returns a consistent structure. The `total_pages` field is always calculated as `ceil(total / per_page)`. For 10,000 items at 20 per page, that is `ceil(10000 / 20) = 500` pages. For 10,000 items at 30 per page, that is `ceil(10000 / 30) = 334` pages (with the last page containing only 10 items).

data/tech_docs/fastapi_path_params.md

@@ -0,0 +1,108 @@
+# Path Parameters in FastAPI
+
+Path parameters allow you to capture variable segments of a URL path and pass them directly to your route handler function. They are declared using curly braces `{}` in the route path string and must have a corresponding parameter in the function signature.
+
+## Basic Path Parameters
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.get("/users/{user_id}")
+async def read_user(user_id: int):
+    return {"user_id": user_id}
+```
+
+When a client sends a request to `/users/42`, FastAPI will automatically parse `"42"` from the URL, validate that it can be converted to an `int`, and pass `user_id=42` to the handler. If the client sends `/users/abc`, FastAPI returns a 422 Unprocessable Entity response with a detailed validation error.
+
+## Type Annotations and Validation
+
+Path parameters support all standard Python types for automatic conversion:
+
+- `int` -- integer values (e.g., `/items/5`)
+- `float` -- floating-point values (e.g., `/prices/9.99`)
+- `str` -- string values (this is the default if no type is specified)
+- `bool` -- boolean values, accepts `true`, `false`, `1`, `0`, `yes`, `no`
+- `uuid.UUID` -- UUID strings (e.g., `/records/550e8400-e29b-41d4-a716-446655440000`)
+
+## Path Parameter Validation with Path()
+
+Use the `Path()` function from FastAPI to add validation constraints:
+
+```python
+from fastapi import FastAPI, Path
+
+app = FastAPI()
+
+@app.get("/items/{item_id}")
+async def read_item(
+    item_id: int = Path(
+        title="The ID of the item",
+        description="A unique integer identifier",
+        ge=1,
+        le=10000,
+    )
+):
+    return {"item_id": item_id}
+```
+
+The `Path()` function supports these numeric validation parameters:
+
+| Parameter | Meaning               | Example |
+|-----------|-----------------------|---------|
+| `gt`      | greater than          | `gt=0`  |
+| `ge`      | greater than or equal | `ge=1`  |
+| `lt`      | less than             | `lt=100`|
+| `le`      | less than or equal    | `le=99` |
+
+For string path parameters, you can use `min_length` and `max_length` constraints. The default `min_length` is `None` (no minimum), and the maximum allowed `max_length` for path parameters in practice is 255 characters due to URL length limitations in most web servers.
+
+## Route Order Matters
+
+FastAPI evaluates routes in the order they are defined. This is critical when you have routes that could match the same URL pattern:
+
+```python
+@app.get("/users/me")
+async def read_current_user():
+    return {"user": "the current user"}
+
+@app.get("/users/{user_id}")
+async def read_user(user_id: str):
+    return {"user_id": user_id}
+```
+
+The `/users/me` route **must** be declared before `/users/{user_id}`. If the order is reversed, a request to `/users/me` would match the parameterized route first, and `user_id` would receive the string `"me"` as its value instead of triggering the dedicated handler.
+
+## Enum Path Parameters
+
+You can restrict path parameters to a fixed set of values using Python's `Enum`:
+
+```python
+from enum import Enum
+
+class ModelName(str, Enum):
+    alexnet = "alexnet"
+    resnet = "resnet"
+    lenet = "lenet"
+
+@app.get("/models/{model_name}")
+async def get_model(model_name: ModelName):
+    if model_name is ModelName.alexnet:
+        return {"model_name": model_name, "message": "Deep Learning FTW!"}
+    return {"model_name": model_name, "message": "Other model selected"}
+```
+
+If the client sends a value not in the enum, FastAPI returns a 422 response listing all permitted values.
+
+## File Path Parameters
+
+To capture an entire file path (including slashes), use the `:path` converter:
+
+```python
+@app.get("/files/{file_path:path}")
+async def read_file(file_path: str):
+    return {"file_path": file_path}
+```
+
+A request to `/files/home/user/data.csv` will set `file_path` to `"home/user/data.csv"`.

data/tech_docs/fastapi_query_params.md

@@ -0,0 +1,134 @@
+# Query Parameters in FastAPI
+
+Query parameters are the key-value pairs that appear after the `?` in a URL (e.g., `/items?skip=0&limit=10`). In FastAPI, any function parameter that is not part of the path is automatically interpreted as a query parameter.
+
+## Basic Query Parameters
+
+```python
+from fastapi import FastAPI
+
+app = FastAPI()
+
+# Sample data
+fake_items_db = [{"item_name": f"Item {i}"} for i in range(100)]
+
+@app.get("/items/")
+async def read_items(skip: int = 0, limit: int = 10):
+    return fake_items_db[skip : skip + limit]
+```
+
+In this example, both `skip` and `limit` are query parameters with default values. A request to `/items/` uses the defaults (`skip=0`, `limit=10`), while `/items/?skip=20&limit=5` overrides both. FastAPI automatically converts the string values from the URL into their declared Python types.
+
+## Required vs Optional Query Parameters
+
+The distinction between required and optional query parameters depends on whether a default value is provided:
+
+```python
+from fastapi import FastAPI, Query
+from typing import Optional
+
+app = FastAPI()
+
+@app.get("/search/")
+async def search(
+    q: str,                          # Required - no default
+    category: str = "all",           # Optional - has default
+    max_price: Optional[float] = None,  # Optional - default is None
+):
+    results = {"q": q, "category": category}
+    if max_price is not None:
+        results["max_price"] = max_price
+    return results
+```
+
+If a client calls `/search/` without the `q` parameter, FastAPI returns a 422 Unprocessable Entity error. The `category` parameter defaults to `"all"`, and `max_price` defaults to `None`.
+
+## Query Parameter Validation with Query()
+
+The `Query()` function provides additional validation and metadata:
+
+```python
+from fastapi import FastAPI, Query
+
+app = FastAPI()
+
+@app.get("/items/")
+async def read_items(
+    q: str = Query(
+        default=None,
+        min_length=3,
+        max_length=50,
+        pattern="^[a-zA-Z0-9 ]+$",
+        title="Search query",
+        description="The search string to filter items by name",
+        example="laptop",
+    )
+):
+    results = {"items": []}
+    if q:
+        results["q"] = q
+    return results
+```
+
+The `Query()` function supports the following validation parameters for strings:
+
+- `min_length` -- minimum character length (default: `None`, no minimum)
+- `max_length` -- maximum character length (default: `None`, no maximum)
+- `pattern` -- a regular expression the value must match
+
+For numeric query parameters, `Query()` supports the same `gt`, `ge`, `lt`, and `le` constraints as `Path()`.
+
+## Multiple Values for a Single Query Parameter
+
+To accept a list of values for one query parameter (e.g., `/items/?tag=food&tag=drink`), declare the parameter as a `list`:
+
+```python
+from typing import List
+from fastapi import FastAPI, Query
+
+app = FastAPI()
+
+@app.get("/items/")
+async def read_items(
+    tags: List[str] = Query(default=[], description="Filter by tags")
+):
+    return {"tags": tags}
+```
+
+A request to `/items/?tags=food&tags=drink` yields `tags=["food", "drink"]`. The default is an empty list if no tags are provided.
+
+## Combining Path and Query Parameters
+
+Path and query parameters work together seamlessly. FastAPI distinguishes them based on whether the parameter name appears in the path template:
+
+```python
+@app.get("/users/{user_id}/items/")
+async def read_user_items(
+    user_id: int,              # Path parameter (in URL path)
+    skip: int = 0,             # Query parameter (not in path)
+    limit: int = 10,           # Query parameter (not in path)
+    include_archived: bool = False,  # Query parameter
+):
+    return {
+        "user_id": user_id,
+        "skip": skip,
+        "limit": limit,
+        "include_archived": include_archived,
+    }
+```
+
+A request to `/users/42/items/?skip=5&limit=20&include_archived=true` passes `user_id=42` from the path and all other values from the query string. Boolean query parameters accept `true`, `false`, `1`, `0`, `yes`, `no`, `on`, and `off` (case-insensitive). FastAPI converts all these values to Python `bool`.
+
+## Deprecating Query Parameters
+
+You can mark a query parameter as deprecated to signal to API consumers that it will be removed in a future version:
+
+```python
+@app.get("/items/")
+async def read_items(
+    q: str = Query(default=None, deprecated=True)
+):
+    return {"q": q}
+```
+
+The parameter still functions normally, but it appears as deprecated in the generated OpenAPI documentation and Swagger UI.

data/tech_docs/fastapi_request_body.md

@@ -0,0 +1,145 @@
+# Request Body in FastAPI
+
+A request body is data sent by the client to your API, typically as JSON in POST, PUT, or PATCH requests. FastAPI uses Pydantic models to declare, validate, and serialize request bodies with full type safety.
+
+## Defining a Request Body with Pydantic
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class Item(BaseModel):
+    name: str
+    description: str | None = None
+    price: float
+    tax: float = 0.0
+
+@app.post("/items/")
+async def create_item(item: Item):
+    item_dict = item.model_dump()
+    if item.tax > 0:
+        price_with_tax = item.price + item.tax
+        item_dict.update({"price_with_tax": price_with_tax})
+    return item_dict
+```
+
+When a client sends a POST request with a JSON body like `{"name": "Widget", "price": 35.99, "tax": 3.60}`, FastAPI automatically parses the JSON, validates it against the `Item` model, and passes the validated object to the handler. If `description` is omitted, it defaults to `None`. If `tax` is omitted, it defaults to `0.0`. If `name` or `price` is missing, a 422 Unprocessable Entity response is returned.
+
+## Field Validation
+
+The `Field()` function from Pydantic lets you add constraints and metadata to individual model fields:
+
+```python
+from pydantic import BaseModel, Field
+
+class Item(BaseModel):
+    name: str = Field(
+        min_length=1,
+        max_length=100,
+        description="The name of the item",
+    )
+    description: str | None = Field(
+        default=None,
+        max_length=500,
+        description="An optional text description",
+    )
+    price: float = Field(
+        gt=0,
+        le=1_000_000,
+        description="Price must be greater than 0 and at most 1,000,000",
+    )
+    quantity: int = Field(
+        default=1,
+        ge=1,
+        le=9999,
+        description="Quantity between 1 and 9999",
+    )
+```
+
+Pydantic validates all constraints at request time. The `gt`, `ge`, `lt`, `le` parameters mirror the same semantics as FastAPI's `Path()` and `Query()`. The `min_length` and `max_length` parameters work on string fields.
+
+## Nested Models
+
+Pydantic models can contain other models, lists, and complex nested structures:
+
+```python
+from pydantic import BaseModel, HttpUrl
+
+class Image(BaseModel):
+    url: HttpUrl
+    name: str
+    width: int = Field(ge=1, le=10000)
+    height: int = Field(ge=1, le=10000)
+
+class Item(BaseModel):
+    name: str
+    description: str | None = None
+    price: float
+    tags: list[str] = []
+    images: list[Image] = []
+
+class Offer(BaseModel):
+    name: str
+    description: str | None = None
+    items: list[Item]
+    discount_percent: float = Field(ge=0, le=100)
+```
+
+FastAPI validates the entire nested structure recursively. If any nested field fails validation, the error response includes the exact path to the invalid field (e.g., `body -> items -> 0 -> images -> 1 -> url`).
+
+## Combining Body, Path, and Query Parameters
+
+You can accept all three parameter types in a single endpoint:
+
+```python
+from fastapi import FastAPI, Path, Query
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class Item(BaseModel):
+    name: str
+    price: float
+
+@app.put("/items/{item_id}")
+async def update_item(
+    item_id: int = Path(ge=1, le=10000),
+    q: str | None = Query(default=None, max_length=50),
+    item: Item = ...,
+):
+    result = {"item_id": item_id, **item.model_dump()}
+    if q:
+        result["q"] = q
+    return result
+```
+
+FastAPI determines the source of each parameter by these rules: if the parameter name appears in the path string, it is a path parameter; if the type is a Pydantic model (or annotated with `Body()`), it comes from the request body; otherwise, it is a query parameter.
+
+## Multiple Body Parameters
+
+When you need multiple distinct objects in the request body, declare multiple Pydantic model parameters:
+
+```python
+from fastapi import Body
+
+class Item(BaseModel):
+    name: str
+    price: float
+
+class User(BaseModel):
+    username: str
+    email: str
+
+@app.put("/items/{item_id}")
+async def update_item(
+    item_id: int,
+    item: Item,
+    user: User,
+    importance: int = Body(gt=0, le=5),
+):
+    return {"item_id": item_id, "item": item, "user": user, "importance": importance}
+```
+
+The expected JSON body becomes `{"item": {...}, "user": {...}, "importance": 3}`. Each model is keyed by its parameter name. The `Body()` function embeds a singular value inside the body alongside the models, rather than treating it as a query parameter. The maximum request body size is controlled by the ASGI server; Uvicorn defaults to approximately 1 MB.

data/tech_docs/fastapi_response_model.md

@@ -0,0 +1,128 @@
+# Response Model in FastAPI
+
+The `response_model` parameter on route decorators lets you declare the shape of the data your endpoint returns. FastAPI uses it to validate, serialize, and document the response -- filtering out any fields not defined in the model and generating accurate OpenAPI schemas.
+
+## Basic Response Model
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class UserIn(BaseModel):
+    username: str
+    email: str
+    password: str
+
+class UserOut(BaseModel):
+    username: str
+    email: str
+
+@app.post("/users/", response_model=UserOut, status_code=201)
+async def create_user(user: UserIn):
+    # In a real app, hash the password and save to DB
+    return user  # password is automatically filtered out
+```
+
+Even though the handler returns the full `UserIn` object (which includes `password`), the `response_model=UserOut` declaration ensures that only `username` and `email` appear in the response. This is a critical security pattern -- it prevents accidental leakage of sensitive fields like passwords, tokens, or internal IDs.
+
+## Status Codes
+
+FastAPI provides the `status_code` parameter to set the HTTP response status code. Common codes include:
+
+| Code | Constant                           | Usage                |
+|------|------------------------------------|----------------------|
+| 200  | `status.HTTP_200_OK`               | Successful GET       |
+| 201  | `status.HTTP_201_CREATED`          | Successful creation  |
+| 204  | `status.HTTP_204_NO_CONTENT`       | Successful deletion  |
+| 400  | `status.HTTP_400_BAD_REQUEST`      | Client error         |
+| 404  | `status.HTTP_404_NOT_FOUND`        | Resource not found   |
+| 422  | `status.HTTP_422_UNPROCESSABLE_ENTITY` | Validation error |
+
+```python
+from fastapi import status
+
+@app.delete("/items/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_item(item_id: int):
+    # delete logic
+    return None
+```
+
+The default `status_code` for all route decorators is `200`.
+
+## Filtering Fields with response_model_include and response_model_exclude
+
+You can dynamically control which fields appear in the response without creating a separate model:
+
+```python
+class Item(BaseModel):
+    name: str
+    description: str | None = None
+    price: float
+    tax: float = 0.0
+    internal_code: str = "N/A"
+
+@app.get(
+    "/items/{item_id}",
+    response_model=Item,
+    response_model_exclude={"internal_code"},
+)
+async def read_item(item_id: int):
+    return {
+        "name": "Widget",
+        "description": "A useful widget",
+        "price": 35.99,
+        "tax": 3.60,
+        "internal_code": "WDG-001",
+    }
+```
+
+The `response_model_exclude` parameter accepts a `set` of field names to strip from the output. Similarly, `response_model_include` accepts a `set` of field names to keep -- all others are excluded. If both are provided, `response_model_include` is applied first, then `response_model_exclude` removes fields from that subset.
+
+## Excluding Unset and Default Values
+
+Two additional parameters control whether default or unset values appear in the response:
+
+```python
+@app.get(
+    "/items/{item_id}",
+    response_model=Item,
+    response_model_exclude_unset=True,
+)
+async def read_item(item_id: int):
+    return Item(name="Widget", price=35.99)
+    # Response: {"name": "Widget", "price": 35.99}
+    # Fields with defaults (description, tax) are omitted
+```
+
+- `response_model_exclude_unset=True` -- omits fields the user did not explicitly set (default: `False`)
+- `response_model_exclude_defaults=True` -- omits fields whose value matches the default (default: `False`)
+- `response_model_exclude_none=True` -- omits fields with `None` values (default: `False`)
+
+## Multiple Response Models
+
+Use `Union` types or the `responses` parameter to document endpoints that may return different shapes:
+
+```python
+from typing import Union
+
+class ItemPublic(BaseModel):
+    name: str
+    price: float
+
+class ItemAdmin(BaseModel):
+    name: str
+    price: float
+    internal_code: str
+    profit_margin: float
+
+@app.get("/items/{item_id}", response_model=Union[ItemAdmin, ItemPublic])
+async def read_item(item_id: int, is_admin: bool = False):
+    item_data = get_item(item_id)
+    if is_admin:
+        return ItemAdmin(**item_data)
+    return ItemPublic(**item_data)
+```
+
+When using `Union`, Pydantic validates the response against each model in order and uses the first match. Place the more specific model first (the one with more fields) to avoid premature matching.

data/tech_docs/fastapi_security.md

@@ -0,0 +1,155 @@
+# Security and Authentication in FastAPI
+
+FastAPI provides integrated security utilities built on top of OpenAPI standards. It supports OAuth2, API keys, HTTP Basic/Bearer authentication, and OpenID Connect, with each scheme automatically reflected in the interactive documentation.
+
+## OAuth2 with Password Flow
+
+The most common authentication pattern uses OAuth2 "password" flow with JWT tokens:
+
+```python
+from datetime import datetime, timedelta
+from fastapi import FastAPI, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
+from jose import JWTError, jwt
+from pydantic import BaseModel
+
+app = FastAPI()
+
+SECRET_KEY = "your-secret-key-at-least-32-characters-long"
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES = 30
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
+
+class Token(BaseModel):
+    access_token: str
+    token_type: str
+
+class User(BaseModel):
+    username: str
+    email: str | None = None
+    disabled: bool = False
+
+def create_access_token(data: dict, expires_delta: timedelta | None = None):
+    to_encode = data.copy()
+    expire = datetime.utcnow() + (expires_delta or timedelta(minutes=15))
+    to_encode.update({"exp": expire})
+    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
+
+async def get_current_user(token: str = Depends(oauth2_scheme)):
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+        username: str = payload.get("sub")
+        if username is None:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+    user = get_user_from_db(username)
+    if user is None:
+        raise credentials_exception
+    return user
+
+@app.post("/token", response_model=Token)
+async def login(form_data: OAuth2PasswordRequestForm = Depends()):
+    user = authenticate_user(form_data.username, form_data.password)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    access_token = create_access_token(
+        data={"sub": user.username},
+        expires_delta=timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES),
+    )
+    return {"access_token": access_token, "token_type": "bearer"}
+```
+
+The `OAuth2PasswordBearer(tokenUrl="token")` declaration tells FastAPI that the client obtains a token by sending credentials to the `/token` endpoint. The `tokenUrl` is relative to the application root. The token is then sent in subsequent requests via the `Authorization: Bearer <token>` header.
+
+## HTTP Bearer Authentication
+
+For simpler token-based auth without the full OAuth2 flow:
+
+```python
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+security = HTTPBearer()
+
+@app.get("/protected/")
+async def protected_route(
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+):
+    token = credentials.credentials
+    # validate token
+    return {"token": token, "scheme": credentials.scheme}
+```
+
+`HTTPBearer` extracts the token from the `Authorization: Bearer <token>` header. If the header is missing or does not use the Bearer scheme, FastAPI returns a 403 Forbidden response automatically.
+
+## API Key Authentication
+
+API keys can be passed via headers, query parameters, or cookies:
+
+```python
+from fastapi.security import APIKeyHeader, APIKeyQuery
+
+api_key_header = APIKeyHeader(name="X-API-Key", auto_error=True)
+api_key_query = APIKeyQuery(name="api_key", auto_error=False)
+
+async def get_api_key(
+    header_key: str | None = Depends(api_key_header),
+    query_key: str | None = Depends(api_key_query),
+):
+    if header_key == "valid-api-key-12345":
+        return header_key
+    if query_key == "valid-api-key-12345":
+        return query_key
+    raise HTTPException(status_code=403, detail="Invalid API key")
+
+@app.get("/data/", dependencies=[Depends(get_api_key)])
+async def read_data():
+    return {"data": "sensitive information"}
+```
+
+The `auto_error=True` parameter (the default) causes FastAPI to return an automatic 403 error when the key is missing. Setting `auto_error=False` allows the dependency to return `None` instead, letting you check multiple sources.
+
+## OAuth2 Scopes
+
+Scopes provide fine-grained permission control:
+
+```python
+from fastapi.security import SecurityScopes
+
+oauth2_scheme = OAuth2PasswordBearer(
+    tokenUrl="token",
+    scopes={
+        "items:read": "Read items",
+        "items:write": "Create and update items",
+        "admin": "Full administrative access",
+    },
+)
+
+async def get_current_user(
+    security_scopes: SecurityScopes,
+    token: str = Depends(oauth2_scheme),
+):
+    # Decode token and verify required scopes
+    payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
+    token_scopes = payload.get("scopes", [])
+    for scope in security_scopes.scopes:
+        if scope not in token_scopes:
+            raise HTTPException(status_code=403, detail="Not enough permissions")
+    return get_user_from_db(payload.get("sub"))
+
+@app.get("/items/", dependencies=[Depends(Security(get_current_user, scopes=["items:read"]))])
+async def read_items():
+    return [{"item": "Widget"}]
+```
+
+Each endpoint declares the scopes it requires, and the dependency verifies the token contains all necessary permissions before allowing access.

data/tech_docs/fastapi_testing.md

@@ -0,0 +1,153 @@
+# Testing FastAPI Applications
+
+FastAPI applications are tested using the `TestClient` class, which provides a synchronous interface for sending requests to your application without running an actual server. For async testing, use `httpx.AsyncClient`.
+
+## Basic Testing with TestClient
+
+```python
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+app = FastAPI()
+
+@app.get("/items/{item_id}")
+async def read_item(item_id: int, q: str = None):
+    result = {"item_id": item_id}
+    if q:
+        result["q"] = q
+    return result
+
+client = TestClient(app)
+
+def test_read_item():
+    response = client.get("/items/42?q=test")
+    assert response.status_code == 200
+    assert response.json() == {"item_id": 42, "q": "test"}
+
+def test_read_item_not_found():
+    response = client.get("/items/abc")
+    assert response.status_code == 422  # Validation error
+```
+
+The `TestClient` is built on top of `httpx` (which replaced `requests` as of Starlette 0.20.0). It supports all HTTP methods: `client.get()`, `client.post()`, `client.put()`, `client.delete()`, `client.patch()`, `client.options()`, and `client.head()`.
+
+## Pytest Fixtures
+
+Use fixtures to share the `TestClient` and set up test data:
+
+```python
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from myapp.main import app
+from myapp.database import Base, engine
+
+@pytest.fixture(scope="module")
+def client():
+    Base.metadata.create_all(bind=engine)
+    with TestClient(app) as c:
+        yield c
+    Base.metadata.drop_all(bind=engine)
+
+@pytest.fixture
+def auth_headers():
+    return {"Authorization": "Bearer test-token-12345"}
+
+def test_create_item(client, auth_headers):
+    response = client.post(
+        "/items/",
+        json={"name": "Widget", "price": 35.99},
+        headers=auth_headers,
+    )
+    assert response.status_code == 201
+    data = response.json()
+    assert data["name"] == "Widget"
+    assert "id" in data
+```
+
+Using `scope="module"` means the fixture is created once per test module rather than once per test function, improving performance when database setup is expensive. The `with` statement ensures proper cleanup of the test client's underlying transport.
+
+## Overriding Dependencies in Tests
+
+Override dependencies to inject mock services or test databases:
+
+```python
+from fastapi import FastAPI, Depends
+
+app = FastAPI()
+
+async def get_db():
+    db = ProductionDatabase()
+    try:
+        yield db
+    finally:
+        db.close()
+
+@app.get("/items/")
+async def read_items(db=Depends(get_db)):
+    return db.query_all_items()
+
+# In your test file:
+def get_test_db():
+    db = TestDatabase()
+    try:
+        yield db
+    finally:
+        db.close()
+
+app.dependency_overrides[get_db] = get_test_db
+
+client = TestClient(app)
+
+def test_read_items():
+    response = client.get("/items/")
+    assert response.status_code == 200
+
+# Clean up overrides after tests
+app.dependency_overrides.clear()
+```
+
+The `app.dependency_overrides` dictionary maps original dependencies to their replacements. This works for any dependency in the chain, including sub-dependencies. Always call `app.dependency_overrides.clear()` after tests to prevent overrides from leaking between test modules.
+
+## Async Testing with httpx
+
+For testing async-specific behavior (e.g., async database calls, WebSocket-related setup), use `httpx.AsyncClient` with `pytest-asyncio`:
+
+```python
+import pytest
+from httpx import AsyncClient, ASGITransport
+from myapp.main import app
+
+@pytest.mark.anyio
+async def test_read_items_async():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/items/")
+        assert response.status_code == 200
+
+@pytest.mark.anyio
+async def test_create_item_async():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.post(
+            "/items/",
+            json={"name": "Widget", "price": 35.99},
+        )
+        assert response.status_code == 201
+```
+
+The `ASGITransport` connects `httpx` directly to the ASGI application without network overhead. The `base_url` parameter is required but can be any valid URL since no real network requests are made. Install the async test dependencies with `pip install httpx pytest-asyncio` (or use `anyio` with the `@pytest.mark.anyio` marker).
+
+## Testing WebSockets
+
+```python
+def test_websocket():
+    client = TestClient(app)
+    with client.websocket_connect("/ws") as websocket:
+        websocket.send_text("hello")
+        data = websocket.receive_text()
+        assert data == "Message received: hello"
+```
+
+The `websocket_connect` context manager establishes a WebSocket connection. It supports `send_text()`, `send_json()`, `send_bytes()`, `receive_text()`, `receive_json()`, and `receive_bytes()` methods.

data/tech_docs/fastapi_websockets.md

@@ -0,0 +1,150 @@
+# WebSockets in FastAPI
+
+FastAPI supports WebSocket connections through Starlette's WebSocket implementation, enabling full-duplex, bidirectional communication between clients and servers. WebSockets are ideal for real-time features such as chat applications, live dashboards, and streaming updates.
+
+## Basic WebSocket Endpoint
+
+```python
+from fastapi import FastAPI, WebSocket
+
+app = FastAPI()
+
+@app.websocket("/ws")
+async def websocket_endpoint(ws: WebSocket):
+    await ws.accept()
+    while True:
+        data = await ws.receive_text()
+        await ws.send_text(f"Echo: {data}")
+```
+
+The `@app.websocket()` decorator registers a WebSocket route. The handler receives a `WebSocket` object, which must be explicitly accepted by calling `await ws.accept()` before any data can be sent or received. The `accept()` method sends the HTTP 101 Switching Protocols response to the client.
+
+## Send and Receive Methods
+
+The `WebSocket` object provides several methods for communication:
+
+| Method              | Description                              |
+|---------------------|------------------------------------------|
+| `receive_text()`    | Receive a text (string) message          |
+| `receive_bytes()`   | Receive a binary message                 |
+| `receive_json()`    | Receive and parse a JSON message         |
+| `send_text(data)`   | Send a text message                      |
+| `send_bytes(data)`  | Send binary data                         |
+| `send_json(data)`   | Serialize and send a JSON message        |
+| `close(code=1000)`  | Close the connection with a status code  |
+
+The default close code is `1000` (normal closure). Other common codes are `1001` (going away), `1008` (policy violation), and `1011` (unexpected condition). The maximum WebSocket message size defaults to 16 MB in Uvicorn, configurable via the `--ws-max-size` flag.
+
+## Handling Disconnects
+
+Clients can disconnect at any time. Handle this with `WebSocketDisconnect`:
+
+```python
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+
+app = FastAPI()
+
+class ConnectionManager:
+    def __init__(self):
+        self.active_connections: list[WebSocket] = []
+
+    async def connect(self, websocket: WebSocket):
+        await websocket.accept()
+        self.active_connections.append(websocket)
+
+    def disconnect(self, websocket: WebSocket):
+        self.active_connections.remove(websocket)
+
+    async def broadcast(self, message: str):
+        for connection in self.active_connections:
+            await connection.send_text(message)
+
+manager = ConnectionManager()
+
+@app.websocket("/ws/chat")
+async def chat_endpoint(ws: WebSocket):
+    await manager.connect(ws)
+    try:
+        while True:
+            data = await ws.receive_text()
+            await manager.broadcast(f"User says: {data}")
+    except WebSocketDisconnect:
+        manager.disconnect(ws)
+        await manager.broadcast("A user has left the chat")
+```
+
+The `WebSocketDisconnect` exception is raised when `receive_text()`, `receive_bytes()`, or `receive_json()` detects that the client has closed the connection. The exception has a `code` attribute containing the close code sent by the client.
+
+## WebSocket with Path Parameters and Dependencies
+
+WebSocket endpoints support path parameters, query parameters, and dependency injection:
+
+```python
+from fastapi import FastAPI, WebSocket, Depends, Query, Path, Cookie, Header
+
+app = FastAPI()
+
+async def get_token(
+    websocket: WebSocket,
+    token: str | None = Query(default=None),
+    x_token: str | None = Header(default=None),
+):
+    if token is None and x_token is None:
+        await websocket.close(code=1008)
+        return None
+    return token or x_token
+
+@app.websocket("/ws/{room_id}")
+async def room_websocket(
+    ws: WebSocket,
+    room_id: int = Path(ge=1, le=1000),
+    token: str | None = Depends(get_token),
+):
+    if token is None:
+        return
+    await ws.accept()
+    await ws.send_text(f"Connected to room {room_id}")
+    try:
+        while True:
+            data = await ws.receive_text()
+            await ws.send_text(f"[Room {room_id}] {data}")
+    except WebSocketDisconnect:
+        pass
+```
+
+Dependencies for WebSocket endpoints work the same as for HTTP endpoints, including `Depends()`, `Path()`, `Query()`, `Header()`, and `Cookie()`. However, WebSocket endpoints do not support `Body()` parameters since WebSocket communication uses its own message protocol rather than HTTP request bodies.
+
+## WebSocket with JSON Messages
+
+For structured communication, use JSON messages with Pydantic validation:
+
+```python
+from pydantic import BaseModel, ValidationError
+
+class ChatMessage(BaseModel):
+    username: str
+    content: str
+    channel: str = "general"
+
+@app.websocket("/ws/json")
+async def json_websocket(ws: WebSocket):
+    await ws.accept()
+    try:
+        while True:
+            raw_data = await ws.receive_json()
+            try:
+                message = ChatMessage(**raw_data)
+                await ws.send_json({
+                    "status": "ok",
+                    "echo": message.model_dump(),
+                })
+            except ValidationError as e:
+                await ws.send_json({
+                    "status": "error",
+                    "errors": e.errors(),
+                })
+    except WebSocketDisconnect:
+        pass
+```
+
+The `receive_json()` method parses the incoming text message as JSON. If the message is not valid JSON, it raises a `json.JSONDecodeError`. Pydantic validation is applied manually since FastAPI does not automatically validate WebSocket message payloads the way it validates HTTP request bodies.

pyproject.toml

@@ -11,7 +11,7 @@ dependencies = [
     "pydantic>=2.9.0",
     "pydantic-settings>=2.5.0",
     "pyyaml>=6.0",
-    "sentence-transformers>=3.0.0",
+    "sentence-transformers>=3.0.0,<5.0.0",
     "faiss-cpu>=1.8.0",
     "rank-bm25>=0.2.2",
     "structlog>=24.0.0",

scripts/ingest.py

@@ -0,0 +1,109 @@
+"""Ingest documents into the hybrid vector store.
+
+Usage:
+    python scripts/ingest.py --config configs/tasks/tech_docs.yaml
+    python scripts/ingest.py --doc-dir data/tech_docs/ --store-path .cache/store
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Ensure the package is importable when running as a script
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from agent_bench.rag.chunker import chunk_text
+from agent_bench.rag.embedder import Embedder
+from agent_bench.rag.store import HybridStore
+
+
+def ingest(
+    doc_dir: str,
+    store_path: str,
+    chunk_strategy: str = "recursive",
+    chunk_size: int = 512,
+    chunk_overlap: int = 64,
+    model_name: str = "all-MiniLM-L6-v2",
+    cache_dir: str = ".cache/embeddings",
+) -> None:
+    """Ingest all markdown files from doc_dir into a HybridStore."""
+    doc_path = Path(doc_dir)
+    if not doc_path.exists():
+        print(f"Error: document directory {doc_dir} does not exist")
+        sys.exit(1)
+
+    md_files = sorted(doc_path.glob("*.md"))
+    if not md_files:
+        print(f"Error: no markdown files found in {doc_dir}")
+        sys.exit(1)
+
+    print(f"Found {len(md_files)} markdown files in {doc_dir}")
+
+    # Chunk all documents
+    all_chunks = []
+    for md_file in md_files:
+        text = md_file.read_text(encoding="utf-8")
+        source = md_file.name  # bare filename
+        chunks = chunk_text(
+            text, source, strategy=chunk_strategy, chunk_size=chunk_size, chunk_overlap=chunk_overlap
+        )
+        print(f"  {source}: {len(chunks)} chunks")
+        all_chunks.extend(chunks)
+
+    print(f"Total chunks: {len(all_chunks)}")
+
+    # Embed
+    print(f"Embedding with {model_name}...")
+    embedder = Embedder(model_name=model_name, cache_dir=cache_dir)
+    texts = [c.content for c in all_chunks]
+    embeddings = embedder.embed_batch(texts)
+    print(f"Embeddings shape: {embeddings.shape}")
+
+    # Store
+    store = HybridStore(dimension=embeddings.shape[1])
+    store.add(all_chunks, embeddings)
+    store.save(store_path)
+
+    stats = store.stats()
+    print(f"Store saved to {store_path}")
+    print(f"  Chunks: {stats.total_chunks}")
+    print(f"  FAISS index size: {stats.faiss_index_size}")
+    print(f"  Unique sources: {stats.unique_sources}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Ingest documents into vector store")
+    parser.add_argument("--doc-dir", default="data/tech_docs/", help="Document directory")
+    parser.add_argument("--store-path", default=".cache/store", help="Store output path")
+    parser.add_argument("--chunk-strategy", default="recursive", choices=["recursive", "fixed"])
+    parser.add_argument("--chunk-size", type=int, default=512)
+    parser.add_argument("--chunk-overlap", type=int, default=64)
+    parser.add_argument("--model", default="all-MiniLM-L6-v2", help="Embedding model name")
+    parser.add_argument("--cache-dir", default=".cache/embeddings", help="Embedding cache dir")
+    parser.add_argument(
+        "--config", default=None, help="Task config YAML (overrides other args for doc-dir)"
+    )
+    args = parser.parse_args()
+
+    doc_dir = args.doc_dir
+    if args.config:
+        from agent_bench.core.config import load_task_config
+
+        task = load_task_config(Path(args.config).stem, path=Path(args.config))
+        doc_dir = task.document_dir
+
+    ingest(
+        doc_dir=doc_dir,
+        store_path=args.store_path,
+        chunk_strategy=args.chunk_strategy,
+        chunk_size=args.chunk_size,
+        chunk_overlap=args.chunk_overlap,
+        model_name=args.model,
+        cache_dir=args.cache_dir,
+    )
+
+
+if __name__ == "__main__":
+    main()