@ai.ntellect/core 0.5.0 → 0.6.0

package/dist/graph/controller.js

@@ -0,0 +1,63 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphController = void 0;
+const engine_1 = require("./engine");
+/**
+ * Controller responsible for executing workflows based on graph definitions.
+ * @template T The type representing the graph's state.
+ */
+class GraphController {
+    /**
+     * Executes a sequence of actions using the corresponding graph definitions.
+     * @param {any[]} actions - The list of actions to execute.
+     * @param {GraphDefinition<T>[]} graphs - The available graph definitions.
+     * @returns {Promise<any>} The final state of the executed workflow.
+     * @throws {Error} If no actions are provided or if the graph is not found.
+     */
+    run(actions, graphs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (actions.length === 0) {
+                throw new Error("No actions provided");
+            }
+            // Create a mapping of graph names to their definitions for quick lookup.
+            const graphMap = new Map(graphs.map((g) => [g.name, g]));
+            for (const action of actions) {
+                // Retrieve the graph definition based on the action name.
+                const graphDefinition = graphMap.get(action.name);
+                if (!graphDefinition) {
+                    throw new Error(`Graph not found: ${action.name}`);
+                }
+                // Initialize the graph engine with the selected graph definition.
+                const graph = new engine_1.GraphEngine(graphDefinition, {
+                    schema: graphDefinition.schema,
+                    autoDetectCycles: true,
+                });
+                // Construct the initial state from action parameters.
+                const initialState = {
+                    context: action.parameters.reduce((acc, param) => {
+                        acc[param.name] = param.value;
+                        return acc;
+                    }, {}),
+                };
+                // Execute the graph starting from the defined entry node.
+                yield graph.execute(initialState, graphDefinition.entryNode);
+                // Retrieve the final state after execution.
+                const result = graph.getState();
+                if (!result) {
+                    throw new Error("Workflow execution failed to return a state");
+                }
+                return result;
+            }
+        });
+    }
+}
+exports.GraphController = GraphController;

package/dist/graph/engine.js

@@ -0,0 +1,563 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphEngine = void 0;
+const dotenv_1 = require("dotenv");
+const events_1 = __importDefault(require("events"));
+const zod_1 = require("zod");
+(0, dotenv_1.configDotenv)();
+/**
+ * Represents a directed worflow structure capable of executing nodes in sequence or parallel.
+ * The worflow can handle state management, event emissions, and conditional execution paths.
+ *
+ * @template T - The type of data stored in the worflow's context
+ */
+class GraphEngine {
+    /**
+     * Creates a new Graph instance.
+     *
+     * @param {GraphDefinition<T>} [definition] - Initial worflow structure and configuration
+     * @param {Object} [config] - Additional configuration options
+     * @param {boolean} [config.autoDetectCycles] - Whether to check for cycles during initialization
+     * @throws {Error} If cycles are detected when autoDetectCycles is true
+     */
+    constructor(definition, options) {
+        this.name = (definition === null || definition === void 0 ? void 0 : definition.name) || "anonymous";
+        this.eventEmitter = new events_1.default();
+        this.globalContext = new Map();
+        this.nodes = new Map();
+        this.executedNodes = new Set();
+        this.persistence = null;
+        this.notifier = null;
+        this.schema = options === null || options === void 0 ? void 0 : options.schema;
+        this.currentState = { context: {} };
+        if (definition) {
+            this.loadFromDefinition(definition);
+        }
+        if ((options === null || options === void 0 ? void 0 : options.autoDetectCycles) && this.checkForCycles()) {
+            throw new Error("Cycle detected in the workflow");
+        }
+        if (options === null || options === void 0 ? void 0 : options.initialState) {
+            this.setState(options.initialState);
+        }
+    }
+    /**
+     * Adds a value to the global context.
+     * @param {string} key - The key to store the value under
+     * @param {any} value - The value to store
+     */
+    addToContext(key, value) {
+        this.globalContext.set(key, value);
+    }
+    /**
+     * Retrieves a value from the global context.
+     * @param {string} key - The key to retrieve
+     * @returns {any} The stored value, or undefined if not found
+     */
+    getContext(key) {
+        return this.globalContext.get(key);
+    }
+    /**
+     * Removes a value from the global context.
+     * @param {string} key - The key to remove
+     */
+    removeFromContext(key) {
+        this.globalContext.delete(key);
+    }
+    /**
+     * Sets the persistence layer for the worflow.
+     * @param {Persistence<T>} persistence - The persistence implementation
+     */
+    setPersistence(persistence) {
+        this.persistence = persistence;
+    }
+    /**
+     * Sets the real-time notifier for the worflow.
+     * @param {RealTimeNotifier} notifier - The notifier implementation
+     */
+    setNotifier(notifier) {
+        this.notifier = notifier;
+    }
+    /**
+     * Loads a worflow structure from a definition object.
+     * @private
+     * @param {GraphDefinition<T>} definition - The worflow definition
+     */
+    loadFromDefinition(definition) {
+        Object.entries(definition.nodes).forEach(([_, nodeConfig]) => {
+            this.addNode(nodeConfig, {
+                condition: nodeConfig.condition,
+                relationships: nodeConfig.relationships,
+            });
+        });
+    }
+    /**
+     * Recursively checks if a node is part of a cycle.
+     * @private
+     * @param {string} nodeName - The name of the node to check
+     * @param {Set<string>} visited - Set of visited nodes
+     * @param {Set<string>} recStack - Set of nodes in the current recursion stack
+     * @returns {boolean} True if a cycle is detected, false otherwise
+     */
+    isCyclic(nodeName, visited, recStack) {
+        if (!visited.has(nodeName)) {
+            visited.add(nodeName);
+            recStack.add(nodeName);
+            const currentNode = this.nodes.get(nodeName);
+            if (currentNode === null || currentNode === void 0 ? void 0 : currentNode.relationships) {
+                for (const relation of currentNode.relationships) {
+                    const targetNode = relation.name;
+                    if (!visited.has(targetNode) &&
+                        this.isCyclic(targetNode, visited, recStack)) {
+                        return true;
+                    }
+                    else if (recStack.has(targetNode)) {
+                        return true;
+                    }
+                }
+            }
+        }
+        recStack.delete(nodeName);
+        return false;
+    }
+    /**
+     * Checks if the worflow contains any cycles.
+     * @returns {boolean} True if cycles are detected, false otherwise
+     */
+    checkForCycles() {
+        const visited = new Set();
+        const recStack = new Set();
+        for (const nodeName of this.nodes.keys()) {
+            if (this.isCyclic(nodeName, visited, recStack)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Adds a new node to the worflow.
+     * @param {Node<T>} node - The node to add
+     * @param {Object} options - Node configuration options
+     * @param {Function} [options.condition] - Condition function for node execution
+     * @param {string[]} [options.relations] - Array of relations node names
+     * @param {string[]} [options.events] - Array of event names to listen for
+     */
+    addNode(node, { condition, relationships, events, }) {
+        node.relationships = relationships;
+        node.condition = condition;
+        if (events) {
+            events.forEach((event) => {
+                this.eventEmitter.on(event, (data) => __awaiter(this, void 0, void 0, function* () {
+                    const state = data.state || {};
+                    yield this.execute(state, node.name);
+                }));
+            });
+        }
+        this.nodes.set(node.name, node);
+    }
+    /**
+     * Emits an event to the worflow's event emitter.
+     * @param {string} eventName - Name of the event to emit
+     * @param {any} data - Data to pass with the event
+     */
+    emit(eventName, data) {
+        this.eventEmitter.emit(eventName, data);
+    }
+    /**
+     * Adds a subworflow as a node in the current worflow.
+     * @param {Graph<T>} subGraph - The subworflow to add
+     * @param {string} entryNode - The entry node name in the subworflow
+     * @param {string} name - The name for the subworflow node
+     */
+    addSubGraph(subGraph, entryNode, name) {
+        const subGraphNode = {
+            name: name,
+            execute: (state) => __awaiter(this, void 0, void 0, function* () {
+                yield subGraph.execute(state, entryNode);
+                return state;
+            }),
+        };
+        this.nodes.set(name, subGraphNode);
+    }
+    /**
+     * Executes the worflow starting from a specific node.
+     * @param {SharedState<T>} state - The initial state
+     * @param {string} startNode - The name of the starting node
+     * @param {Function} [onStream] - Callback for streaming state updates
+     * @param {Function} [onError] - Callback for handling errors
+     */
+    execute(state, startNode, onStream, onError) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            try {
+                if (this.schema) {
+                    try {
+                        this.schema.parse(state.context);
+                    }
+                    catch (error) {
+                        const validationError = new Error(`Initial state validation failed: ${error instanceof Error ? error.message : error}`);
+                        if (onError)
+                            onError(validationError, startNode, state);
+                        throw validationError;
+                    }
+                }
+                this.setState(state);
+                let currentNodeName = startNode;
+                while (currentNodeName) {
+                    this.executedNodes.add(currentNodeName);
+                    const currentNode = this.nodes.get(currentNodeName);
+                    if (!currentNode)
+                        throw new Error(`Node ${currentNodeName} not found.`);
+                    if (currentNode.condition &&
+                        !currentNode.condition(this.currentState)) {
+                        break;
+                    }
+                    try {
+                        if (this.notifier) {
+                            this.notifier.notify("nodeExecutionStarted", {
+                                workflow: this.name,
+                                node: currentNodeName,
+                            });
+                        }
+                        const params = (_a = currentNode.schema) === null || _a === void 0 ? void 0 : _a.parse(this.currentState);
+                        const newState = yield currentNode.execute(params || {}, this.currentState);
+                        if (newState) {
+                            this.setState(newState);
+                            if (onStream)
+                                onStream(this.currentState);
+                        }
+                        if (this.persistence) {
+                            yield this.persistence.saveState(this.name, this.currentState, currentNodeName);
+                        }
+                        if (this.notifier) {
+                            yield this.notifier.notify("nodeExecutionCompleted", {
+                                workflow: this.name,
+                                node: currentNodeName,
+                                state: this.currentState,
+                            });
+                        }
+                    }
+                    catch (error) {
+                        if (onError)
+                            onError(error, currentNodeName, this.currentState);
+                        if (this.notifier) {
+                            this.notifier.notify("nodeExecutionFailed", {
+                                workflow: this.name,
+                                node: currentNodeName,
+                                state: this.currentState,
+                                error,
+                            });
+                        }
+                        break;
+                    }
+                    const relationsNodes = currentNode.relationships || [];
+                    if (relationsNodes.length > 1) {
+                        yield Promise.all(relationsNodes.map((relation) => this.execute(this.currentState, relation.name, onStream, onError)));
+                        break;
+                    }
+                    else {
+                        currentNodeName = ((_b = relationsNodes[0]) === null || _b === void 0 ? void 0 : _b.name) || "";
+                    }
+                }
+                return this.getState();
+            }
+            catch (error) {
+                if (onError) {
+                    onError(error, startNode, state);
+                }
+                throw error;
+            }
+        });
+    }
+    /**
+     * Executes multiple nodes in parallel with a concurrency limit.
+     * @param {SharedState<T>} state - The shared state
+     * @param {string[]} nodeNames - Array of node names to execute
+     * @param {number} [concurrencyLimit=5] - Maximum number of concurrent executions
+     * @param {Function} [onStream] - Callback for streaming state updates
+     * @param {Function} [onError] - Callback for handling errors
+     */
+    executeParallel(state_1, nodeNames_1) {
+        return __awaiter(this, arguments, void 0, function* (state, nodeNames, concurrencyLimit = 5, onStream, onError) {
+            const executeWithLimit = (nodeName) => __awaiter(this, void 0, void 0, function* () {
+                yield this.execute(state, nodeName, onStream, onError);
+            });
+            const chunks = [];
+            for (let i = 0; i < nodeNames.length; i += concurrencyLimit) {
+                chunks.push(nodeNames.slice(i, i + concurrencyLimit));
+            }
+            for (const chunk of chunks) {
+                yield Promise.all(chunk.map(executeWithLimit));
+            }
+        });
+    }
+    /**
+     * Updates the worflow structure with a new definition.
+     * @param {GraphDefinition<T>} definition - The new worflow definition
+     */
+    updateGraph(definition) {
+        Object.entries(definition.nodes).forEach(([_, nodeConfig]) => {
+            if (this.nodes.has(nodeConfig.name)) {
+                const existingNode = this.nodes.get(nodeConfig.name);
+                existingNode.relationships =
+                    nodeConfig.relationships || existingNode.relationships;
+                existingNode.condition = nodeConfig.condition || existingNode.condition;
+            }
+            else {
+                this.addNode(nodeConfig, {
+                    condition: nodeConfig.condition,
+                    relationships: nodeConfig.relationships,
+                });
+            }
+        });
+    }
+    /**
+     * Replace the worflow with a new definition.
+     * @param {GraphDefinition<T>} definition - The new worflow definition
+     */
+    replaceGraph(definition) {
+        this.nodes.clear();
+        this.loadFromDefinition(definition);
+    }
+    /**
+     * Generates a visual representation of the worflow using Mermaid diagram syntax.
+     * The diagram shows all nodes and their connections, with special highlighting for:
+     * - Entry nodes (green)
+     * - Event nodes (yellow)
+     * - Conditional nodes (orange)
+     *
+     * @param {string} [title] - Optional title for the diagram
+     * @returns {string} Mermaid diagram syntax representing the worflow
+     */
+    generateMermaidDiagram(title) {
+        const lines = ["flowchart TD"];
+        if (title) {
+            lines.push(`  subgraph ${title}`);
+        }
+        // Add nodes with styling
+        this.nodes.forEach((node, nodeName) => {
+            const hasEvents = node.events && node.events.length > 0;
+            const hasCondition = !!node.condition;
+            // Style nodes based on their properties
+            let style = "";
+            if (hasEvents) {
+                style = "style " + nodeName + " fill:#FFD700,stroke:#DAA520"; // Yellow for event nodes
+            }
+            else if (hasCondition) {
+                style = "style " + nodeName + " fill:#FFA500,stroke:#FF8C00"; // Orange for conditional nodes
+            }
+            // Add node definition
+            lines.push(`  ${nodeName}[${nodeName}]`);
+            if (style) {
+                lines.push(`  ${style}`);
+            }
+        });
+        // Add connections
+        this.nodes.forEach((node, nodeName) => {
+            if (node.relationships) {
+                node.relationships.forEach((relationsNode) => {
+                    let connectionStyle = "";
+                    if (node.condition) {
+                        connectionStyle = "---|condition|"; // Add label for conditional connections
+                    }
+                    else {
+                        connectionStyle = "-->"; // Normal connection
+                    }
+                    lines.push(`  ${nodeName} ${connectionStyle} ${relationsNode}`);
+                });
+            }
+            // Add event connections if any
+            if (node.events && node.events.length > 0) {
+                node.events.forEach((event) => {
+                    const eventNodeId = `${event}_event`;
+                    lines.push(`  ${eventNodeId}((${event})):::event`);
+                    lines.push(`  ${eventNodeId} -.->|trigger| ${nodeName}`);
+                });
+                // Add style class for event nodes
+                lines.push("  classDef event fill:#FFD700,stroke:#DAA520");
+            }
+        });
+        if (title) {
+            lines.push("  end");
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Renders the worflow visualization using Mermaid syntax.
+     * This method can be used to visualize the worflow structure in supported environments.
+     *
+     * @param {string} [title] - Optional title for the visualization
+     */
+    visualize(title) {
+        const diagram = this.generateMermaidDiagram(title);
+        console.log("To visualize this worflow, use a Mermaid-compatible renderer with this syntax:");
+        console.log("\n```mermaid");
+        console.log(diagram);
+        console.log("```\n");
+    }
+    exportGraphToJson(worflow) {
+        const result = {
+            worflowName: worflow.name,
+            entryNode: worflow.entryNode,
+            nodes: Object.entries(worflow.nodes).reduce((acc, [key, node]) => {
+                acc[key] = {
+                    name: node.name,
+                    description: node.description || "No description provided",
+                    execute: node.execute.name,
+                    condition: node.condition ? node.condition.toString() : "None",
+                    relationships: node.relationships || [],
+                };
+                return acc;
+            }, {}),
+        };
+        return JSON.stringify(result, null, 2);
+    }
+    /**
+     * Generates a visual representation of the workflow schema.
+     * Displays the structure of the data expected for each node.
+     *
+     * @returns {string} A formatted string describing the workflow schema
+     */
+    visualizeSchema() {
+        const output = [];
+        output.push(`📋 Graph: ${this.name}`);
+        output.push("=".repeat(50));
+        if (this.schema) {
+            output.push("🔷 Global Schema:");
+            output.push("-".repeat(30));
+            if (this.schema instanceof zod_1.z.ZodObject) {
+                const shape = this.schema.shape;
+                Object.entries(shape).forEach(([key, value]) => {
+                    const description = this.describeZodType(value, 1);
+                    output.push(`${key}:`);
+                    output.push(description);
+                });
+            }
+            output.push("");
+        }
+        output.push("🔷 Nodes:");
+        output.push("-".repeat(30));
+        this.nodes.forEach((node, nodeName) => {
+            output.push(`\n📍 Node: ${nodeName}`);
+            output.push(`Description: ${node.description || "No description provided"}`);
+            if (node.relationships && node.relationships.length > 0) {
+                output.push(`Next nodes: ${node.relationships.join(", ")}`);
+            }
+            output.push("");
+        });
+        return output.join("\n");
+    }
+    /**
+     * Recursively describes a Zod type.
+     */
+    describeZodType(type, indent = 0) {
+        const padding = "  ".repeat(indent);
+        if (type instanceof zod_1.z.ZodObject) {
+            const shape = type.shape;
+            const lines = [];
+            Object.entries(shape).forEach(([key, value]) => {
+                const isOptional = value instanceof zod_1.z.ZodOptional;
+                const actualType = isOptional
+                    ? value.unwrap()
+                    : value;
+                const description = this.describeZodType(actualType, indent + 1);
+                lines.push(`${padding}${key}${isOptional ? "?" : ""}: ${description}`);
+            });
+            return lines.join("\n");
+        }
+        if (type instanceof zod_1.z.ZodArray) {
+            const elementType = this.describeZodType(type.element, indent);
+            return `Array<${elementType}>`;
+        }
+        if (type instanceof zod_1.z.ZodString) {
+            const checks = type._def.checks || [];
+            const constraints = checks
+                .map((check) => {
+                if (check.kind === "url")
+                    return "url";
+                if (check.kind === "email")
+                    return "email";
+                return check.kind;
+            })
+                .join(", ");
+            return constraints ? `string (${constraints})` : "string";
+        }
+        if (type instanceof zod_1.z.ZodNumber) {
+            return "number";
+        }
+        if (type instanceof zod_1.z.ZodBoolean) {
+            return "boolean";
+        }
+        if (type instanceof zod_1.z.ZodOptional) {
+            return `${this.describeZodType(type.unwrap(), indent)} (optional)`;
+        }
+        return type.constructor.name.replace("Zod", "") || "unknown";
+    }
+    /**
+     * Updates the state of a node.
+     * @param {SharedState<T>} state - The current state
+     * @param {Partial<T>} updates - The updates to apply
+     * @returns {SharedState<T>} The updated state
+     */
+    updateNodeState(state, updates) {
+        return Object.assign(Object.assign({}, state), { context: Object.assign(Object.assign({}, (state.context || {})), updates) });
+    }
+    /**
+     * Retrieves the current state of the workflow.
+     * @returns {SharedState<T>} The current state
+     */
+    getState() {
+        return this.currentState;
+    }
+    /**
+     * Sets the state of the workflow.
+     * @param {Partial<SharedState<T>>} state - The new state
+     */
+    setState(state) {
+        this.currentState = this.mergeStates(this.currentState, state);
+        if (state.context) {
+            Object.entries(state.context).forEach(([key, value]) => {
+                this.globalContext.set(key, value);
+            });
+        }
+        const currentNode = Array.from(this.executedNodes).pop();
+        if (currentNode) {
+            const node = this.nodes.get(currentNode);
+            if (node) {
+                node.state = Object.assign(Object.assign({}, (node.state || {})), (state.context || {}));
+            }
+        }
+    }
+    /**
+     * Merges two states.
+     * @param {SharedState<T>} currentState - The current state
+     * @param {Partial<SharedState<T>>} newState - The new state
+     * @returns {SharedState<T>} The merged state
+     */
+    mergeStates(currentState, newState) {
+        return Object.assign(Object.assign({}, currentState), { context: Object.assign(Object.assign({}, (currentState.context || {})), (newState.context || {})) });
+    }
+    /**
+     * Updates the state of the workflow.
+     * @param {Partial<SharedState<T>>} updates - The updates to apply
+     * @returns {SharedState<T>} The updated state
+     */
+    updateState(updates) {
+        const currentState = this.getState();
+        const newState = Object.assign(Object.assign({}, currentState), { context: Object.assign(Object.assign({}, currentState.context), (updates.context || {})) });
+        this.setState(newState);
+        return newState;
+    }
+}
+exports.GraphEngine = GraphEngine;

package/dist/index.js

@@ -14,10 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./agent"), exports);
-__exportStar(require("./llm/interpreter"), exports);
-__exportStar(require("./llm/interpreter/context"), exports);
-__exportStar(require("./llm/orchestrator"), exports);
+__exportStar(require("./graph/controller"), exports);
+__exportStar(require("./graph/engine"), exports);
+__exportStar(require("./memory"), exports);
+__exportStar(require("./memory/adapters/meilisearch"), exports);
+__exportStar(require("./memory/adapters/redis"), exports);
+__exportStar(require("./interfaces"), exports);
 __exportStar(require("./types"), exports);
-__exportStar(require("./memory/cache"), exports);
-__exportStar(require("./memory/persistent"), exports);