@particle-academy/fancy-flow 0.12.0 → 0.14.0

package/dist/capabilities-B6r1Snfj.d.ts

@@ -0,0 +1,77 @@
+import { F as FlowGraph } from './types-fc0fFKkf.js';
+
+/**
+ * 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>;
+
+export { type CapabilityId as C, type LlmRouteRequest as L, type WorkflowResolver as W, type LlmClient as a, type LlmRoute as b, type LlmRouteChoice as c, capabilityStatus as d, getWorkflowResolver as e, registerWorkflowResolver as f, getLlmClient as g, registerLlmClient as r };

package/dist/capabilities-D-V9Rxv1.d.cts

@@ -0,0 +1,77 @@
+import { F as FlowGraph } from './types-fc0fFKkf.cjs';
+
+/**
+ * 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>;
+
+export { type CapabilityId as C, type LlmRouteRequest as L, type WorkflowResolver as W, type LlmClient as a, type LlmRoute as b, type LlmRouteChoice as c, capabilityStatus as d, getWorkflowResolver as e, registerWorkflowResolver as f, getLlmClient as g, registerLlmClient as r };

package/dist/{chunk-IK5DS5JP.js → chunk-7U3EP4Q5.js}

@@ -3,44 +3,10 @@ import { runFlow } from './chunk-L4AX73Q6.js';
 import { resolveNodePorts, nodeConfig } from './chunk-TITD5W4Y.js';
 import { getNodeKind, categoryAccent, registerNodeKind, listNodeKinds, kindIds } from './chunk-U5F22BHV.js';
 import { RichInputPreview } from './chunk-F5RPRB7A.js';
+import { getWorkflowResolver, getLlmClient } from './chunk-BB45F6S3.js';
 import { memo, useMemo, createElement } from 'react';
 import { jsxs, jsx } from 'react/jsx-runtime';
 
-// src/registry/capabilities.ts
-var llmClient = null;
-function registerLlmClient(client) {
-  llmClient = client;
-  return () => {
-    if (llmClient === client) llmClient = null;
-  };
-}
-function getLlmClient() {
-  return llmClient;
-}
-var workflowResolver = null;
-function registerWorkflowResolver(resolver) {
-  workflowResolver = resolver;
-  return () => {
-    if (workflowResolver === resolver) workflowResolver = null;
-  };
-}
-function getWorkflowResolver() {
-  return workflowResolver;
-}
-function capabilityStatus() {
-  let documentReady = false;
-  try {
-    documentReady = Boolean(globalThis.__fancyFlowDocumentAdapter);
-  } catch {
-    documentReady = false;
-  }
-  return {
-    llm: llmClient !== null,
-    workflow_resolver: workflowResolver !== null,
-    document: documentReady
-  };
-}
-
 // src/registry/subflow.ts
 var DEFAULT_MAX_DEPTH = 8;
 function subflowMode(config) {
@@ -110,7 +76,7 @@ var subflowExecutor = async (ctx) => {
   return { __port: "out", value: result.outputs };
 };
 
-// src/registry/llm-branch.ts
+// src/registry/llm-router.ts
 function declaredRoutes(config) {
   const raw = config.routes;
   if (!Array.isArray(raw)) return [];
@@ -120,11 +86,11 @@ function resolveFallbackPort(routes, fallbackEnabled) {
   if (fallbackEnabled) return "fallback";
   return routes[0]?.port ?? "out";
 }
-var llmBranchExecutor = async (ctx) => {
+var llmRouterExecutor = async (ctx) => {
   const config = ctx.node.data?.config ?? {};
   const routes = declaredRoutes(config);
   if (routes.length === 0) {
-    ctx.abort("llm_branch has no routes configured");
+    ctx.abort("llm_router has no routes configured");
   }
   const client = getLlmClient();
   if (!client) {
@@ -150,7 +116,7 @@ var llmBranchExecutor = async (ctx) => {
       type: "log",
       nodeId: ctx.node.id,
       level: "warn",
-      message: `llm_branch: model returned "${port || "(nothing)"}", which is not a declared route. Routing to "${safe}".`
+      message: `llm_router: model returned "${port || "(nothing)"}", which is not a declared route. Routing to "${safe}".`
     });
     reason = reason ?? `unrecognised route "${port}"`;
     port = safe;
@@ -464,10 +430,13 @@ var KINDS = [
         description: "Streaming adds a second port so a parent can show progress instead of a spinner."
       },
       {
-        type: "json",
+        type: "keyvalue",
         key: "inputs",
         label: "Input mapping",
-        description: "Entry-point inputs for the child run. Omit to pass this node's inputs straight through."
+        description: "Values handed to the child's entry points. Omit to pass this node's inputs straight through.",
+        keyLabel: "Name",
+        valueLabel: "Value",
+        addLabel: "Add input"
       },
       {
         type: "number",
@@ -491,7 +460,57 @@ var KINDS = [
     inputs: [{ id: "in" }],
     outputs: [{ id: "true", label: "true" }, { id: "false", label: "false" }],
     configSchema: [
-      { type: "expression", key: "condition", label: "Condition", example: "{{ $json.active }}", required: true }
+      {
+        type: "select",
+        key: "match",
+        label: "Match",
+        default: "all",
+        options: [
+          { value: "all", label: "All conditions (AND)" },
+          { value: "any", label: "Any condition (OR)" }
+        ]
+      },
+      {
+        type: "repeater",
+        key: "conditions",
+        label: "Conditions",
+        description: "Routes to `true` when these match, otherwise `false`.",
+        titleKey: "left",
+        addLabel: "Add condition",
+        minItems: 1,
+        fields: [
+          { type: "expression", key: "left", label: "Value", example: "{{ $json.status }}", required: true },
+          {
+            type: "select",
+            key: "operator",
+            label: "Is",
+            default: "eq",
+            options: [
+              { value: "eq", label: "equal to" },
+              { value: "neq", label: "not equal to" },
+              { value: "contains", label: "contains" },
+              { value: "not_contains", label: "does not contain" },
+              { value: "gt", label: "greater than" },
+              { value: "gte", label: "greater than or equal to" },
+              { value: "lt", label: "less than" },
+              { value: "lte", label: "less than or equal to" },
+              { value: "truthy", label: "true" },
+              { value: "falsy", label: "false" },
+              { value: "empty", label: "empty" },
+              { value: "not_empty", label: "not empty" }
+            ]
+          },
+          { type: "text", key: "right", label: "Compared to", placeholder: "active" }
+        ],
+        default: [{ left: "", operator: "eq", right: "" }]
+      },
+      {
+        type: "expression",
+        key: "condition",
+        label: "Raw expression (advanced)",
+        example: "{{ $json.active && $json.score > 10 }}",
+        description: "Escape hatch for logic the builder can't express. Overrides the conditions above when set."
+      }
     ]
   },
   {
@@ -581,12 +600,35 @@ var KINDS = [
     description: "Reshape data with an expression.",
     icon: "\u0192",
     configSchema: [
+      {
+        type: "select",
+        key: "mode",
+        label: "Build the output",
+        default: "fields",
+        options: [
+          { value: "fields", label: "Field by field" },
+          { value: "expression", label: "One expression" }
+        ]
+      },
+      {
+        type: "repeater",
+        key: "fields",
+        label: "Output fields",
+        description: "Each row becomes a key on the result.",
+        titleKey: "key",
+        addLabel: "Add field",
+        fields: [
+          { type: "text", key: "key", label: "Key", required: true, placeholder: "name" },
+          { type: "expression", key: "value", label: "Value", example: "{{ $json.first }}", required: true }
+        ],
+        default: [{ key: "", value: "" }]
+      },
       {
         type: "expression",
         key: "expression",
-        label: "Expression",
+        label: "Expression (advanced)",
         example: "{{ { id: $json.id, name: $json.first + ' ' + $json.last } }}",
-        required: true
+        description: "Used when the mode above is set to one expression."
       }
     ]
   },
@@ -636,7 +678,15 @@ var KINDS = [
       },
       { type: "text", key: "table", label: "Table / collection", required: true },
       { type: "text", key: "key", label: "Key" },
-      { type: "json", key: "where", label: "Where (JSON)", description: "For query/list operations." },
+      {
+        type: "keyvalue",
+        key: "where",
+        label: "Where",
+        description: "Field/value pairs to match. For query and list operations.",
+        keyLabel: "Field",
+        valueLabel: "Equals",
+        addLabel: "Add filter"
+      },
       { type: "expression", key: "value", label: "Value (set only)", example: "{{ $json }}" },
       { type: "credential", key: "store", label: "Data store", credentialType: "data_store" }
     ]
@@ -678,13 +728,32 @@ var KINDS = [
       { type: "expression", key: "prompt", label: "User prompt", example: "{{ $json.question }}", required: true },
       { type: "number", key: "temperature", label: "Temperature", min: 0, max: 2, step: 0.1, default: 0.7 },
       { type: "number", key: "max_tokens", label: "Max tokens", min: 1, max: 8192, default: 1024 },
-      { type: "json", key: "tools", label: "Tools (JSON)", description: "Optional Anthropic-style tool definitions." },
+      {
+        type: "repeater",
+        key: "tools",
+        label: "Tools",
+        description: "Tools the model may call.",
+        titleKey: "name",
+        addLabel: "Add tool",
+        fields: [
+          { type: "text", key: "name", label: "Name", required: true, placeholder: "search_index" },
+          { type: "text", key: "description", label: "When to use it" },
+          {
+            type: "json",
+            key: "input_schema",
+            label: "Input schema",
+            description: "JSON Schema for the tool's arguments."
+          }
+        ]
+      },
       { type: "credential", key: "credential", label: "API credential", credentialType: "llm_credential" }
     ]
   },
   {
-    name: "@particle-academy/llm_branch",
-    aliases: ["llm_branch", "@fancy/llm_branch"],
+    name: "@particle-academy/llm_router",
+    // Every id this node has ever shipped under keeps resolving — MOIC's saved
+    // flows carry the bare `llm_branch`.
+    aliases: ["llm_router", "llm_branch", "@fancy/llm_branch", "@fancy/llm_router"],
     category: "ai",
     label: "LLM Router",
     description: "Let a model choose which route the flow takes.",
@@ -696,7 +765,7 @@ var KINDS = [
     // A shuttle, not an engine: it carries the routes out to whatever LLM
     // client the host registered and carries the choice back. No provider SDK
     // reaches core, so this stays a builtin without adding a dependency.
-    executor: llmBranchExecutor,
+    executor: llmRouterExecutor,
     configSchema: [
       {
         type: "textarea",
@@ -793,7 +862,17 @@ var KINDS = [
     configSchema: [
       ...HTTP_METHODS,
       { type: "text", key: "url", label: "URL", placeholder: "https://api.example.com/...", required: true },
-      { type: "json", key: "headers", label: "Headers", default: { "content-type": "application/json" } },
+      {
+        type: "keyvalue",
+        key: "headers",
+        label: "Headers",
+        keyLabel: "Header",
+        valueLabel: "Value",
+        keyPlaceholder: "content-type",
+        valuePlaceholder: "application/json",
+        addLabel: "Add header",
+        default: { "content-type": "application/json" }
+      },
       { type: "json", key: "body", label: "Body" },
       { type: "credential", key: "auth", label: "Auth", credentialType: "api_credential" }
     ]
@@ -807,7 +886,14 @@ var KINDS = [
     icon: "\u2197",
     configSchema: [
       { type: "text", key: "url", label: "URL", required: true },
-      { type: "json", key: "headers", label: "Headers" },
+      {
+        type: "keyvalue",
+        key: "headers",
+        label: "Headers",
+        keyLabel: "Header",
+        valueLabel: "Value",
+        addLabel: "Add header"
+      },
       { type: "expression", key: "payload", label: "Payload", required: true, example: "{{ $json }}" }
     ]
   },
@@ -897,6 +983,6 @@ function buildNodeTypes() {
   return map;
 }
 
-export { BUILTIN_KINDS, DEFAULT_MAX_DEPTH, RegistryNode, buildNodeTypes, capabilityStatus, declaredRoutes, getLlmClient, getWorkflowResolver, llmBranchExecutor, registerBuiltinKinds, registerLlmClient, registerWorkflowResolver, resolveFallbackPort, subflowExecutor, subflowMode, subflowPorts };
-//# sourceMappingURL=chunk-IK5DS5JP.js.map
-//# sourceMappingURL=chunk-IK5DS5JP.js.map
+export { BUILTIN_KINDS, DEFAULT_MAX_DEPTH, RegistryNode, buildNodeTypes, declaredRoutes, llmRouterExecutor, registerBuiltinKinds, resolveFallbackPort, subflowExecutor, subflowMode, subflowPorts };
+//# sourceMappingURL=chunk-7U3EP4Q5.js.map
+//# sourceMappingURL=chunk-7U3EP4Q5.js.map