groundwork-method 0.0.1 → 0.11.0

package/src/generators/python-microservice/files/src/__packageName__/entrypoints/api/websocket_handler.py.template

@@ -0,0 +1,20 @@
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect, Depends
+from <%= packageName %>.adapters.websocket_hub import WebSocketHub
+
+# Instantiate hub (in a real app, bind to app state in lifespan)
+hub = WebSocketHub()
+
+router = APIRouter(prefix="/ws", tags=["websocket"])
+
+@router.websocket("")
+async def websocket_endpoint(websocket: WebSocket):
+    await hub.connect(websocket)
+    try:
+        # Subscribe to a default channel or read from query
+        await hub.subscribe("global")
+        while True:
+            data = await websocket.receive_text()
+            # Handle incoming data if needed
+            await hub.broadcast("global", {"echo": data})
+    except WebSocketDisconnect:
+        hub.disconnect(websocket)

package/src/generators/python-microservice/files/src/__packageName__/entrypoints/worker/cleanup.py.template

@@ -0,0 +1,35 @@
+import asyncio
+import logging
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy import text
+from <%= packageName %>.adapters.config import settings
+
+logger = logging.getLogger(__name__)
+
+async def cleanup_idempotency_keys():
+    """
+    Background worker to delete idempotency keys older than 24 hours.
+    Designed to be run as a cron job or Kubernetes CronJob.
+    """
+    logger.info("Starting idempotency key cleanup worker...")
+    
+    if not settings.database_url:
+        logger.error("DATABASE_URL not set.")
+        return
+
+    engine = create_async_engine(settings.database_url)
+    
+    try:
+        async with engine.begin() as conn:
+            result = await conn.execute(
+                text("DELETE FROM idempotency_keys WHERE created_at < NOW() - INTERVAL '24 hours'")
+            )
+            logger.info(f"Cleanup complete. Deleted {result.rowcount} expired idempotency keys.")
+    except Exception as e:
+        logger.error(f"Error during idempotency cleanup: {e}", exc_info=True)
+    finally:
+        await engine.dispose()
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.INFO)
+    asyncio.run(cleanup_idempotency_keys())

package/src/generators/python-microservice/files/src/__packageName__/entrypoints/worker/worker.py.template

@@ -0,0 +1,28 @@
+import runpod
+from typing import Any, Dict
+
+<% if (llm) { %>
+from <%= packageName %>.adapters.llm import LLMClient
+<% } %>
+<% if (postgres) { %>
+from <%= packageName %>.adapters.database import get_db_session
+from <%= packageName %>.adapters.repository import PostgresExampleRepository
+from <%= packageName %>.core.domain.entities import ExampleEntity
+import uuid
+import asyncio
+<% } %>
+
+def handler(job: Dict[str, Any]) -> Dict[str, Any]:
+    job_input = job['input']
+    
+    # Example boundary validation
+    if 'prompt' not in job_input:
+        return {"error": "Missing required field 'prompt' in input"}
+        
+    prompt = job_input['prompt']
+    
+    # In a real app, initialize services here. For async, use asyncio.run
+    return {"status": "success", "echo": prompt}
+
+if __name__ == '__main__':
+    runpod.serverless.start({'handler': handler})

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

@@ -0,0 +1,108 @@
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Request
+from fastapi.middleware.cors import CORSMiddleware
+import asyncio
+
+from <%= packageName %>.adapters.config import settings
+from <%= packageName %>.adapters.telemetry import setup_telemetry, setup_logging
+<% if (rest) { %>
+from <%= packageName %>.entrypoints.api.router import router as example_router
+from <%= packageName %>.entrypoints.api.middleware import (
+    DomainExceptionHandlerMiddleware,
+    ConcurrencyLimitingMiddleware,
+    GlobalTimeoutMiddleware,
+    IdempotencyMiddleware
+)
+<% } %>
+<% if (postgres) { %>
+from <%= packageName %>.adapters.database import engine
+from <%= packageName %>.adapters.repository import PostgresIdempotencyRepository
+<% } %>
+
+<% if (rest && websockets) { %>
+from <%= packageName %>.entrypoints.api.websocket_handler import router as ws_router
+<% } %>
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Initialize resources like Redis pools, DB connections
+    app.state.startup_failed = False
+    # Configure JSON logging with trace_id/span_id correlation. (Tracing itself is
+    # set up at module scope below — instrumenting the app must happen before
+    # Starlette builds its middleware stack, which is already done by the time the
+    # lifespan runs, so it cannot be done here.)
+    setup_logging()
+    try:
+<% if (postgres) { %>
+        # Provide the repository for the idempotency middleware
+        # For simplicity, we just inject the class/engine. In a real app, DI container is better.
+        # But wait, PostgresIdempotencyRepository needs an AsyncSession which is bound to a request scope.
+        # For the middleware, we can bind an engine or sessionmaker to app.state.
+        app.state.db_engine = engine
+<% } %>
+        pass
+    except Exception:
+        app.state.startup_failed = True
+
+    yield
+
+    # Cleanup resources gracefully
+    # Flush buffered spans before exit (BatchSpanProcessor flushes on shutdown).
+    _tracer_provider.shutdown()
+<% if (postgres) { %>
+    await engine.dispose()
+<% } %>
+
+app = FastAPI(
+    title="<%= name %> API",
+    lifespan=lifespan
+)
+# Set up tracing + instrument the app at import time, BEFORE Starlette builds its
+# middleware stack (which happens on first request / at startup). FastAPIInstrumentor
+# adds an ASGI middleware; doing this inside the lifespan is too late and silently
+# produces no spans. The provider is flushed on shutdown in the lifespan above.
+_tracer_provider = setup_telemetry(app, settings.otel_exporter_otlp_endpoint)
+
+<% if (rest) { %>
+# Middlewares are executed in reverse order of addition
+# 1. Exception Handler catches all
+app.add_middleware(DomainExceptionHandlerMiddleware)
+# 2. Timeout prevents hanging
+app.add_middleware(GlobalTimeoutMiddleware, timeout=30.0)
+# 3. Concurrency Limits protect from overload
+app.add_middleware(ConcurrencyLimitingMiddleware, max_concurrent_requests=100)
+# 5. Idempotency protects mutating endpoints
+app.add_middleware(IdempotencyMiddleware)
+<% } %>
+# 4. CORS — always add
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://your-frontend.com"],
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "DELETE"],
+    allow_headers=["*"],
+)
+<% if (rest) { %>
+app.include_router(example_router)
+<% } %>
+<% if (rest && websockets) { %>
+app.include_router(ws_router)
+<% } %>
+
+@app.get("/health", status_code=200)
+@app.get("/healthz", status_code=200)
+async def liveness_probe():
+    """Liveness probe."""
+    return {"status": "alive"}
+
+@app.get("/readyz")
+async def readiness_probe(request: Request):
+    """Kubernetes readiness probe. Checks backing services."""
+    from fastapi.responses import JSONResponse
+    if getattr(request.app.state, "startup_failed", False):
+        return JSONResponse(status_code=503, content={"status": "not ready"})
+    return {"status": "ready"}
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run("<%= packageName %>.main:app", host="0.0.0.0", port=settings.server_port, reload=True)

package/src/generators/python-microservice/files/tests/test_main.py.template

@@ -0,0 +1,74 @@
+import pytest
+from httpx import AsyncClient, ASGITransport
+import pytest_asyncio
+<% if (rest) { %>
+from <%= packageName %>.main import app
+<% } %>
+
+<% if (postgres) { %>
+from testcontainers.postgres import PostgresContainer
+import os
+
+@pytest.fixture(scope="session", autouse=True)
+def setup_postgres():
+    with PostgresContainer("postgres:15-alpine") as postgres:
+        os.environ["DB_HOST"] = postgres.get_container_host_ip()
+        os.environ["DB_PORT"] = postgres.get_exposed_port(5432)
+        os.environ["DB_USER"] = postgres.username
+        os.environ["DB_PASSWORD"] = postgres.password
+        os.environ["DB_NAME"] = postgres.dbname
+        yield
+<% } %>
+
+<% if (messaging === 'redis' || websockets) { %>
+from testcontainers.redis import RedisContainer
+
+@pytest.fixture(scope="session", autouse=True)
+def setup_redis():
+    with RedisContainer("redis:7-alpine") as redis:
+        os.environ["REDIS_URL"] = f"redis://{redis.get_container_host_ip()}:{redis.get_exposed_port(6379)}"
+        yield
+<% } %>
+
+<% if (rest) { %>
+@pytest_asyncio.fixture
+async def async_client():
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        yield client
+
+@pytest.mark.asyncio
+async def test_liveness_probe(async_client: AsyncClient):
+    response = await async_client.get("/healthz")
+    assert response.status_code == 200
+    assert response.json() == {"status": "alive"}
+
+@pytest.mark.asyncio
+async def test_readiness_probe(async_client: AsyncClient):
+    response = await async_client.get("/readyz")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ready"}
+
+@pytest.mark.asyncio
+async def test_health_alias_reports_alive(async_client: AsyncClient):
+    # /health and /healthz are both wired to the liveness probe.
+    response = await async_client.get("/health")
+    assert response.status_code == 200
+    assert response.json() == {"status": "alive"}
+
+@pytest.mark.asyncio
+async def test_readyz_503_when_dependency_down(async_client: AsyncClient):
+    # Drives the real readiness 503 branch (main.py readiness_probe): when a
+    # backing dependency failed to start, /readyz must report not-ready.
+    # Phase 1-4 is expected to replace this flag with a live DB ping; tighten
+    # this test to exercise that ping once it lands.
+    app.state.startup_failed = True
+    try:
+        response = await async_client.get("/readyz")
+        assert response.status_code == 503
+        assert response.json() == {"status": "not ready"}
+    finally:
+        app.state.startup_failed = False
+
+<% } %>

package/src/generators/python-microservice/files/tests/test_middleware.py.template

@@ -0,0 +1,109 @@
+<% if (rest) { %>
+import pytest
+from httpx import AsyncClient, ASGITransport
+import pytest_asyncio
+from fastapi import FastAPI
+
+from <%= packageName %>.entrypoints.api.middleware import (
+    IdempotencyMiddleware,
+    ConcurrencyLimitingMiddleware,
+)
+from <%= packageName %>.core.domain.entities import IdempotencyResponse
+
+
+class InMemoryIdempotencyRepo:
+    """Real (non-mock) IdempotencyRepository implementation for tests."""
+
+    def __init__(self):
+        self.completed = {}   # (key, user_id) -> IdempotencyResponse
+        self.in_progress = set()
+
+    async def get(self, key, user_id):
+        k = (key, user_id)
+        if k in self.completed:
+            return ("COMPLETED", self.completed[k])
+        if k in self.in_progress:
+            return ("IN_PROGRESS", None)
+        return None
+
+    async def lock(self, key, user_id):
+        k = (key, user_id)
+        if k in self.in_progress or k in self.completed:
+            return False
+        self.in_progress.add(k)
+        return True
+
+    async def save(self, key, user_id, response: IdempotencyResponse):
+        k = (key, user_id)
+        self.in_progress.discard(k)
+        self.completed[k] = response
+
+
+def build_app_with_idempotency():
+    app = FastAPI()
+    app.add_middleware(IdempotencyMiddleware)
+    app.state.idempotency_repo = InMemoryIdempotencyRepo()
+    app.state.calls = 0
+
+    @app.post("/thing")
+    async def create_thing():
+        app.state.calls += 1
+        return {"created": True}
+
+    return app
+
+
+@pytest_asyncio.fixture
+async def idem_client():
+    app = build_app_with_idempotency()
+    async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as client:
+        yield client, app
+
+
+@pytest.mark.asyncio
+async def test_idempotency_replays_cached_response(idem_client):
+    client, app = idem_client
+    headers = {"Idempotency-Key": "abc-123"}
+
+    r1 = await client.post("/thing", headers=headers)
+    assert r1.status_code == 200
+
+    r2 = await client.post("/thing", headers=headers)
+    # Second call replays the cached response; the handler runs exactly once.
+    assert r2.status_code == r1.status_code
+    assert app.state.calls == 1
+
+
+@pytest.mark.asyncio
+async def test_idempotency_get_is_not_deduplicated(idem_client):
+    client, app = idem_client
+    # GET bypasses the middleware entirely (no /thing GET route -> 405, never cached).
+    r = await client.get("/thing", headers={"Idempotency-Key": "abc-123"})
+    assert r.status_code in (404, 405)
+
+
+@pytest.mark.asyncio
+async def test_concurrency_limit_sheds_with_503():
+    import asyncio
+
+    app = FastAPI()
+    app.add_middleware(ConcurrencyLimitingMiddleware, max_concurrent_requests=1)
+    release = asyncio.Event()
+
+    @app.get("/slow")
+    async def slow():
+        await release.wait()
+        return {"ok": True}
+
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        # Hold the single slot, then fire a second request which must be shed (503).
+        first = asyncio.create_task(client.get("/slow"))
+        await asyncio.sleep(0.05)
+        second = await client.get("/slow")
+        assert second.status_code == 503
+        assert second.json()["detail"].startswith("Service overloaded")
+        release.set()
+        r1 = await first
+        assert r1.status_code == 200
+<% } %>

package/src/generators/python-microservice/files/tests/test_worker.py.template

@@ -0,0 +1,16 @@
+<% if (runpod) { %>
+from <%= packageName %>.entrypoints.worker.worker import handler
+
+
+def test_worker_rejects_missing_prompt():
+    # Boundary validation: a job without 'prompt' must return a structured error,
+    # never raise an unhandled exception.
+    result = handler({"input": {}})
+    assert "error" in result
+    assert "prompt" in result["error"]
+
+
+def test_worker_echoes_valid_prompt():
+    result = handler({"input": {"prompt": "hello"}})
+    assert result == {"status": "success", "echo": "hello"}
+<% } %>

package/src/generators/python-microservice/generator.ts

@@ -0,0 +1,286 @@
+import {
+  formatFiles,
+  generateFiles,
+  Tree,
+  names,
+} from '@nx/devkit';
+import * as path from 'path';
+import { recordGeneratorProvenance } from '../shared/provenance';
+import {
+  promoteEngineerSkill,
+  deployStackDocs,
+  ensureOptionalInfra,
+  readProjectPrefix,
+  registerRunner,
+} from '../shared/scaffold-helpers';
+import { applyCapability } from '../shared/capabilities';
+
+export interface PythonMicroserviceGeneratorSchema {
+  name: string;
+  rest: boolean;
+  postgres: boolean;
+  messaging: 'none' | 'redis' | 'kafka' | 'gcp-pubsub';
+  websockets: boolean;
+  runpod: boolean;
+  llm: boolean;
+  llmProvider: 'openai' | 'anthropic' | 'local' | 'none';
+  native?: boolean;
+}
+
+export default async function (tree: Tree, options: PythonMicroserviceGeneratorSchema) {
+  const serviceNames = names(options.name);
+  const projectRoot = `services/${serviceNames.fileName}`;
+  // src-layout: the importable package is `src/<packageName>` (PEP src-layout),
+  // so the package name is the service name in snake_case (a valid Python
+  // identifier). It names the `src/__packageName__/` template dir, every
+  // `from <pkg>.…` import, the hatch wheel package, and the import-linter root.
+  // Derive it from the kebab fileName (hyphens → underscores), NOT constantName:
+  // nx's constantName collapses single-char segments (`a-b1` → `AB1`), which would
+  // make the package name diverge from the intuitive `a_b1` a developer expects.
+  const packageName = serviceNames.fileName.replace(/-/g, '_');
+
+  let assignedPort = 8000;
+  let composeDoc: any = null;
+  if (tree.exists('docker-compose.yml')) {
+    try {
+      const yaml = require('yaml');
+      const composeContent = tree.read('docker-compose.yml', 'utf-8');
+      composeDoc = yaml.parseDocument(composeContent);
+
+      const usedPorts = new Set<number>();
+
+      // Collect ports from docker-compose.yml
+      const servicesMap = composeDoc.get('services');
+      if (servicesMap && servicesMap.items) {
+        for (const item of servicesMap.items) {
+          const service = item.value;
+          if (service && service.get) {
+            const ports = service.get('ports');
+            if (ports && ports.items) {
+              for (const pItem of ports.items) {
+                const portStr = String(pItem.value || pItem);
+                const match = portStr.match(/^(\d+):/);
+                if (match) {
+                  usedPorts.add(parseInt(match[1], 10));
+                }
+              }
+            }
+          }
+        }
+      }
+
+      // Also collect ports from .env files of natively-run services (not in docker-compose)
+      if (tree.exists('services')) {
+        for (const svcName of tree.children('services') ?? []) {
+          const envPath = `services/${svcName}/.env`;
+          if (tree.exists(envPath)) {
+            const envContent = tree.read(envPath, 'utf-8') ?? '';
+            for (const line of envContent.split('\n')) {
+              const m = line.match(/^(?:PORT|SERVER_PORT)=(\d+)/);
+              if (m) usedPorts.add(parseInt(m[1], 10));
+            }
+          }
+        }
+      }
+
+      while (usedPorts.has(assignedPort)) {
+        assignedPort++;
+      }
+    } catch (e) {
+      console.warn('Failed to parse docker-compose.yml for port calculation:', e);
+    }
+  }
+
+  // Default the provider so programmatic callers (e.g. tests) that omit it get
+  // today's OpenAI behaviour unchanged. Only consumed inside `--llm` templates.
+  const llmProvider = options.llmProvider ?? 'openai';
+
+  const templateOptions = {
+    ...options,
+    ...serviceNames,
+    packageName,
+    assignedPort,
+    llmProvider,
+    tmpl: '' // required by generateFiles
+  };
+
+  generateFiles(
+    tree,
+    path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'python-microservice', 'files'),
+    projectRoot,
+    templateOptions
+  );
+
+  deployStackDocs(tree, path.join(__dirname, '..', '..', '..', '..', 'src', 'generators', 'python-microservice', 'docs'));
+
+  // Auto-inject into docker-compose.yml if it exists
+  if (composeDoc) {
+    try {
+      if (!composeDoc.get('services')) {
+        // createNode so the result is a YAMLMap with .has/.set (a plain {} is not).
+        composeDoc.set('services', composeDoc.createNode({}));
+      }
+      const servicesMap = composeDoc.get('services');
+      // Only wire the infrastructure this service actually uses. Redis is needed
+      // for the WebSocket backplane or Redis pub/sub; the Pub/Sub emulator only
+      // for GCP Pub/Sub messaging. A plain --rest --postgres --llm service
+      // provisions neither.
+      const usesRedis = options.websockets || options.messaging === 'redis';
+      const usesPubSub = options.messaging === 'gcp-pubsub';
+      if (!options.native && !servicesMap.has(serviceNames.fileName)) {
+        const environment: string[] = [`SERVER_PORT=${assignedPort}`];
+        if (options.postgres) {
+          environment.push(
+            'DB_HOST=db',
+            'DB_PORT=5432',
+            'DB_USER=${DB_USER:-postgres}',
+            'DB_PASSWORD=${DB_PASSWORD:-postgres}',
+            `DB_NAME=\${DB_NAME:-${serviceNames.fileName}}`
+          );
+        }
+        if (usesRedis) {
+          environment.push('REDIS_URL=redis:6379');
+        }
+        if (usesPubSub) {
+          environment.push('PUBSUB_EMULATOR_HOST=pubsub:${PUBSUB_PORT:-8085}');
+        }
+        environment.push(
+          'OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317',
+          'OTEL_EXPORTER_OTLP_PROTOCOL=grpc'
+        );
+
+        const dependsOn: Record<string, { condition: string }> = {};
+        if (options.postgres) {
+          dependsOn.db = { condition: 'service_healthy' };
+        }
+        if (usesRedis) {
+          dependsOn.redis = { condition: 'service_healthy' };
+        }
+
+        const newService: Record<string, unknown> = {
+          build: {
+            context: `./${projectRoot}`,
+            dockerfile: 'Dockerfile'
+          },
+          container_name: serviceNames.fileName,
+          restart: 'unless-stopped',
+          ports: [
+            `${assignedPort}:${assignedPort}`
+          ],
+          environment
+        };
+        // Only the REST entrypoint serves /healthz; the runpod worker image
+        // runs a background worker with no HTTP server, so it gets no probe.
+        if (options.rest && !options.runpod) {
+          // The python:slim runtime image has no curl, so probe the health
+          // endpoint with the interpreter that is guaranteed to be present.
+          newService.healthcheck = {
+            test: [
+              'CMD-SHELL',
+              `python -c "import urllib.request,sys; sys.exit(0 if urllib.request.urlopen('http://localhost:${assignedPort}/healthz').status==200 else 1)"`
+            ],
+            interval: '10s',
+            timeout: '5s',
+            retries: 5,
+            start_period: '20s'
+          };
+        }
+        if (Object.keys(dependsOn).length > 0) {
+          newService.depends_on = dependsOn;
+        }
+        newService.networks = ['groundwork-net'];
+
+        servicesMap.set(serviceNames.fileName, newService);
+        // db only when this service uses Postgres; jaeger always for a
+        // containerized service (it exports OTLP). Neither is in the base compose.
+        ensureOptionalInfra(composeDoc, servicesMap, {
+          usesRedis,
+          usesPubSub,
+          usesDb: !!options.postgres,
+          usesTelemetry: true,
+          projectPrefix: readProjectPrefix(tree),
+        });
+        tree.write('docker-compose.yml', composeDoc.toString());
+      } else if (options.native && (options.postgres || usesRedis || usesPubSub)) {
+        // Native sidecar: no app container in compose, but provision the backing
+        // infra it connects to. A host process gets no forced tracing backend —
+        // telemetry is wired only if the project explicitly runs jaeger.
+        ensureOptionalInfra(composeDoc, servicesMap, {
+          usesRedis,
+          usesPubSub,
+          usesDb: !!options.postgres,
+          usesTelemetry: false,
+          projectPrefix: readProjectPrefix(tree),
+        });
+        tree.write('docker-compose.yml', composeDoc.toString());
+      }
+    } catch (e) {
+      console.warn('Failed to update docker-compose.yml:', e);
+    }
+  }
+
+  // Native mode: the service runs as a host process (e.g. it needs Metal/MPS that
+  // Docker on macOS can't provide), so register it as a sidecar runner instead of
+  // a compose service. `./dev start` launches it via `uv run`.
+  if (options.native) {
+    registerRunner(tree, {
+      name: serviceNames.fileName,
+      kind: 'sidecar',
+      cmd: `uv run python -m ${packageName}.main`,
+      cwd: projectRoot,
+      autostart: true,
+    });
+  }
+
+  const pkgRoot = `${projectRoot}/src/${packageName}`;
+
+  if (!options.rest) {
+    tree.delete(`${pkgRoot}/entrypoints/api`);
+    // Middleware tests import the API entrypoint, which only exists with --rest.
+    tree.delete(`${projectRoot}/tests/test_middleware.py`);
+  }
+
+  if (!options.postgres) {
+    tree.delete(`${pkgRoot}/adapters/database.py`);
+    tree.delete(`${pkgRoot}/adapters/repository.py`);
+    // Schema lives in db/ (parity with Go); migrate runs scripts/apply-schema.sh.
+    tree.delete(`${projectRoot}/db`);
+    tree.delete(`${projectRoot}/scripts/apply-schema.sh`);
+  }
+
+  if (!options.websockets) {
+    tree.delete(`${pkgRoot}/entrypoints/api/websocket_handler.py`);
+    tree.delete(`${pkgRoot}/adapters/websocket_hub.py`);
+  }
+
+  if (options.messaging === 'none') {
+    tree.delete(`${pkgRoot}/adapters/message_queue.py`);
+  }
+
+  if (!options.runpod) {
+    tree.delete(`${pkgRoot}/entrypoints/worker`);
+    tree.delete(`${pkgRoot}/adapters/comfyui.py`);
+    // Worker test imports the runpod worker handler, deleted above.
+    tree.delete(`${projectRoot}/tests/test_worker.py`);
+  }
+
+  // LLM is a composable capability port (plan WS-F). The chosen provider —
+  // anthropic | openai | local | none — selects the adapter; the port, the
+  // contract test, the provider dependency and its env footprint all come from
+  // the capability registry via one shared injector (no inline per-provider
+  // template here). `none` ships the bare port: the interface + a stub + a red bet.
+  if (options.llm) {
+    applyCapability(tree, {
+      capability: 'llm',
+      provider: llmProvider,
+      stack: 'python',
+      serviceRoot: projectRoot,
+    });
+  }
+
+  promoteEngineerSkill(tree, 'groundwork-python-engineer');
+
+  await formatFiles(tree);
+
+  recordGeneratorProvenance(tree, 'python-microservice', options as unknown as Record<string, unknown>);
+}