@doclo/flows 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,932 @@
+import * as _doclo_core from '@doclo/core';
+import { FlowInput, FlowInputValidation, AcceptedMimeType, NodeDef, FlowContext, FlowResult, OutputNodeConfig, JSONSchemaNode, VLMProvider, OCRProvider, DocumentIR, LLMJsonProvider } from '@doclo/core';
+export { FlowContext, bufferToBase64, bufferToDataUri } from '@doclo/core';
+export { SimpleOut, simpleSchema } from './schemas.js';
+import { ObservabilityConfig, ExecutionContext, TraceContext } from '@doclo/core/observability';
+export { BatchEndContext, BatchItemContext, BatchItemEndContext, BatchStartContext, CircuitBreakerContext, ConsensusCompleteContext, ConsensusRunContext, ConsensusStartContext, CustomMetric, ExecutionContext, FlowEndContext, FlowErrorContext, FlowStartContext, FlowStats, ObservabilityConfig, ProviderRequestContext, ProviderResponseContext, ProviderRetryContext, StepEndContext, StepErrorContext, StepStartContext, TraceContext } from '@doclo/core/observability';
+import { ProviderRegistry as ProviderRegistry$1 } from '@doclo/nodes';
+export { categorize, chunk, combine, extract, parse, split, trigger } from '@doclo/nodes';
+
+/**
+ * Progress callback options for flow execution
+ */
+interface FlowProgressCallbacks {
+    /** Called when a step starts execution */
+    onStepStart?: (stepId: string, stepIndex: number, stepType: string) => void;
+    /** Called when a step completes successfully */
+    onStepComplete?: (stepId: string, stepIndex: number, stepType: string, durationMs: number) => void;
+    /** Called when a step fails with an error */
+    onStepError?: (stepId: string, stepIndex: number, stepType: string, error: Error) => void;
+}
+/**
+ * Validation error for a flow step
+ */
+interface FlowValidationError {
+    stepId: string;
+    stepIndex: number;
+    stepType: string;
+    message: string;
+}
+/**
+ * Result of flow validation
+ */
+interface FlowValidationResult {
+    valid: boolean;
+    errors: FlowValidationError[];
+    warnings: string[];
+}
+
+/**
+ * Batch result type returned when flow has multiple outputs
+ */
+type BatchFlowResult = {
+    results: FlowResult<any>[];
+};
+/**
+ * Type representing the built flow object returned by Flow.build()
+ */
+type BuiltFlow<TInput = any, TOutput = any> = {
+    run: (input: TInput, callbacks?: FlowProgressCallbacks) => Promise<FlowResult<TOutput> | BatchFlowResult>;
+    validate: () => FlowValidationResult;
+};
+/**
+ * Type helper to extract the unwrapped input type from a wrapped type.
+ * If T has an 'input' property, returns the type of that property.
+ * Otherwise returns T unchanged.
+ *
+ * This matches the runtime behavior where conditionals receive wrapped data
+ * but pass unwrapped data to the selected node.
+ */
+type UnwrapInput<T> = T extends {
+    input: infer I;
+} ? I : T;
+/**
+ * Options for creating a flow
+ */
+interface FlowOptions {
+    /** Observability configuration */
+    observability?: ObservabilityConfig;
+    /** User metadata to include in all observability contexts */
+    metadata?: Record<string, unknown>;
+    /**
+     * Input format validation configuration.
+     * Allows specifying accepted MIME types for early validation
+     * before flow execution begins.
+     */
+    inputValidation?: FlowInputValidation;
+}
+/**
+ * Flow builder class for creating document processing pipelines.
+ * @template TInput - The input type for the flow
+ * @template TOutput - The output type for the flow
+ */
+declare class Flow<TInput = any, TOutput = any> {
+    private steps;
+    private observability?;
+    private metadata?;
+    private inputValidation?;
+    private traceContextManager?;
+    private currentExecution?;
+    constructor(options?: FlowOptions);
+    /**
+     * Set accepted input formats for this flow (fluent API).
+     * Validates input format before flow execution begins.
+     *
+     * @param formats - List of accepted MIME types (e.g., ['application/pdf', 'image/jpeg'])
+     * @returns This flow instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const pdfOnlyFlow = createFlow()
+     *   .acceptFormats(['application/pdf'])
+     *   .step('parse', parse({ provider }))
+     *   .build();
+     *
+     * // Throws FlowInputValidationError if input is not a PDF
+     * await pdfOnlyFlow.run({ base64: jpegBase64 });
+     * ```
+     */
+    acceptFormats(formats: AcceptedMimeType[]): Flow<TInput, TOutput>;
+    /**
+     * Add a sequential step to the flow
+     */
+    step<TStepOutput>(id: string, node: NodeDef<TOutput, TStepOutput>, name?: string): Flow<TInput, TStepOutput>;
+    /**
+     * Add a conditional step that chooses a node based on input data
+     *
+     * IMPORTANT: Conditionals must return a NODE, not a promise or executed flow.
+     * The SDK will execute the returned node for you.
+     *
+     * The condition function receives the full wrapped data (e.g., { input, quality })
+     * but the returned node should accept the unwrapped input (e.g., just FlowInput).
+     * The SDK automatically unwraps the data before passing it to the selected node.
+     *
+     * ✅ CORRECT - Return a node (declarative):
+     * ```typescript
+     * .step('qualify', qualify({ provider, levels: ['low', 'medium', 'high'] }))
+     * .conditional('parse', (data) => {
+     *   // data is { input: FlowInput, quality: string }
+     *   if (data.quality === 'high') {
+     *     return parse({ provider: fastProvider });  // Return the node
+     *   }
+     *   return parse({ provider: accurateProvider }); // Return the node
+     * })
+     * ```
+     *
+     * ❌ INCORRECT - Do NOT return a promise (imperative):
+     * ```typescript
+     * .conditional('parse', (data) => {
+     *   // This will throw an error!
+     *   return createFlow()
+     *     .step('parse', parse({ provider }))
+     *     .build()
+     *     .run(data.input)  // ❌ Don't call .run() here!
+     *     .then(r => r.output);
+     * })
+     * ```
+     *
+     * 🆕 NEW - Access previous step outputs via context:
+     * ```typescript
+     * .step('categorize', categorize({ provider, categories }))
+     * .conditional('parse', (data) => parse({ provider }))
+     * .conditional('extract', (data, context) => {
+     *   // Access category from earlier step via context.artifacts
+     *   const category = context?.artifacts.categorize?.category;
+     *   return extract({ provider, schema: SCHEMAS[category] });
+     * })
+     * ```
+     *
+     * Use the declarative pattern (return nodes) for consistent flow execution,
+     * proper error tracking, and accurate metrics collection.
+     */
+    conditional<TConditionalOutput>(id: string, condition: (data: TOutput, context?: FlowContext) => NodeDef<UnwrapInput<TOutput>, TConditionalOutput>, name?: string): Flow<TInput, TConditionalOutput>;
+    /**
+     * Process each item from previous step (which must return an array) with a child flow
+     * Each item is processed in parallel as its own isolated run
+     */
+    forEach<TItem, TForEachOutput>(id: string, childFlow: (item: TItem) => Flow<TItem, TForEachOutput>, name?: string): Flow<TInput, FlowResult<TForEachOutput>[]>;
+    /**
+     * Add an explicit output node to mark which data to return from the flow
+     *
+     * By default, flows return the output of the last step. Use output nodes to:
+     * - Return data from earlier steps
+     * - Return multiple named outputs
+     * - Transform outputs before returning
+     *
+     * @param config - Output configuration
+     * @returns Flow with output node added
+     *
+     * @example
+     * // Single output
+     * .output({ name: 'invoice_data' })
+     *
+     * // Select specific source
+     * .output({ name: 'result', source: 'step2' })
+     *
+     * // Multiple outputs
+     * .step('extract1', extract({ provider, schema1 }))
+     * .output({ name: 'summary', source: 'extract1' })
+     * .step('extract2', extract({ provider, schema2 }))
+     * .output({ name: 'details', source: 'extract2' })
+     */
+    output<TOutputShape = TOutput>(config?: OutputNodeConfig): Flow<TInput, TOutputShape>;
+    /**
+     * Get current execution context
+     *
+     * Returns null if not currently executing.
+     */
+    getExecutionContext(): ExecutionContext | null;
+    /**
+     * Get current trace context
+     *
+     * Returns null if not currently executing or observability not configured.
+     */
+    getTraceContext(): TraceContext | null;
+    /**
+     * Set a custom attribute on the current execution
+     *
+     * Custom attributes appear in execution context and can be accessed by hooks.
+     */
+    setCustomAttribute(key: string, value: unknown): void;
+    /**
+     * Record a custom metric for the current execution
+     *
+     * Custom metrics appear in execution context and can be accessed by hooks.
+     */
+    recordMetric(name: string, value: number, unit?: string): void;
+    /**
+     * Build and return the executable flow
+     */
+    build(): BuiltFlow<TInput, TOutput>;
+    /**
+     * Generate a unique step ID for unnamed output nodes
+     * Prevents duplicate IDs when multiple .output() calls without names
+     */
+    private generateOutputStepId;
+    /**
+     * Validate the flow configuration
+     */
+    private validate;
+    /**
+     * Validate type compatibility between consecutive steps
+     */
+    private validateTypeCompatibility;
+    /**
+     * Check for inefficient flow patterns and add warnings.
+     *
+     * Detects patterns like:
+     * - parse() → extract(raw-document-provider): The extract provider ignores parse output
+     */
+    private checkEfficiencyPatterns;
+    /**
+     * Extract provider ID from a node definition.
+     * Returns undefined if provider cannot be determined.
+     */
+    private getProviderFromNode;
+    /**
+     * Execute the flow with optional progress callbacks
+     */
+    private execute;
+}
+/**
+ * Create a new flow builder
+ *
+ * @param options - Flow configuration options including observability and metadata
+ * @example
+ * ```typescript
+ * const flow = createFlow({
+ *   observability: {
+ *     onFlowStart: (ctx) => console.log('Flow started:', ctx.flowId),
+ *     onStepEnd: (ctx) => console.log('Step done:', ctx.stepId, ctx.duration),
+ *   },
+ *   metadata: { environment: 'production', userId: 'user_123' }
+ * });
+ * ```
+ */
+declare function createFlow<TInput = FlowInput>(options?: FlowOptions): Flow<TInput, TInput>;
+
+/**
+ * Flow Registry for Serializable Trigger Nodes
+ *
+ * This registry allows flows to be referenced by string IDs in serialized configs.
+ * Used by the config API (serializable version) of trigger nodes.
+ *
+ * ## Usage
+ *
+ * ### Registration
+ * ```typescript
+ * import { registerFlow } from '@doclo/flows';
+ * import { createFlow } from '@doclo/flows';
+ * import { parse, extract } from '@doclo/nodes';
+ *
+ * // Register a flow builder
+ * registerFlow('invoice-processing-v2', (providers) =>
+ *   createFlow()
+ *     .step('parse', parse({ provider: providers.ocr }))
+ *     .step('extract', extract({ provider: providers.vlm, schema: invoiceSchema }))
+ * );
+ * ```
+ *
+ * ### Retrieval
+ * ```typescript
+ * import { getFlow } from '@doclo/flows';
+ *
+ * const flowBuilder = getFlow('invoice-processing-v2');
+ * if (flowBuilder) {
+ *   const flow = flowBuilder(myProviders);
+ *   const result = await flow.build().run(input);
+ * }
+ * ```
+ *
+ * ### Serialization
+ * ```typescript
+ * import { buildFlowFromConfig } from '@doclo/flows';
+ *
+ * const flowDef = {
+ *   version: '1.0.0',
+ *   steps: [
+ *     {
+ *       type: 'step',
+ *       nodeType: 'trigger',
+ *       config: {
+ *         type: 'trigger',
+ *         flowRef: 'invoice-processing-v2'  // References registered flow
+ *       }
+ *     }
+ *   ]
+ * };
+ *
+ * const flow = buildFlowFromConfig(flowDef, { providers, flows: FLOW_REGISTRY });
+ * ```
+ */
+
+/**
+ * Flow builder function signature
+ * Takes optional provider registry and returns a Flow instance with build() method
+ *
+ * A FlowBuilder is a function that:
+ * 1. Accepts an optional ProviderRegistry (for provider injection/override)
+ * 2. Returns a Flow instance (from createFlow()) that has a build() method
+ * 3. The build() method returns a BuiltFlow with run() and validate()
+ */
+type FlowBuilder<TInput = any, TOutput = any> = (providers?: ProviderRegistry$1) => {
+    build: () => BuiltFlow<TInput, TOutput>;
+};
+/**
+ * Global flow registry
+ * Maps flow IDs to flow builder functions
+ */
+declare const FLOW_REGISTRY: Map<string, FlowBuilder<any, any>>;
+/**
+ * Register a flow builder in the global registry
+ *
+ * @param id - Unique identifier for the flow
+ * @param builder - Flow builder function that accepts providers
+ *
+ * @example
+ * ```typescript
+ * registerFlow('invoice-processing', (providers) =>
+ *   createFlow()
+ *     .step('parse', parse({ provider: providers.ocr }))
+ *     .step('extract', extract({ provider: providers.vlm, schema }))
+ * );
+ * ```
+ */
+declare function registerFlow<TInput = any, TOutput = any>(id: string, builder: FlowBuilder<TInput, TOutput>): void;
+/**
+ * Get a flow builder from the registry
+ *
+ * @param id - Flow identifier
+ * @returns Flow builder function or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const builder = getFlow('invoice-processing');
+ * if (builder) {
+ *   const flow = builder(providers);
+ *   const result = await flow.build().run(input);
+ * }
+ * ```
+ */
+declare function getFlow<TInput = any, TOutput = any>(id: string): FlowBuilder<TInput, TOutput> | undefined;
+/**
+ * Check if a flow is registered
+ *
+ * @param id - Flow identifier
+ * @returns true if flow is registered
+ */
+declare function hasFlow(id: string): boolean;
+/**
+ * Unregister a flow from the registry
+ *
+ * @param id - Flow identifier
+ * @returns true if flow was removed, false if it didn't exist
+ */
+declare function unregisterFlow(id: string): boolean;
+/**
+ * Clear all registered flows
+ * Useful for testing or resetting state
+ */
+declare function clearRegistry(): void;
+/**
+ * Get all registered flow IDs
+ *
+ * @returns Array of flow identifiers
+ */
+declare function listFlows(): string[];
+/**
+ * Get the number of registered flows
+ *
+ * @returns Number of flows in registry
+ */
+declare function getFlowCount(): number;
+
+/**
+ * Flow Serialization
+ *
+ * Provides serialization/deserialization for doclo-sdk flows.
+ * Supports all flow types: sequential steps, conditional branches, and forEach loops.
+ *
+ * Limitations:
+ * - Provider instances must be reconstructed at runtime
+ */
+
+/**
+ * Union type for providers used in flow serialization
+ */
+type FlowProvider = VLMProvider | OCRProvider;
+/**
+ * JSON value type for literal field mappings
+ */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Serializable input validation configuration
+ */
+type SerializableInputValidation = {
+    /**
+     * List of accepted MIME types.
+     * If specified, input must match one of these types or validation fails.
+     */
+    acceptedFormats?: Array<'application/pdf' | 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp'>;
+    /**
+     * Whether to throw on validation failure.
+     * @default true
+     */
+    throwOnInvalid?: boolean;
+};
+/**
+ * Serializable flow definition
+ */
+type SerializableFlow = {
+    version: string;
+    steps: SerializableStep[];
+    /**
+     * Optional input format validation configuration.
+     * Allows specifying accepted MIME types for early validation.
+     */
+    inputValidation?: SerializableInputValidation;
+};
+/**
+ * Serializable step definition
+ */
+type SerializableStep = SerializableStandardStep | SerializableConditionalStep | SerializableForEachStep;
+/**
+ * Standard sequential step
+ */
+type SerializableStandardStep = {
+    type: 'step';
+    id: string;
+    name?: string;
+    nodeType: 'parse' | 'extract' | 'split' | 'categorize' | 'trigger' | 'output';
+    config: NodeConfig;
+};
+/**
+ * Flow reference (alternative to inline SerializableFlow)
+ * Used to reduce JSON nesting depth for complex flows
+ */
+type FlowReference = {
+    flowRef: string;
+};
+/**
+ * Conditional step (categorize + branches)
+ *
+ * Branches can be either inline flows or references to separate flows.
+ * Use references to avoid hitting database JSON nesting limits (e.g., Convex's 16-level limit).
+ */
+type SerializableConditionalStep = {
+    type: 'conditional';
+    id: string;
+    name?: string;
+    nodeType: 'categorize';
+    config: CategorizeConfig;
+    branches: Record<string, SerializableFlow | FlowReference>;
+};
+/**
+ * ForEach step (split + item flow)
+ *
+ * itemFlow can be either an inline flow or a reference to a separate flow.
+ * Use references to avoid hitting database JSON nesting limits.
+ */
+type SerializableForEachStep = {
+    type: 'forEach';
+    id: string;
+    name?: string;
+    nodeType: 'split';
+    config: SplitConfig;
+    itemFlow: SerializableFlow | FlowReference;
+};
+/**
+ * Input mapping configuration for trigger nodes
+ * Declarative alternatives to mapInput functions (for serialization)
+ */
+type InputMappingConfig = {
+    type: 'passthrough';
+} | {
+    type: 'unwrap';
+} | {
+    type: 'artifact';
+    path: string;
+} | {
+    type: 'merge';
+    artifactPath: string;
+} | {
+    type: 'construct';
+    fields: Record<string, FieldMapping>;
+};
+type FieldMapping = {
+    source: 'input';
+    path?: string;
+} | {
+    source: 'artifact';
+    path: string;
+} | {
+    source: 'literal';
+    value: JsonValue;
+};
+/**
+ * Node configuration (without provider instances)
+ */
+type NodeConfig = ParseConfig | ExtractConfig | SplitConfig | CategorizeConfig | TriggerConfig | OutputConfig;
+type ParseConfig = {
+    type: 'parse';
+    providerRef: string;
+    consensus?: {
+        runs: number;
+        strategy?: 'majority' | 'unanimous';
+        onTie?: 'random' | 'fail' | 'retry';
+    };
+};
+type ExtractConfig = {
+    type: 'extract';
+    providerRef: string;
+    schema: JSONSchemaNode;
+    consensus?: {
+        runs: number;
+        strategy?: 'majority' | 'unanimous';
+        onTie?: 'random' | 'fail' | 'retry';
+    };
+    reasoning?: {
+        enabled?: boolean;
+        effort?: 'low' | 'medium' | 'high';
+        max_tokens?: number;
+    };
+};
+type SplitConfig = {
+    type: 'split';
+    providerRef: string;
+    schemas: Record<string, JSONSchemaNode>;
+    includeOther?: boolean;
+    consensus?: {
+        runs: number;
+        strategy?: 'majority' | 'unanimous';
+        onTie?: 'random' | 'fail' | 'retry';
+    };
+    schemaRef?: string;
+};
+type CategorizeConfig = {
+    type: 'categorize';
+    providerRef: string;
+    categories: string[];
+    consensus?: {
+        runs: number;
+        strategy?: 'majority' | 'unanimous';
+        onTie?: 'random' | 'fail' | 'retry';
+    };
+    promptRef?: string;
+};
+type TriggerConfig = {
+    type: 'trigger';
+    flowRef: string;
+    providerOverrides?: Record<string, string>;
+    inputMapping?: InputMappingConfig;
+    mergeMetrics?: boolean;
+    timeout?: number;
+};
+type OutputConfig = {
+    type: 'output';
+    name?: string;
+    source?: string | string[];
+    transform?: 'first' | 'last' | 'merge' | 'pick';
+    fields?: string[];
+};
+/**
+ * Provider registry for deserialization
+ */
+type ProviderRegistry = Record<string, FlowProvider>;
+/**
+ * Extract node metadata from a node (if available)
+ * Note: This is a best-effort extraction since nodes don't currently
+ * expose their config. Returns null for nodes without metadata.
+ */
+declare function extractNodeMetadata(node: NodeDef<unknown, unknown>): {
+    nodeType: string;
+    config: NodeConfig;
+} | null;
+/**
+ * Validation error for flow serialization
+ */
+declare class FlowSerializationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Flow registry type
+ * Maps flow IDs to SerializableFlow objects (from database/Convex)
+ */
+type FlowRegistry$1 = Record<string, SerializableFlow>;
+/**
+ * Type guard to check if a value is a FlowReference
+ */
+declare function isFlowReference(value: SerializableFlow | FlowReference): value is FlowReference;
+/**
+ * Resolve a flow reference to a SerializableFlow
+ *
+ * @param flowOrRef - Either an inline flow or a flow reference
+ * @param flows - Flow registry to resolve references from
+ * @returns SerializableFlow
+ * @throws FlowSerializationError if reference cannot be resolved
+ */
+declare function resolveFlowReference(flowOrRef: SerializableFlow | FlowReference, flows?: FlowRegistry$1): SerializableFlow;
+/**
+ * Build a flow from a serializable definition
+ *
+ * @param flowDef - Serializable flow definition
+ * @param providers - Provider registry (map of provider refs to provider instances)
+ * @param flows - Optional flow registry for:
+ *   - Trigger nodes (map of flow refs to flow builders)
+ *   - Conditional branches (when using flowRef instead of inline SerializableFlow)
+ *   - ForEach itemFlow (when using flowRef instead of inline SerializableFlow)
+ * @returns Executable flow
+ *
+ * @example
+ * ```typescript
+ * const flowDef: SerializableFlow = {
+ *   version: '1.0.0',
+ *   steps: [
+ *     {
+ *       type: 'step',
+ *       id: 'parse',
+ *       nodeType: 'parse',
+ *       config: { type: 'parse', providerRef: 'ocr' }
+ *     },
+ *     {
+ *       type: 'step',
+ *       id: 'extract',
+ *       nodeType: 'extract',
+ *       config: {
+ *         type: 'extract',
+ *         providerRef: 'llm',
+ *         schema: { ... }
+ *       }
+ *     }
+ *   ]
+ * };
+ *
+ * const providers = {
+ *   ocr: suryaProvider,
+ *   llm: geminiProvider
+ * };
+ *
+ * const flow = buildFlowFromConfig(flowDef, providers);
+ * ```
+ */
+declare function buildFlowFromConfig(flowDef: SerializableFlow, providers: ProviderRegistry, flows?: FlowRegistry$1, options?: FlowOptions): BuiltFlow<FlowInput, unknown>;
+/**
+ * Helper to create a serializable flow definition
+ *
+ * @example
+ * ```typescript
+ * const flowDef = defineFlowConfig({
+ *   version: '1.0.0',
+ *   steps: [
+ *     {
+ *       type: 'step',
+ *       id: 'parse',
+ *       nodeType: 'parse',
+ *       config: { type: 'parse', providerRef: 'ocr' }
+ *     }
+ *   ]
+ * });
+ *
+ * // Save to database
+ * await db.flows.create({ definition: JSON.stringify(flowDef) });
+ *
+ * // Later, load and build
+ * const loaded = JSON.parse(row.definition);
+ * const flow = buildFlowFromConfig(loaded, providers);
+ * ```
+ */
+declare function defineFlowConfig(config: Omit<SerializableFlow, 'version'>): SerializableFlow;
+
+/**
+ * Composite nodes for conditional and forEach execution
+ *
+ * These nodes wrap complex multi-step operations (categorize + branch, split + forEach)
+ * into single logical steps with proper observability, metrics, and error handling.
+ */
+
+/**
+ * Flow registry type
+ * Maps flow IDs to SerializableFlow objects (from database/Convex)
+ */
+type FlowRegistry = Record<string, SerializableFlow>;
+/**
+ * Configuration for conditional composite node
+ */
+interface ConditionalCompositeConfig {
+    stepId: string;
+    categorizeConfig: CategorizeConfig;
+    branches: Record<string, SerializableFlow | FlowReference>;
+    providers: ProviderRegistry;
+    flows: FlowRegistry;
+}
+/**
+ * Creates a composite node that:
+ * 1. Executes a categorize node to determine the category
+ * 2. Selects and executes the appropriate branch flow
+ * 3. Returns the branch flow's output
+ *
+ * Includes full observability, metrics merging, and error context.
+ */
+declare function createConditionalCompositeNode(config: ConditionalCompositeConfig): NodeDef<FlowInput, unknown>;
+/**
+ * Configuration for forEach composite node
+ */
+interface ForEachCompositeConfig {
+    stepId: string;
+    splitConfig: SplitConfig;
+    itemFlow: SerializableFlow | FlowReference;
+    providers: ProviderRegistry;
+    flows: FlowRegistry;
+}
+/**
+ * Creates a composite node that:
+ * 1. Executes a split node to get an array of items
+ * 2. Executes the item flow for each item in parallel
+ * 3. Returns aggregated results
+ *
+ * Includes full observability, metrics merging, and error context.
+ */
+declare function createForEachCompositeNode(config: ForEachCompositeConfig): NodeDef<FlowInput, unknown[]>;
+
+/**
+ * Flow Validation
+ *
+ * Provides validation for flow configurations before execution.
+ */
+
+/**
+ * Validation result
+ */
+type ValidationResult = {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+};
+/**
+ * Validation error
+ */
+type ValidationError = {
+    type: 'missing_provider' | 'invalid_schema' | 'invalid_config' | 'version_mismatch';
+    stepId?: string;
+    message: string;
+    details?: Record<string, unknown>;
+};
+/**
+ * Validation warning
+ */
+type ValidationWarning = {
+    type: 'deprecated' | 'performance' | 'best_practice';
+    stepId?: string;
+    message: string;
+    details?: Record<string, unknown>;
+};
+/**
+ * Provider instance used for validation (minimal interface)
+ */
+interface ValidationProviderInstance {
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * Validation options
+ */
+type ValidationOptions = {
+    checkProviders?: boolean;
+    checkSchemas?: boolean;
+    checkVersion?: boolean;
+    providers?: Record<string, ValidationProviderInstance>;
+};
+/**
+ * Validate a serializable flow definition
+ *
+ * @param flowDef - Flow definition to validate
+ * @param options - Validation options
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateFlow(flowDef, {
+ *   checkProviders: true,
+ *   checkSchemas: true,
+ *   providers: { ocr: suryaProvider, llm: geminiProvider }
+ * });
+ *
+ * if (!result.valid) {
+ *   console.error('Flow validation failed:', result.errors);
+ * }
+ * ```
+ */
+declare function validateFlow(flowDef: SerializableFlow, options?: ValidationOptions): ValidationResult;
+/**
+ * Validate and throw if invalid
+ *
+ * @param flowDef - Flow definition to validate
+ * @param options - Validation options
+ * @throws ValidationError if flow is invalid
+ */
+declare function validateFlowOrThrow(flowDef: SerializableFlow, options?: ValidationOptions): void;
+
+/**
+ * Build a flow with automatic fallback between multiple LLM providers
+ *
+ * Example usage:
+ * ```
+ * const flow = buildMultiProviderFlow({
+ *   ocr: suryaProvider({ endpoint, apiKey }),
+ *   llmConfigs: [
+ *     { provider: 'openai', model: 'gpt-4.1', apiKey: process.env.OPENAI_KEY },
+ *     { provider: 'anthropic', model: 'claude-haiku-4.5', apiKey: process.env.ANTHROPIC_KEY, via: 'openrouter' },
+ *     { provider: 'google', model: 'gemini-2.5-flash', apiKey: process.env.GOOGLE_KEY }
+ *   ],
+ *   maxRetries: 2
+ * });
+ * ```
+ */
+declare function buildMultiProviderFlow(opts: {
+    ocr: OCRProvider;
+    llmConfigs: Array<{
+        provider: 'openai' | 'anthropic' | 'google' | 'xai';
+        model: string;
+        apiKey: string;
+        via?: 'openrouter' | 'native';
+        baseUrl?: string;
+    }>;
+    maxRetries?: number;
+    retryDelay?: number;
+    circuitBreakerThreshold?: number;
+}): {
+    run(input: {
+        url?: string;
+        base64?: string;
+    }): Promise<{
+        ir: DocumentIR;
+        output: any;
+        metrics: _doclo_core.StepMetric[];
+        artifacts: {
+            parse: unknown;
+            extract: unknown;
+        };
+    }>;
+};
+
+/**
+ * Build a flow that uses VLM (Vision Language Model) for direct extraction
+ * Skips OCR entirely - sends image/PDF directly to the vision model
+ *
+ * Pros:
+ * - Faster (one API call instead of two)
+ * - Can understand layout, tables, charts visually
+ * - No OCR errors/artifacts
+ *
+ * Cons:
+ * - More expensive (vision tokens cost more)
+ * - Limited to models with vision capabilities
+ */
+declare function buildVLMDirectFlow(opts: {
+    llmConfigs: Array<{
+        provider: 'openai' | 'anthropic' | 'google' | 'xai';
+        model: string;
+        apiKey: string;
+        via?: 'openrouter' | 'native';
+        baseUrl?: string;
+    }>;
+    maxRetries?: number;
+    retryDelay?: number;
+    circuitBreakerThreshold?: number;
+}): {
+    run(input: {
+        url?: string;
+        base64?: string;
+    }): Promise<{
+        output: any;
+        metrics: _doclo_core.StepMetric[];
+        artifacts: {
+            vlm_extract: unknown;
+        };
+    }>;
+};
+
+declare function buildTwoProviderFlow(opts: {
+    ocr: OCRProvider;
+    llmA: LLMJsonProvider;
+    llmB: LLMJsonProvider;
+}): {
+    run(input: {
+        url?: string;
+        base64?: string;
+    }): Promise<{
+        ir: DocumentIR;
+        outputA: any;
+        outputB: any;
+        metrics: _doclo_core.StepMetric[];
+        artifacts: {
+            parse: unknown;
+            extractA: unknown;
+            extractB: unknown;
+        };
+    }>;
+};
+
+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 };