@particle-academy/fancy-flow 0.11.0 → 0.13.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-BwLr5tZV.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-BwLr5tZV.cjs';
-import { F as FlowNode, P as PortDescriptor } from '../types-BS3Gwnkq.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,6 +46,60 @@ declare function resolveNodePorts(node: Pick<FlowNode, "data">, kind?: Pick<Node
     outputs?: PortDescriptor[];
 };
 
+/**
+ * `@fancy/subflow` — run another workflow and bring its result home.
+ *
+ * Core, not marketplace: it introduces no third-party dependency. It runs a
+ * child graph through the very same engine, so the only thing it needs from the
+ * host is where workflows live (`registerWorkflowResolver`).
+ *
+ * Three output modes, because both halves are genuinely useful:
+ *
+ *   - `output` — the child's outputs arrive on `out` when it finishes.
+ *   - `stream` — the child's events are forwarded live on `stream` as they
+ *     happen, so a parent can show progress instead of a spinner.
+ *   - `both`   — stream while running AND deliver the final outputs.
+ *
+ * Recursion is guarded by depth. A workflow that references itself (directly or
+ * through a chain) would otherwise recurse until the stack dies, which surfaces
+ * as an opaque crash rather than "you built a loop".
+ */
+declare const DEFAULT_MAX_DEPTH = 8;
+type SubflowMode = "output" | "stream" | "both";
+declare function subflowMode(config: Record<string, unknown>): SubflowMode;
+/** Ports follow the mode — `stream` only exists when something streams. */
+declare function subflowPorts(config: Record<string, unknown>): {
+    id: string;
+    label: string;
+}[];
+declare const subflowExecutor: NodeExecutor;
+
+/**
+ * `@fancy/llm_branch` — a SHUTTLE, not an engine.
+ *
+ * It carries the declared routes and the decision prompt out to whatever LLM
+ * client the host registered, and carries the chosen port back down the graph.
+ * It contains no provider SDK, no prompt engineering, no response parsing and
+ * no retry policy — all of that belongs to the host's client, which is what
+ * lets this node live in core without every consumer inheriting an LLM
+ * dependency.
+ *
+ * The one thing it does own is graph integrity, because that is a workflow
+ * concern rather than an AI one: a port the model invents must never route.
+ */
+/** Read the node's declared routes out of config. */
+declare function declaredRoutes(config: Record<string, unknown>): LlmRoute[];
+/**
+ * Where a run goes when the model returns a port that was never offered.
+ *
+ * Emitting on a port with no edge silently ends the branch — the worst failure
+ * mode in a workflow engine, because the run reports success having done
+ * nothing. So: the `fallback` port when it exists, else the first declared
+ * route, and always loudly.
+ */
+declare function resolveFallbackPort(routes: LlmRoute[], fallbackEnabled: boolean): string;
+declare const llmBranchExecutor: NodeExecutor;
+
 /**
  * Rich user input — the injection point.
  *
@@ -174,4 +230,4 @@ declare const BUILTIN_KINDS: NodeKindDefinition[];
  */
 declare function buildNodeTypes(): NodeTypes;
 
-export { BUILTIN_KINDS, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, kindIds, listNodeKinds, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveKindId, resolveNodePorts, resolvePortSpec, 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, llmBranchExecutor, 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-CsEe3EQl.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-CsEe3EQl.js';
-import { F as FlowNode, P as PortDescriptor } from '../types-BS3Gwnkq.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,6 +46,60 @@ declare function resolveNodePorts(node: Pick<FlowNode, "data">, kind?: Pick<Node
     outputs?: PortDescriptor[];
 };
 
+/**
+ * `@fancy/subflow` — run another workflow and bring its result home.
+ *
+ * Core, not marketplace: it introduces no third-party dependency. It runs a
+ * child graph through the very same engine, so the only thing it needs from the
+ * host is where workflows live (`registerWorkflowResolver`).
+ *
+ * Three output modes, because both halves are genuinely useful:
+ *
+ *   - `output` — the child's outputs arrive on `out` when it finishes.
+ *   - `stream` — the child's events are forwarded live on `stream` as they
+ *     happen, so a parent can show progress instead of a spinner.
+ *   - `both`   — stream while running AND deliver the final outputs.
+ *
+ * Recursion is guarded by depth. A workflow that references itself (directly or
+ * through a chain) would otherwise recurse until the stack dies, which surfaces
+ * as an opaque crash rather than "you built a loop".
+ */
+declare const DEFAULT_MAX_DEPTH = 8;
+type SubflowMode = "output" | "stream" | "both";
+declare function subflowMode(config: Record<string, unknown>): SubflowMode;
+/** Ports follow the mode — `stream` only exists when something streams. */
+declare function subflowPorts(config: Record<string, unknown>): {
+    id: string;
+    label: string;
+}[];
+declare const subflowExecutor: NodeExecutor;
+
+/**
+ * `@fancy/llm_branch` — a SHUTTLE, not an engine.
+ *
+ * It carries the declared routes and the decision prompt out to whatever LLM
+ * client the host registered, and carries the chosen port back down the graph.
+ * It contains no provider SDK, no prompt engineering, no response parsing and
+ * no retry policy — all of that belongs to the host's client, which is what
+ * lets this node live in core without every consumer inheriting an LLM
+ * dependency.
+ *
+ * The one thing it does own is graph integrity, because that is a workflow
+ * concern rather than an AI one: a port the model invents must never route.
+ */
+/** Read the node's declared routes out of config. */
+declare function declaredRoutes(config: Record<string, unknown>): LlmRoute[];
+/**
+ * Where a run goes when the model returns a port that was never offered.
+ *
+ * Emitting on a port with no edge silently ends the branch — the worst failure
+ * mode in a workflow engine, because the run reports success having done
+ * nothing. So: the `fallback` port when it exists, else the first declared
+ * route, and always loudly.
+ */
+declare function resolveFallbackPort(routes: LlmRoute[], fallbackEnabled: boolean): string;
+declare const llmBranchExecutor: NodeExecutor;
+
 /**
  * Rich user input — the injection point.
  *
@@ -174,4 +230,4 @@ declare const BUILTIN_KINDS: NodeKindDefinition[];
  */
 declare function buildNodeTypes(): NodeTypes;
 
-export { BUILTIN_KINDS, NodeKindDefinition, PortSpec, RegistryNode, type RichInputAdapter, RichInputPreview, buildNodeTypes, categoryAccent, defaultConfigFor, getNodeKind, getRichInputAdapter, isRichInputEnabled, kindIds, listNodeKinds, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveKindId, resolveNodePorts, resolvePortSpec, 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, llmBranchExecutor, nodeConfig, onNodeKindsChanged, onRichInputAdapterChanged, registerBuiltinKinds, registerNodeKind, registerRichInputAdapter, resolveFallbackPort, resolveKindId, resolveNodePorts, resolvePortSpec, subflowExecutor, subflowMode, subflowPorts, validateConfig };