rote-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{rote_cli-0.3.0 → rote_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rote-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Graduate fuzzy AI skills into deterministic, reliable workflows
 Project-URL: Homepage, https://github.com/trevhud/rote
 Project-URL: Repository, https://github.com/trevhud/rote
@@ -59,8 +59,13 @@ applies a structured graduation rubric, and emits:
 - and runtime code for your durable execution engine of choice.
 
 ```sh
-# Two runtimes shipped today — emit Python for Temporal, or TypeScript
-# for Cloudflare Workflows:
+pip install rote-cli    # or zero-install: uvx --from rote-cli rote ...
+
+# Default target is DBOS — durable execution as a plain Python library,
+# no orchestrator to run, SQLite for dev / Postgres for prod:
+rote graduate ./examples/bdr-outreach/skill --out ./graduated/
+
+# Or target Temporal (Python) or Cloudflare Workflows (TypeScript):
 rote graduate ./examples/bdr-outreach/skill --runtime temporal   --out ./graduated/
 rote graduate ./examples/bdr-outreach/skill --runtime cloudflare --out ./graduated/
 ```
@@ -140,6 +145,10 @@ The graduator independently:
 After the agent finishes, a runtime adapter consumes the IR and emits
 the target runtime's native code shape:
 
+- The **DBOS** adapter (the default) emits a single `main.py` — one
+  `@DBOS.workflow` DAG plus a `@DBOS.step` per node, checkpointing to
+  SQLite or Postgres. `python main.py` *is* the runtime; there is no
+  orchestrator to deploy.
 - The **Temporal** adapter emits `workflow.py` (the orchestration
   class with `@workflow.defn` and signal handlers for the HITL gates)
   and `activities.py` (one `@activity.defn` per node, lazy-importing
@@ -150,6 +159,14 @@ the target runtime's native code shape:
   `signatures/*.ts` (Zod schemas + Anthropic SDK calls) and the
   supporting `wrangler.jsonc` / `package.json` / `tsconfig.json`. The
   output is `wrangler deploy`-ready.
+- The **DBOS (TypeScript)** adapter (`--runtime dbos-ts`) emits a
+  Node.js app for DBOS Transact: `src/main.ts` registers one durable
+  workflow (`DBOS.registerWorkflow`) running the DAG waves and one
+  `DBOS.registerStep` per node, with `DBOS.recv(...)` parking each
+  HITL gate durably in Postgres until `DBOS.send(...)` resumes it.
+  Zero-orchestrator like the Python DBOS target — `node dist/main.js`
+  *is* the runtime — but note the TS SDK is Postgres-only (no SQLite
+  mode; `npx dbos postgres start` covers local dev).
 
 None of the emitted code references an MCP runtime, in either
 language — the agent's crystallization step replaces tool calls with
@@ -297,11 +314,12 @@ The repository includes a real BDR outreach skill in
 `examples/bdr-outreach/skill/`. Graduate it:
 
 ```sh
-rote graduate examples/bdr-outreach/skill \
-  --runtime temporal \
-  --out /tmp/bdr-graduated
+rote graduate examples/bdr-outreach/skill --out /tmp/bdr-graduated
 ```
 
+This targets DBOS by default; pass `--runtime temporal` or
+`--runtime cloudflare` for the other adapters.
+
 By default `rote` auto-detects an available agent driver in this
 order: `claude` (Claude Code CLI) → `codex` (Codex CLI) → `api`
 (Anthropic SDK with `ANTHROPIC_API_KEY`). Override with `--agent`:
@@ -320,10 +338,12 @@ The output directory is structured as:
 │   ├── signatures/*.py          # typed LLM-judge signatures
 │   ├── evals/*.jsonl            # seed eval examples
 │   └── graduation-report.md     # human-readable summary
-└── runtime/temporal/            # produced by the adapter
-    ├── workflow.py
-    ├── activities.py
-    └── __init__.py
+└── runtime/dbos/                # produced by the adapter
+    ├── main.py                  # @DBOS.workflow + one @DBOS.step per node
+    ├── extracted/*.py           # copied deterministic functions
+    ├── signatures/*.py          # generated Pydantic + vendor-SDK judges
+    ├── dbos-config.yaml
+    └── README.md                # how to run, signal HITL gates, deploy
 ```
 
 ### Render an IR without re-running the agent
@@ -332,6 +352,7 @@ If you already have a `pipeline.yaml` (hand-written or from a previous
 graduation), `rote emit` runs just the adapter step:
 
 ```sh
+rote emit /path/to/pipeline.yaml --out /tmp/emitted/            # dbos (default)
 rote emit /path/to/pipeline.yaml --runtime temporal --out /tmp/emitted/
 ```
 
@@ -393,10 +414,12 @@ Opus's extra reasoning earns its cost.
 ## Status
 
 `rote` is **pre-1.0**. The end-to-end flow works on the BDR example
-and the test suite covers each layer (133 tests in the fast suite,
-plus 3 slow tests that compile the emitted Cloudflare TypeScript
-against the real `@cloudflare/workers-types` definitions and drive a
-real workflow instance through both HITL gates via `wrangler dev`).
+and the test suite covers each layer (231 tests in the fast suite,
+plus 5 slow tests that run the emitted code against real runtimes:
+a DBOS runtime over SQLite, Temporal's time-skipping test server, the
+emitted Cloudflare TypeScript compiled against real
+`@cloudflare/workers-types` and driven through both HITL gates via
+`wrangler dev`, and the MCP server over a real stdio transport).
 Run `pytest tests/` for the fast suite; `pytest tests/ -m slow` for
 the toolchain-dependent integration tests.
 
@@ -406,6 +429,7 @@ the toolchain-dependent integration tests.
 | Temporal adapter | working (validated with mocked-activities e2e test) |
 | Cloudflare Workflows adapter | working (validated with `tsc --noEmit` over the real emitted output) |
 | DBOS adapter | working (validated against a real DBOS runtime over SQLite in the e2e test) |
+| DBOS TypeScript adapter (`dbos-ts`) | working (validated with `tsc --noEmit` over the real emitted output and a live run on the DBOS TS runtime against Docker Postgres) |
 | Graduator orchestrator | working |
 | `rote graduate` / `rote emit` CLI commands | working |
 | `claude` driver | working |
@@ -413,8 +437,8 @@ the toolchain-dependent integration tests.
 | `codex` driver | stub (`is_available` works; `run` not implemented) |
 | Inngest / Restate adapters | planned |
 | Real implementations of the extracted modules | the agent produces stubs that raise `NotImplementedError`; humans fill them in with real API client code |
-| Workflow data flow between activities | working — nodes declare `inputs:` bindings and all three adapters (Temporal, Cloudflare, DBOS) thread real payloads through the DAG, validated in the runtime e2e tests |
-| Distribution via PyPI | not yet published — install from source. The release pipeline (tag-driven, Trusted Publishing) is in place; see [docs/releasing.md](docs/releasing.md) |
+| Workflow data flow between activities | working — nodes declare `inputs:` bindings and all four adapters (Temporal, Cloudflare, DBOS, DBOS-TS) thread real payloads through the DAG, validated in the runtime e2e tests |
+| Distribution via PyPI | published as [`rote-cli`](https://pypi.org/project/rote-cli/) (`pip install rote-cli`); tag-driven Trusted Publishing releases — see [docs/releasing.md](docs/releasing.md) |
 
 The project explicitly **does not** depend on `claude-agent-sdk`.
 Anthropic's terms of service forbid third-party agents built on the

{rote_cli-0.3.0 → rote_cli-0.4.0}/README.md

@@ -13,8 +13,13 @@ applies a structured graduation rubric, and emits:
 - and runtime code for your durable execution engine of choice.
 
 ```sh
-# Two runtimes shipped today — emit Python for Temporal, or TypeScript
-# for Cloudflare Workflows:
+pip install rote-cli    # or zero-install: uvx --from rote-cli rote ...
+
+# Default target is DBOS — durable execution as a plain Python library,
+# no orchestrator to run, SQLite for dev / Postgres for prod:
+rote graduate ./examples/bdr-outreach/skill --out ./graduated/
+
+# Or target Temporal (Python) or Cloudflare Workflows (TypeScript):
 rote graduate ./examples/bdr-outreach/skill --runtime temporal   --out ./graduated/
 rote graduate ./examples/bdr-outreach/skill --runtime cloudflare --out ./graduated/
 ```
@@ -94,6 +99,10 @@ The graduator independently:
 After the agent finishes, a runtime adapter consumes the IR and emits
 the target runtime's native code shape:
 
+- The **DBOS** adapter (the default) emits a single `main.py` — one
+  `@DBOS.workflow` DAG plus a `@DBOS.step` per node, checkpointing to
+  SQLite or Postgres. `python main.py` *is* the runtime; there is no
+  orchestrator to deploy.
 - The **Temporal** adapter emits `workflow.py` (the orchestration
   class with `@workflow.defn` and signal handlers for the HITL gates)
   and `activities.py` (one `@activity.defn` per node, lazy-importing
@@ -104,6 +113,14 @@ the target runtime's native code shape:
   `signatures/*.ts` (Zod schemas + Anthropic SDK calls) and the
   supporting `wrangler.jsonc` / `package.json` / `tsconfig.json`. The
   output is `wrangler deploy`-ready.
+- The **DBOS (TypeScript)** adapter (`--runtime dbos-ts`) emits a
+  Node.js app for DBOS Transact: `src/main.ts` registers one durable
+  workflow (`DBOS.registerWorkflow`) running the DAG waves and one
+  `DBOS.registerStep` per node, with `DBOS.recv(...)` parking each
+  HITL gate durably in Postgres until `DBOS.send(...)` resumes it.
+  Zero-orchestrator like the Python DBOS target — `node dist/main.js`
+  *is* the runtime — but note the TS SDK is Postgres-only (no SQLite
+  mode; `npx dbos postgres start` covers local dev).
 
 None of the emitted code references an MCP runtime, in either
 language — the agent's crystallization step replaces tool calls with
@@ -251,11 +268,12 @@ The repository includes a real BDR outreach skill in
 `examples/bdr-outreach/skill/`. Graduate it:
 
 ```sh
-rote graduate examples/bdr-outreach/skill \
-  --runtime temporal \
-  --out /tmp/bdr-graduated
+rote graduate examples/bdr-outreach/skill --out /tmp/bdr-graduated
 ```
 
+This targets DBOS by default; pass `--runtime temporal` or
+`--runtime cloudflare` for the other adapters.
+
 By default `rote` auto-detects an available agent driver in this
 order: `claude` (Claude Code CLI) → `codex` (Codex CLI) → `api`
 (Anthropic SDK with `ANTHROPIC_API_KEY`). Override with `--agent`:
@@ -274,10 +292,12 @@ The output directory is structured as:
 │   ├── signatures/*.py          # typed LLM-judge signatures
 │   ├── evals/*.jsonl            # seed eval examples
 │   └── graduation-report.md     # human-readable summary
-└── runtime/temporal/            # produced by the adapter
-    ├── workflow.py
-    ├── activities.py
-    └── __init__.py
+└── runtime/dbos/                # produced by the adapter
+    ├── main.py                  # @DBOS.workflow + one @DBOS.step per node
+    ├── extracted/*.py           # copied deterministic functions
+    ├── signatures/*.py          # generated Pydantic + vendor-SDK judges
+    ├── dbos-config.yaml
+    └── README.md                # how to run, signal HITL gates, deploy
 ```
 
 ### Render an IR without re-running the agent
@@ -286,6 +306,7 @@ If you already have a `pipeline.yaml` (hand-written or from a previous
 graduation), `rote emit` runs just the adapter step:
 
 ```sh
+rote emit /path/to/pipeline.yaml --out /tmp/emitted/            # dbos (default)
 rote emit /path/to/pipeline.yaml --runtime temporal --out /tmp/emitted/
 ```
 
@@ -347,10 +368,12 @@ Opus's extra reasoning earns its cost.
 ## Status
 
 `rote` is **pre-1.0**. The end-to-end flow works on the BDR example
-and the test suite covers each layer (133 tests in the fast suite,
-plus 3 slow tests that compile the emitted Cloudflare TypeScript
-against the real `@cloudflare/workers-types` definitions and drive a
-real workflow instance through both HITL gates via `wrangler dev`).
+and the test suite covers each layer (231 tests in the fast suite,
+plus 5 slow tests that run the emitted code against real runtimes:
+a DBOS runtime over SQLite, Temporal's time-skipping test server, the
+emitted Cloudflare TypeScript compiled against real
+`@cloudflare/workers-types` and driven through both HITL gates via
+`wrangler dev`, and the MCP server over a real stdio transport).
 Run `pytest tests/` for the fast suite; `pytest tests/ -m slow` for
 the toolchain-dependent integration tests.
 
@@ -360,6 +383,7 @@ the toolchain-dependent integration tests.
 | Temporal adapter | working (validated with mocked-activities e2e test) |
 | Cloudflare Workflows adapter | working (validated with `tsc --noEmit` over the real emitted output) |
 | DBOS adapter | working (validated against a real DBOS runtime over SQLite in the e2e test) |
+| DBOS TypeScript adapter (`dbos-ts`) | working (validated with `tsc --noEmit` over the real emitted output and a live run on the DBOS TS runtime against Docker Postgres) |
 | Graduator orchestrator | working |
 | `rote graduate` / `rote emit` CLI commands | working |
 | `claude` driver | working |
@@ -367,8 +391,8 @@ the toolchain-dependent integration tests.
 | `codex` driver | stub (`is_available` works; `run` not implemented) |
 | Inngest / Restate adapters | planned |
 | Real implementations of the extracted modules | the agent produces stubs that raise `NotImplementedError`; humans fill them in with real API client code |
-| Workflow data flow between activities | working — nodes declare `inputs:` bindings and all three adapters (Temporal, Cloudflare, DBOS) thread real payloads through the DAG, validated in the runtime e2e tests |
-| Distribution via PyPI | not yet published — install from source. The release pipeline (tag-driven, Trusted Publishing) is in place; see [docs/releasing.md](docs/releasing.md) |
+| Workflow data flow between activities | working — nodes declare `inputs:` bindings and all four adapters (Temporal, Cloudflare, DBOS, DBOS-TS) thread real payloads through the DAG, validated in the runtime e2e tests |
+| Distribution via PyPI | published as [`rote-cli`](https://pypi.org/project/rote-cli/) (`pip install rote-cli`); tag-driven Trusted Publishing releases — see [docs/releasing.md](docs/releasing.md) |
 
 The project explicitly **does not** depend on `claude-agent-sdk`.
 Anthropic's terms of service forbid third-party agents built on the

{rote_cli-0.3.0 → rote_cli-0.4.0}/src/rote/__init__.py

@@ -1,3 +1,3 @@
 """rote — graduate fuzzy AI skills into deterministic workflows."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{rote_cli-0.3.0 → rote_cli-0.4.0}/src/rote/adapters/__init__.py

@@ -48,12 +48,19 @@ def _dbos_adapter_factory() -> Adapter:
     return DbosAdapter()
 
 
+def _dbos_ts_adapter_factory() -> Adapter:
+    from rote.adapters.dbos_ts import DbosTsAdapter
+
+    return DbosTsAdapter()
+
+
 #: Name → factory. Keep the values as zero-arg callables so adapters can
 #: lazy-import their heavy dependencies.
 ADAPTERS: dict[str, Callable[[], Adapter]] = {
     "temporal": _temporal_adapter_factory,
     "cloudflare": _cloudflare_adapter_factory,
     "dbos": _dbos_adapter_factory,
+    "dbos-ts": _dbos_ts_adapter_factory,
 }
 
 

{rote_cli-0.3.0 → rote_cli-0.4.0}/src/rote/adapters/_common.py

@@ -13,9 +13,63 @@ from __future__ import annotations
 
 import hashlib
 import re
+from pathlib import Path
 
 from rote.ir import Node, Pipeline, parse_input_ref
 
+# ───────── Prose → safe code comment/docstring ─────────
+
+
+def safe_docstring_line(text: str, fallback: str = "") -> str:
+    """First line of ``text``, escaped so it cannot break out of a docstring.
+
+    Node ``description`` is prose (it legitimately contains quotes and
+    backslashes), yet adapters splice its first line straight into a
+    ``\"\"\"…\"\"\"`` Python docstring / block comment. An unescaped
+    ``\"\"\"`` — or a trailing backslash that escapes the closing quote —
+    lets a crafted pipeline.yaml close the docstring early and inject
+    code. Escaping backslashes and double-quotes neutralizes both without
+    charset-restricting prose at the IR layer.
+    """
+    stripped = text.strip() if text else ""
+    first = stripped.splitlines()[0] if stripped else fallback
+    return first.replace("\\", "\\\\").replace('"', '\\"')
+
+
+def safe_block_comment_line(text: str, fallback: str = "") -> str:
+    """First line of ``text``, safe to splice into a ``/* … */`` block comment.
+
+    The TypeScript adapter emits ``description`` first-lines into JSDoc
+    comments. An unescaped ``*/`` would close the comment early and let a
+    crafted pipeline.yaml inject code after it; neutralize the sequence by
+    inserting a space (``*/`` → ``* /``). Newlines are already dropped by
+    taking the first line.
+    """
+    stripped = text.strip() if text else ""
+    first = stripped.splitlines()[0] if stripped else fallback
+    return first.replace("*/", "* /")
+
+
+# ───────── Output-path containment ─────────
+
+
+def resolve_within(base: Path, *parts: str) -> Path:
+    """Join ``parts`` onto ``base`` and assert the result stays inside it.
+
+    Defense-in-depth for emitted-file paths. IR validation already pins
+    ``node.id`` to an identifier, but this guard means any future field
+    that reaches a filename cannot escape the output directory via an
+    absolute segment or ``..`` traversal — it fails loudly at emit time.
+    """
+    base_resolved = base.resolve()
+    target = base_resolved.joinpath(*parts).resolve()
+    if target != base_resolved and base_resolved not in target.parents:
+        raise ValueError(
+            f"Refusing to write outside output directory: {target} is not within {base_resolved}"
+        )
+    return target
+
+
 # ───────── Case conversion ─────────
 
 

rote_cli-0.4.0/src/rote/adapters/_ts_common.py

@@ -0,0 +1,338 @@
+"""Helpers shared by every TypeScript-emitting runtime adapter.
+
+Extracted from ``rote.adapters.cloudflare`` once the DBOS TypeScript
+adapter became the second TS consumer — same rule as ``_common``: a
+helper moves here only after two adapters prove it's genuinely shared.
+
+What lives here:
+
+* the JSON-Schema-to-Zod converter (``json_schema_to_zod`` and its
+  internals ``_resolve_refs`` / ``_convert_zod``),
+* the typed LLM signature module emitters
+  (``emit_signature_anthropic`` / ``emit_signature_openai``) plus the
+  runtime prompt-interpolation helper they embed
+  (``_INTERPOLATE_HELPER``).
+
+What deliberately does *not* live here: anything encoding a runtime's
+execution semantics (Cloudflare ``step.do`` configs, DBOS step retry
+options, …) — that stays in the adapter that owns it. Case conversion
+(``_to_camel_case`` etc.) already lives in ``rote.adapters._common``
+because the Python adapters use it too.
+
+The emitted signature modules are runtime-agnostic TypeScript: they
+import only Zod and the vendor SDK, and take API keys via an explicit
+``env`` parameter so they work identically inside a Workers isolate
+(bindings) and a Node process (``process.env``).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from rote.adapters._common import safe_block_comment_line
+
+# ───────── JSON Schema → Zod ─────────
+
+
+def _resolve_refs(schema: Any, defs: dict[str, Any]) -> Any:
+    """Recursively inline ``$ref`` references using a pre-extracted ``$defs`` map.
+
+    Pydantic emits nested types as ``$ref: "#/$defs/Name"``. Zod schemas
+    are constructed inline so we resolve refs eagerly.
+    """
+    if isinstance(schema, dict):
+        if "$ref" in schema:
+            ref = schema["$ref"]
+            if not ref.startswith("#/$defs/"):
+                raise ValueError(f"Unsupported $ref form: {ref!r}")
+            name = ref[len("#/$defs/") :]
+            if name not in defs:
+                raise ValueError(f"Unknown $ref target: {name!r}")
+            return _resolve_refs(defs[name], defs)
+        return {k: _resolve_refs(v, defs) for k, v in schema.items() if k != "$defs"}
+    if isinstance(schema, list):
+        return [_resolve_refs(x, defs) for x in schema]
+    return schema
+
+
+def _convert_zod(schema: Any, indent: int = 0) -> str:
+    """Convert a (resolved, ref-free) JSON Schema fragment to a Zod expression."""
+    if not isinstance(schema, dict):
+        raise ValueError(f"Expected schema dict, got {type(schema).__name__}: {schema!r}")
+
+    # Nullable / unions via anyOf or oneOf
+    for union_key in ("anyOf", "oneOf"):
+        if union_key in schema:
+            variants = schema[union_key]
+            non_null = [
+                v for v in variants if not (isinstance(v, dict) and v.get("type") == "null")
+            ]
+            has_null = len(non_null) < len(variants)
+            if len(non_null) == 1:
+                inner = _convert_zod(non_null[0], indent)
+                return f"{inner}.nullable()" if has_null else inner
+            parts = [_convert_zod(v, indent) for v in non_null]
+            union = "z.union([" + ", ".join(parts) + "])"
+            return f"{union}.nullable()" if has_null else union
+
+    if "enum" in schema:
+        values = schema["enum"]
+        if all(isinstance(v, str) for v in values):
+            return "z.enum([" + ", ".join(json.dumps(v) for v in values) + "])"
+        # Mixed-type enum
+        literals = [f"z.literal({json.dumps(v)})" for v in values]
+        return "z.union([" + ", ".join(literals) + "])"
+
+    schema_type = schema.get("type")
+
+    if schema_type == "object":
+        props = schema.get("properties", {})
+        required = set(schema.get("required", []))
+        if not props:
+            return "z.object({}).strict()"
+        pad = "  " * (indent + 1)
+        outer = "  " * indent
+        lines = []
+        for name, prop_schema in props.items():
+            inner = _convert_zod(prop_schema, indent + 1)
+            if name not in required:
+                inner = f"{inner}.optional()"
+            lines.append(f"{pad}{json.dumps(name)}: {inner},")
+        body = "\n".join(lines)
+        return f"z.object({{\n{body}\n{outer}}}).strict()"
+
+    if schema_type == "array":
+        items = schema.get("items", {})
+        return f"z.array({_convert_zod(items, indent)})"
+
+    if schema_type == "string":
+        return "z.string()"
+    if schema_type == "integer":
+        return "z.number().int()"
+    if schema_type == "number":
+        return "z.number()"
+    if schema_type == "boolean":
+        return "z.boolean()"
+    if schema_type == "null":
+        return "z.null()"
+
+    # Permissive fallback for under-specified schemas.
+    return "z.unknown()"
+
+
+def json_schema_to_zod(schema: dict[str, Any], indent: int = 0) -> str:
+    """Public entry point: convert a (possibly ref-laden) JSON Schema to Zod source."""
+    defs = schema.get("$defs", {})
+    resolved = _resolve_refs(schema, defs)
+    return _convert_zod(resolved, indent)
+
+
+# ───────── signatures/<id>.ts emission ─────────
+
+_INTERPOLATE_HELPER = """\
+function interpolate(template: string, vars: Record<string, unknown>): string {
+    return template.replace(/\\{\\{\\s*([\\w.]+)\\s*\\}\\}/g, (_match, key: string) => {
+        const value = key.split(".").reduce<unknown>(
+            (acc, part) =>
+                acc != null && typeof acc === "object"
+                    ? (acc as Record<string, unknown>)[part]
+                    : undefined,
+            vars,
+        );
+        if (value === undefined) {
+            // A hole in a judge prompt produces confident garbage that is
+            // far harder to debug than an error naming the missing field.
+            throw new Error(
+                `prompt template references {{ ${key} }} but the input has no ` +
+                    `such field; available top-level keys: ${Object.keys(vars).sort().join(", ")}`,
+            );
+        }
+        if (value === null) return "";
+        return typeof value === "string" ? value : JSON.stringify(value);
+    });
+}
+"""
+
+
+def emit_signature_anthropic(
+    *,
+    node_id: str,
+    fn_name: str,
+    pascal: str,
+    description: str,
+    input_zod: str,
+    output_zod: str,
+    output_schema_json: str,
+    prompt_template: str,
+    model: str,
+    temperature: float | None,
+    generated_by: str,
+) -> str:
+    """Emit a signatures/<id>.ts module calling Anthropic with tool-use output.
+
+    ``generated_by`` names the emitting adapter module in the header
+    JSDoc (e.g. ``rote.adapters.cloudflare``) so regeneration
+    instructions point at the right runtime.
+    """
+    desc_first = safe_block_comment_line(description, fallback=node_id)
+    temp_line = f"        temperature: {temperature},\n" if temperature is not None else ""
+    quoted_id = json.dumps(node_id)
+    quoted_desc = json.dumps(desc_first)
+    quoted_model = json.dumps(model)
+    quoted_prompt = json.dumps(prompt_template)
+    parts = [
+        "/**",
+        f" * Typed LLM signature: {node_id}",
+        " *",
+        f" * {desc_first}",
+        " *",
+        f" * Auto-generated by {generated_by} from the IR's",
+        " * `signature_spec`. The non-determinism lives inside this module;",
+        " * the workflow that calls it stays deterministic.",
+        " */",
+        "",
+        'import Anthropic from "@anthropic-ai/sdk";',
+        'import { z } from "zod";',
+        "",
+        f"export const {pascal}Input = {input_zod};",
+        f"export type {pascal}Input = z.infer<typeof {pascal}Input>;",
+        "",
+        f"export const {pascal}Output = {output_zod};",
+        f"export type {pascal}Output = z.infer<typeof {pascal}Output>;",
+        "",
+        f"const PROMPT = {quoted_prompt};",
+        "",
+        f"const OUTPUT_JSON_SCHEMA = {output_schema_json};",
+        "",
+        _INTERPOLATE_HELPER.rstrip("\n"),
+        "",
+        f"export async function {fn_name}(",
+        "    rawInput: unknown,",
+        "    env: { ANTHROPIC_API_KEY: string },",
+        f"): Promise<{pascal}Output> {{",
+        f"    const input = {pascal}Input.parse(rawInput);",
+        "    const client = new Anthropic({ apiKey: env.ANTHROPIC_API_KEY });",
+        "",
+        "    const response = await client.messages.create({",
+        f"        model: {quoted_model},",
+        "        max_tokens: 4096,",
+    ]
+    if temp_line:
+        parts.append(temp_line.rstrip("\n"))
+    schema_cast = 'as { type: "object"; [k: string]: unknown }'
+    msg_line = (
+        '            { role: "user", '
+        "content: interpolate(PROMPT, input as Record<string, unknown>) },"
+    )
+    parts.extend(
+        [
+            "        tools: [",
+            "            {",
+            f"                name: {quoted_id},",
+            f"                description: {quoted_desc},",
+            f"                input_schema: OUTPUT_JSON_SCHEMA {schema_cast},",
+            "            },",
+            "        ],",
+            f'        tool_choice: {{ type: "tool", name: {quoted_id} }},',
+            "        messages: [",
+            msg_line,
+            "        ],",
+            "    });",
+            "",
+            '    const toolUse = response.content.find((b) => b.type === "tool_use");',
+            '    if (!toolUse || toolUse.type !== "tool_use") {',
+            f'        throw new Error("LLM did not return a tool_use block for {node_id}");',
+            "    }",
+            f"    return {pascal}Output.parse(toolUse.input);",
+            "}",
+            "",
+        ]
+    )
+    return "\n".join(parts)
+
+
+def emit_signature_openai(
+    *,
+    node_id: str,
+    fn_name: str,
+    pascal: str,
+    description: str,
+    input_zod: str,
+    output_zod: str,
+    output_schema_json: str,
+    prompt_template: str,
+    model: str,
+    temperature: float | None,
+    generated_by: str,
+) -> str:
+    """Emit a signatures/<id>.ts module using OpenAI structured outputs."""
+    desc_first = safe_block_comment_line(description, fallback=node_id)
+    temp_line = f"        temperature: {temperature},\n" if temperature is not None else ""
+    quoted_id = json.dumps(node_id)
+    quoted_model = json.dumps(model)
+    quoted_prompt = json.dumps(prompt_template)
+    parts = [
+        "/**",
+        f" * Typed LLM signature: {node_id}",
+        " *",
+        f" * {desc_first}",
+        " *",
+        f" * Auto-generated by {generated_by} from the IR's",
+        " * `signature_spec`. Uses OpenAI structured outputs with JSON Schema.",
+        " */",
+        "",
+        'import OpenAI from "openai";',
+        'import { z } from "zod";',
+        "",
+        f"export const {pascal}Input = {input_zod};",
+        f"export type {pascal}Input = z.infer<typeof {pascal}Input>;",
+        "",
+        f"export const {pascal}Output = {output_zod};",
+        f"export type {pascal}Output = z.infer<typeof {pascal}Output>;",
+        "",
+        f"const PROMPT = {quoted_prompt};",
+        f"const OUTPUT_JSON_SCHEMA = {output_schema_json};",
+        "",
+        _INTERPOLATE_HELPER.rstrip("\n"),
+        "",
+        f"export async function {fn_name}(",
+        "    rawInput: unknown,",
+        "    env: { OPENAI_API_KEY: string },",
+        f"): Promise<{pascal}Output> {{",
+        f"    const input = {pascal}Input.parse(rawInput);",
+        "    const client = new OpenAI({ apiKey: env.OPENAI_API_KEY });",
+        "",
+        "    const response = await client.chat.completions.create({",
+        f"        model: {quoted_model},",
+    ]
+    if temp_line:
+        parts.append(temp_line.rstrip("\n"))
+    schema_inline = (
+        f"            json_schema: {{ name: {quoted_id}, "
+        "schema: OUTPUT_JSON_SCHEMA, strict: true },"
+    )
+    msg_line = (
+        '            { role: "user", '
+        "content: interpolate(PROMPT, input as Record<string, unknown>) },"
+    )
+    parts.extend(
+        [
+            "        response_format: {",
+            '            type: "json_schema",',
+            schema_inline,
+            "        },",
+            "        messages: [",
+            msg_line,
+            "        ],",
+            "    });",
+            "    const content = response.choices[0]?.message?.content;",
+            "    if (!content) {",
+            f'        throw new Error("OpenAI returned no content for {node_id}");',
+            "    }",
+            f"    return {pascal}Output.parse(JSON.parse(content));",
+            "}",
+            "",
+        ]
+    )
+    return "\n".join(parts)