groundwork-method 0.0.1 → 0.11.0

package/src/engineer-skills/groundwork-python-engineer/references/documentation-mcp.md

@@ -0,0 +1,167 @@
+# Code Documentation
+
+## Hierarchy
+
+Structure documents more reliably than comments. Documentation priority:
+
+1. **Type annotations** — `mypy`/`pyright` reject incorrect types. Zero drift risk.
+2. **Pydantic `Field(description=...)`** — part of the code; flows into OpenAPI, Swagger UI, validation errors.
+3. **Naming** — descriptive function and variable names. Refactor first; comment last.
+4. **Test names** — executable documentation verified by CI.
+5. **Docstrings** — one-line summaries for route handlers (Swagger) and complex public APIs.
+6. **Inline "why" comments** — last resort for genuinely non-obvious decisions.
+
+Levels 1–4 are verified by tooling. Levels 5–6 are human promises with drift risk. Minimise them.
+
+## Pydantic as Documentation
+
+```python
+from pydantic import BaseModel, Field
+from typing import Annotated
+
+class ItemCreate(BaseModel):
+    """Request payload for creating a new item."""
+
+    title: Annotated[str, Field(
+        max_length=200,
+        description="Human-readable item title",
+        examples=["Sprint Planning"],
+    )]
+    owner_id: Annotated[str, Field(
+        description="UUID of the owning user",
+        pattern=r"^[0-9a-f]{8}-...$",
+    )]
+```
+
+**Never duplicate `Field(description=...)` content in a class docstring.** One line for the model's domain role — nothing more.
+
+## Route Handler Docstrings
+
+One line for Swagger UI. Add a second only for non-obvious behaviour:
+
+```python
+@router.post("/items", status_code=201)
+async def create_item(body: ItemCreate) -> ItemResponse:
+    """Creates a new item. Requires `items:write` scope."""
+```
+
+## What to Document
+
+| What | How |
+|------|-----|
+| Pydantic fields | `Field(description=...)` |
+| Pydantic class | One-line docstring |
+| Route handler | One-line for Swagger |
+| Complex public function | Minimal docstring for edge cases |
+| Side effects | Note in docstring |
+| Module (non-obvious name) | 1–3 line module docstring |
+
+## What NOT to Document
+
+- `__init__` with typed parameters — types say everything
+- Simple functions where signature is self-evident
+- `Args`/`Returns` sections that duplicate type hints
+
+Document only what types cannot convey:
+
+```python
+def process(audio_url: str, diarize: bool = True) -> Result:
+    """Processes audio and returns a structured result.
+
+    Raises:
+        DownloadError: If the URL is unreachable.
+        ConfigError: If diarization is requested but API key is missing.
+    """
+```
+
+## Inline Comments
+
+Justified only for genuinely non-obvious "why":
+
+```python
+# Batch size 16 determined via GPU memory profiling on T4 instances.
+segments = self._model.process(data, batch_size=16)
+
+# HACK(alice): Library returns negative start times on clips <2s.
+# Clamp to zero until upstream fix. See lib#XXX.
+for seg in segments:
+    seg.start = max(0.0, seg.start)
+```
+
+## In-Code Markers
+
+```python
+# TODO(bob): Switch to streaming when SDK v4 adds support. Issue #123.
+# FIXME(carol): Race condition on concurrent requests. Issue #456.
+# HACK(dave): Workaround for library bug. Remove after v3.2 upgrade.
+```
+
+A marker without an issue reference will never be resolved.
+
+---
+
+# MCP Servers in Python
+
+## Architecture
+
+MCP servers live in the entrypoint layer. Tools delegate to services — they contain no business logic. Docstrings and type hints are the schema.
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="my-service",
+    instructions="Capabilities this server exposes.",
+)
+```
+
+## Tools
+
+```python
+@mcp.tool()
+async def process_item(
+    input_url: str,
+    language: str = "en",
+) -> ProcessedResult:
+    """
+    Process an item and return structured output.
+
+    Returns segments with labels, confidence scores, and timestamps.
+    Use when you need to convert raw input into structured data.
+
+    Args:
+        input_url: URI of the input file.
+        language: BCP-47 language code.
+    """
+    return await service.process(input_url, language=language)
+```
+
+**The docstring is the tool schema.** Write it for an LLM deciding whether to invoke the tool.
+
+**Return domain types, not SDK types.** Tool return types must serialise to JSON cleanly.
+
+## Resources
+
+Read-only data an agent can browse for context. No inference, no side effects:
+
+```python
+@mcp.resource("items://{item_id}")
+async def get_item(item_id: str) -> Item:
+    """Retrieve a completed item by ID."""
+    return await repository.get(item_id)
+```
+
+## Mounting on FastAPI
+
+```python
+app = FastAPI(lifespan=lifespan)
+app.mount("/mcp", mcp.get_asgi_app())
+```
+
+## Anti-Patterns
+
+- **Business logic in tool body.** One line: a service call.
+- **SDK types in signatures.** Use domain Pydantic models.
+- **Missing docstrings.** Agents cannot select tools with vague descriptions.
+- **`stdio` in production.** Use HTTP transport for concurrent agents.
+- **Resources that run inference.** Resources are reads from storage.

package/src/engineer-skills/groundwork-python-engineer/references/implementation-patterns.md

@@ -0,0 +1,166 @@
+# Implementation Patterns
+
+Concrete Python patterns for trace-first development, error handling, dependency injection, and idiomatic standards.
+
+## 1. Trace-First Development
+
+Every inbound request starts a trace. Every outbound call cascades it.
+
+### Initializing a Span
+
+```python
+from opentelemetry import trace
+
+tracer = trace.get_tracer(__name__)
+
+def process_item(item_id: str) -> None:
+    with tracer.start_as_current_span("ProcessItem") as span:
+        span.set_attribute("item.id", item_id)
+        # ... processing logic
+```
+
+When publishing to Pub/Sub or calling another service, explicitly inject the current trace context into HTTP headers or message attributes.
+
+## 2. Error Handling
+
+Use explicit `Exception` subclasses defined in the Domain to prevent SDK errors from polluting business logic.
+
+### Defining Domain Exceptions
+
+```python
+# src/<package>/core/domain/exceptions.py
+
+class AppError(Exception):
+    """Base exception for all application errors."""
+    def __init__(self, message: str, cause: Exception | None = None):
+        super().__init__(message)
+        self.cause = cause
+
+class ModelInferenceError(AppError):
+    """Raised when an AI model fails to return a valid response."""
+
+class TransientInferenceError(AppError):
+    """Raised on transient provider failures — eligible for retry."""
+
+class PermanentInferenceError(AppError):
+    """Raised on permanent failures — do not retry."""
+```
+
+### Wrapping Errors in Adapters
+
+Adapters catch library-specific errors and raise Domain exceptions:
+
+```python
+# src/<package>/adapters/external_api.py
+class ExternalAPIClient:
+    def process(self, payload: str) -> Result:
+        try:
+            raw = self._client.call(payload)
+            if raw.error:
+                raise ModelInferenceError(f"upstream call failed: {raw.error}")
+            return self._to_domain(raw)
+        except sdk.ServerError as e:
+            raise TransientInferenceError("Provider unavailable", cause=e)
+        except sdk.BadRequestError as e:
+            raise PermanentInferenceError("Invalid payload", cause=e)
+```
+
+## 3. Dependency Injection
+
+### The Port
+
+The Protocol belongs in `src/<package>/core/ports.py` (or its own `src/<package>/core/<capability>.py` module) and uses only Domain language:
+
+```python
+from typing import Protocol
+from <package>.core.domain.models import Result
+
+class Processor(Protocol):
+    def process(self, input_uri: str) -> Result: ...
+```
+
+### The Wiring (Composition Root)
+
+Constructor injection at the entrypoint startup:
+
+```python
+from fastapi import Depends
+from <package>.adapters.processor import ConcreteProcessor
+
+def get_processor() -> Processor:
+    return ConcreteProcessor()
+
+def get_processing_service(
+    processor: Processor = Depends(get_processor)
+) -> ProcessingService:
+    return ProcessingService(processor=processor)
+```
+
+The dependency is typed as the Protocol port, not the concrete adapter — the seam stays on the port, and tests override `get_processor` without touching the service.
+
+## 4. Strict Typing over Duck Typing
+
+Use `typing.Protocol` and strict type hints on all domain models. Dependency inversion is compile-time verifiable via `mypy`/`pyright`:
+
+```python
+from typing import Protocol
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class ProcessingRequest:
+    input_url: str
+    language: str
+
+class Processor(Protocol):
+    def process(self, request: ProcessingRequest) -> str: ...
+```
+
+## 5. Context Managers for Resource Lifecycle
+
+Always use `with` and `@contextmanager` for stateful resources. Guarantees cleanup even when domain logic crashes:
+
+```python
+from contextlib import contextmanager
+import tempfile, os
+
+@contextmanager
+def temporary_file(data: bytes, suffix: str = ".tmp"):
+    """Ensures ephemeral files are always deleted after processing."""
+    fd, path = tempfile.mkstemp(suffix=suffix)
+    try:
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+        yield path
+    finally:
+        if os.path.exists(path):
+            os.remove(path)
+```
+
+## 6. Configuration Validation
+
+Validate all environment variables at startup using `pydantic-settings`. Do not use `os.environ.get()` scattered throughout the codebase.
+
+```python
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import Field
+
+class AppSettings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+
+    environment: str = Field(default="production", pattern="^(development|staging|production)$")
+    database_url: str = Field(..., description="Postgres connection string")
+    api_key: str = Field(..., min_length=16)
+
+# Initialised once at the composition root
+settings = AppSettings()
+```
+
+This ensures missing or invalid configuration crashes the service immediately at boot, rather than during a request.
+
+## 7. Idiomatic Standards
+
+- **PEP 8** for fundamental syntax.
+- **Google Python Style Guide** for enterprise structure and docstrings.
+- **`mypy --strict`** in CI for type safety.
+- **`ruff`** for fast linting and formatting.
+- **`uv`** for dependency management — no `pip`, `poetry`, or `pipenv`.

package/src/engineer-skills/groundwork-python-engineer/references/ml-pipelines.md

@@ -0,0 +1,119 @@
+# ML Pipelines
+
+## The Pipeline Contract
+
+Every ML pipeline step follows the same structure:
+
+1. **Receive a typed domain input** — no SDK types, no raw dicts
+2. **Call a provider** through the port the core owns
+3. **Validate the output** — confidence, shape, required fields — before it crosses the boundary
+4. **Return a typed domain output** safe for downstream consumption
+
+No step owns both inference and persistence. No step reaches into another step's domain. This composability makes each step independently testable and replaceable.
+
+## Data Contracts
+
+Domain models at pipeline boundaries use Pydantic with strict validation:
+
+```python
+from pydantic import BaseModel, Field
+
+class Segment(BaseModel):
+    id: int
+    speaker: str
+    start: float          # seconds — never string formats at domain boundaries
+    end: float
+    text: str
+    confidence: float = Field(ge=0.0, le=1.0)
+
+class ProcessedOutput(BaseModel):
+    segments: list[Segment]
+    metadata: OutputMetadata
+```
+
+## Confidence Validation
+
+Filter low-confidence results before they enter domain logic. The threshold is configuration, not a literal:
+
+```python
+def validate_segments(
+    segments: list[Segment],
+    threshold: float,
+) -> list[Segment]:
+    valid = [s for s in segments if s.confidence >= threshold]
+    if len(valid) < len(segments):
+        logger.warning(
+            "low_confidence_segments_filtered",
+            total=len(segments),
+            filtered=len(segments) - len(valid),
+        )
+    return valid
+```
+
+## Mapping at the Edge
+
+Adapters map SDK responses to domain types at the boundary. Core logic never imports any external SDK:
+
+```python
+# src/<package>/adapters/external_api.py
+class ExternalAPIClient:
+    async def process(self, input_uri: str) -> ProcessedOutput:
+        raw = await self._client.process(input_uri)
+        return self._to_domain(raw)
+
+    def _to_domain(self, raw) -> ProcessedOutput:
+        return ProcessedOutput(
+            segments=[
+                Segment(id=i, speaker=u.speaker or "unknown", ...)
+                for i, u in enumerate(raw.items or [])
+            ],
+            metadata=OutputMetadata(...),
+        )
+```
+
+## Embedding Pipeline
+
+### Batching
+Never embed one item at a time. Batch requests reduce API cost and latency 10–100×.
+
+### Versioning
+Store model name and version alongside every vector. Queries against stale embeddings produce incorrect results. Validate dimensions at the boundary.
+
+### Caching
+Cache on text content + model name + model version. Embedding the same input twice is pure cost with no benefit.
+
+## RAG Pipeline
+
+Three composable, independently testable steps:
+
+1. **Retrieve** — embed query, search vector store for top-k candidates
+2. **Rerank** — score candidates for relevance, discard below threshold
+3. **Generate** — pass reranked context to LLM with a version-controlled prompt
+
+**Prompts are code.** Prompts live in version control as Python constants, go through PR review, and are covered by eval suites. A prompt edited outside version control is an untested code change.
+
+## Streaming Pipeline
+
+Use semantic endpointing: buffer until a natural speech boundary (pause, sentence end), then process the completed chunk. Fixed-duration chunking splits mid-word and produces incoherent outputs.
+
+```python
+class SemanticEndpointer:
+    MIN_CHUNK_DURATION_S = 3.0
+    MIN_SILENCE_MS = 500
+
+    def should_process(self, buffer: AudioBuffer) -> bool:
+        if buffer.duration < self.MIN_CHUNK_DURATION_S:
+            return False
+        if buffer.silence_since_ms < self.MIN_SILENCE_MS:
+            return False
+        return True
+```
+
+## Anti-Patterns
+
+- **Raw SDK responses in domain logic.** Map at the adapter boundary.
+- **Hardcoded thresholds.** Confidence scores belong in configuration.
+- **Embedding one at a time.** Always batch.
+- **Embedding without versioning.** Unqueryable after model change.
+- **Prompts in runtime config.** Unreviewed, untested code changes.
+- **Time-based audio chunking.** Semantic endpointing produces coherent chunks.

package/src/engineer-skills/groundwork-python-engineer/references/ml-systems-ai-engineering.md

@@ -0,0 +1,74 @@
+# ML Systems
+
+Python ML services are services first. They meet the same bars for reliability, observability, and maintainability as any other backend. What makes ML different is _what_ we test (model behaviour), not _whether_ we test.
+
+## Principles
+
+### 1. FastAPI for HTTP, Uvicorn for Serving, `uv` for Everything Else
+One combination, applied everywhere. The Python ecosystem has a hundred alternatives — pick one and stick.
+
+### 2. A Pure Core, Swappable Edges from the Outset
+Explicit `core/domain`, `core/ports.py`, `core/service`, `adapters/`, and `entrypoints/` packages under `src/<package>/` (src-layout), with the inward-dependency rule enforced by `import-linter` in CI. Model clients, storage, and the FastAPI router are all adapters. The core has no model-library imports.
+
+### 3. Model Calls Are External Integrations
+Every model call is wrapped behind a port the core owns, implemented by an adapter with timeouts, retries with jitter, circuit breaking, and rate-limit respect. The core never knows which provider is behind the port. Swapping providers is an adapter change.
+
+### 4. Evals Are Part of the Test Suite
+Eval sets for every significant model-driven behaviour. Run in CI. Numeric scores with committed thresholds. Regressions block merge. "The model got a little worse" is not an acceptable landing state.
+
+### 5. Prompts Are Code, Not Configuration
+Prompts live in version control, are reviewed, are tested, and are versioned. Not in a runtime config that someone can edit by accident.
+
+### 6. Observability Spans Both Sides of the Model Call
+Every model call emits a trace span with input hash, prompt version, model ID, latency, token counts, and cost.
+
+### 7. Caching and Determinism Are Explicit
+Cache when input + prompt version + model are identical. Temperature and seed set explicitly per use case.
+
+### 8. Stateful Containers for Model Serving
+Unlike stateless API services, ML services load models into memory at startup and keep them warm. Cold-starting a large model per request is not viable.
+
+## Anti-Patterns
+
+- **Model library imports in the domain.** If the domain imports `openai` or `torch`, it is broken.
+- **Prompts in runtime config.** Untracked, unreviewed, untested.
+- **"It is ML, testing is different."** The tests just include evals.
+- **Uncached expensive calls.** Every stable call paid for twice is a bug.
+- **Model outputs trusted blindly.** Validate shape, length, content at the boundary.
+- **Synchronous long model calls on the request path.** Queue to worker, return job handle.
+
+---
+
+# AI Engineering
+
+## Principles
+
+1. **Prompts are code.** Version-controlled, reviewed, tested, versioned. Shipped through PR review.
+2. **Evals are tests.** Scored comparisons in CI. Thresholds committed. Regressions block merge.
+3. **Context is the interface.** The context window is the biggest lever on model behaviour. Design it deliberately. Measure its token budget.
+4. **Retrieval matters more than the model.** Good retrieval + boring model > clever model + bad retrieval.
+5. **Model outputs are validated at the boundary.** Shape, length, content, expected enumerations. Parse failures handled explicitly.
+6. **Agents are distributed systems.** Bounded retries, circuit breakers, auditable history.
+7. **Cost is part of evaluation.** Quality, latency, _and_ cost.
+8. **Human oversight is designed in.** Review points for high-stakes outputs.
+
+## Anti-Patterns
+
+- "The model will figure it out." Over-stuffed context windows.
+- Skipping evals "this once." Agent loops without termination.
+- Deterministic reasoning on probabilistic output — use structured schemas.
+
+---
+
+# Agent-Native Systems
+
+## Principles
+
+1. **Every interface has a machine-consumable spec.** OpenAPI, AsyncAPI, `llms.txt`, MCP schemas.
+2. **Specs include descriptions, examples, constraints.** An agent should use the interface without reading implementation.
+3. **MCP is the standard tool surface.** Typed, documented, error-reporting tools.
+4. **`llms.txt` ships alongside docs.** Plain-text channel for agent navigation.
+5. **Errors are structured, stable, actionable.** Agents branch on codes, not prose.
+6. **Idempotency enables retry.** Every write endpoint accepts an idempotency key.
+7. **Outputs are structured.** Schema-constrained generation over free-text-then-parse.
+8. **Documentation reviewed for agent consumption.** Would an agent reading through MCP understand what to do?

package/src/engineer-skills/groundwork-python-engineer/references/observability.md

@@ -0,0 +1,57 @@
+# Observability
+
+## Core Principles
+
+### 1. OpenTelemetry Is the Common Language
+Every service emits traces, metrics, and logs through OpenTelemetry SDKs to a single collector. Vendor lock-in at the collector boundary, not inside application code.
+
+### 2. Traces Are the Primary Signal
+Given a choice between adding a metric or enriching a trace, enrich the trace. Traces preserve causality; metrics aggregate it away.
+
+### 3. The Three Pillars Are One Pillar
+Logs, metrics, and traces are different projections of the same events. A log line includes its trace ID; a metric includes dimensions to pivot back to traces.
+
+### 4. Dashboards Derive from SLOs
+Every dashboard starts with the user-journey SLO it supports. Dashboards derived from SLOs stay useful; dashboards assembled by adding "interesting-looking" graphs drift.
+
+### 5. Trace-Driven Development
+Sketch the trace a new feature should produce _before_ writing the handler. What spans must exist? What attributes? The instrumentation design shapes the code.
+
+### 6. Assert on Telemetry in Tests
+System tests assert that traces are unbroken end-to-end — a missing span is a test failure.
+
+### 7. Logs Are Structured, Sampled, and Contextual
+Every log line is structured (JSON), carries its trace ID, and is emitted at an agreed severity. Sample aggressively at debug/info; do not sample errors.
+
+### 8. Cardinality Is a Design Choice
+High-cardinality on traces (per-user, per-tenant), lower cardinality on metrics.
+
+## Python Implementation
+
+- Use `structlog` for structured logging. Inject `trace_id` and `span_id` from the current OTel context.
+- Every route handler and background task initialises a root span.
+- Adapter calls (API, database, Pub/Sub) extract and cascade the span.
+- ML model calls emit spans with: input hash, prompt version, model ID, latency, token counts, cost.
+
+```python
+from opentelemetry import trace
+
+tracer = trace.get_tracer(__name__)
+
+async def process(self, input_uri: str) -> Result:
+    with tracer.start_as_current_span("Process") as span:
+        span.set_attribute("input.uri", input_uri)
+        span.set_attribute("model.id", self._model_id)
+        result = await self._call_model(input_uri)
+        span.set_attribute("model.tokens", result.usage.total)
+        return result
+```
+
+## Anti-Patterns
+
+- **Pillar-at-a-time adoption.** "We'll add metrics now, traces later."
+- **Vendor SDKs in application code.** Application code imports OTel; the collector talks to the vendor.
+- **Dashboards without SLOs.** Charts without a question they answer.
+- **`print` debugging.** Write a test; add a span.
+- **Cardinality explosions.** UUIDs in Prometheus labels.
+- **Model calls without spans.** An uninstrumented model call is a black box.