@particle-academy/fancy-flow 0.12.0 → 0.14.0

package/dist/llm/vercel-ai.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+var ai = require('ai');
+
+// src/llm/vercel-ai.ts
+function registerLlmClient(client) {
+  return () => {
+  };
+}
+
+// src/llm/vercel-ai.ts
+function createVercelAiLlmClient(options) {
+  return {
+    async chooseRoute(request) {
+      const model = options.resolveModel?.(request) ?? options.model;
+      const result = await ai.generateText({
+        model,
+        system: request.system,
+        prompt: buildPrompt(request),
+        output: ai.Output.choice({
+          options: request.routes.map((r) => r.port),
+          name: "route",
+          description: "The single route this input should follow."
+        }),
+        ...options.callOptions ?? {}
+      });
+      const port = String(result.output ?? "");
+      return {
+        port,
+        // The SDK returns the choice, not an explanation. Say where the answer
+        // came from rather than inventing a rationale the model never gave.
+        reason: `chosen by ${describeModel(model)}`
+      };
+    }
+  };
+}
+function useVercelAiForLlmBranch(options) {
+  return registerLlmClient();
+}
+function buildPrompt(request) {
+  const described = request.routes.filter((r) => r.description);
+  if (described.length === 0) return request.prompt;
+  const lines = described.map((r) => `- ${r.port}: ${r.description}`).join("\n");
+  return `${request.prompt}
+
+Routes:
+${lines}`;
+}
+function describeModel(model) {
+  if (typeof model === "string") return model;
+  const id = model.modelId;
+  return id ?? "the configured model";
+}
+
+exports.buildPrompt = buildPrompt;
+exports.createVercelAiLlmClient = createVercelAiLlmClient;
+exports.useVercelAiForLlmBranch = useVercelAiForLlmBranch;
+//# sourceMappingURL=vercel-ai.cjs.map
+//# sourceMappingURL=vercel-ai.cjs.map

package/dist/llm/vercel-ai.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/registry/capabilities.ts","../../src/llm/vercel-ai.ts"],"names":["generateText","Output"],"mappings":";;;;;AA2DO,SAAS,kBAAkB,MAAA,EAA+B;AAE/D,EAAA,OAAO,MAAM;AAC2B,EACxC,CAAA;AACF;;;ACpBO,SAAS,wBAAwB,OAAA,EAAqC;AAC3E,EAAA,OAAO;AAAA,IACL,MAAM,YAAY,OAAA,EAAS;AACzB,MAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,YAAA,GAAe,OAAO,KAAK,OAAA,CAAQ,KAAA;AAMzD,MAAA,MAAM,MAAA,GAAS,MAAMA,eAAA,CAAa;AAAA,QAChC,KAAA;AAAA,QACA,QAAQ,OAAA,CAAQ,MAAA;AAAA,QAChB,MAAA,EAAQ,YAAY,OAAO,CAAA;AAAA,QAC3B,MAAA,EAAQC,UAAO,MAAA,CAAO;AAAA,UACpB,SAAS,OAAA,CAAQ,MAAA,CAAO,IAAI,CAAC,CAAA,KAAM,EAAE,IAAI,CAAA;AAAA,UACzC,IAAA,EAAM,OAAA;AAAA,UACN,WAAA,EAAa;AAAA,SACd,CAAA;AAAA,QACD,GAAI,OAAA,CAAQ,WAAA,IAAe;AAAC,OACpB,CAAA;AAEV,MAAA,MAAM,IAAA,GAAO,MAAA,CAAQ,MAAA,CAAgC,MAAA,IAAU,EAAE,CAAA;AACjE,MAAA,OAAO;AAAA,QACL,IAAA;AAAA;AAAA;AAAA,QAGA,MAAA,EAAQ,CAAA,UAAA,EAAa,aAAA,CAAc,KAAK,CAAC,CAAA;AAAA,OAC3C;AAAA,IACF;AAAA,GACF;AACF;AAGO,SAAS,wBAAwB,OAAA,EAAsC;AAC5E,EAAA,OAAO,iBAAA,CAAkD,CAAA;AAC3D;AASO,SAAS,YAAY,OAAA,EAAkC;AAC5D,EAAA,MAAM,YAAY,OAAA,CAAQ,MAAA,CAAO,OAAO,CAAC,CAAA,KAAM,EAAE,WAAW,CAAA;AAC5D,EAAA,IAAI,SAAA,CAAU,MAAA,KAAW,CAAA,EAAG,OAAO,OAAA,CAAQ,MAAA;AAE3C,EAAA,MAAM,KAAA,GAAQ,SAAA,CAAU,GAAA,CAAI,CAAC,MAAM,CAAA,EAAA,EAAK,CAAA,CAAE,IAAI,CAAA,EAAA,EAAK,CAAA,CAAE,WAAW,CAAA,CAAE,CAAA,CAAE,KAAK,IAAI,CAAA;AAC7E,EAAA,OAAO,CAAA,EAAG,QAAQ,MAAM;;AAAA;AAAA,EAAgB,KAAK,CAAA,CAAA;AAC/C;AAEA,SAAS,cAAc,KAAA,EAA8B;AACnD,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,EAAU,OAAO,KAAA;AACtC,EAAA,MAAM,KAAM,KAAA,CAA+B,OAAA;AAC3C,EAAA,OAAO,EAAA,IAAM,sBAAA;AACf","file":"vercel-ai.cjs","sourcesContent":["import type { FlowGraph } from \"../types\";\n\n/**\n * Host capabilities — the services core nodes need but must never depend on.\n *\n * A node that imports a provider SDK forces every consumer to install it: a\n * workflow app that never calls a model should not inherit an LLM dependency.\n * So core declares the CONTRACT and the host supplies the implementation, the\n * same arrangement `renderDocumentField` already uses for documents.\n *\n * That keeps opinionated nodes in core without their opinions: `llm_branch`\n * ships the routing semantics, port derivation and config UI, while whichever\n * client the host registers — Prism, an OpenAI SDK, a local model, a fake in a\n * test — decides how the question actually gets asked.\n *\n * Registration is deliberately explicit and typed per capability rather than a\n * stringly-keyed bag, so a missing one is a clear error at the seam instead of\n * an undefined somewhere downstream.\n */\n\n// ── LLM ─────────────────────────────────────────────────────────────────────\n\nexport type LlmRoute = { port: string; description?: string };\n\nexport type LlmRouteRequest = {\n  /** Optional framing for the decision. */\n  system?: string;\n  /** What the model is deciding about. */\n  prompt: string;\n  /** The ports it must choose between. */\n  routes: LlmRoute[];\n  provider?: string;\n  model?: string;\n  /** Host-resolved credential reference, never a raw key. */\n  credential?: string;\n};\n\nexport type LlmRouteChoice = {\n  /** Must be one of the requested route ports. */\n  port: string;\n  /** Why — carried down the chosen port so a run is explainable afterwards. */\n  reason?: string;\n};\n\n/**\n * The only thing core asks of an LLM: given routes, pick one.\n *\n * Deliberately not a general chat interface. A narrow contract is one a host\n * can satisfy in a few lines over any SDK, and it keeps the choice\n * machine-checkable — an implementation should constrain the model to the\n * declared ports (structured output / enum) rather than parsing prose.\n */\nexport type LlmClient = {\n  chooseRoute: (request: LlmRouteRequest) => Promise<LlmRouteChoice> | LlmRouteChoice;\n};\n\nlet llmClient: LlmClient | null = null;\n\n/** Install the host's LLM client. Returns an unregister function. */\nexport function registerLlmClient(client: LlmClient): () => void {\n  llmClient = client;\n  return () => {\n    if (llmClient === client) llmClient = null;\n  };\n}\n\nexport function getLlmClient(): LlmClient | null {\n  return llmClient;\n}\n\n// ── Workflow resolution ─────────────────────────────────────────────────────\n\n/**\n * Resolve a workflow reference to a runnable graph.\n *\n * `subflow` names another workflow rather than embedding it, so the host owns\n * where workflows live — a database, a file, an API. Returning null means \"no\n * such workflow\", which the node reports as an error rather than silently\n * running nothing.\n */\nexport type WorkflowResolver = (ref: string) => Promise<FlowGraph | null> | FlowGraph | null;\n\nlet workflowResolver: WorkflowResolver | null = null;\n\n/** Install the host's workflow resolver. Returns an unregister function. */\nexport function registerWorkflowResolver(resolver: WorkflowResolver): () => void {\n  workflowResolver = resolver;\n  return () => {\n    if (workflowResolver === resolver) workflowResolver = null;\n  };\n}\n\nexport function getWorkflowResolver(): WorkflowResolver | null {\n  return workflowResolver;\n}\n\n// ── Introspection ───────────────────────────────────────────────────────────\n\nexport type CapabilityId = \"llm\" | \"workflow_resolver\" | \"document\";\n\n/**\n * Which capabilities are currently satisfied.\n *\n * Exists so a host (or the CLI, or an agent over MCP) can answer \"what does\n * this graph need that I haven't wired?\" BEFORE a run fails halfway through.\n */\nexport function capabilityStatus(): Record<CapabilityId, boolean> {\n  // Imported lazily to avoid dragging the React-dependent rich-input module\n  // into the headless engine.\n  let documentReady = false;\n  try {\n    // eslint-disable-next-line @typescript-eslint/no-var-requires, no-undef\n    documentReady = Boolean((globalThis as any).__fancyFlowDocumentAdapter);\n  } catch {\n    documentReady = false;\n  }\n  return {\n    llm: llmClient !== null,\n    workflow_resolver: workflowResolver !== null,\n    document: documentReady,\n  };\n}\n","/**\n * `@particle-academy/fancy-flow/llm/vercel-ai` — an LLM client backed by the\n * Vercel AI SDK.\n *\n * Core ships the routing but never a provider, so `llm_branch` needs a client\n * before it can run. Making every consumer hand-write one is not \"fully\n * functional\" — so this adapter ships in the box, on an opt-in subpath, exactly\n * like `/rich-input` wires fancy-cms.\n *\n * The AI SDK is chosen because it fronts every provider (Anthropic, OpenAI,\n * Google, local models). Picking it does NOT force it: `registerLlmClient()`\n * takes any implementation, so a different SDK or a hand-rolled fetch works\n * just as well.\n *\n * ```ts\n * import { anthropic } from \"@ai-sdk/anthropic\";\n * import { useVercelAiForLlmBranch } from \"@particle-academy/fancy-flow/llm/vercel-ai\";\n *\n * useVercelAiForLlmBranch({ model: anthropic(\"claude-sonnet-4-5\") });\n * ```\n *\n * `ai` is an OPTIONAL peer — required only by this subpath. The main entry\n * never imports it, so a flow with no AI node pays nothing.\n */\nimport { Output, generateText, type LanguageModel } from \"ai\";\nimport { registerLlmClient, type LlmClient, type LlmRouteRequest } from \"../registry/capabilities\";\n\nexport type VercelAiOptions = {\n  /** The model to route with, e.g. `anthropic(\"claude-sonnet-4-5\")`. */\n  model: LanguageModel;\n  /**\n   * Resolve a per-node model. `llm_branch` config can name a provider/model,\n   * and only the host knows how to turn those strings into a model instance —\n   * core deliberately never maps a name to a provider.\n   */\n  resolveModel?: (request: LlmRouteRequest) => LanguageModel | undefined;\n  /** Extra options merged into every call (temperature, headers, …). */\n  callOptions?: Record<string, unknown>;\n};\n\n/**\n * Build the client without registering it — handy for tests, or for a host\n * that wants to wrap it.\n */\nexport function createVercelAiLlmClient(options: VercelAiOptions): LlmClient {\n  return {\n    async chooseRoute(request) {\n      const model = options.resolveModel?.(request) ?? options.model;\n\n      // Constrain the model to the declared ports instead of parsing prose.\n      // A choice that can only BE one of the ports is the difference between a\n      // routing decision and a guess, and it means the \"hallucinated port\"\n      // guard in the node is a backstop rather than the primary defence.\n      const result = await generateText({\n        model,\n        system: request.system,\n        prompt: buildPrompt(request),\n        output: Output.choice({\n          options: request.routes.map((r) => r.port),\n          name: \"route\",\n          description: \"The single route this input should follow.\",\n        }),\n        ...(options.callOptions ?? {}),\n      } as never);\n\n      const port = String((result as { output?: unknown }).output ?? \"\");\n      return {\n        port,\n        // The SDK returns the choice, not an explanation. Say where the answer\n        // came from rather than inventing a rationale the model never gave.\n        reason: `chosen by ${describeModel(model)}`,\n      };\n    },\n  };\n}\n\n/** Build the client and install it. Returns an unregister function. */\nexport function useVercelAiForLlmBranch(options: VercelAiOptions): () => void {\n  return registerLlmClient(createVercelAiLlmClient(options));\n}\n\n/**\n * Fold the route descriptions into the prompt.\n *\n * The port ids alone are often terse (`billing`, `support`); the descriptions\n * are what the author wrote to distinguish them, so a model that never sees\n * them is choosing on the strength of a label.\n */\nexport function buildPrompt(request: LlmRouteRequest): string {\n  const described = request.routes.filter((r) => r.description);\n  if (described.length === 0) return request.prompt;\n\n  const lines = described.map((r) => `- ${r.port}: ${r.description}`).join(\"\\n\");\n  return `${request.prompt}\\n\\nRoutes:\\n${lines}`;\n}\n\nfunction describeModel(model: LanguageModel): string {\n  if (typeof model === \"string\") return model;\n  const id = (model as { modelId?: string }).modelId;\n  return id ?? \"the configured model\";\n}\n"]}

package/dist/llm/vercel-ai.d.cts

@@ -0,0 +1,59 @@
+import { LanguageModel } from 'ai';
+import { L as LlmRouteRequest, a as LlmClient } from '../capabilities-D-V9Rxv1.cjs';
+import '../types-fc0fFKkf.cjs';
+import '@xyflow/react';
+
+/**
+ * `@particle-academy/fancy-flow/llm/vercel-ai` — an LLM client backed by the
+ * Vercel AI SDK.
+ *
+ * Core ships the routing but never a provider, so `llm_branch` needs a client
+ * before it can run. Making every consumer hand-write one is not "fully
+ * functional" — so this adapter ships in the box, on an opt-in subpath, exactly
+ * like `/rich-input` wires fancy-cms.
+ *
+ * The AI SDK is chosen because it fronts every provider (Anthropic, OpenAI,
+ * Google, local models). Picking it does NOT force it: `registerLlmClient()`
+ * takes any implementation, so a different SDK or a hand-rolled fetch works
+ * just as well.
+ *
+ * ```ts
+ * import { anthropic } from "@ai-sdk/anthropic";
+ * import { useVercelAiForLlmBranch } from "@particle-academy/fancy-flow/llm/vercel-ai";
+ *
+ * useVercelAiForLlmBranch({ model: anthropic("claude-sonnet-4-5") });
+ * ```
+ *
+ * `ai` is an OPTIONAL peer — required only by this subpath. The main entry
+ * never imports it, so a flow with no AI node pays nothing.
+ */
+
+type VercelAiOptions = {
+    /** The model to route with, e.g. `anthropic("claude-sonnet-4-5")`. */
+    model: LanguageModel;
+    /**
+     * Resolve a per-node model. `llm_branch` config can name a provider/model,
+     * and only the host knows how to turn those strings into a model instance —
+     * core deliberately never maps a name to a provider.
+     */
+    resolveModel?: (request: LlmRouteRequest) => LanguageModel | undefined;
+    /** Extra options merged into every call (temperature, headers, …). */
+    callOptions?: Record<string, unknown>;
+};
+/**
+ * Build the client without registering it — handy for tests, or for a host
+ * that wants to wrap it.
+ */
+declare function createVercelAiLlmClient(options: VercelAiOptions): LlmClient;
+/** Build the client and install it. Returns an unregister function. */
+declare function useVercelAiForLlmBranch(options: VercelAiOptions): () => void;
+/**
+ * Fold the route descriptions into the prompt.
+ *
+ * The port ids alone are often terse (`billing`, `support`); the descriptions
+ * are what the author wrote to distinguish them, so a model that never sees
+ * them is choosing on the strength of a label.
+ */
+declare function buildPrompt(request: LlmRouteRequest): string;
+
+export { type VercelAiOptions, buildPrompt, createVercelAiLlmClient, useVercelAiForLlmBranch };

package/dist/llm/vercel-ai.d.ts

@@ -0,0 +1,59 @@
+import { LanguageModel } from 'ai';
+import { L as LlmRouteRequest, a as LlmClient } from '../capabilities-B6r1Snfj.js';
+import '../types-fc0fFKkf.js';
+import '@xyflow/react';
+
+/**
+ * `@particle-academy/fancy-flow/llm/vercel-ai` — an LLM client backed by the
+ * Vercel AI SDK.
+ *
+ * Core ships the routing but never a provider, so `llm_branch` needs a client
+ * before it can run. Making every consumer hand-write one is not "fully
+ * functional" — so this adapter ships in the box, on an opt-in subpath, exactly
+ * like `/rich-input` wires fancy-cms.
+ *
+ * The AI SDK is chosen because it fronts every provider (Anthropic, OpenAI,
+ * Google, local models). Picking it does NOT force it: `registerLlmClient()`
+ * takes any implementation, so a different SDK or a hand-rolled fetch works
+ * just as well.
+ *
+ * ```ts
+ * import { anthropic } from "@ai-sdk/anthropic";
+ * import { useVercelAiForLlmBranch } from "@particle-academy/fancy-flow/llm/vercel-ai";
+ *
+ * useVercelAiForLlmBranch({ model: anthropic("claude-sonnet-4-5") });
+ * ```
+ *
+ * `ai` is an OPTIONAL peer — required only by this subpath. The main entry
+ * never imports it, so a flow with no AI node pays nothing.
+ */
+
+type VercelAiOptions = {
+    /** The model to route with, e.g. `anthropic("claude-sonnet-4-5")`. */
+    model: LanguageModel;
+    /**
+     * Resolve a per-node model. `llm_branch` config can name a provider/model,
+     * and only the host knows how to turn those strings into a model instance —
+     * core deliberately never maps a name to a provider.
+     */
+    resolveModel?: (request: LlmRouteRequest) => LanguageModel | undefined;
+    /** Extra options merged into every call (temperature, headers, …). */
+    callOptions?: Record<string, unknown>;
+};
+/**
+ * Build the client without registering it — handy for tests, or for a host
+ * that wants to wrap it.
+ */
+declare function createVercelAiLlmClient(options: VercelAiOptions): LlmClient;
+/** Build the client and install it. Returns an unregister function. */
+declare function useVercelAiForLlmBranch(options: VercelAiOptions): () => void;
+/**
+ * Fold the route descriptions into the prompt.
+ *
+ * The port ids alone are often terse (`billing`, `support`); the descriptions
+ * are what the author wrote to distinguish them, so a model that never sees
+ * them is choosing on the strength of a label.
+ */
+declare function buildPrompt(request: LlmRouteRequest): string;
+
+export { type VercelAiOptions, buildPrompt, createVercelAiLlmClient, useVercelAiForLlmBranch };

package/dist/llm/vercel-ai.js

@@ -0,0 +1,49 @@
+import { registerLlmClient } from '../chunk-BB45F6S3.js';
+import { generateText, Output } from 'ai';
+
+function createVercelAiLlmClient(options) {
+  return {
+    async chooseRoute(request) {
+      const model = options.resolveModel?.(request) ?? options.model;
+      const result = await generateText({
+        model,
+        system: request.system,
+        prompt: buildPrompt(request),
+        output: Output.choice({
+          options: request.routes.map((r) => r.port),
+          name: "route",
+          description: "The single route this input should follow."
+        }),
+        ...options.callOptions ?? {}
+      });
+      const port = String(result.output ?? "");
+      return {
+        port,
+        // The SDK returns the choice, not an explanation. Say where the answer
+        // came from rather than inventing a rationale the model never gave.
+        reason: `chosen by ${describeModel(model)}`
+      };
+    }
+  };
+}
+function useVercelAiForLlmBranch(options) {
+  return registerLlmClient(createVercelAiLlmClient(options));
+}
+function buildPrompt(request) {
+  const described = request.routes.filter((r) => r.description);
+  if (described.length === 0) return request.prompt;
+  const lines = described.map((r) => `- ${r.port}: ${r.description}`).join("\n");
+  return `${request.prompt}
+
+Routes:
+${lines}`;
+}
+function describeModel(model) {
+  if (typeof model === "string") return model;
+  const id = model.modelId;
+  return id ?? "the configured model";
+}
+
+export { buildPrompt, createVercelAiLlmClient, useVercelAiForLlmBranch };
+//# sourceMappingURL=vercel-ai.js.map
+//# sourceMappingURL=vercel-ai.js.map

package/dist/llm/vercel-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/llm/vercel-ai.ts"],"names":[],"mappings":";;;AA4CO,SAAS,wBAAwB,OAAA,EAAqC;AAC3E,EAAA,OAAO;AAAA,IACL,MAAM,YAAY,OAAA,EAAS;AACzB,MAAA,MAAM,KAAA,GAAQ,OAAA,CAAQ,YAAA,GAAe,OAAO,KAAK,OAAA,CAAQ,KAAA;AAMzD,MAAA,MAAM,MAAA,GAAS,MAAM,YAAA,CAAa;AAAA,QAChC,KAAA;AAAA,QACA,QAAQ,OAAA,CAAQ,MAAA;AAAA,QAChB,MAAA,EAAQ,YAAY,OAAO,CAAA;AAAA,QAC3B,MAAA,EAAQ,OAAO,MAAA,CAAO;AAAA,UACpB,SAAS,OAAA,CAAQ,MAAA,CAAO,IAAI,CAAC,CAAA,KAAM,EAAE,IAAI,CAAA;AAAA,UACzC,IAAA,EAAM,OAAA;AAAA,UACN,WAAA,EAAa;AAAA,SACd,CAAA;AAAA,QACD,GAAI,OAAA,CAAQ,WAAA,IAAe;AAAC,OACpB,CAAA;AAEV,MAAA,MAAM,IAAA,GAAO,MAAA,CAAQ,MAAA,CAAgC,MAAA,IAAU,EAAE,CAAA;AACjE,MAAA,OAAO;AAAA,QACL,IAAA;AAAA;AAAA;AAAA,QAGA,MAAA,EAAQ,CAAA,UAAA,EAAa,aAAA,CAAc,KAAK,CAAC,CAAA;AAAA,OAC3C;AAAA,IACF;AAAA,GACF;AACF;AAGO,SAAS,wBAAwB,OAAA,EAAsC;AAC5E,EAAA,OAAO,iBAAA,CAAkB,uBAAA,CAAwB,OAAO,CAAC,CAAA;AAC3D;AASO,SAAS,YAAY,OAAA,EAAkC;AAC5D,EAAA,MAAM,YAAY,OAAA,CAAQ,MAAA,CAAO,OAAO,CAAC,CAAA,KAAM,EAAE,WAAW,CAAA;AAC5D,EAAA,IAAI,SAAA,CAAU,MAAA,KAAW,CAAA,EAAG,OAAO,OAAA,CAAQ,MAAA;AAE3C,EAAA,MAAM,KAAA,GAAQ,SAAA,CAAU,GAAA,CAAI,CAAC,MAAM,CAAA,EAAA,EAAK,CAAA,CAAE,IAAI,CAAA,EAAA,EAAK,CAAA,CAAE,WAAW,CAAA,CAAE,CAAA,CAAE,KAAK,IAAI,CAAA;AAC7E,EAAA,OAAO,CAAA,EAAG,QAAQ,MAAM;;AAAA;AAAA,EAAgB,KAAK,CAAA,CAAA;AAC/C;AAEA,SAAS,cAAc,KAAA,EAA8B;AACnD,EAAA,IAAI,OAAO,KAAA,KAAU,QAAA,EAAU,OAAO,KAAA;AACtC,EAAA,MAAM,KAAM,KAAA,CAA+B,OAAA;AAC3C,EAAA,OAAO,EAAA,IAAM,sBAAA;AACf","file":"vercel-ai.js","sourcesContent":["/**\n * `@particle-academy/fancy-flow/llm/vercel-ai` — an LLM client backed by the\n * Vercel AI SDK.\n *\n * Core ships the routing but never a provider, so `llm_branch` needs a client\n * before it can run. Making every consumer hand-write one is not \"fully\n * functional\" — so this adapter ships in the box, on an opt-in subpath, exactly\n * like `/rich-input` wires fancy-cms.\n *\n * The AI SDK is chosen because it fronts every provider (Anthropic, OpenAI,\n * Google, local models). Picking it does NOT force it: `registerLlmClient()`\n * takes any implementation, so a different SDK or a hand-rolled fetch works\n * just as well.\n *\n * ```ts\n * import { anthropic } from \"@ai-sdk/anthropic\";\n * import { useVercelAiForLlmBranch } from \"@particle-academy/fancy-flow/llm/vercel-ai\";\n *\n * useVercelAiForLlmBranch({ model: anthropic(\"claude-sonnet-4-5\") });\n * ```\n *\n * `ai` is an OPTIONAL peer — required only by this subpath. The main entry\n * never imports it, so a flow with no AI node pays nothing.\n */\nimport { Output, generateText, type LanguageModel } from \"ai\";\nimport { registerLlmClient, type LlmClient, type LlmRouteRequest } from \"../registry/capabilities\";\n\nexport type VercelAiOptions = {\n  /** The model to route with, e.g. `anthropic(\"claude-sonnet-4-5\")`. */\n  model: LanguageModel;\n  /**\n   * Resolve a per-node model. `llm_branch` config can name a provider/model,\n   * and only the host knows how to turn those strings into a model instance —\n   * core deliberately never maps a name to a provider.\n   */\n  resolveModel?: (request: LlmRouteRequest) => LanguageModel | undefined;\n  /** Extra options merged into every call (temperature, headers, …). */\n  callOptions?: Record<string, unknown>;\n};\n\n/**\n * Build the client without registering it — handy for tests, or for a host\n * that wants to wrap it.\n */\nexport function createVercelAiLlmClient(options: VercelAiOptions): LlmClient {\n  return {\n    async chooseRoute(request) {\n      const model = options.resolveModel?.(request) ?? options.model;\n\n      // Constrain the model to the declared ports instead of parsing prose.\n      // A choice that can only BE one of the ports is the difference between a\n      // routing decision and a guess, and it means the \"hallucinated port\"\n      // guard in the node is a backstop rather than the primary defence.\n      const result = await generateText({\n        model,\n        system: request.system,\n        prompt: buildPrompt(request),\n        output: Output.choice({\n          options: request.routes.map((r) => r.port),\n          name: \"route\",\n          description: \"The single route this input should follow.\",\n        }),\n        ...(options.callOptions ?? {}),\n      } as never);\n\n      const port = String((result as { output?: unknown }).output ?? \"\");\n      return {\n        port,\n        // The SDK returns the choice, not an explanation. Say where the answer\n        // came from rather than inventing a rationale the model never gave.\n        reason: `chosen by ${describeModel(model)}`,\n      };\n    },\n  };\n}\n\n/** Build the client and install it. Returns an unregister function. */\nexport function useVercelAiForLlmBranch(options: VercelAiOptions): () => void {\n  return registerLlmClient(createVercelAiLlmClient(options));\n}\n\n/**\n * Fold the route descriptions into the prompt.\n *\n * The port ids alone are often terse (`billing`, `support`); the descriptions\n * are what the author wrote to distinguish them, so a model that never sees\n * them is choosing on the strength of a label.\n */\nexport function buildPrompt(request: LlmRouteRequest): string {\n  const described = request.routes.filter((r) => r.description);\n  if (described.length === 0) return request.prompt;\n\n  const lines = described.map((r) => `- ${r.port}: ${r.description}`).join(\"\\n\");\n  return `${request.prompt}\\n\\nRoutes:\\n${lines}`;\n}\n\nfunction describeModel(model: LanguageModel): string {\n  if (typeof model === \"string\") return model;\n  const id = (model as { modelId?: string }).modelId;\n  return id ?? \"the configured model\";\n}\n"]}

package/dist/registry/index.d.cts

@@ -1,6 +1,8 @@
-import { a as NodeKindDefinition, P as PortSpec } from '../types-DnQ4TEHN.cjs';
-export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-DnQ4TEHN.cjs';
-import { F as FlowNode, P as PortDescriptor, a as FlowGraph, N as NodeExecutor } from '../types-Dg2REAz5.cjs';
+import { a as NodeKindDefinition, P as PortSpec } from '../types-H60tQAxr.cjs';
+export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-H60tQAxr.cjs';
+import { a as FlowNode, P as PortDescriptor, N as NodeExecutor } from '../types-fc0fFKkf.cjs';
+import { b as LlmRoute } from '../capabilities-D-V9Rxv1.cjs';
+export { C as CapabilityId, a as LlmClient, c as LlmRouteChoice, L as LlmRouteRequest, W as WorkflowResolver, d as capabilityStatus, g as getLlmClient, e as getWorkflowResolver, r as registerLlmClient, f as registerWorkflowResolver } from '../capabilities-D-V9Rxv1.cjs';
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import { NodeProps, NodeTypes } from '@xyflow/react';
@@ -44,80 +46,6 @@ declare function resolveNodePorts(node: Pick<FlowNode, "data">, kind?: Pick<Node
     outputs?: PortDescriptor[];
 };
 
-/**
- * Host capabilities — the services core nodes need but must never depend on.
- *
- * A node that imports a provider SDK forces every consumer to install it: a
- * workflow app that never calls a model should not inherit an LLM dependency.
- * So core declares the CONTRACT and the host supplies the implementation, the
- * same arrangement `renderDocumentField` already uses for documents.
- *
- * That keeps opinionated nodes in core without their opinions: `llm_branch`
- * ships the routing semantics, port derivation and config UI, while whichever
- * client the host registers — Prism, an OpenAI SDK, a local model, a fake in a
- * test — decides how the question actually gets asked.
- *
- * Registration is deliberately explicit and typed per capability rather than a
- * stringly-keyed bag, so a missing one is a clear error at the seam instead of
- * an undefined somewhere downstream.
- */
-type LlmRoute = {
-    port: string;
-    description?: string;
-};
-type LlmRouteRequest = {
-    /** Optional framing for the decision. */
-    system?: string;
-    /** What the model is deciding about. */
-    prompt: string;
-    /** The ports it must choose between. */
-    routes: LlmRoute[];
-    provider?: string;
-    model?: string;
-    /** Host-resolved credential reference, never a raw key. */
-    credential?: string;
-};
-type LlmRouteChoice = {
-    /** Must be one of the requested route ports. */
-    port: string;
-    /** Why — carried down the chosen port so a run is explainable afterwards. */
-    reason?: string;
-};
-/**
- * The only thing core asks of an LLM: given routes, pick one.
- *
- * Deliberately not a general chat interface. A narrow contract is one a host
- * can satisfy in a few lines over any SDK, and it keeps the choice
- * machine-checkable — an implementation should constrain the model to the
- * declared ports (structured output / enum) rather than parsing prose.
- */
-type LlmClient = {
-    chooseRoute: (request: LlmRouteRequest) => Promise<LlmRouteChoice> | LlmRouteChoice;
-};
-/** Install the host's LLM client. Returns an unregister function. */
-declare function registerLlmClient(client: LlmClient): () => void;
-declare function getLlmClient(): LlmClient | null;
-/**
- * Resolve a workflow reference to a runnable graph.
- *
- * `subflow` names another workflow rather than embedding it, so the host owns
- * where workflows live — a database, a file, an API. Returning null means "no
- * such workflow", which the node reports as an error rather than silently
- * running nothing.
- */
-type WorkflowResolver = (ref: string) => Promise<FlowGraph | null> | FlowGraph | null;
-/** Install the host's workflow resolver. Returns an unregister function. */
-declare function registerWorkflowResolver(resolver: WorkflowResolver): () => void;
-declare function getWorkflowResolver(): WorkflowResolver | null;
-type CapabilityId = "llm" | "workflow_resolver" | "document";
-/**
- * Which capabilities are currently satisfied.
- *
- * Exists so a host (or the CLI, or an agent over MCP) can answer "what does
- * this graph need that I haven't wired?" BEFORE a run fails halfway through.
- */
-declare function capabilityStatus(): Record<CapabilityId, boolean>;
-
 /**
  * `@fancy/subflow` — run another workflow and bring its result home.
  *
@@ -170,7 +98,7 @@ declare function declaredRoutes(config: Record<string, unknown>): LlmRoute[];
  * route, and always loudly.
  */
 declare function resolveFallbackPort(routes: LlmRoute[], fallbackEnabled: boolean): string;
-declare const llmBranchExecutor: NodeExecutor;
+declare const llmRouterExecutor: NodeExecutor;
 
 /**
  * Rich user input — the injection point.
@@ -302,4 +230,4 @@ declare const BUILTIN_KINDS: NodeKindDefinition[];
  */
 declare function buildNodeTypes(): NodeTypes;
 
-export { BUILTIN_KINDS, type CapabilityId, DEFAULT_MAX_DEPTH, type LlmClient, type LlmRoute, type LlmRouteChoice, type LlmRouteRequest, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, type SubflowMode, type WorkflowResolver, buildNodeTypes, capabilityStatus, categoryAccent, declaredRoutes, defaultConfigFor, getLlmClient, getNodeKind, getRichInputAdapter, getWorkflowResolver, isRichInputEnabled, kindIds, listNodeKinds, llmBranchExecutor, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerLlmClient, registerNodeKind, registerRichInputAdapter, registerWorkflowResolver, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePortSpec, subflowExecutor, subflowMode, subflowPorts, validateConfig };
+export { BUILTIN_KINDS, DEFAULT_MAX_DEPTH, LlmRoute, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, type SubflowMode, buildNodeTypes, categoryAccent, declaredRoutes, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, kindIds, listNodeKinds, llmRouterExecutor as llmBranchExecutor, llmRouterExecutor, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePortSpec, subflowExecutor, subflowMode, subflowPorts, validateConfig };

package/dist/registry/index.d.ts

@@ -1,6 +1,8 @@
-import { a as NodeKindDefinition, P as PortSpec } from '../types-DtXOwXjA.js';
-export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-DtXOwXjA.js';
-import { F as FlowNode, P as PortDescriptor, a as FlowGraph, N as NodeExecutor } from '../types-Dg2REAz5.js';
+import { a as NodeKindDefinition, P as PortSpec } from '../types-CnnKPnpt.js';
+export { C as ConfigField, b as CredentialConfigField, D as DocumentConfigField, E as ExpressionConfigField, J as JsonConfigField, K as KeyValueConfigField, N as NodeCategory, c as NumberConfigField, R as RenderBodyContext, d as RepeaterConfigField, e as RepeaterRowField, S as SelectConfigField, f as SwitchConfigField, T as TextConfigField, g as TextareaConfigField } from '../types-CnnKPnpt.js';
+import { a as FlowNode, P as PortDescriptor, N as NodeExecutor } from '../types-fc0fFKkf.js';
+import { b as LlmRoute } from '../capabilities-B6r1Snfj.js';
+export { C as CapabilityId, a as LlmClient, c as LlmRouteChoice, L as LlmRouteRequest, W as WorkflowResolver, d as capabilityStatus, g as getLlmClient, e as getWorkflowResolver, r as registerLlmClient, f as registerWorkflowResolver } from '../capabilities-B6r1Snfj.js';
 import * as react from 'react';
 import { ComponentType, ReactNode } from 'react';
 import { NodeProps, NodeTypes } from '@xyflow/react';
@@ -44,80 +46,6 @@ declare function resolveNodePorts(node: Pick<FlowNode, "data">, kind?: Pick<Node
     outputs?: PortDescriptor[];
 };
 
-/**
- * Host capabilities — the services core nodes need but must never depend on.
- *
- * A node that imports a provider SDK forces every consumer to install it: a
- * workflow app that never calls a model should not inherit an LLM dependency.
- * So core declares the CONTRACT and the host supplies the implementation, the
- * same arrangement `renderDocumentField` already uses for documents.
- *
- * That keeps opinionated nodes in core without their opinions: `llm_branch`
- * ships the routing semantics, port derivation and config UI, while whichever
- * client the host registers — Prism, an OpenAI SDK, a local model, a fake in a
- * test — decides how the question actually gets asked.
- *
- * Registration is deliberately explicit and typed per capability rather than a
- * stringly-keyed bag, so a missing one is a clear error at the seam instead of
- * an undefined somewhere downstream.
- */
-type LlmRoute = {
-    port: string;
-    description?: string;
-};
-type LlmRouteRequest = {
-    /** Optional framing for the decision. */
-    system?: string;
-    /** What the model is deciding about. */
-    prompt: string;
-    /** The ports it must choose between. */
-    routes: LlmRoute[];
-    provider?: string;
-    model?: string;
-    /** Host-resolved credential reference, never a raw key. */
-    credential?: string;
-};
-type LlmRouteChoice = {
-    /** Must be one of the requested route ports. */
-    port: string;
-    /** Why — carried down the chosen port so a run is explainable afterwards. */
-    reason?: string;
-};
-/**
- * The only thing core asks of an LLM: given routes, pick one.
- *
- * Deliberately not a general chat interface. A narrow contract is one a host
- * can satisfy in a few lines over any SDK, and it keeps the choice
- * machine-checkable — an implementation should constrain the model to the
- * declared ports (structured output / enum) rather than parsing prose.
- */
-type LlmClient = {
-    chooseRoute: (request: LlmRouteRequest) => Promise<LlmRouteChoice> | LlmRouteChoice;
-};
-/** Install the host's LLM client. Returns an unregister function. */
-declare function registerLlmClient(client: LlmClient): () => void;
-declare function getLlmClient(): LlmClient | null;
-/**
- * Resolve a workflow reference to a runnable graph.
- *
- * `subflow` names another workflow rather than embedding it, so the host owns
- * where workflows live — a database, a file, an API. Returning null means "no
- * such workflow", which the node reports as an error rather than silently
- * running nothing.
- */
-type WorkflowResolver = (ref: string) => Promise<FlowGraph | null> | FlowGraph | null;
-/** Install the host's workflow resolver. Returns an unregister function. */
-declare function registerWorkflowResolver(resolver: WorkflowResolver): () => void;
-declare function getWorkflowResolver(): WorkflowResolver | null;
-type CapabilityId = "llm" | "workflow_resolver" | "document";
-/**
- * Which capabilities are currently satisfied.
- *
- * Exists so a host (or the CLI, or an agent over MCP) can answer "what does
- * this graph need that I haven't wired?" BEFORE a run fails halfway through.
- */
-declare function capabilityStatus(): Record<CapabilityId, boolean>;
-
 /**
  * `@fancy/subflow` — run another workflow and bring its result home.
  *
@@ -170,7 +98,7 @@ declare function declaredRoutes(config: Record<string, unknown>): LlmRoute[];
  * route, and always loudly.
  */
 declare function resolveFallbackPort(routes: LlmRoute[], fallbackEnabled: boolean): string;
-declare const llmBranchExecutor: NodeExecutor;
+declare const llmRouterExecutor: NodeExecutor;
 
 /**
  * Rich user input — the injection point.
@@ -302,4 +230,4 @@ declare const BUILTIN_KINDS: NodeKindDefinition[];
  */
 declare function buildNodeTypes(): NodeTypes;
 
-export { BUILTIN_KINDS, type CapabilityId, DEFAULT_MAX_DEPTH, type LlmClient, type LlmRoute, type LlmRouteChoice, type LlmRouteRequest, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, type SubflowMode, type WorkflowResolver, buildNodeTypes, capabilityStatus, categoryAccent, declaredRoutes, defaultConfigFor, getLlmClient, getNodeKind, getRichInputAdapter, getWorkflowResolver, isRichInputEnabled, kindIds, listNodeKinds, llmBranchExecutor, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerLlmClient, registerNodeKind, registerRichInputAdapter, registerWorkflowResolver, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePortSpec, subflowExecutor, subflowMode, subflowPorts, validateConfig };
+export { BUILTIN_KINDS, DEFAULT_MAX_DEPTH, LlmRoute, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, type SubflowMode, buildNodeTypes, categoryAccent, declaredRoutes, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, kindIds, listNodeKinds, llmRouterExecutor as llmBranchExecutor, llmRouterExecutor, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePortSpec, subflowExecutor, subflowMode, subflowPorts, validateConfig };