@littlebigbrain/create 0.4.0 → 0.6.0

package/README.md

@@ -11,6 +11,18 @@ npm install
 npm test
 ```
 
+`--lang python` creates the Python port of a template, for the
+`littlebigbrain` Python SDK:
+
+```sh
+npm create @littlebigbrain -- --template values-extract --lang python my-values
+cd my-values
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
 ## Templates
 
 | Template | Does |
@@ -44,33 +56,57 @@ the samples on it and creates the workflow there. `npm run setup` creates the
 workflow on your own graph, and `npm start` serves it. All three read
 `LBB_URL` and `LBB_API_KEY`.
 
+## The Python project
+
+`--lang python` takes a template with a Python port: `values-extract`. The
+project's package is the template name with underscores (`values_extract`).
+
+| File | Holds |
+| --- | --- |
+| `values_extract/workflow.py` | The workflow, its settings, the triggered workflow that sends it the instances (`trigger()`) and the ontology it writes (`ontology()`) |
+| `values_extract/samples.py`, `values_extract/samples/` | The samples, their answer key, and the loader that puts them on a graph |
+| `values_extract/__main__.py` | The commands `python -m values_extract try`, `setup` and `start` |
+| `tests/test_workflow.py`, `tests/fake_lbb.py` | The workflow on its samples, with mock models and no server (`pytest`) |
+| `pyproject.toml` | The project, its dependency `littlebigbrain>=<the version the port is written for>` and the `test` extra with `pytest` |
+
+`try`, `setup` and `start` do what `npm run try`, `npm run setup` and
+`npm start` do in a TypeScript project. They read `LBB_URL`, `LBB_API_KEY`
+and `LBB_GRAPH`.
+
 ## Options
 
 | Option | Meaning |
 | --- | --- |
 | `--template <name>` | The template (required) |
-| `--client <spec>` | The `@littlebigbrain/client` dependency of the project. Default: the version the templates are written for |
+| `--lang <ts\|python>` | The project's language. Default: `ts`. `python` takes a template with a Python port |
+| `--client <spec>` | The `@littlebigbrain/client` dependency of a TypeScript project. Default: the version the templates are written for |
 | `[dir]` | The new project's directory. Default: the template's name. It must be empty or missing |
 
 ## Development
 
 The package is developed in the little big brain monorepo, and the templates
 live in its `sdk/templates`. There the command reads them from that folder.
-`npm pack` copies them into the package (`prepack`) with the client version,
-and removes the copy afterwards.
+The Python ports live in `sdk/python/examples` (`PYTHON_TEMPLATES` in
+`lib/create.mjs`), and the test of a Python project in
+`project/python/<package>`. `npm pack` copies the templates into the package
+(`prepack`) with the client version, and the Python ports into `python/` with
+the Python SDK version. It removes both copies afterwards.
 
 ```sh
 node sdk/create/bin/create-littlebigbrain.mjs --template documents-link /tmp/my-links
+node sdk/create/bin/create-littlebigbrain.mjs --template values-extract --lang python /tmp/my-values
 npm test -w @littlebigbrain/create
 ```
 
 The test creates each project, compiles it against the workspace's client
-and runs its test.
+and runs its test. The Python SDK's suite
+(`sdk/python/tests/test_create_python_project.py`) creates the Python project
+and runs its `pytest` on the SDK of the repository.
 
 The public repository
 [littlebigbrains/lbb-typescript](https://github.com/littlebigbrains/lbb-typescript)
-holds the package in `create/`, with the templates and
-`templates/versions.json` already copied in. There `prepack` keeps that copy.
+holds the package in `create/`, with the templates, the Python ports and
+their `versions.json` already copied in. There `prepack` keeps those copies.
 A new version in `create/package.json` is published to npm by the
 repository's `release-create.yml` workflow.
 

package/lib/create.mjs

@@ -2,6 +2,7 @@
 // Create a project from a starter workflow template:
 //
 //   npm create @littlebigbrain -- --template documents-link [dir]
+//   npm create @littlebigbrain -- --template values-extract --lang python [dir]
 //
 // The project holds the template's workflow, helpers, test and samples, and
 // the scripts that run it: `npm test` (the workflow on its samples, with mock
@@ -9,6 +10,12 @@
 // setup` and `npm start` (your graph). The templates come from `templates/`
 // in the package (copied there when it is packed) or, in the repository,
 // from `sdk/templates`.
+//
+// `--lang python` creates the Python port of a template: its package, a test
+// with mock models (`pytest`) and the commands `python -m <package>
+// try|setup|start`. The ports come from `python/` in the package (copied
+// there when it is packed) or, in the repository, from `sdk/python/examples`.
+// The test and its fake LBB come from `project/python/<package>`.
 import { existsSync, readFileSync } from "node:fs";
 import { cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
@@ -26,27 +33,54 @@ export const TEMPLATES = [
   "sections",
 ];
 
+/**
+ * The templates with a Python port: the folder names under
+ * `sdk/python/examples`, with dashes for underscores.
+ */
+export const PYTHON_TEMPLATES = ["values-extract"];
+
+/** The languages of a project: `ts` (the default) and `python`. */
+export const LANGS = ["ts", "python"];
+
+/**
+ * The Python package of a template's port: `values-extract` is `values_extract`.
+ * @param {string} template
+ */
+export const pythonModule = (template) => template.replaceAll("-", "_");
+
+/**
+ * A copy filter that leaves out Python's caches.
+ * @param {string} source
+ */
+export const withoutCaches = (source) =>
+  basename(source) !== "__pycache__" && !source.endsWith(".pyc");
+
 const PACKAGE = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
 const USAGE = `Create a project from a little big brain starter workflow template.
 
 Usage:
-  npm create @littlebigbrain -- --template <name> [dir]
+  npm create @littlebigbrain -- --template <name> [--lang ts|python] [dir]
 
 Templates: ${TEMPLATES.join(", ")}
+With a Python port (--lang python): ${PYTHON_TEMPLATES.join(", ")}
 
 Options:
   --template <name>   the template (required)
-  --client <spec>     the @littlebigbrain/client dependency (default: ^<the current version>)
+  --lang <ts|python>  the project's language (default: ts)
+  --client <spec>     the @littlebigbrain/client dependency of a TypeScript project
+                      (default: ^<the current version>)
   --help              this text`;
 
+/** @typedef {{ template?: string, dir?: string, client?: string, lang?: string, help: boolean }} Args */
+
 /**
  * The options of the command line.
  * @param {string[]} argv
- * @returns {{ template?: string, dir?: string, client?: string, help: boolean }}
+ * @returns {Args}
  */
 export function parseArgs(argv) {
-  /** @type {{ template?: string, dir?: string, client?: string, help: boolean }} */
+  /** @type {Args} */
   const out = { help: false };
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -59,7 +93,11 @@ export function parseArgs(argv) {
     if (flag === "--help" || flag === "-h") out.help = true;
     else if (flag === "--template" || flag === "-t") out.template = value();
     else if (flag === "--client") out.client = value();
-    else if (flag.startsWith("-")) throw new Error(`unknown option ${flag}`);
+    else if (flag === "--lang") {
+      const lang = value();
+      if (!LANGS.includes(lang)) throw new Error(`--lang is ts or python, not ${lang}`);
+      out.lang = lang;
+    } else if (flag.startsWith("-")) throw new Error(`unknown option ${flag}`);
     else if (out.dir === undefined) out.dir = arg;
     else throw new Error(`one directory, not ${out.dir} and ${arg}`);
   }
@@ -88,6 +126,33 @@ export function clientVersion(templates) {
   return JSON.parse(readFileSync(repo, "utf8")).version;
 }
 
+/**
+ * The folder that holds the Python ports: the package's own copy, else the
+ * repository's `sdk/python/examples`.
+ * @param {string} [root] the package folder
+ */
+export function pythonRoot(root = PACKAGE) {
+  const packed = join(root, "python");
+  if (existsSync(join(packed, "versions.json"))) return packed;
+  const repo = join(root, "..", "python", "examples");
+  if (existsSync(join(repo, "..", "lbb", "_version.py"))) return repo;
+  throw new Error(`no Python ports in ${packed} or ${repo}`);
+}
+
+/**
+ * The version of the `littlebigbrain` Python SDK the ports are written for.
+ * @param {string} ports the folder of the Python ports
+ * @returns {string}
+ */
+export function pythonSdkVersion(ports) {
+  const packed = join(ports, "versions.json");
+  if (existsSync(packed)) return JSON.parse(readFileSync(packed, "utf8")).littlebigbrain;
+  const file = join(ports, "..", "lbb", "_version.py");
+  const found = readFileSync(file, "utf8").match(/^__version__ = "([^"]+)"$/m);
+  if (!found?.[1]) throw new Error(`no __version__ in ${file}`);
+  return found[1];
+}
+
 /** A package name from a directory name. @param {string} dir */
 const packageName = (dir) =>
   basename(resolve(dir))
@@ -95,6 +160,17 @@ const packageName = (dir) =>
     .replace(/[^a-z0-9-._~]+/g, "-")
     .replace(/^[-._]+|[-._]+$/g, "") || "workflow";
 
+/**
+ * A Python project name from a directory name: letters, digits, `.`, `_` and
+ * `-`, with a letter or a digit at each end.
+ * @param {string} dir
+ */
+const pythonName = (dir) =>
+  basename(resolve(dir))
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^[-._]+|[-._]+$/g, "") || "workflow";
+
 /**
  * A template's README as a section of the project's: no title, its headings
  * one level down, and its links into the repository as plain text.
@@ -107,16 +183,25 @@ const projectReadme = (text) =>
     .replace(/^(#{2,}) /gm, "#$1 ");
 
 /**
- * Create the project of `template` in `dir`. Returns the files written,
- * relative to `dir`, sorted.
- * @param {{ template: string, dir: string, client?: string, root?: string }} options
+ * Create the project of `template` in `dir`, in TypeScript (`lang` `ts`, the
+ * default) or in Python. Returns the files written, relative to `dir`, sorted.
+ * @param {{ template: string, dir: string, lang?: string, client?: string, root?: string }} options
  * @returns {Promise<string[]>}
  */
-export async function create({ template, dir, client, root = PACKAGE }) {
+export async function create({ template, dir, lang = "ts", client, root = PACKAGE }) {
   if (!TEMPLATES.includes(template))
     throw new Error(`unknown template ${template}; the templates are ${TEMPLATES.join(", ")}`);
+  if (!LANGS.includes(lang)) throw new Error(`the language is ts or python, not ${lang}`);
+  if (lang === "python" && !PYTHON_TEMPLATES.includes(template))
+    throw new Error(
+      `the template ${template} has no Python port; ` +
+        `the templates with one are ${PYTHON_TEMPLATES.join(", ")}`,
+    );
+  if (lang === "python" && client !== undefined)
+    throw new Error("--client names the dependency of a TypeScript project (--lang ts)");
   if (existsSync(dir) && (await readdir(dir)).length)
     throw new Error(`${dir} is not empty: name a new directory`);
+  if (lang === "python") return createPython({ template, dir, root });
   const templates = templatesRoot(root);
   const from = join(templates, template);
   const src = join(dir, "src");
@@ -156,6 +241,7 @@ export async function create({ template, dir, client, root = PACKAGE }) {
       test: "tsx --test src/workflow.test.ts",
       typecheck: "tsc --noEmit",
       ...(code.includes("grade-run.ts") ? { grade: "tsx src/grade-run.ts" } : {}),
+      ...(code.includes("test-examples.ts") ? { "test:examples": "tsx src/test-examples.ts" } : {}),
     },
     dependencies: { "@littlebigbrain/client": client ?? `^${clientVersion(templates)}` },
     devDependencies: { "@types/node": "^22", tsx: "^4", typescript: "^5.6" },
@@ -192,7 +278,7 @@ project of its own: a workflow that your \`WorkflowWorker\` runs on a graph.
 npm install
 npm test                    # the workflow on its samples, with mock models: no server
 npm run try                 # the samples on a graph of your stack, and the workflow there
-npm run setup && npm start  # your graph: create the workflow, then serve it
+${code.includes("test-examples.ts") ? "npm run test:examples       # the workflow on instances of your graph; writes nothing\n" : ""}npm run setup && npm start  # your graph: create the workflow, then serve it
 \`\`\`
 
 \`npm run try\`, \`npm run setup\` and \`npm start\` read \`LBB_URL\` (your
@@ -221,6 +307,124 @@ ${projectReadme(readme).trim()}
   return listFiles(dir);
 }
 
+/**
+ * Create the Python project of `template` in `dir`: the port's package, the
+ * test and the fake LBB it runs on (`tests/`), `pyproject.toml`, `.gitignore`
+ * and `README.md`. Returns the files written, relative to `dir`, sorted.
+ * @param {{ template: string, dir: string, root: string }} options
+ * @returns {Promise<string[]>}
+ */
+async function createPython({ template, dir, root }) {
+  const ports = pythonRoot(root);
+  const module = pythonModule(template);
+  const from = join(ports, module);
+  const portReadme = join(from, "README.md");
+  await mkdir(dir, { recursive: true });
+  // The port's package, without its README: the project's README holds it.
+  await cp(from, join(dir, module), {
+    recursive: true,
+    filter: (source) => withoutCaches(source) && source !== portReadme,
+  });
+  await cp(join(root, "project", "python", module), dir, {
+    recursive: true,
+    filter: withoutCaches,
+  });
+
+  const name = pythonName(dir);
+  await writeFile(
+    join(dir, "pyproject.toml"),
+    `[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "${name}"
+version = "0.1.0"
+description = "The ${template} starter workflow template of little big brain, in Python"
+requires-python = ">=3.10"
+dependencies = ["littlebigbrain>=${pythonSdkVersion(ports)}"]
+
+[project.optional-dependencies]
+# pytest: the workflow on its samples, with mock models.
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+include = ["${module}*"]
+
+[tool.setuptools.package-data]
+${module} = ["samples/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "tests"]
+`,
+  );
+  await writeFile(
+    join(dir, ".gitignore"),
+    ".venv/\n__pycache__/\n*.egg-info/\n.pytest_cache/\n.env\n",
+  );
+
+  // The port's README up to its first section: what the workflow does.
+  const about = projectReadme((await readFile(portReadme, "utf8")).split(/^## /m)[0] ?? "");
+  await writeFile(
+    join(dir, "README.md"),
+    `# ${name}
+
+The \`${template}\` starter workflow template of little big brain, in Python,
+as a project of its own: a workflow that your \`WorkflowWorker\` runs on a
+graph.
+
+## Commands
+
+Create a virtual environment, install the project with its test
+dependencies, and run the test. The test runs the workflow on its samples,
+with mock models and no server.
+
+\`\`\`sh
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[test]"
+pytest
+\`\`\`
+
+Then put the samples on a graph of your stack, create the workflow there, and
+serve it:
+
+\`\`\`sh
+export LBB_URL=... LBB_API_KEY=...
+python -m ${module} try
+LBB_GRAPH=try-${template} python -m ${module} start
+\`\`\`
+
+| Command | Does |
+| --- | --- |
+| \`python -m ${module} try\` | Creates a graph (\`LBB_GRAPH\`, default \`try-${template}\`), puts the samples on it, and creates the workflow there |
+| \`python -m ${module} setup\` | Creates the workflow on your graph (\`LBB_GRAPH\`, default \`main\`) |
+| \`python -m ${module} start\` | Serves the workflow on \`LBB_GRAPH\` (default \`main\`) until SIGTERM or Ctrl-C. \`LBB_WORKER_ID\` names the worker, \`LBB_CONCURRENCY\` sets how many turns run at once |
+
+The three commands read \`LBB_URL\` (your stack's endpoint) and
+\`LBB_API_KEY\` (a key of the stack). The server needs the workflow engine,
+and the models need a plan with managed models.
+
+## Files
+
+- \`${module}/workflow.py\`: the workflow, its settings (\`Settings\`,
+  \`DEFAULTS\`), the triggered workflow that sends it the instances
+  (\`trigger()\`) and the ontology it writes (\`ontology()\`). Change it here.
+- \`${module}/samples.py\` and \`${module}/samples/\`: the samples, their
+  answer key, and what \`try\` does with them.
+- \`${module}/__main__.py\`: the three commands.
+- \`tests/test_workflow.py\` and \`tests/fake_lbb.py\`: the test, and the fake
+  LBB it runs the SDK's worker against.
+
+## The template
+
+${about.trim()}
+`,
+  );
+  return listFiles(dir);
+}
+
 /**
  * The TypeScript files of a template folder, relative, in its folders too;
  * the samples are copied on their own.
@@ -258,11 +462,21 @@ export async function main(argv, io = {}) {
     if (!options.help) throw new Error("--template is required");
     return;
   }
-  const dir = options.dir ?? options.template;
-  const files = await create({ template: options.template, dir, client: options.client });
-  log(`Created ${dir} from the ${options.template} template (${files.length} files). Next:`);
+  const { template, lang = "ts", client } = options;
+  const dir = options.dir ?? template;
+  const files = await create({ template, dir, lang, client });
+  if (lang === "python") {
+    log(`Created ${dir} from the ${template} template, in Python (${files.length} files). Next:`);
+    log(`  cd ${dir}`);
+    log("  python3 -m venv .venv && source .venv/bin/activate");
+    log('  pip install -e ".[test]"');
+    log("  pytest");
+    log(`  LBB_URL=... LBB_API_KEY=... python -m ${pythonModule(template)} try`);
+    return;
+  }
+  log(`Created ${dir} from the ${template} template (${files.length} files). Next:`);
   log(`  cd ${dir}`);
   log("  npm install");
   log("  npm test");
-  log(`  LBB_URL=... LBB_API_KEY=... LBB_GRAPH=try-${options.template} npm run try`);
+  log(`  LBB_URL=... LBB_API_KEY=... LBB_GRAPH=try-${template} npm run try`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@littlebigbrain/create",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Create a project from a little big brain starter workflow template: npm create @littlebigbrain",
   "license": "Apache-2.0",
   "repository": {
@@ -25,6 +25,7 @@
     "lib",
     "project",
     "templates",
+    "python",
     "README.md",
     "LICENSE"
   ],

package/project/python/values_extract/tests/fake_lbb.py

@@ -0,0 +1,226 @@
+"""A fake LBB for the test of the workflow, in memory: the workflow engine,
+the model activities with the mock rules the test gives, the SPARQL rows of
+the samples, commits and review items. The real ``WorkflowWorker`` and
+``lbb_activities`` of the SDK run against it, so the test needs no server."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+from lbb import AsyncLbbClient
+from lbb.workflows import WorkflowWorker, lbb_activities
+
+from values_extract.workflow import DEFAULTS, Settings, create_workflow
+
+BASE = "/v1/workflows/turns"
+TIME = "2026-10-21T10:00:00Z"
+
+# The rows of a SPARQL query: `s` (the IRI), `label` and `text`.
+Rows = Callable[[str], list[dict[str, str]]]
+# The value of the reasoning model for a `reason` request.
+Reason = Callable[[dict[str, Any]], dict[str, Any]]
+# The answers of the decision model for a `decide` request, by question id.
+Decide = Callable[[dict[str, Any]], dict[str, Any]]
+
+
+def iri_of(name: str, class_name: str = DEFAULTS.class_name) -> str:
+    """The IRI of the instance ``name`` in the fake graph."""
+    digest = hashlib.sha256(f"{class_name}:{name}".encode()).hexdigest()[:32]
+    return f"https://littlebigbrain.com/e/{digest}"
+
+
+def message(iris: list[str]) -> dict[str, Any]:
+    """The message the triggered workflow sends for new or changed instances."""
+    return {
+        "type": "instances",
+        "workflow": "values-extract",
+        "graph": "main",
+        "as_of_commit_seq": 1,
+        "reason": "changed",
+        "instances": iris,
+        "removed": [],
+    }
+
+
+class FakeLbb:
+    """The routes the workflow calls. Each queued message is one turn,
+    claimed in order."""
+
+    def __init__(self, rows: Rows, *, reason: Reason, decide: Decide) -> None:
+        self.rows = rows
+        self.reason = reason
+        self.decide = decide
+        self.turns = 0
+        self.pending: list[dict[str, Any]] = []
+        self.model_calls: list[str] = []
+        self.commits: dict[str, dict[str, Any]] = {}
+        # The review items the workflow filed, by key.
+        self.reviews: dict[str, dict[str, Any]] = {}
+        self.requeued: list[str] = []
+        self.completed: list[dict[str, Any]] = []
+
+    def queue(self, message: dict[str, Any]) -> None:
+        """A turn for ``message``, claimed next."""
+        self.turns += 1
+        number = self.turns
+        workflow_id = f"starter.{message['workflow']}"
+        self.pending.append(
+            {
+                "workflow_type": "values-extract",
+                "state": {},
+                "token": f"token-{number}",
+                "lease_ms": 60_000,
+                "effect_prefix": f"e{number}",
+                "turn": {
+                    "workflow_id": workflow_id,
+                    "number": number,
+                    "message_id": f"{workflow_id}-{number}",
+                    "message": message,
+                    "version": "v1",
+                    "status": "running",
+                    "attempt": 1,
+                    "created_at_ms": 1,
+                    "updated_at_ms": 1,
+                    "ready_at_ms": 1,
+                    "steps": [],
+                    "result": None,
+                    "state_after": None,
+                    "sequence": 1,
+                    "run": {"id": f"run-{number}", "started_at_ms": 1, "queue_before": 1},
+                },
+            }
+        )
+
+    def sparql(self, query: str) -> dict[str, Any]:
+        bindings = []
+        for row in self.rows(query):
+            binding = {"s": {"type": "uri", "value": row["s"]}}
+            for name, value in row.items():
+                if name != "s":
+                    binding[name] = {"type": "literal", "value": value}
+            bindings.append(binding)
+        doc = {"head": {"vars": ["s", "label", "text"]}, "results": {"bindings": bindings}}
+        return {"results": json.dumps(doc)}
+
+    def model(self, kind: str, body: dict[str, Any]) -> httpx.Response:
+        self.model_calls.append(body.get("effect_id", ""))
+        usage = {"model": "mock", "tokens_in": 10, "tokens_out": 5, "cost_micro_usd": 1}
+        if kind == "reason":
+            answer = {"value": self.reason(body), **usage, "cached": False}
+        else:
+            answer = {"answers": self.decide(body), **usage, "cached": False}
+        return httpx.Response(200, json=answer)
+
+    def item_of(self, request: dict[str, Any]) -> dict[str, Any]:
+        """A review item as the server keeps it: open, with no answer yet."""
+        key = request["key"]
+        return {
+            "id": f"rev_{key[-8:]}",
+            "object": "review_item",
+            "created": TIME,
+            "updated": TIME,
+            "kind": request["kind"],
+            "scope": "live",
+            "status": "open",
+            "key": key,
+            "title": request["title"],
+            "rationale": request.get("rationale"),
+            "origin": request["origin"],
+            "workflow": request.get("workflow"),
+            "subject": request.get("subject"),
+            "question": request["question"],
+            "evidence": request.get("evidence", []),
+            "evidence_hash": request.get("evidence_hash"),
+            "facts": request.get("facts"),
+            "revision": 1,
+        }
+
+    async def handle(self, request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        body: Any = json.loads(request.content) if request.content else None
+        if path == f"{BASE}/claim":
+            task = self.pending.pop(0) if self.pending else None
+            return httpx.Response(200, json={"task": task})
+        if path == f"{BASE}/complete":
+            self.completed.append(body)
+            return httpx.Response(200, json={})
+        if path.startswith(BASE):
+            # Checkpoints and heartbeats: one attempt per turn needs no saved steps.
+            return httpx.Response(200, json={})
+        if path == "/v1/workflows/activities/reason":
+            return self.model("reason", body)
+        if path == "/v1/workflows/activities/decide":
+            return self.model("decide", body)
+        if path == "/v1/query/sparql-text":
+            return httpx.Response(200, json=self.sparql(body["query"]))
+        if path == "/v1/graph/commit":
+            key = request.headers["idempotency-key"]
+            replayed = key in self.commits
+            self.commits.setdefault(key, body)
+            return httpx.Response(
+                200,
+                json={
+                    "commit_seq": list(self.commits).index(key) + 1,
+                    "idempotency_key": key,
+                    "replayed": replayed,
+                    "entities_written": len(body.get("entity_properties", [])),
+                    "edges_written": len(body.get("triplets", [])),
+                },
+            )
+        if path == "/v1/reviews" and request.method == "POST":
+            self.reviews[body["key"]] = body
+            return httpx.Response(200, json=self.item_of(body))
+        if path == "/v1/reviews":
+            keys = [key for key in request.url.params.get("key", "").split(",") if key]
+            data = [
+                self.item_of(self.reviews[key])
+                for key in dict.fromkeys(keys)
+                if key in self.reviews
+            ]
+            return httpx.Response(
+                200, json={"object": "list", "data": data, "has_more": False, "next_cursor": None}
+            )
+        if path == "/v1/workflows/named/requeue":
+            self.requeued += [item["instance"] for item in body["items"]]
+            return httpx.Response(
+                200,
+                json={
+                    "attempt": 1,
+                    "requeued": [item["instance"] for item in body["items"]],
+                    "exhausted": [],
+                    "not_before": TIME,
+                },
+            )
+        raise AssertionError(f"the fake LBB has no route {request.method} {path}")
+
+    def written(self, name: str, class_name: str = DEFAULTS.class_name) -> dict[str, Any]:
+        """The values written on the instance ``name``, over every commit."""
+        values: dict[str, Any] = {}
+        for commit in self.commits.values():
+            for row in commit.get("entity_properties", []):
+                if row["type"] == class_name and row["name"] == name:
+                    values.update(row["properties"])
+        return values
+
+
+def serve(fake: FakeLbb, settings: Settings = DEFAULTS) -> None:
+    """Run the workflow with the SDK's worker on each queued turn."""
+
+    async def main() -> None:
+        async with AsyncLbbClient(
+            "http://localhost:7400",
+            graph="main",
+            retry_delay=0,
+            transport=httpx.MockTransport(fake.handle),
+        ) as client:
+            workflow = create_workflow(lbb_activities(client), settings)
+            worker = WorkflowWorker(client, [workflow], worker="test-1")
+            while fake.pending:
+                await worker.run_once()
+
+    asyncio.run(main())