@opengroundplan/core 0.1.1

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

@@ -0,0 +1,45 @@
+"""The contract every provider adapter implements.
+
+Deliberately vendor-neutral: nothing here names a model, an endpoint, or an SDK.
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Literal, Protocol
+
+Role = Literal["user", "assistant"]
+
+
+class ProviderError(RuntimeError):
+    """Upstream rejected or failed the call. Adapters wrap vendor exceptions in this."""
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+    role: Role
+    content: str
+
+
+@dataclass(frozen=True, slots=True)
+class Completion:
+    text: str
+    model: str
+    input_tokens: int
+    output_tokens: int
+
+
+class LLMProvider(Protocol):
+    """Adapters are constructed once and reused; implementations must be concurrency-safe."""
+
+    name: str
+
+    async def complete(
+        self,
+        *,
+        role: str,
+        messages: Sequence[Message],
+        system: str | None = None,
+        max_output_tokens: int | None = None,
+    ) -> Completion:
+        """Run one completion for the given purpose. ``role`` selects the model, never the caller."""
+        ...

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

@@ -0,0 +1,35 @@
+"""Provider lookup. Adapters are imported lazily so an unused vendor SDK stays optional."""
+
+from collections.abc import Callable
+from functools import cache
+
+from ..config import get_settings
+from .provider import LLMProvider
+
+
+def _anthropic() -> LLMProvider:
+    from .anthropic_provider import AnthropicProvider
+
+    return AnthropicProvider()
+
+
+def _openai_compatible() -> LLMProvider:
+    from .openai_provider import OpenAICompatibleProvider
+
+    return OpenAICompatibleProvider()
+
+
+_FACTORIES: dict[str, Callable[[], LLMProvider]] = {
+    "anthropic": _anthropic,
+    "openai-compatible": _openai_compatible,
+}
+
+
+@cache
+def get_provider(name: str | None = None) -> LLMProvider:
+    resolved = name or get_settings().llm_provider
+    factory = _FACTORIES.get(resolved)
+    if factory is None:
+        known = ", ".join(sorted(_FACTORIES))
+        raise ValueError(f"Unknown LLM provider {resolved!r}. Known providers: {known}.")
+    return factory()

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

@@ -0,0 +1,33 @@
+"""Application entry point."""
+
+import logging
+
+from fastapi import FastAPI
+
+from .api.routes import router
+from .config import SERVICE_VERSION, get_settings
+
+
+def create_app() -> FastAPI:
+    settings = get_settings()
+    logging.basicConfig(level=settings.log_level.upper())
+
+    app = FastAPI(title="{{ solutionName | title }}", version=SERVICE_VERSION)
+    app.include_router(router)
+    return app
+
+
+app = create_app()
+
+
+def run() -> None:
+    """Console-script entry point declared in pyproject.toml."""
+    import uvicorn
+
+    settings = get_settings()
+    uvicorn.run(
+        "{{ solutionName | snake }}.main:app",
+        host=settings.host,
+        port=settings.port,
+        log_level=settings.log_level.lower(),
+    )

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

@@ -0,0 +1 @@
+"""Tracing and evaluation hooks. Both are no-ops until a sink is registered."""

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

@@ -0,0 +1,28 @@
+"""Evaluation hook.
+
+Call ``record_eval`` wherever quality is measurable — a grader score, a schema-validation
+pass, a user thumbs-up. Nothing is emitted until a sink is registered.
+"""
+
+from typing import Any, Protocol
+
+from ..config import get_settings
+
+
+class EvalSink(Protocol):
+    def on_eval(self, name: str, score: float, metadata: dict[str, Any]) -> None: ...
+
+
+_sink: EvalSink | None = None
+
+
+def set_eval_sink(sink: EvalSink | None) -> None:
+    """Install the process-wide sink. Call once during startup."""
+    global _sink
+    _sink = sink
+
+
+def record_eval(name: str, score: float, **metadata: Any) -> None:
+    if _sink is None or not get_settings().evals_enabled:
+        return
+    _sink.on_eval(name, score, metadata)

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

@@ -0,0 +1,49 @@
+"""Tracing hook.
+
+Business logic wraps work in ``span(...)`` unconditionally. Nothing is emitted until a
+sink is registered, so adding OpenTelemetry (or anything else) touches only this module.
+"""
+
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any, Protocol
+
+from ..config import get_settings
+
+
+class TraceSink(Protocol):
+    def on_span_end(
+        self,
+        name: str,
+        duration_seconds: float,
+        attributes: dict[str, Any],
+        error: BaseException | None,
+    ) -> None: ...
+
+
+_sink: TraceSink | None = None
+
+
+def set_trace_sink(sink: TraceSink | None) -> None:
+    """Install the process-wide sink. Call once during startup."""
+    global _sink
+    _sink = sink
+
+
+@contextmanager
+def span(name: str, **attributes: Any) -> Iterator[dict[str, Any]]:
+    """Yields the attribute dict so callers can add fields discovered mid-span."""
+    if _sink is None or not get_settings().tracing_enabled:
+        yield attributes
+        return
+
+    started = time.perf_counter()
+    error: BaseException | None = None
+    try:
+        yield attributes
+    except BaseException as caught:
+        error = caught
+        raise
+    finally:
+        _sink.on_span_end(name, time.perf_counter() - started, attributes, error)

package/templates/bases/react-vite-spa/blueprint.yaml

@@ -0,0 +1,92 @@
+id: react-vite-spa
+kind: base
+name: React + Vite SPA
+description: >-
+  Client-rendered React single-page app on Vite, routed with TanStack Router (code-based tree,
+  no codegen) and backed by TanStack Query. Ships a typed config module, one example API
+  resource, and nothing else — CI, Docker, auth, db, and testing compose on top as layers.
+stack: typescript
+
+tags:
+  - react
+  - vite
+  - spa
+  - frontend
+  - tanstack
+  - typescript
+
+requires: []
+# Browser-only bundle: there is no server process to run a worker in. Declared here as well
+# as in queue-broker because the resolver reports a conflicting pair only from the
+# lexicographically first side.
+conflicts:
+  - queue-broker
+provides:
+  - spa
+  - frontend-app
+  - client-routing
+  - server-state
+
+# Frontend code-organization styles only. clean/hexagonal/onion are domain-centric server
+# styles, nextjs-colocation needs Next.js, and the service/AI styles need a backend.
+supportsArchitectures:
+  - layered
+  - vertical-slice
+  - feature-sliced-design
+  - mvc-mvvm
+  # The SPA becomes the shell; the overlay adds the workspaces the remotes live in.
+  - micro-frontends
+
+variables:
+  - name: appDescription
+    prompt: One-line description of the app (README, <meta>, package.json, landing copy)
+    type: string
+    default: A React single-page application.
+    required: false
+
+  - name: apiBaseUrl
+    prompt: Default base URL the app calls (relative path or absolute origin)
+    type: string
+    default: /api
+    required: false
+
+  - name: devPort
+    prompt: Vite dev server port
+    type: number
+    default: 5173
+    required: false
+
+  - name: previewPort
+    prompt: Vite preview server port
+    type: number
+    default: 4173
+    required: false
+
+  - name: packageManager
+    prompt: Package manager
+    type: select
+    choices:
+      - { value: pnpm, label: pnpm }
+      - { value: npm, label: npm }
+      - { value: yarn, label: Yarn }
+      - { value: bun, label: Bun }
+    default: pnpm
+    required: false
+
+files:
+  - from: files/**/*
+    to: .
+
+postApply:
+  - run: pnpm install
+    when: packageManager == 'pnpm'
+    optional: true
+  - run: npm install
+    when: packageManager == 'npm'
+    optional: true
+  - run: yarn install
+    when: packageManager == 'yarn'
+    optional: true
+  - run: bun install
+    when: packageManager == 'bun'
+    optional: true

package/templates/bases/react-vite-spa/files/.env.example

@@ -0,0 +1,13 @@
+# Copy to .env.local. Leave a key empty to keep the default from src/config/env.ts.
+# Only VITE_-prefixed keys reach the browser bundle — never put secrets here.
+
+VITE_APP_NAME=
+VITE_APP_DESCRIPTION=
+VITE_API_BASE_URL=
+VITE_API_TIMEOUT_MS=
+VITE_QUERY_STALE_TIME_MS=
+VITE_QUERY_RETRY_COUNT=
+
+# Read by vite.config.ts, not by the app bundle.
+VITE_DEV_PORT=
+VITE_PREVIEW_PORT=

package/templates/bases/react-vite-spa/files/README.md

@@ -0,0 +1,49 @@
+# {{ solutionName | title }}
+
+{{ appDescription }}
+
+React SPA on Vite, routed with TanStack Router and served state by TanStack Query.
+
+## Commands
+
+```bash
+{{ packageManager }} install
+{{ packageManager }} run dev        # http://localhost:{{ devPort }}
+{{ packageManager }} run build      # typecheck, then bundle to dist/
+{{ packageManager }} run preview    # serve dist/ on http://localhost:{{ previewPort }}
+{{ packageManager }} run typecheck
+{{ packageManager }} run lint
+```
+
+## Layout
+
+```
+src/
+├── api/          fetch wrapper + one example resource
+├── app/          router, route tree, query client, root layout
+├── config/       env.ts — the single source of runtime settings
+├── pages/        route components
+└── styles/       global.css
+```
+
+## Configuration
+
+`src/config/env.ts` holds one typed default table and is the only module that reads
+`import.meta.env`. Override any value through a `VITE_`-prefixed variable; see `.env.example`.
+
+Vite-only settings (`VITE_DEV_PORT`, `VITE_PREVIEW_PORT`) are read in `vite.config.ts`.
+
+Everything under `VITE_` is inlined into the client bundle. Secrets do not belong here.
+
+## Routing
+
+Routes are declared in code in `src/app/router.tsx` — no generated route tree, no codegen step.
+Add a route with `createRoute({ getParentRoute: () => rootRoute, path: '/thing', component: Thing })`
+and list it in `rootRoute.addChildren([...])`.
+
+## Notes
+
+`/status` calls `{{ apiBaseUrl }}/health` to demonstrate the Query wiring. This base ships no
+backend, so it renders its error state until you point `VITE_API_BASE_URL` at a real API.
+
+Architecture: {{ architecture }}.

package/templates/bases/react-vite-spa/files/eslint.config.mjs

@@ -0,0 +1,26 @@
+import js from '@eslint/js';
+import { defineConfig, globalIgnores } from 'eslint/config';
+import reactHooks from 'eslint-plugin-react-hooks';
+import reactRefresh from 'eslint-plugin-react-refresh';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default defineConfig([
+  globalIgnores([
+    // Agent infrastructure, deliberately outside any tsconfig.
+    '.agent/**',
+'dist', 'node_modules']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2023,
+      globals: globals.browser,
+    },
+  },
+]);

package/templates/bases/react-vite-spa/files/gitignore

@@ -0,0 +1,25 @@
+node_modules/
+dist/
+dist-ssr/
+*.local
+
+.env
+.env.*
+!.env.example
+
+*.tsbuildinfo
+.vite/
+
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+.DS_Store
+Thumbs.db
+
+.idea/
+.vscode/*
+!.vscode/extensions.json

package/templates/bases/react-vite-spa/files/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="description" content="{{ appDescription }}" />
+    <title>{{ solutionName | title }}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/bases/react-vite-spa/files/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "{{ solutionName | kebab }}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "{{ appDescription | json }}",
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc -b",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.101.2",
+    "@tanstack/react-router": "^1.170.18",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.1.1",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "eslint": "^10.7.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-react-refresh": "^0.5.3",
+    "globals": "^17.7.0",
+    "typescript": "6.0.3",
+    "typescript-eslint": "^8.64.0",
+    "vite": "^8.1.5"
+  }
+}

package/templates/bases/react-vite-spa/files/src/api/client.ts

@@ -0,0 +1,28 @@
+import { config } from '@/config/env';
+
+export class ApiError extends Error {
+  status: number;
+
+  constructor(status: number, message: string) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+  }
+}
+
+/** Joins against the configured base so no call site ever spells out a host. */
+function resolveUrl(path: string): string {
+  return `${config.apiBaseUrl.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}
+
+export async function getJson<T>(path: string, signal?: AbortSignal): Promise<T> {
+  const timeout = AbortSignal.timeout(config.apiTimeoutMs);
+
+  const response = await fetch(resolveUrl(path), {
+    headers: { Accept: 'application/json' },
+    signal: signal ? AbortSignal.any([signal, timeout]) : timeout,
+  });
+
+  if (!response.ok) throw new ApiError(response.status, `GET ${path} failed with ${response.status}`);
+  return (await response.json()) as T;
+}

package/templates/bases/react-vite-spa/files/src/api/health.ts

@@ -0,0 +1,12 @@
+import { getJson } from './client';
+
+export type Health = {
+  status: string;
+  version?: string;
+};
+
+export const healthQueryKey = ['health'] as const;
+
+export function fetchHealth(signal?: AbortSignal): Promise<Health> {
+  return getJson<Health>('health', signal);
+}

package/templates/bases/react-vite-spa/files/src/app/query-client.ts

@@ -0,0 +1,12 @@
+import { QueryClient } from '@tanstack/react-query';
+import { config } from '@/config/env';
+
+export const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: config.queryStaleTimeMs,
+      retry: config.queryRetryCount,
+      refetchOnWindowFocus: false,
+    },
+  },
+});

package/templates/bases/react-vite-spa/files/src/app/root-layout.tsx

@@ -0,0 +1,24 @@
+import { Link, Outlet } from '@tanstack/react-router';
+import { config } from '@/config/env';
+
+export function RootLayout() {
+  return (
+    <div className="shell">
+      <header className="shell-header">
+        <span className="brand">{config.appName}</span>
+        <nav className="nav">
+          <Link to="/" className="nav-link">
+            Overview
+          </Link>
+          <Link to="/status" className="nav-link">
+            Status
+          </Link>
+        </nav>
+      </header>
+
+      <main className="shell-main">
+        <Outlet />
+      </main>
+    </div>
+  );
+}

package/templates/bases/react-vite-spa/files/src/app/router.tsx

@@ -0,0 +1,44 @@
+import type { QueryClient } from '@tanstack/react-query';
+import { createRootRouteWithContext, createRoute, createRouter } from '@tanstack/react-router';
+import { queryClient } from './query-client';
+import { RootLayout } from './root-layout';
+import { HomePage } from '@/pages/home-page';
+import { NotFoundPage } from '@/pages/not-found-page';
+import { StatusPage } from '@/pages/status-page';
+
+/** Loaders reach the cache through router context instead of importing the client. */
+export type RouterContext = {
+  queryClient: QueryClient;
+};
+
+const rootRoute = createRootRouteWithContext<RouterContext>()({
+  component: RootLayout,
+  notFoundComponent: NotFoundPage,
+});
+
+const homeRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/',
+  component: HomePage,
+});
+
+const statusRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: '/status',
+  component: StatusPage,
+});
+
+const routeTree = rootRoute.addChildren([homeRoute, statusRoute]);
+
+export const router = createRouter({
+  routeTree,
+  context: { queryClient },
+  defaultPreload: 'intent',
+  scrollRestoration: true,
+});
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router;
+  }
+}

package/templates/bases/react-vite-spa/files/src/config/env.ts

@@ -0,0 +1,37 @@
+/**
+ * The only place runtime settings are defined. Env wins; this table is the fallback.
+ * Never read `import.meta.env` outside this module.
+ */
+export type AppConfig = {
+  appName: string;
+  appDescription: string;
+  apiBaseUrl: string;
+  apiTimeoutMs: number;
+  queryStaleTimeMs: number;
+  queryRetryCount: number;
+};
+
+const defaults: AppConfig = {
+  appName: '{{ solutionName | title }}',
+  appDescription: '{{ appDescription }}',
+  apiBaseUrl: '{{ apiBaseUrl }}',
+  apiTimeoutMs: 10_000,
+  queryStaleTimeMs: 30_000,
+  queryRetryCount: 1,
+};
+
+const str = (value: string | undefined, fallback: string): string => value?.trim() || fallback;
+
+const num = (value: string | undefined, fallback: number): number => {
+  const parsed = Number(value?.trim());
+  return value?.trim() && Number.isFinite(parsed) ? parsed : fallback;
+};
+
+export const config: AppConfig = {
+  appName: str(import.meta.env.VITE_APP_NAME, defaults.appName),
+  appDescription: str(import.meta.env.VITE_APP_DESCRIPTION, defaults.appDescription),
+  apiBaseUrl: str(import.meta.env.VITE_API_BASE_URL, defaults.apiBaseUrl),
+  apiTimeoutMs: num(import.meta.env.VITE_API_TIMEOUT_MS, defaults.apiTimeoutMs),
+  queryStaleTimeMs: num(import.meta.env.VITE_QUERY_STALE_TIME_MS, defaults.queryStaleTimeMs),
+  queryRetryCount: num(import.meta.env.VITE_QUERY_RETRY_COUNT, defaults.queryRetryCount),
+};

package/templates/bases/react-vite-spa/files/src/main.tsx

@@ -0,0 +1,18 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { QueryClientProvider } from '@tanstack/react-query';
+import { RouterProvider } from '@tanstack/react-router';
+import { queryClient } from '@/app/query-client';
+import { router } from '@/app/router';
+import '@/styles/global.css';
+
+const container = document.getElementById('root');
+if (!container) throw new Error('index.html is missing the #root mount point');
+
+createRoot(container).render(
+  <StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <RouterProvider router={router} />
+    </QueryClientProvider>
+  </StrictMode>,
+);

package/templates/bases/react-vite-spa/files/src/pages/home-page.tsx

@@ -0,0 +1,31 @@
+import { Link } from '@tanstack/react-router';
+import { config } from '@/config/env';
+
+export function HomePage() {
+  return (
+    <section className="stack">
+      <p className="eyebrow">React &middot; Vite &middot; TanStack</p>
+      <h1 className="title">{config.appName}</h1>
+      <p className="lede">{config.appDescription}</p>
+
+      <ul className="facts">
+        <li>
+          <span className="facts-key">Routing</span>
+          <span className="facts-value">TanStack Router, code-based tree in src/app/router.tsx</span>
+        </li>
+        <li>
+          <span className="facts-key">Server state</span>
+          <span className="facts-value">TanStack Query, client in src/app/query-client.ts</span>
+        </li>
+        <li>
+          <span className="facts-key">Settings</span>
+          <span className="facts-value">src/config/env.ts is the only reader of import.meta.env</span>
+        </li>
+      </ul>
+
+      <Link to="/status" className="cta">
+        Try the example query
+      </Link>
+    </section>
+  );
+}