jumpstart-mode 1.1.13 → 1.1.14

package/.jumpstart/skills/python-developer/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: python-developer
+description: >
+  Use this skill when building, reviewing, testing, refactoring, securing, or productionizing Python
+  applications for AI Innovation Pod and Jump Start delivery. Covers FastAPI services, Pydantic models,
+  SQLModel/SQLAlchemy database layers, RAG pipelines, AI/LLM integrations, document processing, CLI tools,
+  automation scripts, background workers, observability instrumentation, and production deployment workflows.
+  Trigger on: Python, FastAPI, Pydantic, SQLModel, SQLAlchemy, Alembic, pytest, ruff, mypy, uv, Poetry,
+  Typer, Celery, RAG pipeline, embedding pipeline, AI service, LLM client, document ingestion, Python API,
+  Python backend, Python refactor, Python tests, Python Docker. Also trigger when the user asks to scaffold,
+  assess, harden, or productionize any Python codebase, even without naming a specific framework.
+argument-hint: 'Describe the workload type (FastAPI service, RAG pipeline, CLI tool, etc.) and what you need (scaffold, review, test, refactor, secure, deploy).'
+---
+
+# Python Developer
+
+This skill produces **production-ready Python** for AI Innovation Pod and Jump Start delivery teams.
+The goal is never to just "write Python" — it is to generate maintainable, typed, tested, secure,
+observable Python services that can be handed to a client and run in production.
+
+## Reference Index
+
+| Topic | File | Use When |
+|-------|------|----------|
+| Modern Python standards | [references/modern-python-standards.md](./references/modern-python-standards.md) | Before any new file or module |
+| FastAPI patterns | [references/fastapi-patterns.md](./references/fastapi-patterns.md) | Building any HTTP service |
+| Pydantic & settings | [references/pydantic-settings.md](./references/pydantic-settings.md) | Config, schemas, validation |
+| Database patterns | [references/database-patterns.md](./references/database-patterns.md) | SQLModel, SQLAlchemy, Alembic |
+| RAG & document processing | [references/rag-pipeline-patterns.md](./references/rag-pipeline-patterns.md) | AI document pipelines |
+| AI & LLM integration | [references/ai-integration-patterns.md](./references/ai-integration-patterns.md) | LLM clients, embeddings |
+| Testing guide | [references/testing-guide.md](./references/testing-guide.md) | All testing work |
+| Security checklist | [references/security-checklist.md](./references/security-checklist.md) | Security review, hardening |
+| Background jobs | [references/background-jobs.md](./references/background-jobs.md) | Workers, queues, async jobs |
+| CLI tools | [references/cli-tools.md](./references/cli-tools.md) | Typer/Click CLIs, scripts |
+| Observability | [references/observability.md](./references/observability.md) | Logging, tracing, metrics |
+| Docker & local dev | [references/docker-local-dev.md](./references/docker-local-dev.md) | Containerization |
+| CI/CD | [references/ci-cd.md](./references/ci-cd.md) | GitHub Actions, Azure DevOps |
+| Production readiness | [references/production-readiness.md](./references/production-readiness.md) | Pre-launch checklist |
+| Refactoring guide | [references/refactoring-guide.md](./references/refactoring-guide.md) | Safely improving existing code |
+
+## Template Index
+
+| Template | File |
+|----------|------|
+| FastAPI pyproject.toml | [templates/pyproject.fastapi.toml](./templates/pyproject.fastapi.toml) |
+| Package pyproject.toml | [templates/pyproject.package.toml](./templates/pyproject.package.toml) |
+| CLI pyproject.toml | [templates/pyproject.cli.toml](./templates/pyproject.cli.toml) |
+| FastAPI main.py | [templates/main.fastapi.py](./templates/main.fastapi.py) |
+| Settings (pydantic-settings) | [templates/settings.py](./templates/settings.py) |
+| Health route | [templates/health_routes.py](./templates/health_routes.py) |
+| Service layer | [templates/service.py](./templates/service.py) |
+| Repository layer | [templates/repository.py](./templates/repository.py) |
+| SQLModel model | [templates/sqlmodel_model.py](./templates/sqlmodel_model.py) |
+| API test (pytest) | [templates/pytest_api_test.py](./templates/pytest_api_test.py) |
+| Service test (pytest) | [templates/pytest_service_test.py](./templates/pytest_service_test.py) |
+| Docker Compose (FastAPI) | [templates/docker-compose.fastapi.yml](./templates/docker-compose.fastapi.yml) |
+| Dockerfile | [templates/Dockerfile](./templates/Dockerfile) |
+| Makefile | [templates/Makefile](./templates/Makefile) |
+| GitHub Actions CI | [templates/github-actions-python.yml](./templates/github-actions-python.yml) |
+| Typer CLI | [templates/typer_cli.py](./templates/typer_cli.py) |
+| LLM client protocol | [templates/llm_client_protocol.py](./templates/llm_client_protocol.py) |
+
+---
+
+## Step 1 — Assess the Project or Workload
+
+### For an existing project
+
+Run the inspection script to understand the current state:
+
+```bash
+python .github/skills/python-developer/scripts/inspect_python_project.py
+```
+
+The script surfaces: Python version, package manager, layout pattern, web framework,
+database stack, testing setup, type checking, linting, Docker support, and modernization gaps.
+
+Manually check these files if they exist:
+`pyproject.toml`, `requirements.txt`, `requirements-dev.txt`, `setup.py`,
+`Pipfile`, `poetry.lock`, `uv.lock`, `pytest.ini`, `mypy.ini`, `ruff.toml`, `.env.example`
+
+### For a new project
+
+Ask: **What type of Python workload is this?**
+
+| Workload | Canonical structure |
+|----------|-------------------|
+| FastAPI service | `app/api/`, `app/services/`, `app/repositories/`, `app/models/`, `app/schemas/`, `app/core/` |
+| Python package | `src/<package_name>/`, tests at root |
+| CLI tool | `src/<tool>/cli.py`, `src/<tool>/commands/` |
+| Data / AI pipeline | `pipelines/`, `src/<domain>/` modules |
+
+Use the appropriate `pyproject.toml` template and scaffold the folder structure before writing any code.
+
+---
+
+## Step 2 — Apply the Right Pattern
+
+Load the relevant reference file(s) from the index above. Quick guide:
+
+- **New FastAPI endpoint** → `fastapi-patterns.md` + `pydantic-settings.md`
+- **Database model or migration** → `database-patterns.md`
+- **LLM call or embedding** → `ai-integration-patterns.md`
+- **RAG pipeline stage** → `rag-pipeline-patterns.md`
+- **Any new code** → `modern-python-standards.md` for baseline rules
+- **Any security concern** → `security-checklist.md`
+- **Before refactoring** → `refactoring-guide.md` (tests first)
+
+---
+
+## Step 3 — Non-Negotiable Standards
+
+These apply to every file generated or modified regardless of workload type.
+
+### Structure
+- Route handlers stay **thin** — delegate to services; services delegate to repositories
+- One responsibility per module; no circular imports
+- Business logic never lives in `main.py` or route files
+
+### Types
+- All function signatures have type hints
+- Use `Pydantic` for all external data boundaries (request, response, settings)
+- Use `dataclasses` or `Pydantic` for internal domain models
+- No implicit `Any` in new code
+
+### Config
+- All configuration from environment variables via `pydantic-settings`
+- No hardcoded credentials, tokens, or secrets in source
+- `.env.example` committed; `.env` gitignored
+
+### Testing
+- New services and routes get at least one test
+- No large refactor without characterization tests first
+- Tests must not require network access unless explicitly integration tests
+
+### Security
+- Run `check_security_basics.py` script on any new module
+- Validate file uploads (size, MIME type)
+- Parameterize all SQL; never format strings into queries
+- Prompt injection risk review for any AI-facing input
+
+### Observability
+- Structured logging (`structlog` or `logging` with JSON formatter)
+- Correlation/request IDs on every request
+- Token usage logged for all LLM calls
+
+---
+
+## Step 4 — Deliver Cleanly
+
+Before calling any Python implementation complete:
+
+- [ ] `uv run ruff check .` passes (or `ruff check` in active venv)
+- [ ] `uv run ruff format .` applied
+- [ ] `uv run mypy .` has no new errors
+- [ ] `uv run pytest` passes
+- [ ] No secrets in source (`uv run detect-secrets scan`)
+- [ ] `pyproject.toml` is the single source of project metadata
+- [ ] `README.md` or inline comments explain non-obvious decisions
+
+For production handoff, also run through [references/production-readiness.md](./references/production-readiness.md).
+
+---
+
+## Quick-Start Scaffolds
+
+### Minimal FastAPI service
+
+```python
+# app/main.py
+from fastapi import FastAPI
+from app.api.routes import health, documents
+from app.core.config import settings
+from app.core.logging import configure_logging
+
+configure_logging()
+
+app = FastAPI(title=settings.app_name, version="0.1.0")
+app.include_router(health.router)
+app.include_router(documents.router, prefix="/api/v1")
+```
+
+### LLM provider abstraction (required for all AI integrations)
+
+```python
+from typing import Protocol
+from pydantic import BaseModel
+
+
+class CompletionRequest(BaseModel):
+    system_prompt: str
+    user_prompt: str
+    temperature: float = 0.2
+
+
+class CompletionResponse(BaseModel):
+    text: str
+    model: str
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+
+
+class LlmClient(Protocol):
+    def complete(self, request: CompletionRequest) -> CompletionResponse: ...
+```
+
+**Always code against the Protocol, not the concrete provider.**
+This enables provider swaps and makes every AI integration testable.
+
+### Service layer pattern
+
+```python
+# app/services/documents.py
+from app.repositories.documents import DocumentRepository
+from app.schemas.documents import DocumentCreate, DocumentRead
+
+
+class DocumentService:
+    def __init__(self, repo: DocumentRepository) -> None:
+        self.repo = repo
+
+    def create_document(self, payload: DocumentCreate) -> DocumentRead:
+        if not payload.content.strip():
+            raise ValueError("Document content is required.")
+        doc = self.repo.add(payload)
+        return DocumentRead.model_validate(doc)
+```
+
+---
+
+## AI Pod-Specific Guidance
+
+These patterns appear in nearly every AI Innovation Pod delivery:
+
+| Concern | Key principle |
+|---------|---------------|
+| RAG source traceability | Every chunk stores `source_id`, `content_hash`, `chunk_index` |
+| LLM provider portability | Always use a Protocol-based abstraction |
+| Evaluation | Build an eval dataset from day 1; do not demo without evals |
+| Human-in-the-loop | Approval gates must be explicit states, not afterthoughts |
+| Token costs | Log `input_tokens`, `output_tokens` per request from the start |
+| Prompt versioning | Store prompt template version in trace metadata |
+
+For RAG pipelines, load [references/rag-pipeline-patterns.md](./references/rag-pipeline-patterns.md) before writing any ingestion or retrieval code.
+
+For agentic workflows, combine this skill with the `agent-governance` and `agent-observability-spec` skills.

package/.jumpstart/skills/python-developer/evals/evals.json

@@ -0,0 +1,162 @@
+{
+  "skill_name": "python-developer",
+  "version": "1.0.0",
+  "description": "Evaluation suite for the python-developer skill. Tests that the skill produces AI Innovation Pod-compliant Python code across core scenarios.",
+  "evals": [
+    {
+      "id": 1,
+      "scenario": "FastAPI service scaffold",
+      "prompt": "Scaffold a new FastAPI service for document management with SQLModel and Alembic migrations. Include health endpoints, JWT auth, and settings from environment variables.",
+      "expected_behaviors": [
+        "Creates pyproject.toml with uv as package manager",
+        "Uses app factory pattern (create_app function, not module-level app)",
+        "Separates routes, service, and repository layers",
+        "Adds /health and /ready endpoints",
+        "Uses pydantic-settings BaseSettings with SecretStr for secrets",
+        "No hardcoded credentials or database URLs"
+      ],
+      "anti_patterns": [
+        "Business logic inside route handlers",
+        "Direct database access from routes",
+        "Hardcoded config values",
+        "import app from module level before factory call",
+        "requirements.txt as only dependency file"
+      ]
+    },
+    {
+      "id": 2,
+      "scenario": "RAG pipeline for PDF ingestion",
+      "prompt": "Add a RAG pipeline to an existing FastAPI service that processes PDF uploads, chunks them, generates embeddings, and supports semantic search with citations.",
+      "expected_behaviors": [
+        "Uses LlmClient Protocol interface, not concrete OpenAI client",
+        "Implements DocumentChunk SQLModel with pgvector Vector column",
+        "Adds cosine distance search via repository method",
+        "Returns citations (source_file, page_number, chunk_text) in responses",
+        "Logs LLM calls with model, tokens, elapsed_ms, finish_reason via structlog",
+        "Sets max_tokens on all completion requests"
+      ],
+      "anti_patterns": [
+        "Directly instantiating AzureOpenAI inside route handler",
+        "Storing embeddings as JSON strings",
+        "No citation tracking",
+        "Missing max_tokens on completion calls",
+        "No logging of LLM usage metrics"
+      ]
+    },
+    {
+      "id": 3,
+      "scenario": "Security review of Python service",
+      "prompt": "Review this Python service for security issues and provide remediation steps.",
+      "expected_behaviors": [
+        "Checks for hardcoded secrets and API keys",
+        "Identifies missing max_tokens on LLM completion calls",
+        "Checks CORS configuration for allow_origins=[\"*\"]",
+        "Recommends pip-audit for dependency vulnerabilities",
+        "Reviews file upload handling for path traversal",
+        "Checks JWT validation completeness"
+      ],
+      "anti_patterns": [
+        "Skipping OWASP Top 10 coverage",
+        "Only checking one or two issues",
+        "Recommending overly complex remediation for simple issues",
+        "Missing AI-specific security concerns (prompt injection, token exhaustion)"
+      ]
+    },
+    {
+      "id": 4,
+      "scenario": "Unit tests for a service class",
+      "prompt": "Write tests for this DocumentService class that creates, retrieves, lists, and deletes documents.",
+      "expected_behaviors": [
+        "Uses FakeLlmClient or mock repository, not real database",
+        "Tests happy path and error cases (not found, duplicate)",
+        "Follows naming convention: test_<method>_<condition>_<expected>",
+        "Uses pytest fixtures for service and mock repo setup",
+        "Tests that delete returns False when document not found",
+        "Tests are isolated — no shared state between test cases"
+      ],
+      "anti_patterns": [
+        "Tests that hit a real database",
+        "Generic test names like test_service or test_1",
+        "No error-path tests",
+        "Using unittest.TestCase instead of pytest style",
+        "Fixtures defined inline rather than in conftest.py"
+      ]
+    },
+    {
+      "id": 5,
+      "scenario": "Background job processing",
+      "prompt": "Set up background job processing for document ingestion that handles large files and retries failures.",
+      "expected_behaviors": [
+        "Recommends Celery over FastAPI BackgroundTasks for heavy work",
+        "Uses acks_late=True and reject_on_worker_lost=True",
+        "Implements idempotency via content_hash to prevent duplicate ingestion",
+        "Adds job status tracking table for progress reporting",
+        "Configures exponential backoff with max_retries",
+        "Adds Dead Letter Queue handling for repeated failures"
+      ],
+      "anti_patterns": [
+        "Using BackgroundTasks for CPU-bound or long-running work",
+        "No idempotency check",
+        "No retry configuration",
+        "Job status not persisted (can't be queried by client)"
+      ]
+    },
+    {
+      "id": 6,
+      "scenario": "Modernize a legacy Python service",
+      "prompt": "This Flask service uses requirements.txt, no type hints, print() for logging, and direct os.environ.get() calls. Modernize it to AI Pod standards.",
+      "expected_behaviors": [
+        "Migrates to pyproject.toml with uv",
+        "Replaces print() with structlog structured logging",
+        "Adds pydantic-settings Settings class",
+        "Adds type hints to all function signatures",
+        "Suggests FastAPI migration path with tradeoffs",
+        "Adds ruff and mypy to dev dependencies"
+      ],
+      "anti_patterns": [
+        "Rewriting everything at once without a phased plan",
+        "Keeping os.environ.get() after migration",
+        "Adding type hints only to new code",
+        "Missing migration path documentation"
+      ]
+    },
+    {
+      "id": 7,
+      "scenario": "CI pipeline setup",
+      "prompt": "Set up a GitHub Actions CI pipeline for a FastAPI service with PostgreSQL and Redis dependencies.",
+      "expected_behaviors": [
+        "Uses astral-sh/setup-uv@v3 action",
+        "Caches uv packages using uv.lock hash",
+        "Includes postgres service container in test job",
+        "Runs ruff, mypy, pytest, pip-audit, bandit",
+        "Uploads coverage to Codecov",
+        "Includes docker build job gated on lint and test success"
+      ],
+      "anti_patterns": [
+        "Using pip install instead of uv sync",
+        "No dependency caching",
+        "Tests without a real postgres service (SQLite only for integration tests)",
+        "Missing security scan step"
+      ]
+    },
+    {
+      "id": 8,
+      "scenario": "Protocol-based LLM abstraction",
+      "prompt": "Add Azure OpenAI integration to the document service. It needs to be testable without real API calls.",
+      "expected_behaviors": [
+        "Creates LlmClient(Protocol) interface",
+        "Creates CompletionRequest and CompletionResponse Pydantic models",
+        "AzureOpenAIClient implements the protocol",
+        "Creates FakeLlmClient for tests that records calls",
+        "Service receives LlmClient via dependency injection",
+        "All LLM calls log model, tokens, elapsed_ms"
+      ],
+      "anti_patterns": [
+        "Directly calling openai.AzureOpenAI inside service methods",
+        "No test double — tests marked skip or using vcr only",
+        "LLM client instantiated inside route handlers",
+        "Missing token logging"
+      ]
+    }
+  ]
+}

package/.jumpstart/skills/python-developer/references/ai-integration-patterns.md

@@ -0,0 +1,261 @@
+# AI & LLM Integration Patterns
+
+## Core Principle: Always Abstracted
+
+Never call OpenAI, Azure OpenAI, or Anthropic directly from business logic.
+Always code against a Protocol. This enables:
+- Provider swaps without touching service code
+- Test doubles without calling real APIs
+- Consistent logging and retry behavior in one place
+
+## LLM Client Protocol
+
+```python
+# app/integrations/llm.py
+from typing import Protocol, runtime_checkable
+from pydantic import BaseModel
+
+
+class CompletionRequest(BaseModel):
+    system_prompt: str
+    user_prompt: str
+    temperature: float = 0.2
+    max_tokens: int | None = None
+    response_format: str | None = None  # "json_object" for structured output
+
+
+class CompletionResponse(BaseModel):
+    text: str
+    model: str
+    input_tokens: int | None = None
+    output_tokens: int | None = None
+    finish_reason: str | None = None
+
+
+@runtime_checkable
+class LlmClient(Protocol):
+    def complete(self, request: CompletionRequest) -> CompletionResponse: ...
+```
+
+## Azure OpenAI Implementation
+
+```python
+# app/integrations/azure_openai_client.py
+import time
+import structlog
+from openai import AzureOpenAI
+from app.integrations.llm import CompletionRequest, CompletionResponse
+from app.core.config import settings
+
+log = structlog.get_logger(__name__)
+
+
+class AzureOpenAIClient:
+    def __init__(self) -> None:
+        self._client = AzureOpenAI(
+            azure_endpoint=settings.azure_openai_endpoint,
+            api_key=settings.azure_openai_api_key,
+            api_version="2024-02-01",
+        )
+        self.deployment = settings.azure_openai_deployment
+
+    def complete(self, request: CompletionRequest) -> CompletionResponse:
+        start = time.time()
+        try:
+            response = self._client.chat.completions.create(
+                model=self.deployment,
+                messages=[
+                    {"role": "system", "content": request.system_prompt},
+                    {"role": "user", "content": request.user_prompt},
+                ],
+                temperature=request.temperature,
+                max_tokens=request.max_tokens,
+            )
+            choice = response.choices[0]
+            elapsed_ms = round((time.time() - start) * 1000)
+
+            log.info(
+                "llm_completion",
+                model=response.model,
+                input_tokens=response.usage.prompt_tokens if response.usage else None,
+                output_tokens=response.usage.completion_tokens if response.usage else None,
+                finish_reason=choice.finish_reason,
+                elapsed_ms=elapsed_ms,
+            )
+
+            return CompletionResponse(
+                text=choice.message.content or "",
+                model=response.model,
+                input_tokens=response.usage.prompt_tokens if response.usage else None,
+                output_tokens=response.usage.completion_tokens if response.usage else None,
+                finish_reason=choice.finish_reason,
+            )
+        except Exception as exc:
+            log.error("llm_completion_failed", error=str(exc), deployment=self.deployment)
+            raise
+```
+
+## Embedding Client Protocol
+
+```python
+# app/integrations/embeddings.py
+from typing import Protocol
+
+
+class EmbeddingClient(Protocol):
+    model_name: str
+
+    def embed_text(self, text: str) -> list[float]: ...
+    def embed_batch(self, texts: list[str]) -> list[list[float]]: ...
+```
+
+## Azure OpenAI Embedding Implementation
+
+```python
+class AzureOpenAIEmbeddingClient:
+    def __init__(self) -> None:
+        self._client = AzureOpenAI(
+            azure_endpoint=settings.azure_openai_endpoint,
+            api_key=settings.azure_openai_api_key,
+            api_version="2024-02-01",
+        )
+        self.model_name = settings.azure_openai_embedding_deployment
+
+    def embed_text(self, text: str) -> list[float]:
+        return self.embed_batch([text])[0]
+
+    def embed_batch(self, texts: list[str]) -> list[list[float]]:
+        # Azure OpenAI supports up to 2048 inputs per call
+        response = self._client.embeddings.create(
+            input=texts,
+            model=self.model_name,
+        )
+        return [item.embedding for item in response.data]
+```
+
+## Structured Output (JSON Mode)
+
+```python
+import json
+from pydantic import BaseModel
+
+
+class ExtractedEntities(BaseModel):
+    companies: list[str]
+    people: list[str]
+    dates: list[str]
+
+
+def extract_entities(llm: LlmClient, text: str) -> ExtractedEntities:
+    response = llm.complete(CompletionRequest(
+        system_prompt=(
+            "Extract entities from the text. Return valid JSON matching this schema: "
+            '{"companies": [...], "people": [...], "dates": [...]}'
+        ),
+        user_prompt=text,
+        temperature=0.0,
+        response_format="json_object",
+    ))
+
+    data = json.loads(response.text)
+    return ExtractedEntities.model_validate(data)
+```
+
+## Retry with Backoff
+
+```python
+import time
+from typing import TypeVar, Callable
+
+T = TypeVar("T")
+
+
+def with_retry(
+    fn: Callable[[], T],
+    max_attempts: int = 3,
+    initial_delay: float = 1.0,
+    backoff: float = 2.0,
+) -> T:
+    last_exc: Exception | None = None
+    delay = initial_delay
+
+    for attempt in range(max_attempts):
+        try:
+            return fn()
+        except Exception as exc:
+            last_exc = exc
+            if attempt < max_attempts - 1:
+                time.sleep(delay)
+                delay *= backoff
+
+    raise RuntimeError(f"All {max_attempts} attempts failed.") from last_exc
+```
+
+## Prompt Template Management
+
+Store prompt templates as string constants with version identifiers.
+Log the template version with every LLM call.
+
+```python
+# app/prompts/rag.py
+RAG_SYSTEM_PROMPT_V1 = """
+You are a helpful assistant for {company_name}.
+Answer questions using only the provided context.
+Cite sources as [SOURCE N]. If the answer is not in the context, say so clearly.
+"""
+
+RAG_SYSTEM_PROMPT_VERSION = "rag-v1"
+```
+
+```python
+log.info("llm_call", prompt_template=RAG_SYSTEM_PROMPT_VERSION, ...)
+```
+
+## Test Double (no real API calls in unit tests)
+
+```python
+# tests/fakes/llm.py
+from app.integrations.llm import CompletionRequest, CompletionResponse
+
+
+class FakeLlmClient:
+    def __init__(self, response_text: str = "Fake response.") -> None:
+        self.response_text = response_text
+        self.calls: list[CompletionRequest] = []
+
+    def complete(self, request: CompletionRequest) -> CompletionResponse:
+        self.calls.append(request)
+        return CompletionResponse(
+            text=self.response_text,
+            model="fake-model",
+            input_tokens=10,
+            output_tokens=5,
+        )
+```
+
+## Observability Requirements for AI Calls
+
+Every LLM call must log:
+
+| Field | Source |
+|-------|--------|
+| `model` | Response metadata |
+| `input_tokens` | Response usage |
+| `output_tokens` | Response usage |
+| `finish_reason` | Response choice |
+| `prompt_template` | Application constant |
+| `elapsed_ms` | Timing wrapper |
+| `correlation_id` | Request context |
+
+This data is required for cost tracking, quality evaluation, and incident triage.
+
+## Provider Decision Matrix
+
+| Provider | Use When |
+|----------|----------|
+| Azure OpenAI | Client requires Azure data residency or enterprise agreement |
+| OpenAI | Greenfield project, no Azure requirement, fastest iteration |
+| Anthropic | Longer context, document analysis, instruction-following tasks |
+| Local / Ollama | Air-gapped, cost-sensitive, PII that cannot leave premises |
+
+Always make provider selection a configuration change, not a code change.