groundwork-method 0.0.1 → 0.11.0

package/src/generators/python-microservice/docs/principles/stack/python/testing.md

@@ -0,0 +1,322 @@
+---
+title: Testing
+description: Honeycomb testing for Python microservices — service-perimeter tests as the default, unit tests reserved for complex isolated logic.
+status: active
+last_reviewed: 2026-05-26
+---
+
+# Testing
+
+## TL;DR
+
+We test from the perimeter of the service inward. A request goes in through the HTTP entrypoint, traverses real service and provider logic, and comes back out — with real infrastructure running in containers. Unit tests are reserved for logic so complex it earns isolation. Most tests never see a mock.
+
+---
+
+## The Model: Why Honeycomb, Not Pyramid
+
+The classical test pyramid (many unit tests → some integration tests → few E2E tests) made sense when running a database in a test was expensive and slow. That constraint no longer exists. Testcontainers spins up a real Postgres or Pub/Sub emulator in seconds, and the confidence it provides is categorically different from any mock.
+
+The failure mode of a mock-heavy suite is insidious: tests pass while production breaks. Mocked adapters drift from real behaviour. SQL queries are never exercised. Serialisation boundaries are never crossed. The suite is green and the system is broken.
+
+The **honeycomb model** inverts the priority:
+
+- **Service tests are the default.** The bulk of test coverage comes from tests that exercise the full vertical slice — HTTP in, real infrastructure out.
+- **Unit tests are reserved.** Complex isolated algorithms, domain computations, and pure validation logic earn a unit test. Everything else does not.
+- **System tests are minimal.** A bootstrap test verifies the DI container wires correctly. A small number of golden-path tests exercise the service end-to-end against a live stack.
+
+This gives us a suite where a passing run is a meaningful signal. The bugs we care about — boundary mismatches, SQL correctness, serialisation errors, provider contract violations — are caught before they reach production.
+
+This is the Python idiom of the framework testing canon (`docs/principles/foundations/testing.md`); the canon is the parent principle and wins on any disagreement.
+
+---
+
+## The Three Tiers
+
+### Tier 1 — Service Tests (the default)
+
+A service test drives the FastAPI app through its HTTP interface using `httpx.AsyncClient` with `ASGITransport`. Infrastructure dependencies (Pub/Sub, storage, databases) run in containers. Provider dependencies that cannot be containerised are replaced at the FastAPI dependency boundary using `dependency_overrides` — not mocked in the interior of the code.
+
+This is the tier where most new tests belong. If you are testing a use case, an endpoint, a pipeline step, or a provider interaction with infrastructure — write a service test.
+
+**Structure:**
+
+```
+tests/
+  integration/
+    entrypoints/       # HTTP-level service tests
+    providers/         # Provider tests against real containers or live APIs
+```
+
+**Fixture setup — app + async client:**
+
+```python
+# tests/integration/conftest.py
+import pytest
+import httpx
+from app.main import create_app
+
+@pytest.fixture(scope="session")
+def app():
+    return create_app()
+
+@pytest.fixture
+async def client(app):
+    async with httpx.AsyncClient(
+        transport=httpx.ASGITransport(app=app),
+        base_url="http://test",
+    ) as c:
+        yield c
+```
+
+**Fixture setup — containerised infrastructure:**
+
+```python
+# tests/integration/conftest.py (continued)
+import pytest
+from testcontainers.postgres import PostgresContainer
+from testcontainers.google import PubSubContainer
+
+@pytest.fixture(scope="session")
+def postgres():
+    with PostgresContainer("postgres:16-alpine") as container:
+        yield container
+
+@pytest.fixture(scope="session")
+def pubsub():
+    with PubSubContainer() as container:
+        yield container
+```
+
+Scope containers at `session` when startup cost is high. Reset state between tests using transactions or truncation, not by restarting the container.
+
+**Replacing non-containerisable providers:**
+
+When a provider calls a live third-party API, replace it at the FastAPI boundary — not by patching the internals:
+
+```python
+# tests/integration/entrypoints/test_transcribe_api.py
+import pytest
+from unittest.mock import AsyncMock
+from app.entrypoints.api.dependencies import get_transcriber
+from app.core.domain.models import Transcript
+
+@pytest.fixture
+def fake_transcriber():
+    port = AsyncMock()
+    port.transcribe.return_value = Transcript(...)
+    return port
+
+async def test_transcribe_returns_structured_result(client, app, fake_transcriber):
+    app.dependency_overrides[get_transcriber] = lambda: fake_transcriber
+
+    response = await client.post("/transcribe", json={"audio_url": "gs://bucket/file.mp3"})
+
+    assert response.status_code == 200
+    assert response.json()["segments"][0]["confidence"] >= 0.0
+```
+
+The key distinction: we are replacing the provider at the dependency injection boundary. The route handler, service, and validation logic all run for real. Only the external API call is substituted.
+
+**Live provider tests** (requiring real API keys) live in `tests/integration/providers/` and are marked `@pytest.mark.live` so they can be excluded from normal runs with pytest's `-m` flag:
+
+```python
+@pytest.mark.live
+async def test_assemblyai_transcribes_real_audio(transcriber, audio_fixture):
+    result = await transcriber.transcribe(audio_fixture)
+    assert len(result.segments) > 0
+    assert result.metadata.duration > 0
+```
+
+Run with: `uv run pytest tests/integration -m live`
+
+---
+
+### Tier 2 — Unit Tests (reserved)
+
+A unit test is appropriate when the logic is genuinely complex, has many branches, operates on pure data, and would be painful to exercise through the full HTTP stack. Domain model invariants, audio codec transformations, confidence score calculations, and parsing algorithms are good candidates.
+
+The test for "does this service method call the adapter and return the result" is not a unit test. That behaviour is validated by a service test.
+
+**What earns a unit test:**
+
+- Domain models: immutability, field validation, business rules
+- Complex transformations: audio resampling, segment merging, transcript normalisation
+- Pure algorithms: confidence thresholding, speaker attribution logic, chunking strategies
+- Edge cases too costly to set up through a real HTTP path
+
+**What does not earn a unit test:**
+
+- Service methods that orchestrate calls between an adapter and a domain object
+- Endpoint handlers that validate input and delegate
+- Providers that translate SDK responses into domain types
+
+**Pattern — domain model:**
+
+```python
+# tests/unit/core/domain/test_transcript.py
+class TestTranscriptSegment:
+    def test_rejects_confidence_above_one(self):
+        with pytest.raises(ValidationError):
+            TranscriptSegment(text="hello", confidence=1.5, start=0.0, end=1.0)
+
+    def test_is_immutable(self):
+        segment = TranscriptSegment(text="hello", confidence=0.9, start=0.0, end=1.0)
+        with pytest.raises(ValidationError):
+            segment.text = "goodbye"
+```
+
+**Pattern — complex algorithm:**
+
+```python
+# tests/unit/providers/test_audio_codec.py
+class TestResample:
+    def test_output_matches_target_sample_rate(self, codec, wav_16khz):
+        result = codec.resample(wav_16khz, target_hz=8000)
+        assert result.sample_rate == 8000
+
+    def test_duration_is_preserved_within_tolerance(self, codec, wav_16khz):
+        result = codec.resample(wav_16khz, target_hz=8000)
+        assert abs(result.duration - wav_16khz.duration) < 0.01
+```
+
+---
+
+### Tier 3 — System Tests (minimal)
+
+System tests answer one question: does the fully-wired application start and serve requests correctly? There are two of them.
+
+**Bootstrap test** — verifies the DI container initialises without error. Catches missing environment variables, wiring mistakes, and import-time failures before they hit production:
+
+```python
+# tests/system/test_bootstrap.py
+def test_application_starts_without_error():
+    app = create_app()
+    assert app is not None
+```
+
+**Golden path test** — one end-to-end test per critical user journey, run against the full live stack in CI. Not a substitute for service tests; a smoke check that the seams hold.
+
+---
+
+## Async Configuration
+
+All test functions are async by default. `asyncio_mode = "auto"` in `pyproject.toml` means no decorator is needed:
+
+```toml
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+```
+
+Write async tests as plain `async def` functions:
+
+```python
+async def test_streaming_session_emits_events(client):
+    response = await client.post("/streaming/start", json={"meeting_id": "m-1"})
+    assert response.status_code == 200
+```
+
+Do not use `@pytest.mark.asyncio` — it is redundant under auto mode and adds noise.
+
+---
+
+## Test Isolation
+
+**Container-backed tests** should not share state. Use one of:
+
+- **Transaction rollback** — wrap each test in a transaction and roll back on teardown. Zero teardown cost, guaranteed clean state.
+- **Truncation fixture** — truncate relevant tables in a `function`-scoped fixture. Slower but simpler when transactions interfere with the code under test.
+
+Never rely on test ordering to manage state. A test that requires a previous test to have run is a broken test.
+
+**`dependency_overrides` cleanup** — always reset overrides after a test to prevent state leaking between tests:
+
+```python
+@pytest.fixture(autouse=True)
+def reset_dependency_overrides(app):
+    yield
+    app.dependency_overrides.clear()
+```
+
+---
+
+## Naming
+
+Every test name describes observable behaviour, not implementation:
+
+```python
+# Good
+async def test_transcribe_returns_422_when_audio_url_is_missing(client): ...
+async def test_streaming_session_assigns_unique_id_per_meeting(client): ...
+
+# Bad
+async def test_transcribe_success(client): ...
+async def test_streaming(client): ...
+```
+
+A failing test name should give an on-call engineer enough information to form a hypothesis without opening the test file.
+
+---
+
+## Trace Assertions — observability is a test surface
+
+A critical-path request must emit an unbroken trace; a missing span is a test failure, not an instrumentation TODO. Register an OTel **`InMemorySpanExporter`** in the test process, exercise the endpoint, and assert on the finished spans — the entry span exists, the trace stays connected across the service hop, and the attributes a dashboard query depends on are present.
+
+```python
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
+
+@pytest.fixture
+def spans():
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    # install provider for the test, exercise the system, then:
+    return exporter
+
+async def test_transcribe_emits_connected_trace(client, spans):
+    await client.post("/transcribe", json={"audio_url": "gs://b/f.mp3"})
+    names = [s.name for s in spans.get_finished_spans()]
+    assert "POST /transcribe" in names
+```
+
+Assert the spans the contract promises and let the rest float — pinning the whole tree couples the test to implementation.
+
+---
+
+## Mutation Testing — the assertion-quality read-out
+
+A service test drives many branches through one HTTP call and can *execute* them all while only asserting on the response body. Mutation testing proves the suite checks what it runs: inject a fault, confirm a test fails; a surviving mutant is a covered-but-unchecked line. Python's tooling is production-grade — **`mutmut`** and **`cosmic-ray`** — but it is expensive, so it is a **signal, never a gate**: run it incrementally on the high-risk modules the risk matrix flags and on changed code only. A surviving mutant on changed high-risk code is the missing assertion to add — the same read-out catches AI-generated tests whose oracle was lifted from the implementation. (Note: `mutmut` 3 no longer mutates module-level code.)
+
+---
+
+## Generate the Inputs You Can't Enumerate
+
+Example-based tests check the cases you thought of; the bugs live in the cases you didn't. For pure logic with a real invariant — a round-trip (`decode ∘ encode = id`), a parser that must never raise, a domain calculation with an algebraic law — state the property and let **`Hypothesis`** generate and shrink counterexamples. One property covers an infinity of examples, and most caught faults surface on a single generated input. At the API boundary, **Schemathesis** derives a semantics-aware fuzzer straight from the OpenAPI schema and finds materially more defects than example-based API tests for the cost of pointing it at the spec. Reach for these where invariants are real; the authoring cost (a meaningful property needs a generator) is why they are not everywhere.
+
+---
+
+## Running Tests
+
+```bash
+uv run pytest tests/unit                        # Unit tests — no infrastructure required
+uv run pytest tests/integration -m "not live"   # Service tests — requires Docker; skips live APIs
+uv run pytest tests/integration -m live         # Live API provider tests — requires real keys
+uv run pytest tests/system                      # Bootstrap + golden path
+uv run pytest                                   # Everything
+```
+
+---
+
+## Anti-Patterns
+
+**Mocking the interior of a service.** Replacing an adapter with `MagicMock` inside a service test asserts nothing about real behaviour. If you are mocking something that could run in a container, use a container.
+
+**Testing that delegation happens.** `assert transcriber.transcribe.called_once_with(segment)` is an assertion about the implementation, not the behaviour. Test what comes back out of the system, not which internal methods were invoked.
+
+**Fixture factories that mirror the domain.** A fixture that constructs a complex domain object with many defaults trains engineers to not think about what data matters for the test. Construct only what the test needs; leave everything else visible.
+
+**`scope="session"` on mutable state.** Session-scoped fixtures that hold mutable objects leak state between tests. Containers are safe at session scope. Application state is not.
+
+**Skipping the async client.** `TestClient` is a synchronous wrapper that hides async behaviour. Use `httpx.AsyncClient` with `ASGITransport` for all entrypoint tests so the lifespan and async middleware execute correctly.

package/src/generators/python-microservice/files/.env.example.template

@@ -0,0 +1,30 @@
+# Environment Configuration
+# Copy this file to .env and fill in the values.
+
+# HTTP server port for this service.
+SERVER_PORT=<%= assignedPort %>
+<% if (postgres) { %>
+# Postgres connection (composed into the async DSN by the service config).
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=postgres
+DB_PASSWORD=postgres
+DB_NAME=<%= fileName %>
+<% } %>
+<% if (messaging === 'redis' || websockets) { %>
+# Redis (message bus and/or WebSocket backplane).
+REDIS_URL=redis://localhost:6379
+<% } %>
+<% if (messaging === 'kafka') { %>
+# Kafka broker list (comma-separated host:port).
+KAFKA_BROKERS=localhost:9092
+<% } %>
+<% if (messaging === 'gcp-pubsub') { %>
+# GCP Pub/Sub project id (use any value when running against the emulator).
+PUBSUB_PROJECT_ID=local-project
+<% } %>
+# OpenTelemetry OTLP gRPC endpoint for trace export. Docker compose injects the
+# in-cluster Jaeger address; this default covers native (`./dev start`) runs.
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+<%# LLM env vars are written by the llm capability footprint (plan WS-F) so they
+    match the chosen provider's defaults — see the "# llm capability" block. %>

package/src/generators/python-microservice/files/Dockerfile.template

@@ -0,0 +1,36 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Install system dependencies (e.g. for psycopg2, if needed)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv for fast dependency resolution
+RUN pip install uv
+
+COPY pyproject.toml .
+# Compile locked requirements for layer caching, then install
+RUN uv pip compile pyproject.toml -o requirements.txt \
+    && uv pip install --system -r requirements.txt
+
+COPY src/ ./src/
+# src-layout: the importable package is src/<%= packageName %>, so the source root
+# (not the app root) is what goes on the import path.
+ENV PYTHONPATH=/app/src
+<% if (postgres) { %>
+# Declarative schema (db/schema.sql) + apply-schema.sh, applied by `./dev migrate`.
+COPY db/ ./db/
+COPY scripts/ ./scripts/
+<% } %>
+
+<% if (runpod) { %>
+# Runpod serverless entrypoint
+CMD ["python", "-m", "<%= packageName %>.entrypoints.worker.worker"]
+<% } else { %>
+# FastAPI entrypoint
+EXPOSE <%= assignedPort %>
+CMD ["uvicorn", "<%= packageName %>.main:app", "--host", "0.0.0.0", "--port", "<%= assignedPort %>"]
+<% } %>

package/src/generators/python-microservice/files/db/schema.sql.template

@@ -0,0 +1,19 @@
+-- Declarative Schema definition
+-- Use a diffing engine (e.g. pg-schema-diff or atlas) to apply this to the database.
+
+CREATE TABLE examples (
+    id VARCHAR(36) PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    description TEXT
+);
+
+CREATE TABLE idempotency_keys (
+    key VARCHAR(255) PRIMARY KEY,
+    user_id VARCHAR(255) NOT NULL,
+    status VARCHAR(50) NOT NULL,
+    response_code INT,
+    response_body TEXT,
+    response_headers TEXT,
+    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);

package/src/generators/python-microservice/files/pyproject.toml.template

@@ -0,0 +1,76 @@
+[project]
+name = "<%= name %>"
+version = "0.1.0"
+description = "A GroundWork python microservice"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "tenacity>=8.0.0",
+    "circuitbreaker>=2.0.0",
+    "httpx>=0.27.0",
+    "opentelemetry-api",
+    "opentelemetry-sdk",
+    "opentelemetry-instrumentation-fastapi",
+    "opentelemetry-exporter-otlp-proto-grpc",
+    "python-json-logger>=2.0.0",
+    "fastapi>=0.110.0",
+    "uvicorn[standard]>=0.29.0",
+<% if (postgres) { %>
+    "sqlalchemy>=2.0.0",
+    "asyncpg>=0.29.0",
+    "alembic>=1.13.0",
+    # SQLAlchemy's async engine requires greenlet at runtime; it is not always
+    # pulled in transitively (notably on newer Python), so pin it explicitly —
+    # without it every async DB call raises "the greenlet library is required".
+    "greenlet>=3.0.0",
+<% } %>
+<% if (messaging === 'redis' || websockets) { %>
+    "redis>=5.0.0",
+<% } %>
+<% if (runpod) { %>
+    "runpod>=1.5.0",
+<% } %>
+]<%# The LLM provider dependency (anthropic/openai/none) is injected by the llm
+    capability footprint, plan WS-F — not declared inline. %>
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "testcontainers[postgres,redis]>=3.7.1",
+    "httpx>=0.27.0",
+    "import-linter>=2.0",
+    "ruff>=0.6.0",
+    "black>=24.0.0"
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/<%= packageName %>"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+# import-linter enforces the inward dependency rule structurally: the core
+# (domain + service ports) must never import an adapter, an entrypoint, or a
+# web/db framework. Run `lint-imports` to check it (CI + pre-commit).
+[tool.importlinter]
+root_package = "<%= packageName %>"
+
+[[tool.importlinter.contracts]]
+name = "core depends on nothing outward"
+type = "forbidden"
+source_modules = [
+    "<%= packageName %>.core",
+]
+forbidden_modules = [
+    "<%= packageName %>.adapters",
+    "<%= packageName %>.entrypoints",
+    "fastapi",
+    "sqlalchemy",
+]

package/src/generators/python-microservice/files/scripts/apply-schema.sh.template

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -e
+
+# Loads environment variables if .env exists
+if [ -f .env ]; then
+    export $(cat .env | xargs)
+fi
+
+# Ensure database URL is available
+DB_URL=${DATABASE_URL:-"postgres://postgres:postgres@localhost:5432/<%= name %>?sslmode=disable"}
+
+echo "Applying declarative schema to database..."
+
+# Uses Stripe's pg-schema-diff to declaratively migrate the database to match
+# db/schema.sql. This is a Python service (no go.mod), so the tool is pinned with
+# an explicit @version — `go run <pkg>@<ver>` runs module-independently, whereas a
+# bare `go run <pkg>` would require a surrounding go.mod. Version matches the Go
+# scaffold's pinned pg-schema-diff for parity. Requires the Go toolchain on PATH
+# (./dev doctor checks for it when a Python service is present).
+go run github.com/stripe/pg-schema-diff/cmd/pg-schema-diff@v1.0.5 apply \
+    --from-dsn "$DB_URL" \
+    --to-dir ./db \
+    --skip-confirm-prompt
+
+echo "Schema applied successfully!"

package/src/generators/python-microservice/files/src/__packageName__/adapters/comfyui.py.template

@@ -0,0 +1,87 @@
+import httpx
+import websockets
+import json
+import logging
+from typing import Dict, Any, Optional
+from circuitbreaker import circuit
+from <%= packageName %>.adapters.config import settings
+from <%= packageName %>.core.domain.exceptions import TransientInferenceError, PermanentInferenceError, CircuitBreakerOpenError
+
+logger = logging.getLogger(__name__)
+
+def comfyui_fallback(e):
+    logger.error(f"ComfyUI circuit breaker tripped! {e}")
+    raise CircuitBreakerOpenError("ComfyUI server is currently unavailable.")
+
+class ComfyUIClient:
+    """
+    Adapter to interact with a remote ComfyUI instance over REST and WebSockets.
+    """
+    def __init__(self):
+        self.http_client = httpx.AsyncClient(base_url=settings.comfyui_base_url, timeout=60.0)
+        # ComfyUI websocket uses ws:// instead of http://
+        self.ws_url = settings.comfyui_base_url.replace("http://", "ws://").replace("https://", "wss://") + "/ws"
+        self.client_id = "media-service-client-1"
+        
+    @circuit(failure_threshold=3, recovery_timeout=60, fallback_function=comfyui_fallback, expected_exception=TransientInferenceError)
+    async def queue_prompt(self, workflow_json: Dict[str, Any]) -> str:
+        """
+        Submits a workflow to ComfyUI for execution and returns the Prompt ID.
+        """
+        payload = {
+            "prompt": workflow_json,
+            "client_id": self.client_id
+        }
+        
+        try:
+            response = await self.http_client.post("/prompt", json=payload)
+            
+            if response.status_code >= 500:
+                raise TransientInferenceError(f"ComfyUI internal server error: {response.text}")
+            elif response.status_code >= 400:
+                raise PermanentInferenceError(f"Invalid workflow request: {response.text}")
+                
+            data = response.json()
+            prompt_id = data.get("prompt_id")
+            if not prompt_id:
+                raise PermanentInferenceError("ComfyUI response missing prompt_id")
+                
+            return prompt_id
+            
+        except httpx.RequestError as e:
+            raise TransientInferenceError(f"Network error connecting to ComfyUI: {e}")
+
+    async def poll_execution_progress(self, prompt_id: str) -> None:
+        """
+        Connects via WebSocket to listen for progress updates for a specific prompt_id.
+        In a real application, you would yield progress events or store them in Redis.
+        """
+        try:
+            url = f"{self.ws_url}?clientId={self.client_id}"
+            async with websockets.connect(url) as ws:
+                while True:
+                    msg = await ws.recv()
+                    if isinstance(msg, str):
+                        data = json.loads(msg)
+                        if data['type'] == 'executing':
+                            node = data['data'].get('node')
+                            if node is None and data['data'].get('prompt_id') == prompt_id:
+                                # Execution is finished
+                                break
+                        elif data['type'] == 'progress':
+                            # Log or publish progress
+                            pass
+        except websockets.exceptions.WebSocketException as e:
+            raise TransientInferenceError(f"WebSocket disconnected from ComfyUI: {e}")
+            
+    async def get_history(self, prompt_id: str) -> Dict[str, Any]:
+        """Fetches the generated artifacts/outputs from ComfyUI history."""
+        try:
+            response = await self.http_client.get(f"/history/{prompt_id}")
+            if response.status_code == 200:
+                history = response.json()
+                return history.get(prompt_id, {})
+            else:
+                raise TransientInferenceError("Failed to fetch history")
+        except httpx.RequestError as e:
+            raise TransientInferenceError(f"Network error fetching history: {e}")

package/src/generators/python-microservice/files/src/__packageName__/adapters/config.py.template

@@ -0,0 +1,48 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from typing import Optional
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file='.env', env_file_encoding='utf-8', extra='ignore')
+    
+    server_port: int = <%= assignedPort %>
+
+    # OTLP gRPC endpoint for trace export. Compose injects
+    # OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317 for docker; this default
+    # covers native (`./dev start`) runs. BaseSettings maps the env var
+    # case-insensitively onto this field.
+    otel_exporter_otlp_endpoint: str = "http://localhost:4317"
+<% if (postgres) { %>
+    db_host: str = "localhost"
+    db_port: int = 5432
+    db_user: str = "postgres"
+    db_password: str = "postgres"
+    db_name: str = "<%= fileName %>"
+
+    @property
+    def database_url(self) -> Optional[str]:
+        return f"postgresql+asyncpg://{self.db_user}:{self.db_password}@{self.db_host}:{self.db_port}/{self.db_name}"
+<% } else { %>
+    @property
+    def database_url(self) -> Optional[str]:
+        return None
+<% } %>
+
+<% if (messaging === 'redis' || websockets) { %>
+    redis_url: str = "redis://localhost:6379"
+<% } %>
+
+<% if (messaging === 'kafka') { %>
+    kafka_brokers: str = "localhost:9092"
+<% } %>
+
+<% if (messaging === 'gcp-pubsub') { %>
+    pubsub_project_id: str = "local-project"
+<% } %>
+
+<% if (llm) { %>
+    llm_api_key: Optional[str] = None
+    llm_base_url: Optional[str] = None
+    llm_model: str = "<% if (llmProvider === 'anthropic') { %>claude-sonnet-4-6<% } else if (llmProvider === 'local') { %>llama3.1<% } else if (llmProvider === 'none') { %><% } else { %>gpt-4o<% } %>"
+<% } %>
+
+settings = Settings()

package/src/generators/python-microservice/files/src/__packageName__/adapters/database.py.template

@@ -0,0 +1,21 @@
+from sqlalchemy.ext.asyncio import create_async_engine, async_sessionmaker
+from sqlalchemy.orm import declarative_base
+from <%= packageName %>.adapters.config import settings
+import asyncio
+
+Base = declarative_base()
+
+engine = create_async_engine(
+    settings.database_url,
+    echo=False,
+    future=True,
+    pool_pre_ping=True
+)
+
+async_session_maker = async_sessionmaker(
+    engine, expire_on_commit=False
+)
+
+async def get_db_session():
+    async with async_session_maker() as session:
+        yield session