@opengroundplan/core 0.1.1

package/templates/bases/nextjs-app/files/src/config/env.ts

@@ -0,0 +1,64 @@
+/**
+ * The only module that reads process.env. Everything else imports `config`.
+ * Precedence: environment > the typed default table below.
+ */
+
+// Next inlines NEXT_PUBLIC_* only at literal `process.env.X` sites, so they are read one by one.
+const raw = {
+  appName: process.env.NEXT_PUBLIC_APP_NAME,
+  appUrl: process.env.NEXT_PUBLIC_APP_URL,
+  appEnv: process.env.APP_ENV,
+  logLevel: process.env.LOG_LEVEL,
+  healthCacheSeconds: process.env.HEALTH_CACHE_SECONDS,
+} as const;
+
+/** The one place a literal default value is allowed to appear. */
+const defaults = {
+  appName: "{{ solutionName | title }}",
+  appDescription: "{{ appDescription | json }}",
+  appUrl: "http://localhost:{{ defaultPort }}",
+  appEnv: "development",
+  logLevel: "info",
+  healthCacheSeconds: 0,
+} as const;
+
+const APP_ENVS = ["development", "test", "staging", "production"] as const;
+const LOG_LEVELS = ["debug", "info", "warn", "error"] as const;
+
+export type AppEnv = (typeof APP_ENVS)[number];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+
+function str(value: string | undefined, fallback: string): string {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : fallback;
+}
+
+function int(value: string | undefined, fallback: number): number {
+  const parsed = Number(value);
+  return value !== undefined && Number.isInteger(parsed) ? parsed : fallback;
+}
+
+function oneOf<T extends string>(
+  value: string | undefined,
+  allowed: readonly T[],
+  fallback: T,
+): T {
+  return allowed.includes(value as T) ? (value as T) : fallback;
+}
+
+export const config = {
+  app: {
+    name: str(raw.appName, defaults.appName),
+    description: defaults.appDescription,
+    url: str(raw.appUrl, defaults.appUrl),
+    env: oneOf(raw.appEnv, APP_ENVS, defaults.appEnv),
+  },
+  observability: {
+    logLevel: oneOf(raw.logLevel, LOG_LEVELS, defaults.logLevel),
+  },
+  health: {
+    cacheSeconds: int(raw.healthCacheSeconds, defaults.healthCacheSeconds),
+  },
+} as const;
+
+export type Config = typeof config;

package/templates/bases/nextjs-app/files/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

package/templates/bases/python-ai-agent/blueprint.yaml

@@ -0,0 +1,84 @@
+id: python-ai-agent
+kind: base
+name: Python AI Agent Service
+description: >-
+  Minimal FastAPI service for LLM and agent workloads. Providers are resolved per role through
+  environment variables, so no model id or key is ever written at a call site. Ships no-op tracing
+  and evaluation hooks that a real backend can be plugged into without touching business logic.
+stack: python
+
+tags:
+  - python
+  - fastapi
+  - llm
+  - agent
+  - service
+
+provides:
+  - http-service
+  - llm-runtime
+
+supportsArchitectures:
+  - layered
+  - clean
+  - hexagonal
+  - onion
+  - vertical-slice
+  - monolith
+  - modular-monolith
+  - cqrs
+  - microservices
+  - serverless
+  - llm-workflow
+  - agentic-tool-loop
+  - multi-agent
+  - rag-hybrid
+  - pipes-and-filters
+  - event-driven
+  - lakehouse
+  - ddd-tactical
+
+variables:
+  - name: pythonVersion
+    prompt: Minimum Python version
+    type: select
+    default: '3.12'
+    required: true
+    choices:
+      - { value: '3.12', label: 'Python 3.12' }
+      - { value: '3.13', label: 'Python 3.13' }
+      - { value: '3.14', label: 'Python 3.14' }
+
+  - name: httpPort
+    prompt: Port the service listens on
+    type: number
+    default: 8000
+    required: true
+
+  - name: llmProvider
+    prompt: Default LLM provider
+    type: select
+    default: anthropic
+    required: true
+    choices:
+      - { value: anthropic, label: 'Anthropic (official SDK)' }
+      - { value: openai-compatible, label: 'OpenAI-compatible endpoint (OpenAI, vLLM, Ollama, ...)' }
+
+files:
+  # Rules are enumerated rather than one `files/**/*` glob so the destinations never overlap.
+  - from: files/pyproject.toml
+    to: .
+  - from: files/README.md
+    to: .
+  - from: files/.env.example
+    to: .
+  # `__pycache__` matches the engine's path-token grammar; nothing here needs substitution.
+  - from: files/gitignore
+    to: .
+    raw: true
+  - from: files/src/**/*
+    to: .
+
+postApply:
+  - run: python -m pip install --editable ".[dev]"
+    optional: true

package/templates/bases/python-ai-agent/files/.env.example

@@ -0,0 +1,29 @@
+# Copy to .env. Every setting is read by src/{{ solutionName | snake }}/config.py,
+# which holds the only default value for each key.
+
+{{ solutionName | upperSnake }}_HOST=127.0.0.1
+{{ solutionName | upperSnake }}_PORT={{ httpPort }}
+{{ solutionName | upperSnake }}_LOG_LEVEL=INFO
+
+{{ solutionName | upperSnake }}_LLM_PROVIDER={{ llmProvider }}
+{{ solutionName | upperSnake }}_LLM_MAX_OUTPUT_TOKENS=4096
+{{ solutionName | upperSnake }}_LLM_TIMEOUT_SECONDS=60
+{{ solutionName | upperSnake }}_LLM_ADAPTIVE_THINKING=true
+
+# Base URL for OpenAI-compatible gateways (vLLM, Ollama, Groq, ...). Leave unset for the vendor default.
+#{{ solutionName | upperSnake }}_LLM_BASE_URL=http://localhost:11434/v1
+
+# Role -> model. A call site asks for a role; never for a model id.
+# Lookup order per role: MODEL_<ROLE>, then MODEL_DEFAULT, then the provider default in config.py.
+{{ solutionName | upperSnake }}_MODEL_DEFAULT=claude-opus-4-8
+#{{ solutionName | upperSnake }}_MODEL_CHAT=claude-opus-4-8
+#{{ solutionName | upperSnake }}_MODEL_CLASSIFY=claude-haiku-4-5
+
+# Role -> API key, same lookup order. Unset falls through to the SDK's own env var
+# (ANTHROPIC_API_KEY / OPENAI_API_KEY).
+#{{ solutionName | upperSnake }}_API_KEY_DEFAULT=
+#{{ solutionName | upperSnake }}_API_KEY_CLASSIFY=
+
+# Observability hooks are no-ops until a sink is registered.
+{{ solutionName | upperSnake }}_TRACING_ENABLED=false
+{{ solutionName | upperSnake }}_EVALS_ENABLED=false

package/templates/bases/python-ai-agent/files/README.md

@@ -0,0 +1,80 @@
+# {{ solutionName | title }}
+
+Python LLM/agent service built on FastAPI. Providers, models, and keys resolve per **role** from the
+environment, so swapping a model or a vendor is a config change rather than a code change.
+
+## Requirements
+
+- Python {{ pythonVersion }} or newer
+
+## Run it
+
+```bash
+python -m venv .venv
+. .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install --editable ".[dev]"
+
+cp .env.example .env          # then set a key, or export ANTHROPIC_API_KEY
+{{ solutionName | kebab }}
+```
+
+The service listens on `http://127.0.0.1:{{ httpPort }}`.
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /health` | Liveness probe — never calls a provider |
+| `POST /v1/completions` | Example endpoint: runs one completion through the configured provider |
+
+```bash
+curl -s http://127.0.0.1:{{ httpPort }}/v1/completions \
+  -H 'content-type: application/json' \
+  -d '{"role": "chat", "messages": [{"role": "user", "content": "Say hello."}]}'
+```
+
+## Lint
+
+```bash
+ruff check .
+ruff format --check .
+```
+
+## Configuration
+
+Every setting lives in `src/{{ solutionName | snake }}/config.py`, which reads the environment first and
+falls back to one typed default table. Nothing else in the codebase holds a URL, port, limit, or model id.
+
+All keys are prefixed `{{ solutionName | upperSnake }}_` — see `.env.example` for the full list.
+
+### Role → model resolution
+
+A call site asks for a role (`"chat"`, `"classify"`, `"summarize"`, ...). The role resolves to a model id
+by env lookup, falling back to the provider default in `config.py`:
+
+```
+{{ solutionName | upperSnake }}_MODEL_<ROLE>  ->  {{ solutionName | upperSnake }}_MODEL_DEFAULT  ->  provider default
+```
+
+API keys follow the same shape (`{{ solutionName | upperSnake }}_API_KEY_<ROLE>`), and fall through to the
+SDK's own environment variable when unset.
+
+## Layout
+
+```
+src/{{ solutionName | snake }}/
+├── main.py              app factory + uvicorn entry point
+├── config.py            the only place a default value is written
+├── api/routes.py        health check + example completion endpoint
+├── llm/
+│   ├── provider.py      transport-agnostic Message/Completion types + LLMProvider protocol
+│   ├── registry.py      provider lookup; adapters are imported lazily
+│   ├── anthropic_provider.py   Anthropic adapter (official SDK)
+│   └── openai_provider.py      OpenAI-compatible adapter (optional `openai` extra)
+└── observability/
+    ├── tracing.py       span hook, no-op until a sink is registered
+    └── evals.py         evaluation hook, no-op until a sink is registered
+```
+
+## Adding a provider
+
+Implement the `LLMProvider` protocol in `llm/`, register it in `llm/registry.py`, and select it with
+`{{ solutionName | upperSnake }}_LLM_PROVIDER`. Nothing above the `llm` package changes.

package/templates/bases/python-ai-agent/files/gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+.env
+
+# Tooling caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

package/templates/bases/python-ai-agent/files/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "{{ solutionName | kebab }}"
+version = "0.1.0"
+description = "{{ solutionName | title }} — LLM agent service"
+requires-python = ">={{ pythonVersion }}"
+dependencies = [
+    "fastapi==0.139.2",
+    "uvicorn[standard]==0.51.0",
+    "pydantic==2.13.4",
+    "pydantic-settings==2.14.2",
+    "anthropic==0.117.0",
+]
+
+[project.optional-dependencies]
+openai = ["openai==2.46.0"]
+dev = ["ruff==0.15.22"]
+
+[project.scripts]
+{{ solutionName | kebab }} = "{{ solutionName | snake }}.main:run"
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/{{ solutionName | snake }}"]
+
+[tool.ruff]
+src = ["src"]
+line-length = 110
+target-version = "py{{ pythonVersion | lower }}"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC", "RUF"]

package/templates/bases/python-ai-agent/files/src/__solutionName.snake__/__init__.py

@@ -0,0 +1 @@
+"""{{ solutionName | title }} — LLM agent service."""

package/templates/bases/python-ai-agent/files/src/__solutionName.snake__/api/__init__.py

@@ -0,0 +1 @@
+"""HTTP surface."""

package/templates/bases/python-ai-agent/files/src/__solutionName.snake__/api/routes.py

@@ -0,0 +1,69 @@
+"""Health check and one worked example of calling the LLM layer."""
+
+from typing import Literal
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from ..config import SERVICE_NAME, SERVICE_VERSION
+from ..llm.provider import Message, ProviderError
+from ..llm.registry import get_provider
+from ..observability.evals import record_eval
+
+router = APIRouter()
+
+
+class HealthResponse(BaseModel):
+    status: Literal["ok"]
+    service: str
+    version: str
+
+
+class MessageIn(BaseModel):
+    role: Literal["user", "assistant"]
+    content: str = Field(min_length=1)
+
+
+class CompletionRequest(BaseModel):
+    messages: list[MessageIn] = Field(min_length=1)
+    # A purpose, not a model id — config.model_for maps it to a model.
+    role: str = "chat"
+    system: str | None = None
+    max_output_tokens: int | None = Field(default=None, gt=0)
+
+
+class CompletionResponse(BaseModel):
+    text: str
+    model: str
+    input_tokens: int
+    output_tokens: int
+
+
+@router.get("/health", response_model=HealthResponse, tags=["ops"])
+async def health() -> HealthResponse:
+    """Liveness only — deliberately never touches a provider."""
+    return HealthResponse(status="ok", service=SERVICE_NAME, version=SERVICE_VERSION)
+
+
+@router.post("/v1/completions", response_model=CompletionResponse, tags=["llm"])
+async def complete(request: CompletionRequest) -> CompletionResponse:
+    provider = get_provider()
+    try:
+        completion = await provider.complete(
+            role=request.role,
+            messages=[Message(role=m.role, content=m.content) for m in request.messages],
+            system=request.system,
+            max_output_tokens=request.max_output_tokens,
+        )
+    except ValueError as error:  # unresolvable role or provider — a configuration problem
+        raise HTTPException(status_code=500, detail=str(error)) from error
+    except ProviderError as error:
+        raise HTTPException(status_code=502, detail=str(error)) from error
+
+    record_eval("completion.non_empty", 1.0 if completion.text else 0.0, role=request.role)
+    return CompletionResponse(
+        text=completion.text,
+        model=completion.model,
+        input_tokens=completion.input_tokens,
+        output_tokens=completion.output_tokens,
+    )

package/templates/bases/python-ai-agent/files/src/__solutionName.snake__/config.py

@@ -0,0 +1,70 @@
+"""Single source of configuration: environment first, then one typed default table.
+
+No other module may hold a URL, port, limit, or model id. LLM usage resolves by role
+(``model_for("chat")``), never by a literal model id at the call site.
+"""
+
+import os
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+SERVICE_NAME = "{{ solutionName | kebab }}"
+SERVICE_VERSION = "0.1.0"
+
+ENV_PREFIX = "{{ solutionName | upperSnake }}_"
+
+# The only provider with a safe default; anything else must set <PREFIX>MODEL_DEFAULT.
+DEFAULT_MODELS: dict[str, str] = {"anthropic": "claude-opus-4-8"}
+
+
+class Settings(BaseSettings):
+    """Typed defaults. Every field is overridable by ``{{ solutionName | upperSnake }}_<FIELD>``."""
+
+    model_config = SettingsConfigDict(
+        env_prefix=ENV_PREFIX,
+        env_file=".env",
+        extra="ignore",
+        protected_namespaces=(),
+    )
+
+    host: str = "127.0.0.1"
+    port: int = {{ httpPort }}
+    log_level: str = "INFO"
+
+    llm_provider: str = "{{ llmProvider }}"
+    llm_base_url: str | None = None
+    llm_timeout_seconds: float = 60.0
+    llm_max_output_tokens: int = 4096
+    # Anthropic-only knob; other adapters ignore it.
+    llm_adaptive_thinking: bool = True
+
+    tracing_enabled: bool = False
+    evals_enabled: bool = False
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    return Settings()
+
+
+def _role_env(kind: str, role: str) -> str:
+    normalized = "".join(c if c.isalnum() else "_" for c in role).upper()
+    return f"{ENV_PREFIX}{kind}_{normalized}"
+
+
+def _resolve(kind: str, role: str) -> str | None:
+    return os.getenv(_role_env(kind, role)) or os.getenv(f"{ENV_PREFIX}{kind}_DEFAULT") or None
+
+
+def model_for(role: str) -> str:
+    """Role -> model id. Raises rather than guessing, so a misconfigured role fails loudly."""
+    resolved = _resolve("MODEL", role) or DEFAULT_MODELS.get(get_settings().llm_provider)
+    if not resolved:
+        raise ValueError(f"No model configured for role {role!r}. Set {_role_env('MODEL', role)}.")
+    return resolved
+
+
+def api_key_for(role: str) -> str | None:
+    """Role -> API key. ``None`` lets the vendor SDK read its own environment variable."""
+    return _resolve("API_KEY", role)

package/templates/bases/python-ai-agent/files/src/__solutionName.snake__/llm/__init__.py

@@ -0,0 +1 @@
+"""Provider-agnostic LLM access. Import from ``provider`` and ``registry`` directly."""

package/templates/bases/python-ai-agent/files/src/__solutionName.snake__/llm/anthropic_provider.py

@@ -0,0 +1,69 @@
+"""Anthropic adapter, built on the official SDK."""
+
+from collections.abc import Sequence
+from typing import Any
+
+import anthropic
+
+from ..config import api_key_for, get_settings, model_for
+from ..observability.tracing import span
+from .provider import Completion, Message, ProviderError
+
+
+class AnthropicProvider:
+    name = "anthropic"
+
+    def __init__(self) -> None:
+        settings = get_settings()
+        self._settings = settings
+        options: dict[str, Any] = {"timeout": settings.llm_timeout_seconds}
+        if settings.llm_base_url:
+            options["base_url"] = settings.llm_base_url
+        self._client_options = options
+        # One client per role: the key is resolved per role and baked into the client.
+        self._clients: dict[str, anthropic.AsyncAnthropic] = {}
+
+    def _client(self, role: str) -> anthropic.AsyncAnthropic:
+        if role not in self._clients:
+            options = dict(self._client_options)
+            key = api_key_for(role)
+            if key:
+                options["api_key"] = key
+            self._clients[role] = anthropic.AsyncAnthropic(**options)
+        return self._clients[role]
+
+    async def complete(
+        self,
+        *,
+        role: str,
+        messages: Sequence[Message],
+        system: str | None = None,
+        max_output_tokens: int | None = None,
+    ) -> Completion:
+        model = model_for(role)
+        thinking = "adaptive" if self._settings.llm_adaptive_thinking else "disabled"
+        request: dict[str, Any] = {
+            "model": model,
+            "max_tokens": max_output_tokens or self._settings.llm_max_output_tokens,
+            "messages": [{"role": m.role, "content": m.content} for m in messages],
+            # Adaptive is the only on-mode on current models; omitting it disables thinking.
+            "thinking": {"type": thinking},
+        }
+        if system:
+            request["system"] = system
+
+        with span("llm.complete", provider=self.name, role=role, model=model):
+            try:
+                response = await self._client(role).messages.create(**request)
+            except Exception as error:
+                # Deliberately broad: the SDK signals missing credentials with TypeError,
+                # transport failures with its own hierarchy. Callers only need one type.
+                raise ProviderError(f"anthropic call failed: {error}") from error
+
+        text = "".join(block.text for block in response.content if block.type == "text")
+        return Completion(
+            text=text,
+            model=response.model,
+            input_tokens=response.usage.input_tokens,
+            output_tokens=response.usage.output_tokens,
+        )

package/templates/bases/python-ai-agent/files/src/__solutionName.snake__/llm/openai_provider.py

@@ -0,0 +1,75 @@
+"""Adapter for any OpenAI-compatible chat endpoint (OpenAI, vLLM, Ollama, Groq, ...).
+
+Requires the optional ``openai`` extra: ``pip install --editable ".[openai]"``.
+"""
+
+from collections.abc import Sequence
+from typing import Any
+
+from ..config import api_key_for, get_settings, model_for
+from ..observability.tracing import span
+from .provider import Completion, Message, ProviderError
+
+
+class OpenAICompatibleProvider:
+    name = "openai-compatible"
+
+    def __init__(self) -> None:
+        try:
+            from openai import AsyncOpenAI
+        except ImportError as error:
+            raise RuntimeError(
+                "The openai-compatible provider needs the 'openai' extra: pip install '.[openai]'"
+            ) from error
+
+        self._settings = get_settings()
+        self._factory = AsyncOpenAI
+        self._clients: dict[str, Any] = {}
+
+    def _client(self, role: str) -> Any:
+        if role not in self._clients:
+            options: dict[str, Any] = {"timeout": self._settings.llm_timeout_seconds}
+            if self._settings.llm_base_url:
+                options["base_url"] = self._settings.llm_base_url
+            key = api_key_for(role)
+            if key:
+                options["api_key"] = key
+            self._clients[role] = self._factory(**options)
+        return self._clients[role]
+
+    async def complete(
+        self,
+        *,
+        role: str,
+        messages: Sequence[Message],
+        system: str | None = None,
+        max_output_tokens: int | None = None,
+    ) -> Completion:
+        model = model_for(role)
+        payload: list[dict[str, str]] = []
+        if system:
+            payload.append({"role": "system", "content": system})
+        payload.extend({"role": m.role, "content": m.content} for m in messages)
+
+        with span("llm.complete", provider=self.name, role=role, model=model):
+            try:
+                response = await self._client(role).chat.completions.create(
+                    model=model,
+                    messages=payload,
+                    # max_tokens rather than max_completion_tokens: the compatible gateways
+                    # this adapter targets do not all implement the newer field.
+                    max_tokens=max_output_tokens or self._settings.llm_max_output_tokens,
+                )
+            except Exception as error:
+                # Deliberately broad: missing credentials and transport failures surface
+                # as different exception families. Callers only need one type.
+                raise ProviderError(f"openai-compatible call failed: {error}") from error
+
+        choice = response.choices[0]
+        usage = response.usage
+        return Completion(
+            text=choice.message.content or "",
+            model=response.model,
+            input_tokens=getattr(usage, "prompt_tokens", 0) or 0,
+            output_tokens=getattr(usage, "completion_tokens", 0) or 0,
+        )