@ai.ntellect/core 0.6.17 → 0.6.19

package/dist/graph/index.js

@@ -8,74 +8,159 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         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.Graph = void 0;
-const events_1 = __importDefault(require("events"));
-class Graph {
+exports.GraphFlow = void 0;
+const events_1 = require("events");
+/**
+ * @module GraphFlow
+ * @description A flexible workflow engine that manages the execution of nodes in a graph-like structure.
+ *
+ * Key features:
+ * - Multiple branches support
+ * - Conditional branching (runs first matching condition, or all if none have conditions)
+ * - Event-driven nodes
+ * - Zod validation of context/inputs/outputs
+ * - Automatic retry on node failures
+ *
+ * @template T - Extends ZodSchema for type validation
+ */
+class GraphFlow {
+    /**
+     * Creates a new instance of GraphFlow
+     * @param {string} name - The name of the graph flow
+     * @param {GraphDefinition<T>} config - Configuration object containing nodes, schema, context, and error handlers
+     */
     constructor(name, config) {
         this.name = name;
         this.nodes = new Map(config.nodes.map((node) => [node.name, node]));
-        this.context = config.initialContext || {};
-        this.validator = config.validator;
-        this.globalErrorHandler = config.globalErrorHandler;
-        this.eventEmitter = new events_1.default();
+        this.validator = config.schema;
+        this.context = config.schema.parse(config.context);
+        this.globalErrorHandler = config.onError;
+        this.eventEmitter = config.eventEmitter || new events_1.EventEmitter();
+        this.graphEvents = config.events;
         this.setupEventListeners();
+        this.setupGraphEventListeners();
     }
+    /**
+     * Creates a new context for execution
+     * @private
+     * @returns {GraphContext<T>} A cloned context to prevent pollution during parallel execution
+     */
     createNewContext() {
         return structuredClone(this.context);
     }
+    /**
+     * Sets up event listeners for node-based events
+     * @private
+     * @description Attaches all node-based event triggers while preserving external listeners
+     */
     setupEventListeners() {
-        var _a;
+        // First remove only the existing node-based listeners that we might have created previously
+        // We do NOT remove, for example, "nodeStarted" or "nodeCompleted" listeners that test code added.
+        for (const [eventName, listener] of this.eventEmitter
+            .rawListeners("*")
+            .entries()) {
+            // This can be tricky—EventEmitter doesn't directly let you remove by "type" of listener.
+            // Alternatively, we can store references in a separate structure.
+            // For simplicity, let's do a full removeAllListeners() on node-specified events (only),
+            // then re-add them below, but keep the test-based events like "nodeStarted" or "nodeCompleted".
+        }
+        // The simplest approach: removeAllListeners for each event that is declared as a node event
+        // so we don't stack up duplicates:
+        const allEvents = new Set();
         for (const node of this.nodes.values()) {
-            (_a = node.events) === null || _a === void 0 ? void 0 : _a.forEach((event) => {
-                this.eventEmitter.on(event, (data) => __awaiter(this, void 0, void 0, function* () {
-                    const context = this.createNewContext();
-                    if (data)
-                        Object.assign(context, data);
-                    yield this.executeNode(node.name, context);
-                }));
-            });
+            if (node.events) {
+                node.events.forEach((evt) => allEvents.add(evt));
+            }
+        }
+        for (const evt of allEvents) {
+            // remove only those events that are used by nodes
+            this.eventEmitter.removeAllListeners(evt);
+        }
+        // Now re-add the node-based event triggers
+        for (const node of this.nodes.values()) {
+            if (node.events && node.events.length > 0) {
+                node.events.forEach((event) => {
+                    this.eventEmitter.on(event, (data) => __awaiter(this, void 0, void 0, function* () {
+                        const freshContext = this.createNewContext();
+                        if (data)
+                            Object.assign(freshContext, data);
+                        // If triggered by an event, we pass "true" so event-driven node will skip `next`.
+                        yield this.executeNode(node.name, freshContext, undefined, 
+                        /* triggeredByEvent= */ true);
+                    }));
+                });
+            }
         }
     }
-    executeNode(nodeName, context, params) {
-        return __awaiter(this, void 0, void 0, function* () {
+    /**
+     * Executes a specific node in the graph
+     * @private
+     * @param {string} nodeName - Name of the node to execute
+     * @param {GraphContext<T>} context - Current execution context
+     * @param {any} inputs - Input parameters for the node
+     * @param {boolean} triggeredByEvent - Whether the execution was triggered by an event
+     * @returns {Promise<void>}
+     */
+    executeNode(nodeName_1, context_1, inputs_1) {
+        return __awaiter(this, arguments, void 0, function* (nodeName, context, inputs, triggeredByEvent = false) {
             var _a, _b, _c, _d;
             const node = this.nodes.get(nodeName);
             if (!node)
-                throw new Error(`❌ Node ${nodeName} not found`);
-            if (node.condition && !node.condition(context))
+                throw new Error(`❌ Node "${nodeName}" not found.`);
+            if (node.condition && !node.condition(context)) {
                 return;
+            }
             let attempts = 0;
             const maxAttempts = ((_a = node.retry) === null || _a === void 0 ? void 0 : _a.maxAttempts) || 1;
             const delay = ((_b = node.retry) === null || _b === void 0 ? void 0 : _b.delay) || 0;
             while (attempts < maxAttempts) {
                 try {
-                    let validatedParams;
-                    // ✅ Si le nœud a un `parameters`, on valide `params` avant exécution
-                    if (node.parameters) {
-                        if (!params) {
-                            throw new Error(`❌ Paramètres requis pour le nœud "${nodeName}" mais reçus: ${params}`);
+                    let validatedInputs;
+                    if (node.inputs) {
+                        if (!inputs) {
+                            throw new Error(`❌ Inputs required for node "${nodeName}" but received: ${inputs}`);
                         }
-                        validatedParams = node.parameters.parse(params);
+                        validatedInputs = node.inputs.parse(inputs);
                     }
                     this.eventEmitter.emit("nodeStarted", { name: nodeName, context });
-                    if (node.execute) {
-                        yield node.execute(context);
-                    }
-                    else if (node.executeWithParams) {
-                        if (!validatedParams) {
-                            throw new Error(`❌ Paramètres invalides pour le nœud "${nodeName}"`);
-                        }
-                        yield node.executeWithParams(context, validatedParams);
+                    // Execute the node
+                    yield node.execute(context, validatedInputs);
+                    if (node.outputs) {
+                        node.outputs.parse(context);
                     }
                     this.validateContext(context);
                     this.eventEmitter.emit("nodeCompleted", { name: nodeName, context });
-                    if (node.next) {
-                        yield Promise.all(node.next.map((nextNode) => this.executeNode(nextNode, context)));
+                    // IMPORTANT: Si le nœud est déclenché par un événement et a des événements définis,
+                    // on arrête ici et on ne suit pas la chaîne next
+                    if (triggeredByEvent && node.events && node.events.length > 0) {
+                        this.context = structuredClone(context);
+                        return;
+                    }
+                    // Gérer les nœuds suivants
+                    if (node.next && node.next.length > 0) {
+                        const branchContexts = [];
+                        // Exécuter toutes les branches valides
+                        for (const nextNodeName of node.next) {
+                            const nextNode = this.nodes.get(nextNodeName);
+                            if (!nextNode)
+                                continue;
+                            const branchContext = structuredClone(context);
+                            // Si le nœud a une condition et qu'elle n'est pas remplie, passer au suivant
+                            if (nextNode.condition && !nextNode.condition(branchContext)) {
+                                continue;
+                            }
+                            yield this.executeNode(nextNodeName, branchContext);
+                            branchContexts.push(branchContext);
+                        }
+                        // Fusionner les résultats des branches dans l'ordre
+                        if (branchContexts.length > 0) {
+                            const finalContext = branchContexts[branchContexts.length - 1];
+                            Object.assign(context, finalContext);
+                        }
                     }
+                    // Mettre à jour le contexte global
+                    this.context = structuredClone(context);
                     return;
                 }
                 catch (error) {
@@ -92,71 +177,226 @@ class Graph {
             }
         });
     }
+    /**
+     * Validates the current context against the schema
+     * @private
+     * @param {GraphContext<T>} context - Context to validate
+     * @throws {Error} If validation fails
+     */
     validateContext(context) {
         if (this.validator) {
             this.validator.parse(context);
         }
     }
+    /**
+     * Executes the graph flow starting from a specific node
+     * @param {string} startNode - Name of the node to start execution from
+     * @param {Partial<GraphContext<T>>} inputContext - Optional partial context to merge with current context
+     * @param {any} inputParams - Optional input parameters for the start node
+     * @returns {Promise<GraphContext<T>>} Final context after execution
+     */
     execute(startNode, inputContext, inputParams) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
+            // Fresh local context from the global
             const context = this.createNewContext();
             if (inputContext)
                 Object.assign(context, inputContext);
+            // Emit "graphStarted"
             this.eventEmitter.emit("graphStarted", { name: this.name });
             try {
-                yield this.executeNode(startNode, context, inputParams);
-                this.eventEmitter.emit("graphCompleted", { name: this.name, context });
-                return context;
+                // Because we're calling explicitly, it's NOT triggered by an event
+                yield this.executeNode(startNode, context, inputParams, 
+                /* triggeredByEvent= */ false);
+                // Emit "graphCompleted"
+                this.eventEmitter.emit("graphCompleted", {
+                    name: this.name,
+                    context: this.context,
+                });
+                // Return a snapshot of the final global context
+                return structuredClone(this.context);
             }
             catch (error) {
+                // Emit "graphError"
                 this.eventEmitter.emit("graphError", { name: this.name, error });
-                (_a = this.globalErrorHandler) === null || _a === void 0 ? void 0 : _a.call(this, error, context); // Gestionnaire d'erreurs global
+                (_a = this.globalErrorHandler) === null || _a === void 0 ? void 0 : _a.call(this, error, context);
                 throw error;
             }
         });
     }
+    /**
+     * Emits an event to trigger event-based nodes
+     * @param {string} eventName - Name of the event to emit
+     * @param {Partial<GraphContext<T>>} data - Optional data to merge with context
+     * @returns {Promise<GraphContext<T>>} Updated context after event handling
+     */
     emit(eventName, data) {
-        return new Promise((resolve, reject) => {
+        return __awaiter(this, void 0, void 0, function* () {
+            // Merge data into a fresh copy of the global context if desired
+            const context = this.createNewContext();
             if (data)
-                Object.assign(this.context, data); // ✅ Met à jour le contexte global
-            this.eventEmitter.emit(eventName, this.context); // Utilise le contexte global
-            const eventNodes = Array.from(this.nodes.values()).filter((node) => { var _a; return (_a = node.events) === null || _a === void 0 ? void 0 : _a.includes(eventName); });
-            if (eventNodes.length === 0)
-                return resolve(this.context);
-            Promise.all(eventNodes.map((node) => new Promise((resolve) => {
-                this.eventEmitter.once("nodeCompleted", ({ nodeName }) => {
-                    if (nodeName === node.name)
-                        resolve();
-                });
-            })))
-                .then(() => resolve(this.context))
-                .catch(reject);
+                Object.assign(context, data);
+            // Just emit the event; the node-based event listeners in setupEventListeners()
+            // will handle calling "executeNode(...)"
+            this.eventEmitter.emit(eventName, context);
+            // Return the updated global context
+            return this.getContext();
         });
     }
+    /**
+     * Registers an event handler
+     * @param {string} eventName - Name of the event to listen for
+     * @param {Function} handler - Handler function to execute when event is emitted
+     */
     on(eventName, handler) {
         this.eventEmitter.on(eventName, handler);
     }
-    loadDefinition(definition) {
+    /**
+     * Updates the graph definition with new configuration
+     * @param {GraphDefinition<T>} definition - New graph definition
+     */
+    load(definition) {
+        var _a;
+        // Clear all existing nodes
         this.nodes.clear();
-        Object.values(definition.nodes).forEach((node) => this.nodes.set(node.name, node));
-        this.setupEventListeners();
+        // Wipe out old node-based event listeners
+        // (We keep external test listeners like "nodeStarted" or "nodeCompleted".)
+        if ((_a = definition.nodes) === null || _a === void 0 ? void 0 : _a.length) {
+            const allEvents = new Set();
+            definition.nodes.forEach((n) => { var _a; return (_a = n.events) === null || _a === void 0 ? void 0 : _a.forEach((evt) => allEvents.add(evt)); });
+            for (const evt of allEvents) {
+                this.eventEmitter.removeAllListeners(evt);
+            }
+        }
+        // Add in new nodes
+        definition.nodes.forEach((node) => this.nodes.set(node.name, node));
+        // Parse the new context
+        this.context = definition.schema.parse(definition.context);
+        this.validator = definition.schema;
+        // Store entry node
+        this.entryNode = definition.entryNode;
+        // Store graph events
+        this.graphEvents = definition.events;
+        // Re-setup only node-based event triggers
+        for (const node of this.nodes.values()) {
+            if (node.events && node.events.length > 0) {
+                node.events.forEach((event) => {
+                    this.eventEmitter.on(event, (data) => __awaiter(this, void 0, void 0, function* () {
+                        const freshContext = structuredClone(this.context);
+                        if (data)
+                            Object.assign(freshContext, data);
+                        yield this.executeNode(node.name, freshContext, undefined, true);
+                    }));
+                });
+            }
+        }
+        // Re-setup graph event listeners
+        this.setupGraphEventListeners();
     }
+    /**
+     * Returns the current context
+     * @returns {GraphContext<T>} Current graph context
+     */
     getContext() {
         return structuredClone(this.context);
     }
+    /**
+     * Logs a message with optional data
+     * @param {string} message - Message to log
+     * @param {any} data - Optional data to log
+     */
     log(message, data) {
         console.log(`[Graph ${this.name}] ${message}`, data);
     }
+    /**
+     * Adds a new node to the graph
+     * @param {Node<T>} node - Node to add
+     * @throws {Error} If node with same name already exists
+     */
     addNode(node) {
         this.nodes.set(node.name, node);
-        this.setupEventListeners();
+        if (node.events && node.events.length > 0) {
+            for (const evt of node.events) {
+                this.eventEmitter.on(evt, (data) => __awaiter(this, void 0, void 0, function* () {
+                    const freshContext = this.createNewContext();
+                    if (data)
+                        Object.assign(freshContext, data);
+                    yield this.executeNode(node.name, freshContext, undefined, true);
+                }));
+            }
+        }
     }
+    /**
+     * Removes a node from the graph
+     * @param {string} nodeName - Name of the node to remove
+     */
     removeNode(nodeName) {
+        const node = this.nodes.get(nodeName);
+        if (!node)
+            return;
+        // remove the node from the map
         this.nodes.delete(nodeName);
+        // remove any of its event-based listeners
+        if (node.events && node.events.length > 0) {
+            for (const evt of node.events) {
+                // removeAllListeners(evt) would also remove other node listeners,
+                // so we need a more fine-grained approach. Ideally, we should keep a reference
+                // to the exact listener function we attached. For brevity, let's remove all for that event:
+                this.eventEmitter.removeAllListeners(evt);
+            }
+            // Then reattach the others that remain in the graph
+            for (const n of this.nodes.values()) {
+                if (n.events && n.events.length > 0) {
+                    n.events.forEach((e) => {
+                        this.eventEmitter.on(e, (data) => __awaiter(this, void 0, void 0, function* () {
+                            const freshContext = this.createNewContext();
+                            if (data)
+                                Object.assign(freshContext, data);
+                            yield this.executeNode(n.name, freshContext, undefined, true);
+                        }));
+                    });
+                }
+            }
+        }
     }
+    /**
+     * Returns all nodes in the graph
+     * @returns {Node<T>[]} Array of all nodes
+     */
     getNodes() {
         return Array.from(this.nodes.values());
     }
+    setupGraphEventListeners() {
+        if (this.graphEvents && this.graphEvents.length > 0) {
+            this.graphEvents.forEach((event) => {
+                this.eventEmitter.on(event, (data) => __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    const freshContext = this.createNewContext();
+                    if (data)
+                        Object.assign(freshContext, data);
+                    // Emit "graphStarted"
+                    this.eventEmitter.emit("graphStarted", { name: this.name });
+                    try {
+                        // Execute the graph starting from the entry node
+                        if (!this.entryNode) {
+                            throw new Error("No entry node defined for graph event handling");
+                        }
+                        yield this.executeNode(this.entryNode, freshContext, undefined, false);
+                        // Emit "graphCompleted"
+                        this.eventEmitter.emit("graphCompleted", {
+                            name: this.name,
+                            context: this.context,
+                        });
+                    }
+                    catch (error) {
+                        // Emit "graphError"
+                        this.eventEmitter.emit("graphError", { name: this.name, error });
+                        (_a = this.globalErrorHandler) === null || _a === void 0 ? void 0 : _a.call(this, error, freshContext);
+                        throw error;
+                    }
+                }));
+            });
+        }
+    }
 }
-exports.Graph = Graph;
+exports.GraphFlow = GraphFlow;

package/dist/index.js

@@ -1,4 +1,16 @@
 "use strict";
+/**
+ * @module @ai.ntellect/core
+ * @description Core module with workflow functionality, providing graph management,
+ * memory storage, agenda scheduling, and embedding capabilities.
+ *
+ * This module exports various components:
+ * - Graph management and controller
+ * - Memory storage adapters (Meilisearch, Redis)
+ * - Agenda scheduling with node-cron adapter
+ * - Embedding functionality with AI adapter
+ * - Utility functions for action schema generation and header building
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -16,11 +28,14 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./graph"), exports);
 __exportStar(require("./graph/controller"), exports);
-__exportStar(require("./memory"), exports);
-__exportStar(require("./memory/adapters/meilisearch"), exports);
-__exportStar(require("./memory/adapters/redis"), exports);
+__exportStar(require("./modules/memory"), exports);
+__exportStar(require("./modules/memory/adapters/meilisearch"), exports);
+__exportStar(require("./modules/memory/adapters/redis"), exports);
 __exportStar(require("./interfaces"), exports);
-__exportStar(require("./services/agenda"), exports);
-__exportStar(require("./services/embedding"), exports);
+__exportStar(require("./modules/agenda"), exports);
+__exportStar(require("./modules/agenda/adapters/node-cron"), exports);
+__exportStar(require("./modules/embedding"), exports);
+__exportStar(require("./modules/embedding/adapters/ai"), exports);
 __exportStar(require("./types"), exports);
-__exportStar(require("./utils/stringifiy-zod-schema"), exports);
+__exportStar(require("./utils/generate-action-schema"), exports);
+__exportStar(require("./utils/header-builder"), exports);

package/dist/interfaces/index.js

@@ -1,2 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseMemory = void 0;
+/**
+ * Abstract base class for memory implementations
+ * @abstract
+ */
+class BaseMemory {
+    /**
+     * Creates an instance of BaseMemory
+     * @param {IMemoryAdapter} adapter - Memory adapter implementation
+     */
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+}
+exports.BaseMemory = BaseMemory;

package/dist/modules/agenda/adapters/node-cron/index.js

@@ -0,0 +1,29 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeCronAdapter = void 0;
+const node_cron_1 = __importDefault(require("node-cron"));
+/**
+ * @module NodeCronAdapter
+ * @description Adapter implementation for node-cron service.
+ * Provides a bridge between the application's scheduling interface and the node-cron library.
+ * @implements {ICronService}
+ */
+class NodeCronAdapter {
+    /**
+     * Schedules a new cron job
+     * @param {string} expression - Cron expression defining the schedule
+     * @param {Function} callback - Function to be executed when the schedule triggers
+     * @returns {ICronJob} Interface for controlling the scheduled job
+     */
+    schedule(expression, callback) {
+        const job = node_cron_1.default.schedule(expression, callback);
+        return {
+            start: () => job.start(),
+            stop: () => job.stop(),
+        };
+    }
+}
+exports.NodeCronAdapter = NodeCronAdapter;