@opengroundplan/core 0.1.1

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/parallel/gather.py

@@ -0,0 +1,28 @@
+"""Fan out over a bounded worker pool and fan back in.
+
+Results keep input order — an order-of-completion result set makes every golden flaky.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Sequence
+
+from ..types import Step, StepContext
+
+
+async def gather[In, Out](
+    items: Sequence[In],
+    step: Step[In, Out],
+    ctx: StepContext,
+) -> list[Out]:
+    if not items:
+        return []
+
+    limit = asyncio.Semaphore(max(1, ctx.max_parallel))
+
+    async def run(item: In) -> Out:
+        async with limit:
+            return await step(item, ctx)
+
+    return list(await asyncio.gather(*(run(item) for item in items)))

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/ports/__init__.py

@@ -0,0 +1,38 @@
+"""Binding registry — the single place a vendor SDK may ever be reached from.
+
+Add a real provider as ``ports/<vendor>.py`` and register it here. The boundary test rejects an
+SDK import made anywhere else under ``workflow/``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from ..settings import get_settings
+from .llm import Completion, CompletionRequest, LlmPort, ProviderError
+from .stub import StubLlm
+
+
+def _stub() -> LlmPort:
+    return StubLlm()
+
+
+_BINDINGS: dict[str, Callable[[], LlmPort]] = {"stub": _stub}
+_BUILT: dict[str, LlmPort] = {}
+
+
+def resolve_llm(name: str | None = None) -> LlmPort:
+    wanted = name or get_settings().binding
+    if wanted in _BUILT:
+        return _BUILT[wanted]
+
+    factory = _BINDINGS.get(wanted)
+    if factory is None:
+        known = ", ".join(sorted(_BINDINGS))
+        raise ProviderError(f"Unknown LLM binding {wanted!r}. Registered: {known}.")
+
+    _BUILT[wanted] = factory()
+    return _BUILT[wanted]
+
+
+__all__ = ["Completion", "CompletionRequest", "LlmPort", "ProviderError", "resolve_llm"]

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/ports/llm.py

@@ -0,0 +1,41 @@
+"""The provider seam.
+
+Nothing here names a vendor, a model id, or an endpoint, so a model can be swapped and
+re-evaluated without touching a single step.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class ProviderError(RuntimeError):
+    """Upstream rejected or failed the call. Bindings wrap vendor exceptions in this."""
+
+
+@dataclass(frozen=True, slots=True)
+class CompletionRequest:
+    # The step's purpose, e.g. "extract". Selects the model — the caller never does.
+    role: str
+    # Rendered from a versioned prompt file, never a literal at the call site.
+    system: str
+    user: str
+    max_output_tokens: int
+
+
+@dataclass(frozen=True, slots=True)
+class Completion:
+    text: str
+    # What actually answered, recorded so an eval run can attribute a regression.
+    model: str
+    input_tokens: int
+    output_tokens: int
+
+
+class LlmPort(Protocol):
+    """Bindings are built once per process and must be safe to call concurrently."""
+
+    name: str
+
+    async def complete(self, request: CompletionRequest) -> Completion: ...

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/ports/stub.py

@@ -0,0 +1,27 @@
+"""Offline binding: the answer is a pure function of the request.
+
+The golden suite therefore runs on a fresh clone with no key and no network, and still
+exercises the real orchestration.
+"""
+
+from __future__ import annotations
+
+from .llm import Completion, CompletionRequest
+
+
+def _collapse(value: str) -> str:
+    """Collapse whitespace so a reflowed input is not a different golden."""
+    return " ".join(value.split())
+
+
+class StubLlm:
+    name = "stub"
+
+    async def complete(self, request: CompletionRequest) -> Completion:
+        text = f"{request.role}:{_collapse(request.user)}"
+        return Completion(
+            text=text,
+            model="stub",
+            input_tokens=len(request.user),
+            output_tokens=len(text),
+        )

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/prompts.py

@@ -0,0 +1,22 @@
+"""Versioned prompt files.
+
+A wording change has to show up as a reviewable diff, and an eval score has to be attributable
+to a version. Pin the version at the call site and add ``v2.md`` beside ``v1.md`` rather than
+editing a shipped version in place.
+"""
+
+from __future__ import annotations
+
+from functools import cache
+from pathlib import Path
+
+from .settings import get_settings
+
+
+@cache
+def load_prompt(name: str, version: str) -> str:
+    path = Path(get_settings().prompts_dir) / name / f"{version}.md"
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except OSError as error:
+        raise FileNotFoundError(f"Prompt {name!r}@{version!r} not found at {path}") from error

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/routing/__init__.py

@@ -0,0 +1,5 @@
+"""Routing: pick the branch in code, before any model call."""
+
+from .route import Routed, route
+
+__all__ = ["Routed", "route"]

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/routing/route.py

@@ -0,0 +1,47 @@
+"""Routing is a cheap deterministic classifier in code.
+
+Where a classification genuinely needs a model, make it its own step and route on that step's
+output — never inline the call here, or the branch stops being reproducible.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from ..types import StepContext
+
+Route = Literal["single", "chunked"]
+
+
+@dataclass(frozen=True, slots=True)
+class Routed:
+    kind: Route
+    chunks: list[str]
+
+
+def route(text: str, ctx: StepContext) -> Routed:
+    stripped = text.strip()
+    if not stripped:
+        return Routed(kind="single", chunks=[])
+    if len(stripped) <= ctx.chunk_chars:
+        return Routed(kind="single", chunks=[stripped])
+    return Routed(kind="chunked", chunks=_pack(stripped.split(), ctx.chunk_chars))
+
+
+def _pack(words: list[str], limit: int) -> list[str]:
+    """Packs on word boundaries; a single word over the limit becomes its own chunk."""
+    chunks: list[str] = []
+    current = ""
+
+    for word in words:
+        candidate = word if not current else f"{current} {word}"
+        if len(candidate) <= limit or not current:
+            current = candidate
+        else:
+            chunks.append(current)
+            current = word
+
+    if current:
+        chunks.append(current)
+    return chunks

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/settings.py

@@ -0,0 +1,60 @@
+"""The only module in the workflow that reads the environment.
+
+Steps, chains, routing and parallel code receive what they need on the step context.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from functools import lru_cache
+
+ENV_PREFIX = "{{ solutionName | upperSnake }}_WORKFLOW_"
+
+
+@dataclass(frozen=True, slots=True)
+class WorkflowSettings:
+    """One typed default table; every field is overridable by ``<PREFIX><FIELD>``."""
+
+    binding: str = "stub"
+    prompts_dir: str = "{{ promptsDir }}"
+    goldens_file: str = "src/{{ solutionName | snake }}/workflow/evals/goldens.jsonl"
+    # Longest chunk a single model call is given before the chain fans out.
+    chunk_chars: int = 2000
+    max_parallel: int = 4
+    max_output_tokens: int = 1024
+    timeout_seconds: float = 60.0
+
+
+def _text(name: str, fallback: str) -> str:
+    return (os.getenv(ENV_PREFIX + name) or "").strip() or fallback
+
+
+def _positive_int(name: str, fallback: int) -> int:
+    try:
+        value = int(os.getenv(ENV_PREFIX + name, ""))
+    except ValueError:
+        return fallback
+    return value if value > 0 else fallback
+
+
+def _positive_float(name: str, fallback: float) -> float:
+    try:
+        value = float(os.getenv(ENV_PREFIX + name, ""))
+    except ValueError:
+        return fallback
+    return value if value > 0 else fallback
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> WorkflowSettings:
+    defaults = WorkflowSettings()
+    return WorkflowSettings(
+        binding=_text("BINDING", defaults.binding),
+        prompts_dir=_text("PROMPTS_DIR", defaults.prompts_dir),
+        goldens_file=_text("GOLDENS_FILE", defaults.goldens_file),
+        chunk_chars=_positive_int("CHUNK_CHARS", defaults.chunk_chars),
+        max_parallel=_positive_int("MAX_PARALLEL", defaults.max_parallel),
+        max_output_tokens=_positive_int("MAX_OUTPUT_TOKENS", defaults.max_output_tokens),
+        timeout_seconds=_positive_float("TIMEOUT_SECONDS", defaults.timeout_seconds),
+    )

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/steps/__firstStep.snake__.py

@@ -0,0 +1,24 @@
+"""One model call, one purpose.
+
+The provider arrives on the context: a step that builds its own client cannot be pointed at a
+different model for an eval run. The prompt name and version are literals on purpose — the
+boundary test reads them statically and fails when the pinned version has no file behind it.
+"""
+
+from __future__ import annotations
+
+from ..ports.llm import CompletionRequest
+from ..prompts import load_prompt
+from ..types import StepContext
+
+
+async def {{ firstStep | snake }}_step(chunk: str, ctx: StepContext) -> str:
+    completion = await ctx.llm.complete(
+        CompletionRequest(
+            role="{{ firstStep | kebab }}",
+            system=load_prompt("{{ firstStep | kebab }}", "{{ promptVersion }}"),
+            user=chunk,
+            max_output_tokens=ctx.max_output_tokens,
+        )
+    )
+    return completion.text

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/steps/__init__.py

@@ -0,0 +1,6 @@
+"""The step surface chains compose against. Steps never import each other."""
+
+from .{{ firstStep | snake }} import {{ firstStep | snake }}_step
+from .normalize import normalize_step
+
+__all__ = ["{{ firstStep | snake }}_step", "normalize_step"]

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/steps/normalize.py

@@ -0,0 +1,11 @@
+"""Not every step calls a model. A deterministic one keeps the chain's tail assertable."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from ..types import StepContext
+
+
+async def normalize_step(parts: Sequence[str], ctx: StepContext) -> str:
+    return " | ".join(collapsed for part in parts if (collapsed := " ".join(part.split())))

package/templates/architectures/llm-workflow/files/src/__solutionName.snake__/workflow/types.py

@@ -0,0 +1,40 @@
+"""Everything a step is allowed to depend on.
+
+A step that needs something else takes it as an argument — reaching for the environment or a
+module-level client is exactly what the boundary test rejects.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from typing import Protocol
+
+from .ports import resolve_llm
+from .ports.llm import LlmPort
+from .settings import get_settings
+
+
+@dataclass(frozen=True, slots=True)
+class StepContext:
+    llm: LlmPort
+    chunk_chars: int
+    max_parallel: int
+    max_output_tokens: int
+
+
+class Step[In, Out](Protocol):
+    """One composable unit. Steps never call each other; chains and routing compose them."""
+
+    async def __call__(self, value: In, ctx: StepContext) -> Out: ...
+
+
+def create_context(llm: LlmPort | None = None, **overrides: int) -> StepContext:
+    """Settings defaults with per-request overrides on top."""
+    settings = get_settings()
+    base = StepContext(
+        llm=llm if llm is not None else resolve_llm(),
+        chunk_chars=settings.chunk_chars,
+        max_parallel=settings.max_parallel,
+        max_output_tokens=settings.max_output_tokens,
+    )
+    return replace(base, **overrides) if overrides else base

package/templates/architectures/llm-workflow/files/src/workflow/chains/__workflowName.kebab__.ts

@@ -0,0 +1,14 @@
+import { gather } from '../parallel/gather.js';
+import { route } from '../routing/route.js';
+import { {{ firstStep | camel }}Step, normalizeStep } from '../steps/index.js';
+import type { StepContext } from '../types.js';
+
+/**
+ * The predefined code path: route, fan out, then chain the deterministic tail. The control flow
+ * is visible in this one function, which is what makes the workflow debuggable and evaluable.
+ */
+export async function run{{ workflowName | pascal }}(input: string, ctx: StepContext): Promise<string> {
+  const routed = route(input, ctx);
+  const extracted = await gather(routed.chunks, {{ firstStep | camel }}Step, ctx);
+  return normalizeStep(extracted, ctx);
+}

package/templates/architectures/llm-workflow/files/src/workflow/evals/assert.ts

@@ -0,0 +1,59 @@
+/**
+ * Deterministic assertions only. A model grading another model is itself stochastic and cannot
+ * tell a regression from noise.
+ */
+
+export interface Expectation {
+  equals?: string;
+  contains?: string[];
+  notContains?: string[];
+  regex?: string;
+}
+
+export interface GoldenCase {
+  id: string;
+  input: string;
+  /** Per-case override so a case can force the chunked branch without moving the default. */
+  chunkChars?: number;
+  expect: Expectation;
+}
+
+function collapse(value: string): string {
+  return value.trim().split(/\s+/).join(' ');
+}
+
+/** One message per violated expectation; an empty array means the case passed. */
+export function check(expect: Expectation, output: string): string[] {
+  const failures: string[] = [];
+  const actual = collapse(output);
+  const haystack = actual.toLowerCase();
+
+  if (expect.equals !== undefined && actual !== collapse(expect.equals)) {
+    failures.push(`equals: expected "${collapse(expect.equals)}", got "${actual}"`);
+  }
+  for (const needle of expect.contains ?? []) {
+    if (!haystack.includes(needle.toLowerCase())) failures.push(`contains: "${needle}" missing`);
+  }
+  for (const needle of expect.notContains ?? []) {
+    if (haystack.includes(needle.toLowerCase())) failures.push(`notContains: "${needle}" present`);
+  }
+  if (expect.regex !== undefined && !new RegExp(expect.regex).test(actual)) {
+    failures.push(`regex: /${expect.regex}/ did not match "${actual}"`);
+  }
+  return failures;
+}
+
+/** One case per line, reviewed in git. Blank lines and `#` comments are allowed. */
+export function parseGoldens(source: string): GoldenCase[] {
+  return source
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line !== '' && !line.startsWith('#'))
+    .map((line, index) => {
+      try {
+        return JSON.parse(line) as GoldenCase;
+      } catch (error) {
+        throw new Error(`golden line ${index + 1} is not valid JSON: ${(error as Error).message}`);
+      }
+    });
+}

package/templates/architectures/llm-workflow/files/src/workflow/evals/goldens.jsonl

@@ -0,0 +1,4 @@
+{"id": "short-input-takes-the-single-branch", "input": "alpha beta", "chunkChars": 24, "expect": {"equals": "{{ firstStep | kebab }}:alpha beta"}}
+{"id": "long-input-fans-out-and-joins-in-order", "input": "one two three four five six seven eight", "chunkChars": 24, "expect": {"equals": "{{ firstStep | kebab }}:one two three four five | {{ firstStep | kebab }}:six seven eight"}}
+{"id": "ragged-whitespace-does-not-change-the-result", "input": "   alpha    beta   ", "chunkChars": 24, "expect": {"equals": "{{ firstStep | kebab }}:alpha beta"}}
+{"id": "empty-input-produces-no-model-calls", "input": "   ", "chunkChars": 24, "expect": {"equals": ""}}

package/templates/architectures/llm-workflow/files/src/workflow/evals/run.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * Runs the golden dataset against the stub binding. Offline, deterministic, and green on a
+ * fresh clone — it proves the orchestration, not the model. Swapping in a real binding is how
+ * you evaluate a model; that run belongs in CI on a schedule, not on every commit.
+ */
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import { run{{ workflowName | pascal }} } from '../chains/{{ workflowName | kebab }}.js';
+import { StubLlm } from '../ports/stub.js';
+import { settings } from '../settings.js';
+import { createContext } from '../types.js';
+import { check, parseGoldens } from './assert.js';
+
+// Wrapped rather than top-level await: the base owns package.json, and on a CommonJS base a
+// top-level await here fails to transform before a single case runs.
+async function main(): Promise<number> {
+  const file = process.argv[2] ?? settings().goldensFile;
+  const cases = parseGoldens(readFileSync(file, 'utf8'));
+
+  if (cases.length === 0) {
+    console.error(`No golden cases in ${file} — an empty dataset is not a passing suite.`);
+    return 1;
+  }
+
+  const llm = new StubLlm();
+  let failed = 0;
+
+  for (const golden of cases) {
+    const ctx = createContext({
+      llm,
+      ...(golden.chunkChars ? { chunkChars: golden.chunkChars } : {}),
+    });
+    let failures: string[];
+    try {
+      failures = check(golden.expect, await run{{ workflowName | pascal }}(golden.input, ctx));
+    } catch (error) {
+      failures = [`threw: ${(error as Error).message}`];
+    }
+
+    if (failures.length === 0) {
+      console.log(`  pass  ${golden.id}`);
+    } else {
+      failed += 1;
+      console.error(`  FAIL  ${golden.id}`);
+      for (const failure of failures) console.error(`          ${failure}`);
+    }
+  }
+
+  console.log(`${cases.length - failed}/${cases.length} golden cases passed (${file})`);
+  return failed > 0 ? 1 : 0;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error: unknown) => {
+    console.error(error);
+    process.exit(1);
+  },
+);

package/templates/architectures/llm-workflow/files/src/workflow/parallel/gather.ts

@@ -0,0 +1,25 @@
+import type { Step, StepContext } from '../types.js';
+
+/**
+ * Fan out over a fixed worker pool and fan back in. Results keep input order — an
+ * order-of-completion result set makes every golden flaky.
+ */
+export async function gather<In, Out>(
+  items: readonly In[],
+  step: Step<In, Out>,
+  ctx: StepContext,
+): Promise<Out[]> {
+  const results = new Array<Out>(items.length);
+  const queue = items.map((item, index) => ({ item, index }));
+  let cursor = 0;
+
+  const worker = async (): Promise<void> => {
+    for (let job = queue[cursor++]; job !== undefined; job = queue[cursor++]) {
+      results[job.index] = await step(job.item, ctx);
+    }
+  };
+
+  const width = Math.max(1, Math.min(ctx.maxParallel, items.length));
+  await Promise.all(Array.from({ length: width }, worker));
+  return results;
+}

package/templates/architectures/llm-workflow/files/src/workflow/ports/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Binding registry — the single place a vendor SDK may ever be reached from. Add a real
+ * provider as `ports/<vendor>.ts` and register it here; the boundary check rejects an SDK
+ * import made anywhere else under `src/workflow/`.
+ */
+import { settings } from '../settings.js';
+import type { LlmPort } from './llm.js';
+import { ProviderError } from './llm.js';
+import { StubLlm } from './stub.js';
+
+const bindings: Record<string, () => LlmPort> = {
+  stub: () => new StubLlm(),
+};
+
+const built = new Map<string, LlmPort>();
+
+export function resolveLlm(name?: string): LlmPort {
+  const wanted = name ?? settings().binding;
+  const existing = built.get(wanted);
+  if (existing !== undefined) return existing;
+
+  const factory = bindings[wanted];
+  if (factory === undefined) {
+    throw new ProviderError(
+      `Unknown LLM binding "${wanted}". Registered: ${Object.keys(bindings).sort().join(', ')}.`,
+    );
+  }
+  const port = factory();
+  built.set(wanted, port);
+  return port;
+}
+
+export type { Completion, CompletionRequest, LlmPort, Usage } from './llm.js';
+export { ProviderError } from './llm.js';

package/templates/architectures/llm-workflow/files/src/workflow/ports/llm.ts

@@ -0,0 +1,33 @@
+/**
+ * The provider seam. Nothing here names a vendor, a model id, or an endpoint, so a model can
+ * be swapped and re-evaluated without touching a single step.
+ */
+
+export interface Usage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+export interface CompletionRequest {
+  /** The step's purpose, e.g. "extract". Selects the model — the caller never does. */
+  role: string;
+  /** Rendered from a versioned prompt file, never a literal at the call site. */
+  system: string;
+  user: string;
+  maxOutputTokens: number;
+}
+
+export interface Completion {
+  text: string;
+  /** What actually answered, recorded so an eval run can attribute a regression. */
+  model: string;
+  usage: Usage;
+}
+
+export class ProviderError extends Error {}
+
+/** Bindings are constructed once per process and must be safe to call concurrently. */
+export interface LlmPort {
+  readonly name: string;
+  complete(request: CompletionRequest): Promise<Completion>;
+}

package/templates/architectures/llm-workflow/files/src/workflow/ports/stub.ts

@@ -0,0 +1,23 @@
+import type { Completion, CompletionRequest, LlmPort } from './llm.js';
+
+/** Collapse whitespace so a reflowed input is not a different golden. */
+function collapse(value: string): string {
+  return value.trim().split(/\s+/).join(' ');
+}
+
+/**
+ * Offline binding: the answer is a pure function of the request, so the golden suite runs on a
+ * fresh clone with no key and no network and still exercises the real orchestration.
+ */
+export class StubLlm implements LlmPort {
+  readonly name = 'stub';
+
+  async complete(request: CompletionRequest): Promise<Completion> {
+    const text = `${request.role}:${collapse(request.user)}`;
+    return {
+      text,
+      model: 'stub',
+      usage: { inputTokens: request.user.length, outputTokens: text.length },
+    };
+  }
+}

package/templates/architectures/llm-workflow/files/src/workflow/prompts.ts

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { settings } from './settings.js';
+
+const cache = new Map<string, string>();
+
+/**
+ * Prompts are versioned files under the prompts directory, never string literals in a step:
+ * a wording change has to show up as a reviewable diff, and an eval run has to be able to say
+ * which version produced a score. Pin the version at the call site and add `v2.md` beside
+ * `v1.md` rather than editing a shipped version in place.
+ */
+export function loadPrompt(name: string, version: string): string {
+  const key = `${name}@${version}`;
+  const hit = cache.get(key);
+  if (hit !== undefined) return hit;
+
+  const file = path.join(settings().promptsDir, name, `${version}.md`);
+  let text: string;
+  try {
+    text = readFileSync(file, 'utf8').trim();
+  } catch {
+    throw new Error(`Prompt "${key}" not found at ${file}`);
+  }
+  cache.set(key, text);
+  return text;
+}