@wundr.io/langgraph-orchestrator 1.0.3

package/dist/nodes/decision-node.js

@@ -0,0 +1,403 @@
+"use strict";
+/**
+ * Decision Node - Conditional branching node for workflow control flow
+ * @module @wundr.io/langgraph-orchestrator
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecisionNodeConfigSchema = void 0;
+exports.createDecisionNode = createDecisionNode;
+exports.createSwitchNode = createSwitchNode;
+exports.createThresholdNode = createThresholdNode;
+exports.createIfElseNode = createIfElseNode;
+exports.createMultiConditionNode = createMultiConditionNode;
+const zod_1 = require("zod");
+/**
+ * Schema for decision node configuration validation
+ */
+exports.DecisionNodeConfigSchema = zod_1.z.object({
+    branches: zod_1.z.array(zod_1.z.object({
+        name: zod_1.z.string(),
+        target: zod_1.z.string(),
+        condition: zod_1.z.object({
+            type: zod_1.z.enum([
+                'equals',
+                'not_equals',
+                'contains',
+                'greater_than',
+                'less_than',
+                'exists',
+                'not_exists',
+                'custom',
+            ]),
+            field: zod_1.z.string().optional(),
+            value: zod_1.z.unknown().optional(),
+        }),
+        priority: zod_1.z.number().optional(),
+    })),
+    defaultBranch: zod_1.z.string().optional(),
+    throwOnNoMatch: zod_1.z.boolean().optional(),
+});
+/**
+ * Create a decision node for conditional branching
+ *
+ * @example
+ * ```typescript
+ * const decisionNode = createDecisionNode({
+ *   id: 'router',
+ *   name: 'Task Router',
+ *   config: {
+ *     branches: [
+ *       {
+ *         name: 'search',
+ *         target: 'search-node',
+ *         condition: { type: 'equals', field: 'data.action', value: 'search' }
+ *       },
+ *       {
+ *         name: 'answer',
+ *         target: 'answer-node',
+ *         condition: { type: 'equals', field: 'data.action', value: 'answer' }
+ *       }
+ *     ],
+ *     defaultBranch: 'fallback-node'
+ *   }
+ * });
+ *
+ * graph.addNode('router', decisionNode);
+ * ```
+ *
+ * @param options - Node creation options
+ * @returns NodeDefinition for use in StateGraph
+ */
+function createDecisionNode(options) {
+    const { id, name, config, nodeConfig = {} } = options;
+    return {
+        id,
+        name,
+        type: 'decision',
+        config: nodeConfig,
+        execute: async (state, context) => {
+            context.services.logger.debug('Evaluating decision branches', {
+                branchCount: config.branches.length,
+            });
+            // If custom decision function provided, use it
+            if (config.decide) {
+                const target = await config.decide(state);
+                context.services.logger.debug('Custom decision made', { target });
+                return {
+                    state,
+                    next: target,
+                };
+            }
+            // Sort branches by priority
+            const sortedBranches = [...config.branches].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+            // Evaluate branches in order
+            for (const branch of sortedBranches) {
+                const matches = await evaluateCondition(branch.condition, state);
+                if (matches) {
+                    context.services.logger.debug('Branch matched', {
+                        branch: branch.name,
+                        target: branch.target,
+                    });
+                    return {
+                        state,
+                        next: branch.target,
+                    };
+                }
+            }
+            // No branch matched
+            if (config.defaultBranch) {
+                context.services.logger.debug('Using default branch', {
+                    target: config.defaultBranch,
+                });
+                return {
+                    state,
+                    next: config.defaultBranch,
+                };
+            }
+            if (config.throwOnNoMatch) {
+                throw new Error('No decision branch matched and no default configured');
+            }
+            context.services.logger.warn('No decision branch matched, workflow may terminate');
+            return { state };
+        },
+    };
+}
+/**
+ * Evaluate a condition against state
+ */
+async function evaluateCondition(condition, state) {
+    const fieldValue = condition.field
+        ? getFieldValue(state, condition.field)
+        : undefined;
+    switch (condition.type) {
+        case 'equals':
+            return fieldValue === condition.value;
+        case 'not_equals':
+            return fieldValue !== condition.value;
+        case 'contains':
+            if (Array.isArray(fieldValue)) {
+                return fieldValue.includes(condition.value);
+            }
+            if (typeof fieldValue === 'string') {
+                return fieldValue.includes(String(condition.value));
+            }
+            return false;
+        case 'greater_than':
+            return (typeof fieldValue === 'number' &&
+                typeof condition.value === 'number' &&
+                fieldValue > condition.value);
+        case 'less_than':
+            return (typeof fieldValue === 'number' &&
+                typeof condition.value === 'number' &&
+                fieldValue < condition.value);
+        case 'exists':
+            return fieldValue !== undefined && fieldValue !== null;
+        case 'not_exists':
+            return fieldValue === undefined || fieldValue === null;
+        case 'custom':
+            if (condition.evaluate) {
+                return await condition.evaluate(state, {
+                    edge: { from: '', to: '', type: 'conditional', condition },
+                    sourceResult: { state },
+                    graph: {
+                        id: '',
+                        name: '',
+                        entryPoint: '',
+                        nodes: new Map(),
+                        edges: new Map(),
+                        config: {
+                            maxIterations: 100,
+                            timeout: 300000,
+                            checkpointEnabled: false,
+                            checkpointInterval: 1,
+                            parallelExecution: false,
+                            retry: {
+                                maxRetries: 0,
+                                initialDelay: 0,
+                                backoffMultiplier: 1,
+                                maxDelay: 0,
+                                retryableErrors: [],
+                            },
+                            logLevel: 'silent',
+                        },
+                    },
+                });
+            }
+            return false;
+        default:
+            return false;
+    }
+}
+/**
+ * Get a nested field value from state
+ */
+function getFieldValue(state, field) {
+    const parts = field.split('.');
+    let current = state;
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+/**
+ * Create a switch-case style decision node
+ *
+ * @example
+ * ```typescript
+ * const switchNode = createSwitchNode({
+ *   id: 'type-switch',
+ *   name: 'Type Switch',
+ *   field: 'data.messageType',
+ *   cases: {
+ *     'question': 'question-handler',
+ *     'command': 'command-handler',
+ *     'feedback': 'feedback-handler'
+ *   },
+ *   default: 'unknown-handler'
+ * });
+ * ```
+ *
+ * @param options - Switch node options
+ * @returns NodeDefinition for use in StateGraph
+ */
+function createSwitchNode(options) {
+    const branches = Object.entries(options.cases).map(([value, target]) => ({
+        name: `case-${value}`,
+        target,
+        condition: {
+            type: 'equals',
+            field: options.field,
+            value,
+        },
+    }));
+    return createDecisionNode({
+        id: options.id,
+        name: options.name,
+        config: {
+            branches,
+            defaultBranch: options.default,
+            throwOnNoMatch: !options.default,
+        },
+        nodeConfig: options.nodeConfig,
+    });
+}
+/**
+ * Create a threshold-based decision node
+ *
+ * @example
+ * ```typescript
+ * const confidenceRouter = createThresholdNode({
+ *   id: 'confidence-router',
+ *   name: 'Confidence Router',
+ *   field: 'data.confidence',
+ *   thresholds: [
+ *     { value: 0.9, target: 'high-confidence' },
+ *     { value: 0.7, target: 'medium-confidence' },
+ *     { value: 0.5, target: 'low-confidence' }
+ *   ],
+ *   default: 'very-low-confidence'
+ * });
+ * ```
+ *
+ * @param options - Threshold node options
+ * @returns NodeDefinition for use in StateGraph
+ */
+function createThresholdNode(options) {
+    // Sort thresholds in descending order
+    const sortedThresholds = [...options.thresholds].sort((a, b) => b.value - a.value);
+    const branches = sortedThresholds.map((threshold, index) => ({
+        name: `threshold-${threshold.value}`,
+        target: threshold.target,
+        condition: {
+            type: 'custom',
+            evaluate: async (state) => {
+                const value = getFieldValue(state, options.field);
+                if (typeof value !== 'number') {
+                    return false;
+                }
+                // Check if value is >= this threshold but < the next higher threshold
+                const isAboveThreshold = value >= threshold.value;
+                const nextHigherThreshold = sortedThresholds[index - 1];
+                const isBelowNextThreshold = !nextHigherThreshold || value < nextHigherThreshold.value;
+                return isAboveThreshold && isBelowNextThreshold;
+            },
+        },
+        priority: sortedThresholds.length - index,
+    }));
+    return createDecisionNode({
+        id: options.id,
+        name: options.name,
+        config: {
+            branches,
+            defaultBranch: options.default,
+            throwOnNoMatch: !options.default,
+        },
+        nodeConfig: options.nodeConfig,
+    });
+}
+/**
+ * Create a boolean decision node (if-else)
+ *
+ * @example
+ * ```typescript
+ * const ifElseNode = createIfElseNode({
+ *   id: 'has-error',
+ *   name: 'Error Check',
+ *   condition: {
+ *     type: 'exists',
+ *     field: 'error'
+ *   },
+ *   ifTrue: 'error-handler',
+ *   ifFalse: 'success-handler'
+ * });
+ * ```
+ *
+ * @param options - If-else node options
+ * @returns NodeDefinition for use in StateGraph
+ */
+function createIfElseNode(options) {
+    return createDecisionNode({
+        id: options.id,
+        name: options.name,
+        config: {
+            branches: [
+                {
+                    name: 'if-true',
+                    target: options.ifTrue,
+                    condition: options.condition,
+                    priority: 1,
+                },
+            ],
+            defaultBranch: options.ifFalse,
+        },
+        nodeConfig: options.nodeConfig,
+    });
+}
+/**
+ * Create a multi-condition decision node (AND/OR logic)
+ *
+ * @example
+ * ```typescript
+ * const multiConditionNode = createMultiConditionNode({
+ *   id: 'complex-router',
+ *   name: 'Complex Router',
+ *   branches: [
+ *     {
+ *       name: 'premium-user',
+ *       target: 'premium-flow',
+ *       conditions: [
+ *         { type: 'equals', field: 'data.userType', value: 'premium' },
+ *         { type: 'greater_than', field: 'data.credits', value: 0 }
+ *       ],
+ *       logic: 'AND'
+ *     },
+ *     {
+ *       name: 'needs-upgrade',
+ *       target: 'upgrade-flow',
+ *       conditions: [
+ *         { type: 'equals', field: 'data.userType', value: 'free' },
+ *         { type: 'less_than', field: 'data.credits', value: 1 }
+ *       ],
+ *       logic: 'OR'
+ *     }
+ *   ],
+ *   default: 'standard-flow'
+ * });
+ * ```
+ *
+ * @param options - Multi-condition node options
+ * @returns NodeDefinition for use in StateGraph
+ */
+function createMultiConditionNode(options) {
+    const branches = options.branches.map(branch => ({
+        name: branch.name,
+        target: branch.target,
+        priority: branch.priority,
+        condition: {
+            type: 'custom',
+            evaluate: async (state) => {
+                const results = await Promise.all(branch.conditions.map(cond => evaluateCondition(cond, state)));
+                if (branch.logic === 'AND') {
+                    return results.every(r => r);
+                }
+                else {
+                    return results.some(r => r);
+                }
+            },
+        },
+    }));
+    return createDecisionNode({
+        id: options.id,
+        name: options.name,
+        config: {
+            branches,
+            defaultBranch: options.default,
+            throwOnNoMatch: !options.default,
+        },
+        nodeConfig: options.nodeConfig,
+    });
+}
+//# sourceMappingURL=decision-node.js.map

package/dist/nodes/decision-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-node.js","sourceRoot":"","sources":["../../src/nodes/decision-node.ts"],"names":[],"mappings":"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"}

package/dist/nodes/human-node.d.ts

@@ -0,0 +1,272 @@
+/**
+ * Human Node - Human-in-the-loop interaction node
+ * @module @wundr.io/langgraph-orchestrator
+ */
+import { z } from 'zod';
+import type { AgentState, NodeDefinition } from '../types';
+/**
+ * Configuration for human node
+ */
+export interface HumanNodeConfig {
+    /** Prompt to display to the human */
+    readonly prompt?: string | ((state: AgentState) => string);
+    /** Input handler to collect human response */
+    readonly inputHandler: HumanInputHandler;
+    /** Validation for human input */
+    readonly validation?: z.ZodSchema;
+    /** Timeout for human response in milliseconds */
+    readonly timeout?: number;
+    /** What to do on timeout */
+    readonly onTimeout?: 'error' | 'skip' | 'default';
+    /** Default value to use on timeout */
+    readonly defaultValue?: unknown;
+    /** Pre-defined choices for the human */
+    readonly choices?: HumanChoice[];
+    /** Whether to require confirmation */
+    readonly requireConfirmation?: boolean;
+    /** Custom response processor */
+    readonly processResponse?: (response: HumanResponse, state: AgentState) => Partial<AgentState['data']>;
+}
+/**
+ * Handler for collecting human input
+ */
+export interface HumanInputHandler {
+    /** Request input from human */
+    request(context: HumanInputContext): Promise<HumanResponse>;
+    /** Cancel a pending request */
+    cancel?(requestId: string): Promise<void>;
+}
+/**
+ * Context provided to human input handler
+ */
+export interface HumanInputContext {
+    /** Unique request ID */
+    readonly requestId: string;
+    /** Prompt to display */
+    readonly prompt: string;
+    /** Available choices */
+    readonly choices?: HumanChoice[];
+    /** Current workflow state (sanitized) */
+    readonly state: Partial<AgentState>;
+    /** Timeout in milliseconds */
+    readonly timeout?: number;
+    /** Additional metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Human choice option
+ */
+export interface HumanChoice {
+    /** Choice value */
+    readonly value: string;
+    /** Display label */
+    readonly label: string;
+    /** Description */
+    readonly description?: string;
+    /** Whether this is the default choice */
+    readonly default?: boolean;
+}
+/**
+ * Response from human input
+ */
+export interface HumanResponse {
+    /** The response value */
+    readonly value: unknown;
+    /** Response type */
+    readonly type: 'input' | 'choice' | 'confirmation' | 'cancel' | 'timeout';
+    /** Timestamp of response */
+    readonly timestamp: Date;
+    /** Additional metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Schema for human node configuration validation
+ */
+export declare const HumanNodeConfigSchema: z.ZodObject<{
+    prompt: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+    onTimeout: z.ZodOptional<z.ZodEnum<["error", "skip", "default"]>>;
+    choices: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        default: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+        default?: boolean | undefined;
+    }, {
+        value: string;
+        label: string;
+        description?: string | undefined;
+        default?: boolean | undefined;
+    }>, "many">>;
+    requireConfirmation: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    timeout?: number | undefined;
+    prompt?: string | ((...args: unknown[]) => unknown) | undefined;
+    onTimeout?: "error" | "default" | "skip" | undefined;
+    choices?: {
+        value: string;
+        label: string;
+        description?: string | undefined;
+        default?: boolean | undefined;
+    }[] | undefined;
+    requireConfirmation?: boolean | undefined;
+}, {
+    timeout?: number | undefined;
+    prompt?: string | ((...args: unknown[]) => unknown) | undefined;
+    onTimeout?: "error" | "default" | "skip" | undefined;
+    choices?: {
+        value: string;
+        label: string;
+        description?: string | undefined;
+        default?: boolean | undefined;
+    }[] | undefined;
+    requireConfirmation?: boolean | undefined;
+}>;
+/**
+ * Create a human-in-the-loop node
+ *
+ * @example
+ * ```typescript
+ * const humanNode = createHumanNode({
+ *   id: 'approval',
+ *   name: 'Human Approval',
+ *   config: {
+ *     prompt: 'Please review and approve the generated content.',
+ *     inputHandler: myInputHandler,
+ *     choices: [
+ *       { value: 'approve', label: 'Approve' },
+ *       { value: 'reject', label: 'Reject' },
+ *       { value: 'modify', label: 'Request Modifications' }
+ *     ],
+ *     timeout: 300000 // 5 minutes
+ *   }
+ * });
+ *
+ * graph.addNode('approval', humanNode);
+ * ```
+ *
+ * @param options - Node creation options
+ * @returns NodeDefinition for use in StateGraph
+ */
+export declare function createHumanNode<TState extends AgentState = AgentState>(options: {
+    id: string;
+    name: string;
+    config: HumanNodeConfig;
+    nodeConfig?: NodeDefinition<TState>['config'];
+}): NodeDefinition<TState>;
+/**
+ * Create a console-based human input handler
+ *
+ * @example
+ * ```typescript
+ * const handler = createConsoleInputHandler();
+ *
+ * const humanNode = createHumanNode({
+ *   id: 'input',
+ *   name: 'User Input',
+ *   config: {
+ *     inputHandler: handler,
+ *     prompt: 'Enter your response:'
+ *   }
+ * });
+ * ```
+ *
+ * @returns HumanInputHandler for console input
+ */
+export declare function createConsoleInputHandler(): HumanInputHandler;
+/**
+ * Create a callback-based human input handler
+ *
+ * @example
+ * ```typescript
+ * const pendingRequests = new Map();
+ *
+ * const handler = createCallbackInputHandler({
+ *   onRequest: (context) => {
+ *     pendingRequests.set(context.requestId, context);
+ *     // Notify UI or external system
+ *   },
+ *   onResolve: (requestId) => pendingRequests.delete(requestId)
+ * });
+ *
+ * // External system resolves:
+ * handler.resolve(requestId, { value: 'user input', type: 'input', timestamp: new Date() });
+ * ```
+ *
+ * @param options - Handler options
+ * @returns HumanInputHandler with resolve capability
+ */
+export declare function createCallbackInputHandler(options: {
+    onRequest?: (context: HumanInputContext) => void;
+    onResolve?: (requestId: string) => void;
+    onCancel?: (requestId: string) => void;
+}): HumanInputHandler & {
+    resolve: (requestId: string, response: HumanResponse) => void;
+    reject: (requestId: string, error: Error) => void;
+};
+/**
+ * Create a confirmation node for human approval
+ *
+ * @example
+ * ```typescript
+ * const confirmNode = createConfirmationNode({
+ *   id: 'confirm-action',
+ *   name: 'Confirm Action',
+ *   inputHandler: myHandler,
+ *   message: (state) => `Are you sure you want to ${state.data.action}?`,
+ *   onConfirm: 'execute-action',
+ *   onReject: 'cancel-action'
+ * });
+ * ```
+ *
+ * @param options - Confirmation node options
+ * @returns NodeDefinition for use in StateGraph
+ */
+export declare function createConfirmationNode<TState extends AgentState = AgentState>(options: {
+    id: string;
+    name: string;
+    inputHandler: HumanInputHandler;
+    message: string | ((state: TState) => string);
+    onConfirm: string;
+    onReject: string;
+    timeout?: number;
+    nodeConfig?: NodeDefinition<TState>['config'];
+}): NodeDefinition<TState>;
+/**
+ * Create a feedback collection node
+ *
+ * @example
+ * ```typescript
+ * const feedbackNode = createFeedbackNode({
+ *   id: 'collect-feedback',
+ *   name: 'Collect Feedback',
+ *   inputHandler: myHandler,
+ *   questions: [
+ *     { id: 'rating', prompt: 'Rate this response (1-5):', type: 'number' },
+ *     { id: 'comments', prompt: 'Any additional comments?', type: 'text' }
+ *   ]
+ * });
+ * ```
+ *
+ * @param options - Feedback node options
+ * @returns NodeDefinition for use in StateGraph
+ */
+export declare function createFeedbackNode<TState extends AgentState = AgentState>(options: {
+    id: string;
+    name: string;
+    inputHandler: HumanInputHandler;
+    questions: Array<{
+        id: string;
+        prompt: string;
+        type: 'text' | 'number' | 'choice';
+        choices?: string[];
+        required?: boolean;
+    }>;
+    timeout?: number;
+    nodeConfig?: NodeDefinition<TState>['config'];
+}): NodeDefinition<TState>;
+//# sourceMappingURL=human-node.d.ts.map

package/dist/nodes/human-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-node.d.ts","sourceRoot":"","sources":["../../src/nodes/human-node.ts"],"names":[],"mappings":"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"}