@wundr.io/langgraph-orchestrator 1.0.3

package/dist/state-graph.js

@@ -0,0 +1,756 @@
+"use strict";
+/**
+ * StateGraph - Core class for defining workflow graphs with nodes and edges
+ * @module @wundr.io/langgraph-orchestrator
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateGraph = void 0;
+const eventemitter3_1 = require("eventemitter3");
+const uuid_1 = require("uuid");
+/**
+ * Default graph configuration
+ */
+const DEFAULT_CONFIG = {
+    maxIterations: 100,
+    timeout: 300000, // 5 minutes
+    checkpointEnabled: true,
+    checkpointInterval: 1,
+    parallelExecution: false,
+    retry: {
+        maxRetries: 3,
+        initialDelay: 1000,
+        backoffMultiplier: 2,
+        maxDelay: 30000,
+        retryableErrors: ['TIMEOUT', 'RATE_LIMIT', 'NETWORK_ERROR'],
+    },
+    logLevel: 'info',
+};
+/**
+ * Console-based logger implementation
+ */
+class ConsoleLogger {
+    level;
+    constructor(level) {
+        this.level = level;
+    }
+    shouldLog(msgLevel) {
+        const levels = ['debug', 'info', 'warn', 'error', 'silent'];
+        return levels.indexOf(msgLevel) >= levels.indexOf(this.level);
+    }
+    debug(message, data) {
+        if (this.shouldLog('debug')) {
+            // Using process.stderr for logging to avoid polluting stdout
+            process.stderr.write(`[DEBUG] ${message} ${data ? JSON.stringify(data) : ''}\n`);
+        }
+    }
+    info(message, data) {
+        if (this.shouldLog('info')) {
+            // Using process.stderr for logging to avoid polluting stdout
+            process.stderr.write(`[INFO] ${message} ${data ? JSON.stringify(data) : ''}\n`);
+        }
+    }
+    warn(message, data) {
+        if (this.shouldLog('warn')) {
+            console.warn(`[WARN] ${message}`, data ?? '');
+        }
+    }
+    error(message, data) {
+        if (this.shouldLog('error')) {
+            console.error(`[ERROR] ${message}`, data ?? '');
+        }
+    }
+}
+/**
+ * StateGraph class for defining and executing workflow graphs
+ *
+ * @example
+ * ```typescript
+ * const graph = new StateGraph('my-workflow')
+ *   .addNode('start', {
+ *     id: 'start',
+ *     name: 'Start Node',
+ *     type: 'start',
+ *     config: {},
+ *     execute: async (state) => ({ state, next: 'process' })
+ *   })
+ *   .addNode('process', {
+ *     id: 'process',
+ *     name: 'Process Node',
+ *     type: 'transform',
+ *     config: {},
+ *     execute: async (state) => ({ state, next: 'end' })
+ *   })
+ *   .addEdge('start', 'process')
+ *   .setEntryPoint('start');
+ *
+ * const result = await graph.execute();
+ * ```
+ */
+class StateGraph extends eventemitter3_1.EventEmitter {
+    id;
+    name;
+    description;
+    nodes = new Map();
+    edges = new Map();
+    entryPoint;
+    config;
+    _checkpointer;
+    services = {};
+    logger;
+    /** Get the checkpointer */
+    get checkpointer() {
+        return this._checkpointer;
+    }
+    /**
+     * Create a new StateGraph
+     * @param name - Human-readable name for the graph
+     * @param config - Optional configuration overrides
+     */
+    constructor(name, config) {
+        super();
+        this.id = (0, uuid_1.v4)();
+        this.name = name;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+        this.logger = new ConsoleLogger(this.config.logLevel);
+    }
+    /**
+     * Add a node to the graph
+     * @param name - Unique name for the node
+     * @param definition - Node definition
+     * @returns this for chaining
+     */
+    addNode(name, definition) {
+        if (this.nodes.has(name)) {
+            throw new Error(`Node "${name}" already exists in graph "${this.name}"`);
+        }
+        this.nodes.set(name, definition);
+        this.edges.set(name, []);
+        return this;
+    }
+    /**
+     * Add a direct edge between nodes
+     * @param from - Source node name
+     * @param to - Target node name
+     * @returns this for chaining
+     */
+    addEdge(from, to) {
+        this.validateNodeExists(from);
+        this.validateNodeExists(to);
+        const edge = {
+            from,
+            to,
+            type: 'direct',
+        };
+        const edges = this.edges.get(from) ?? [];
+        edges.push(edge);
+        this.edges.set(from, edges);
+        return this;
+    }
+    /**
+     * Add a conditional edge
+     * @param from - Source node name
+     * @param to - Target node name
+     * @param condition - Condition for traversal
+     * @returns this for chaining
+     */
+    addConditionalEdge(from, to, condition) {
+        this.validateNodeExists(from);
+        this.validateNodeExists(to);
+        const edge = {
+            from,
+            to,
+            type: 'conditional',
+            condition,
+        };
+        const edges = this.edges.get(from) ?? [];
+        edges.push(edge);
+        this.edges.set(from, edges);
+        return this;
+    }
+    /**
+     * Add a loop edge that can cycle back
+     * @param from - Source node name
+     * @param to - Target node name (can be same as from)
+     * @param condition - Condition to continue looping
+     * @returns this for chaining
+     */
+    addLoopEdge(from, to, condition) {
+        this.validateNodeExists(from);
+        this.validateNodeExists(to);
+        const edge = {
+            from,
+            to,
+            type: 'loop',
+            condition,
+        };
+        const edges = this.edges.get(from) ?? [];
+        edges.push(edge);
+        this.edges.set(from, edges);
+        return this;
+    }
+    /**
+     * Add parallel edges to multiple targets
+     * @param from - Source node name
+     * @param targets - Target node names
+     * @returns this for chaining
+     */
+    addParallelEdges(from, targets) {
+        this.validateNodeExists(from);
+        targets.forEach(t => this.validateNodeExists(t));
+        for (const to of targets) {
+            const edge = {
+                from,
+                to,
+                type: 'parallel',
+            };
+            const edges = this.edges.get(from) ?? [];
+            edges.push(edge);
+            this.edges.set(from, edges);
+        }
+        return this;
+    }
+    /**
+     * Set the entry point node
+     * @param nodeName - Name of the entry point node
+     * @returns this for chaining
+     */
+    setEntryPoint(nodeName) {
+        this.validateNodeExists(nodeName);
+        this.entryPoint = nodeName;
+        return this;
+    }
+    /**
+     * Set the checkpointer for state persistence
+     * @param checkpointer - Checkpointer implementation
+     * @returns this for chaining
+     */
+    setCheckpointer(checkpointer) {
+        this._checkpointer = checkpointer;
+        this.services = { ...this.services, checkpointer };
+        return this;
+    }
+    /**
+     * Set services available to nodes
+     * @param services - Services to provide
+     * @returns this for chaining
+     */
+    setServices(services) {
+        this.services = { ...this.services, ...services };
+        return this;
+    }
+    /**
+     * Get the graph configuration
+     * @returns GraphConfig object
+     */
+    getConfig() {
+        if (!this.entryPoint) {
+            throw new Error('Entry point not set. Call setEntryPoint() before getConfig()');
+        }
+        // The nodes Map uses TState-specific NodeDefinition, but GraphConfig uses the base type.
+        // This cast is safe because GraphConfig is used for inspection/serialization,
+        // while actual execution uses the strongly-typed internal this.nodes Map.
+        const typedNodes = new Map();
+        for (const [key, value] of this.nodes) {
+            // Cast through unknown is necessary here because NodeDefinition<TState>
+            // has contravariant parameter in execute function signature
+            typedNodes.set(key, value);
+        }
+        return {
+            id: this.id,
+            name: this.name,
+            description: this.description,
+            entryPoint: this.entryPoint,
+            nodes: typedNodes,
+            edges: new Map(this.edges),
+            config: this.config,
+        };
+    }
+    /**
+     * Execute the graph
+     * @param options - Execution options
+     * @returns Execution result
+     */
+    async execute(options) {
+        if (!this.entryPoint) {
+            throw new Error('Entry point not set. Call setEntryPoint() before execute()');
+        }
+        const executionId = (0, uuid_1.v4)();
+        const startTime = Date.now();
+        const path = [];
+        let nodesExecuted = 0;
+        let iterations = 0;
+        let tokensUsed = 0;
+        let checkpointsCreated = 0;
+        let retries = 0;
+        // Initialize or restore state
+        let state = await this.initializeState(executionId, options);
+        this.emit('execution:start', state);
+        options?.handlers?.onStart?.(state);
+        let currentNode = options?.resumeFrom
+            ? await this.getNodeFromCheckpoint(options.resumeFrom)
+            : this.entryPoint;
+        try {
+            while (currentNode && iterations < this.config.maxIterations) {
+                iterations++;
+                const node = this.nodes.get(currentNode);
+                if (!node) {
+                    throw this.createError('NODE_NOT_FOUND', `Node "${currentNode}" not found`);
+                }
+                path.push(currentNode);
+                this.logger.debug(`Entering node: ${currentNode}`, {
+                    iteration: iterations,
+                });
+                this.emit('node:enter', currentNode, state);
+                options?.handlers?.onNodeEnter?.(currentNode, state);
+                // Execute node with retry logic
+                const result = await this.executeNodeWithRetry(node, state, executionId, iterations);
+                nodesExecuted++;
+                if (result.metadata?.tokensUsed) {
+                    tokensUsed += result.metadata.tokensUsed;
+                }
+                if (result.metadata?.retryCount) {
+                    retries += result.metadata.retryCount;
+                }
+                // Update state with history
+                state = this.updateStateWithHistory(result.state, currentNode, state);
+                this.emit('node:exit', currentNode, result);
+                this.emit('state:updated', state);
+                options?.handlers?.onNodeExit?.(currentNode, result);
+                // Create checkpoint if enabled
+                if (this.config.checkpointEnabled &&
+                    iterations % this.config.checkpointInterval === 0 &&
+                    this.checkpointer) {
+                    const checkpoint = await this.createCheckpoint(state, currentNode, executionId, iterations);
+                    checkpointsCreated++;
+                    this.emit('checkpoint:created', checkpoint);
+                    options?.handlers?.onCheckpoint?.(checkpoint);
+                }
+                // Check for termination
+                if (result.terminate) {
+                    this.logger.info('Workflow terminated by node', {
+                        node: currentNode,
+                    });
+                    break;
+                }
+                // Determine next node
+                const nextNode = await this.determineNextNode(currentNode, result, state);
+                currentNode = nextNode ?? '';
+                // Check abort signal
+                if (options?.signal?.aborted) {
+                    throw this.createError('ABORTED', 'Execution was aborted');
+                }
+            }
+            if (iterations >= this.config.maxIterations) {
+                throw this.createError('MAX_ITERATIONS', `Exceeded maximum iterations (${this.config.maxIterations})`);
+            }
+            const duration = Date.now() - startTime;
+            const stats = {
+                duration,
+                nodesExecuted,
+                iterations,
+                tokensUsed,
+                checkpointsCreated,
+                retries,
+            };
+            const result = {
+                state,
+                success: true,
+                stats,
+                path,
+            };
+            this.emit('execution:complete', result);
+            options?.handlers?.onComplete?.(state);
+            return result;
+        }
+        catch (error) {
+            const workflowError = this.normalizeError(error, currentNode ?? 'unknown');
+            state = {
+                ...state,
+                error: workflowError,
+                updatedAt: new Date(),
+            };
+            this.emit('execution:error', workflowError);
+            options?.handlers?.onError?.(workflowError);
+            const duration = Date.now() - startTime;
+            return {
+                state,
+                success: false,
+                error: workflowError,
+                stats: {
+                    duration,
+                    nodesExecuted,
+                    iterations,
+                    tokensUsed,
+                    checkpointsCreated,
+                    retries,
+                },
+                path,
+            };
+        }
+    }
+    /**
+     * Compile the graph into an executable form
+     * @returns Compiled graph configuration
+     */
+    compile() {
+        // Validate graph structure
+        this.validateGraph();
+        return this.getConfig();
+    }
+    /**
+     * Create a subgraph from a subset of nodes
+     * @param nodeNames - Names of nodes to include
+     * @returns New StateGraph containing the subgraph
+     */
+    subgraph(nodeNames) {
+        const sub = new StateGraph(`${this.name}-subgraph`, this.config);
+        for (const name of nodeNames) {
+            const node = this.nodes.get(name);
+            if (node) {
+                sub.addNode(name, node);
+                // Add edges that connect nodes within the subgraph
+                const edges = this.edges.get(name) ?? [];
+                for (const edge of edges) {
+                    if (nodeNames.includes(edge.to)) {
+                        const existing = sub.edges.get(name) ?? [];
+                        existing.push(edge);
+                        sub.edges.set(name, existing);
+                    }
+                }
+            }
+        }
+        return sub;
+    }
+    // Private helper methods
+    validateNodeExists(nodeName) {
+        if (!this.nodes.has(nodeName)) {
+            throw new Error(`Node "${nodeName}" does not exist in graph "${this.name}"`);
+        }
+    }
+    validateGraph() {
+        if (!this.entryPoint) {
+            throw new Error('Graph validation failed: No entry point defined');
+        }
+        if (this.nodes.size === 0) {
+            throw new Error('Graph validation failed: No nodes defined');
+        }
+        // Check all edge targets exist
+        for (const [source, edges] of this.edges) {
+            for (const edge of edges) {
+                if (!this.nodes.has(edge.to)) {
+                    throw new Error(`Graph validation failed: Edge from "${source}" references non-existent node "${edge.to}"`);
+                }
+            }
+        }
+        // Check entry point is reachable
+        if (!this.nodes.has(this.entryPoint)) {
+            throw new Error(`Graph validation failed: Entry point "${this.entryPoint}" does not exist`);
+        }
+    }
+    async initializeState(executionId, options) {
+        const now = new Date();
+        const metadata = {
+            sessionId: (0, uuid_1.v4)(),
+            executionId,
+            stepCount: 0,
+            tags: [],
+        };
+        const baseState = {
+            id: (0, uuid_1.v4)(),
+            messages: [],
+            data: {},
+            currentStep: this.entryPoint ?? '',
+            history: [],
+            createdAt: now,
+            updatedAt: now,
+            metadata,
+            ...options?.initialState,
+        };
+        return baseState;
+    }
+    async getNodeFromCheckpoint(checkpointId) {
+        if (!this.checkpointer) {
+            throw new Error('Checkpointer not configured');
+        }
+        const checkpoint = await this.checkpointer.load(checkpointId);
+        if (!checkpoint) {
+            throw new Error(`Checkpoint "${checkpointId}" not found`);
+        }
+        return checkpoint.nodeName;
+    }
+    async executeNodeWithRetry(node, state, executionId, iterationCount) {
+        const retryConfig = { ...this.config.retry, ...node.config.retry };
+        let lastError = null;
+        let retryCount = 0;
+        const context = {
+            node: node,
+            graph: this.getConfig(),
+            executionId,
+            iterationCount,
+            services: {
+                logger: this.logger,
+                checkpointer: this._checkpointer,
+                toolRegistry: this.services.toolRegistry,
+                llmProvider: this.services.llmProvider,
+            },
+        };
+        while (retryCount <= retryConfig.maxRetries) {
+            try {
+                // Execute pre-hooks
+                let currentState = state;
+                if (node.preHooks) {
+                    for (const hook of node.preHooks) {
+                        currentState = await hook(currentState, context);
+                    }
+                }
+                // Execute node
+                const startTime = Date.now();
+                let result = await node.execute(currentState, context);
+                const duration = Date.now() - startTime;
+                // Execute post-hooks
+                if (node.postHooks) {
+                    for (const hook of node.postHooks) {
+                        result = {
+                            ...result,
+                            state: await hook(result.state, context),
+                        };
+                    }
+                }
+                // Validate output if schema provided
+                if (node.outputSchema) {
+                    node.outputSchema.parse(result.state);
+                }
+                return {
+                    ...result,
+                    metadata: {
+                        ...result.metadata,
+                        duration,
+                        retryCount,
+                    },
+                };
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                const errorCode = error.code ?? 'UNKNOWN';
+                if (!retryConfig.retryableErrors.includes(errorCode) ||
+                    retryCount >= retryConfig.maxRetries) {
+                    throw error;
+                }
+                const delay = Math.min(retryConfig.initialDelay *
+                    Math.pow(retryConfig.backoffMultiplier, retryCount), retryConfig.maxDelay);
+                this.logger.warn(`Retrying node ${node.name} after ${delay}ms`, {
+                    attempt: retryCount + 1,
+                    error: lastError.message,
+                });
+                await this.sleep(delay);
+                retryCount++;
+            }
+        }
+        throw lastError ?? new Error('Unknown error during node execution');
+    }
+    updateStateWithHistory(newState, nodeName, previousState) {
+        const changes = this.computeStateChanges(previousState, newState);
+        const historyEntry = {
+            step: nodeName,
+            timestamp: new Date(),
+            snapshot: {
+                currentStep: previousState.currentStep,
+                data: { ...previousState.data },
+            },
+            changes,
+        };
+        return {
+            ...newState,
+            currentStep: nodeName,
+            history: [...previousState.history, historyEntry],
+            updatedAt: new Date(),
+            metadata: {
+                ...newState.metadata,
+                stepCount: previousState.metadata.stepCount + 1,
+            },
+        };
+    }
+    computeStateChanges(previous, current) {
+        const changes = [];
+        // Compare data fields
+        const allKeys = new Set([
+            ...Object.keys(previous.data),
+            ...Object.keys(current.data),
+        ]);
+        for (const key of allKeys) {
+            const prevValue = previous.data[key];
+            const currValue = current.data[key];
+            if (JSON.stringify(prevValue) !== JSON.stringify(currValue)) {
+                changes.push({
+                    path: `data.${key}`,
+                    previousValue: prevValue,
+                    newValue: currValue,
+                });
+            }
+        }
+        // Compare messages
+        if (current.messages.length !== previous.messages.length) {
+            changes.push({
+                path: 'messages',
+                previousValue: previous.messages.length,
+                newValue: current.messages.length,
+            });
+        }
+        return changes;
+    }
+    async determineNextNode(currentNode, result, state) {
+        // If node explicitly specifies next
+        if (result.next) {
+            if (Array.isArray(result.next)) {
+                // For parallel execution, return the first one
+                // (proper parallel execution would need more complex handling)
+                return result.next[0];
+            }
+            return result.next;
+        }
+        // Evaluate edges
+        const edges = this.edges.get(currentNode) ?? [];
+        for (const edge of edges) {
+            const shouldFollow = await this.evaluateEdgeCondition(edge, result, state);
+            if (shouldFollow) {
+                return edge.to;
+            }
+        }
+        // No matching edge - end of workflow
+        return undefined;
+    }
+    async evaluateEdgeCondition(edge, result, state) {
+        // Direct edges always follow
+        if (edge.type === 'direct' || edge.type === 'parallel') {
+            return true;
+        }
+        // Conditional and loop edges need condition evaluation
+        if (!edge.condition) {
+            return true;
+        }
+        const { condition } = edge;
+        const context = {
+            edge,
+            sourceResult: result,
+            graph: this.getConfig(),
+        };
+        switch (condition.type) {
+            case 'equals':
+                return this.getFieldValue(state, condition.field) === condition.value;
+            case 'not_equals':
+                return this.getFieldValue(state, condition.field) !== condition.value;
+            case 'contains': {
+                const fieldValue = this.getFieldValue(state, condition.field);
+                return (Array.isArray(fieldValue) && fieldValue.includes(condition.value));
+            }
+            case 'greater_than':
+                return (this.getFieldValue(state, condition.field) >
+                    condition.value);
+            case 'less_than':
+                return (this.getFieldValue(state, condition.field) <
+                    condition.value);
+            case 'exists':
+                return this.getFieldValue(state, condition.field) !== undefined;
+            case 'not_exists':
+                return this.getFieldValue(state, condition.field) === undefined;
+            case 'custom':
+                if (condition.evaluate) {
+                    return await condition.evaluate(state, context);
+                }
+                return false;
+            default:
+                return false;
+        }
+    }
+    getFieldValue(state, field) {
+        if (!field) {
+            return undefined;
+        }
+        const parts = field.split('.');
+        let current = state;
+        for (const part of parts) {
+            if (current === null || current === undefined) {
+                return undefined;
+            }
+            current = current[part];
+        }
+        return current;
+    }
+    async createCheckpoint(state, nodeName, executionId, stepNumber) {
+        const checkpoint = {
+            id: (0, uuid_1.v4)(),
+            executionId,
+            stepNumber,
+            nodeName,
+            state,
+            timestamp: new Date(),
+        };
+        if (this.checkpointer) {
+            await this.checkpointer.save(checkpoint);
+        }
+        return checkpoint;
+    }
+    createError(code, message, node) {
+        return {
+            code,
+            message,
+            node,
+            recoverable: ['TIMEOUT', 'RATE_LIMIT', 'NETWORK_ERROR'].includes(code),
+            recoveryHints: this.getRecoveryHints(code),
+        };
+    }
+    normalizeError(error, node) {
+        if (this.isWorkflowError(error)) {
+            return error;
+        }
+        const err = error instanceof Error ? error : new Error(String(error));
+        return {
+            code: error.code ?? 'EXECUTION_ERROR',
+            message: err.message,
+            stack: err.stack,
+            node,
+            recoverable: false,
+        };
+    }
+    isWorkflowError(error) {
+        return (typeof error === 'object' &&
+            error !== null &&
+            'code' in error &&
+            'message' in error &&
+            'recoverable' in error);
+    }
+    getRecoveryHints(code) {
+        const hints = {
+            TIMEOUT: [
+                'Increase timeout configuration',
+                'Check network connectivity',
+                'Reduce payload size',
+            ],
+            RATE_LIMIT: [
+                'Add delay between requests',
+                'Reduce concurrency',
+                'Contact API provider',
+            ],
+            NETWORK_ERROR: [
+                'Check network connectivity',
+                'Verify endpoint availability',
+                'Check firewall settings',
+            ],
+            MAX_ITERATIONS: [
+                'Review loop conditions',
+                'Increase maxIterations config',
+                'Check for infinite loops',
+            ],
+            ABORTED: [
+                'Execution was cancelled by user',
+                'Resume from checkpoint if needed',
+            ],
+        };
+        return hints[code] ?? [];
+    }
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+exports.StateGraph = StateGraph;
+//# sourceMappingURL=state-graph.js.map