@doclo/flows 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -45,10 +45,27 @@ type BatchFlowResult = {
 /**
  * Type representing the built flow object returned by Flow.build()
  */
+/**
+ * Options for running a built flow
+ */
+interface FlowRunOptions {
+    /** Progress callbacks for step execution */
+    callbacks?: FlowProgressCallbacks;
+    /** Initial artifacts to merge into the flow context (for forEach child flows) */
+    initialArtifacts?: Record<string, any>;
+}
 type BuiltFlow<TInput = any, TOutput = any> = {
-    run: (input: TInput, callbacks?: FlowProgressCallbacks) => Promise<FlowResult<TOutput> | BatchFlowResult>;
+    run: (input: TInput, callbacksOrOptions?: FlowProgressCallbacks | FlowRunOptions) => Promise<FlowResult<TOutput> | BatchFlowResult>;
     validate: () => FlowValidationResult;
 };
+/**
+ * Type guard to check if a flow result is a single result (not batch)
+ */
+declare function isSingleFlowResult<T>(result: FlowResult<T> | BatchFlowResult): result is FlowResult<T>;
+/**
+ * Type guard to check if a flow result is a batch result
+ */
+declare function isBatchFlowResult(result: FlowResult<unknown> | BatchFlowResult): result is BatchFlowResult;
 /**
  * Type helper to extract the unwrapped input type from a wrapped type.
  * If T has an 'input' property, returns the type of that property.
@@ -537,6 +554,7 @@ type ParseConfig = {
         strategy?: 'majority' | 'unanimous';
         onTie?: 'random' | 'fail' | 'retry';
     };
+    maxTokens?: number;
 };
 type ExtractConfig = {
     type: 'extract';
@@ -552,6 +570,7 @@ type ExtractConfig = {
         effort?: 'low' | 'medium' | 'high';
         max_tokens?: number;
     };
+    maxTokens?: number;
 };
 type SplitConfig = {
     type: 'split';
@@ -564,6 +583,7 @@ type SplitConfig = {
         onTie?: 'random' | 'fail' | 'retry';
     };
     schemaRef?: string;
+    maxTokens?: number;
 };
 type CategorizeConfig = {
     type: 'categorize';
@@ -575,6 +595,7 @@ type CategorizeConfig = {
         onTie?: 'random' | 'fail' | 'retry';
     };
     promptRef?: string;
+    maxTokens?: number;
 };
 type TriggerConfig = {
     type: 'trigger';
@@ -929,4 +950,4 @@ declare function buildTwoProviderFlow(opts: {
     }>;
 };
 
-export { type BuiltFlow, type CategorizeConfig, type ConditionalCompositeConfig, type ExtractConfig, FLOW_REGISTRY, type FieldMapping, type FlowBuilder, type FlowOptions, type FlowProgressCallbacks, type FlowReference, type FlowRegistry$1 as FlowRegistry, FlowSerializationError, type FlowValidationResult, type ForEachCompositeConfig, type InputMappingConfig, type NodeConfig, type OutputConfig, type ParseConfig, type ProviderRegistry, type SerializableConditionalStep, type SerializableFlow, type SerializableForEachStep, type SerializableInputValidation, type SerializableStandardStep, type SerializableStep, type SplitConfig, type TriggerConfig, type ValidationError, type ValidationOptions, type ValidationResult, type ValidationWarning, buildFlowFromConfig, buildMultiProviderFlow, buildTwoProviderFlow, buildVLMDirectFlow, clearRegistry, createConditionalCompositeNode, createFlow, createForEachCompositeNode, defineFlowConfig, extractNodeMetadata, getFlow, getFlowCount, hasFlow, isFlowReference, listFlows, registerFlow, resolveFlowReference, unregisterFlow, validateFlow, validateFlowOrThrow };
+export { type BatchFlowResult, type BuiltFlow, type CategorizeConfig, type ConditionalCompositeConfig, type ExtractConfig, FLOW_REGISTRY, type FieldMapping, type FlowBuilder, type FlowOptions, type FlowProgressCallbacks, type FlowReference, type FlowRegistry$1 as FlowRegistry, type FlowRunOptions, FlowSerializationError, type FlowValidationResult, type ForEachCompositeConfig, type InputMappingConfig, type NodeConfig, type OutputConfig, type ParseConfig, type ProviderRegistry, type SerializableConditionalStep, type SerializableFlow, type SerializableForEachStep, type SerializableInputValidation, type SerializableStandardStep, type SerializableStep, type SplitConfig, type TriggerConfig, type ValidationError, type ValidationOptions, type ValidationResult, type ValidationWarning, buildFlowFromConfig, buildMultiProviderFlow, buildTwoProviderFlow, buildVLMDirectFlow, clearRegistry, createConditionalCompositeNode, createFlow, createForEachCompositeNode, defineFlowConfig, extractNodeMetadata, getFlow, getFlowCount, hasFlow, isBatchFlowResult, isFlowReference, isSingleFlowResult, listFlows, registerFlow, resolveFlowReference, unregisterFlow, validateFlow, validateFlowOrThrow };

package/dist/index.js

@@ -32,6 +32,9 @@ import {
 function isSingleFlowResult(result) {
   return "output" in result && "artifacts" in result;
 }
+function isBatchFlowResult(result) {
+  return "results" in result && Array.isArray(result.results);
+}
 function normalizeFlowInput(input) {
   if (input == null) {
     return input;
@@ -257,8 +260,18 @@ var Flow = class {
    */
   build() {
     return {
-      run: async (input, callbacks) => {
-        return this.execute(input, callbacks);
+      run: async (input, callbacksOrOptions) => {
+        let callbacks;
+        let initialArtifacts;
+        if (callbacksOrOptions) {
+          if ("callbacks" in callbacksOrOptions || "initialArtifacts" in callbacksOrOptions) {
+            callbacks = callbacksOrOptions.callbacks;
+            initialArtifacts = callbacksOrOptions.initialArtifacts;
+          } else {
+            callbacks = callbacksOrOptions;
+          }
+        }
+        return this.execute(input, callbacks, initialArtifacts);
       },
       validate: () => {
         return this.validate();
@@ -483,9 +496,9 @@ var Flow = class {
   /**
    * Execute the flow with optional progress callbacks
    */
-  async execute(input, callbacks) {
+  async execute(input, callbacks, initialArtifacts) {
     const flowStartTime = Date.now();
-    const artifacts = {};
+    const artifacts = initialArtifacts ? { ...initialArtifacts } : {};
     const metrics = [];
     const completedSteps = [];
     const outputs = {};
@@ -532,6 +545,7 @@ var Flow = class {
       }
     }
     let currentData = normalizeFlowInput(input);
+    artifacts.__flowInput = currentData;
     if (this.inputValidation?.acceptedFormats?.length) {
       const dataUrl = currentData?.base64 || currentData?.url;
       if (dataUrl) {
@@ -641,7 +655,7 @@ var Flow = class {
               } : {
                 // Always pass stepId for metrics tracking, even without observability
                 stepId: step.id
-              });
+              }, artifacts);
               artifacts[step.id] = result2.output;
               metrics.push(...result2.metrics);
               completedSteps.push(step.id);
@@ -913,7 +927,11 @@ Correct: .conditional('step', () => parse({ provider }))`
                   const childFlow = step.childFlow(item);
                   const builtFlow = childFlow.build();
                   const flowInput = item && typeof item === "object" && "input" in item ? item.input : item;
-                  const result2 = await builtFlow.run(flowInput);
+                  const childInitialArtifacts = {
+                    __originalFlowInput: artifacts.__flowInput
+                    // Original source before split
+                  };
+                  const result2 = await builtFlow.run(flowInput, { initialArtifacts: childInitialArtifacts });
                   let itemResult;
                   if ("results" in result2 && Array.isArray(result2.results)) {
                     const aggregatedMetrics = (result2.results || []).flatMap((r) => r && r.metrics || []);
@@ -1063,20 +1081,26 @@ Correct: .conditional('step', () => parse({ provider }))`
               context: stepErrorContext
             });
           }
-          const completedStepsStr = completedSteps.length > 0 ? `
+          const isNestedFlowError = err instanceof FlowExecutionError;
+          const completedStepsStr = isNestedFlowError ? "" : completedSteps.length > 0 ? `
   Completed steps: ${completedSteps.join(" \u2192 ")}` : "\n  No steps completed before failure";
           const artifactsStr = Object.keys(artifacts).length > 0 ? `
   Partial results available in: ${Object.keys(artifacts).join(", ")}` : "";
+          const allCompleted = isNestedFlowError ? [...err.allCompletedSteps || err.completedSteps, ...completedSteps] : completedSteps;
+          const flowPath = isNestedFlowError && err.flowPath ? [...err.flowPath, { stepId: step.id, stepIndex, stepType: step.type }] : [{ stepId: step.id, stepIndex, stepType: step.type }];
+          const errorMessage = isNestedFlowError ? err.getRootCause().message : err.message;
           throw new FlowExecutionError(
             `Flow execution failed at step "${step.id}" (index ${stepIndex}, type: ${step.type})
-  Error: ${err.message}` + completedStepsStr + artifactsStr,
+  Error: ${errorMessage}` + completedStepsStr + artifactsStr,
             step.id,
             stepIndex,
             step.type,
             completedSteps,
-            err,
-            artifacts
+            isNestedFlowError ? err.originalError : err,
+            artifacts,
             // Include partial artifacts for debugging
+            flowPath,
+            allCompleted
           );
         }
       }
@@ -1218,6 +1242,7 @@ function getFlowCount() {
 import { parse, extract, split as split2, categorize as categorize2, trigger, output } from "@doclo/nodes";
 
 // src/composite-nodes.ts
+import { FlowExecutionError as FlowExecutionError2 } from "@doclo/core";
 import { categorize, split } from "@doclo/nodes";
 function parseProviderName(name) {
   const colonIndex = name.indexOf(":");
@@ -1363,6 +1388,7 @@ function createConditionalCompositeNode(config) {
         return branchResult.output;
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
+        const isNestedFlowError = err instanceof FlowExecutionError2;
         if (ctx?.metrics) {
           ctx.metrics.push({
             step: stepId,
@@ -1382,8 +1408,27 @@ function createConditionalCompositeNode(config) {
             }
           });
         }
-        throw new Error(
-          `Conditional step "${stepId}" failed (${selectedCategory ? `category: ${selectedCategory}, ` : ""}phase: ${phase}): ` + err.message
+        const flowPath = [{
+          stepId,
+          stepIndex: 0,
+          stepType: "conditional",
+          branch: selectedCategory || void 0
+        }];
+        if (isNestedFlowError && err.flowPath) {
+          flowPath.push(...err.flowPath);
+        }
+        const rootCauseMessage = isNestedFlowError ? err.getRootCause().message : err.message;
+        throw new FlowExecutionError2(
+          `Conditional step "${stepId}" failed${selectedCategory ? ` (category: ${selectedCategory})` : ""} in phase: ${phase}
+  Error: ${rootCauseMessage}`,
+          stepId,
+          0,
+          "conditional",
+          [],
+          isNestedFlowError ? err.originalError : err,
+          void 0,
+          flowPath,
+          isNestedFlowError ? err.allCompletedSteps : void 0
         );
       }
     }
@@ -1520,6 +1565,7 @@ function createForEachCompositeNode(config) {
         return results;
       } catch (error) {
         const err = error instanceof Error ? error : new Error(String(error));
+        const isNestedFlowError = err instanceof FlowExecutionError2;
         if (ctx?.metrics) {
           ctx.metrics.push({
             step: stepId,
@@ -1539,8 +1585,26 @@ function createForEachCompositeNode(config) {
             }
           });
         }
-        throw new Error(
-          `ForEach step "${stepId}" failed (${items ? `itemCount: ${items.length}, ` : ""}phase: ${phase}): ` + err.message
+        const flowPath = [{
+          stepId,
+          stepIndex: 0,
+          stepType: "forEach"
+        }];
+        if (isNestedFlowError && err.flowPath) {
+          flowPath.push(...err.flowPath);
+        }
+        const rootCauseMessage = isNestedFlowError ? err.getRootCause().message : err.message;
+        throw new FlowExecutionError2(
+          `ForEach step "${stepId}" failed${items ? ` (itemCount: ${items.length})` : ""} in phase: ${phase}
+  Error: ${rootCauseMessage}`,
+          stepId,
+          0,
+          "forEach",
+          [],
+          isNestedFlowError ? err.originalError : err,
+          void 0,
+          flowPath,
+          isNestedFlowError ? err.allCompletedSteps : void 0
         );
       }
     }
@@ -1743,7 +1807,8 @@ function createNodeFromConfig(nodeType, config, providers, flows) {
       const cfg = config;
       return parse({
         provider,
-        consensus: cfg.consensus
+        consensus: cfg.consensus,
+        maxTokens: cfg.maxTokens
       });
     }
     case "extract": {
@@ -1752,7 +1817,8 @@ function createNodeFromConfig(nodeType, config, providers, flows) {
         provider,
         schema: cfg.schema,
         consensus: cfg.consensus,
-        reasoning: cfg.reasoning
+        reasoning: cfg.reasoning,
+        maxTokens: cfg.maxTokens
       });
     }
     case "split": {
@@ -1761,7 +1827,8 @@ function createNodeFromConfig(nodeType, config, providers, flows) {
         provider,
         schemas: cfg.schemas,
         includeOther: cfg.includeOther,
-        consensus: cfg.consensus
+        consensus: cfg.consensus,
+        maxTokens: cfg.maxTokens
       });
     }
     case "categorize": {
@@ -1769,7 +1836,8 @@ function createNodeFromConfig(nodeType, config, providers, flows) {
       return categorize2({
         provider,
         categories: cfg.categories,
-        consensus: cfg.consensus
+        consensus: cfg.consensus,
+        maxTokens: cfg.maxTokens
       });
     }
     default:
@@ -2519,7 +2587,9 @@ export {
   getFlow,
   getFlowCount,
   hasFlow,
+  isBatchFlowResult,
   isFlowReference,
+  isSingleFlowResult,
   listFlows,
   parse2 as parse,
   registerFlow,