@ai.ntellect/core 0.7.7 → 1.0.0

package/index.ts

@@ -1,29 +1,469 @@
+import EventEmitter from "events";
+import {
+  Node,
+  Persistence,
+  RealTimeNotifier,
+  SharedState,
+  WorkflowDefinition,
+  mergeState,
+} from "./types";
+
 /**
- * @module @ai.ntellect/core
- * @description Core module with workflow functionality, providing graph management,
- * memory storage, agenda scheduling, and embedding capabilities.
+ * 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.
  *
- * 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
+ * @template T - The type of data stored in the worflow's context
  */
+export class Workflow<T> {
+  /** Stores global context data accessible to all nodes */
+  public globalContext: Map<string, any>;
+
+  /** Event emitter for handling worflow-wide events */
+  private eventEmitter: EventEmitter;
+
+  /** Map of all nodes in the worflow */
+  public nodes: Map<string, Node<T>>;
+
+  /** Set of nodes that have been executed */
+  public executedNodes: Set<string>;
+
+  /** Name identifier for the worflow */
+  public name: string;
+
+  /** Optional persistence layer for saving worflow state */
+  private persistence: Persistence<T> | null;
+
+  /** Optional notifier for real-time updates */
+  private notifier: RealTimeNotifier | null;
+
+  /**
+   * Creates a new Workflow instance.
+   *
+   * @param {WorkflowDefinition<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?: WorkflowDefinition<T>,
+    config?: { autoDetectCycles?: boolean }
+  ) {
+    this.name = definition?.name || "anonymous";
+    this.eventEmitter = new EventEmitter();
+    this.globalContext = new Map();
+    this.nodes = new Map();
+    this.executedNodes = new Set();
+    this.persistence = null;
+    this.notifier = null;
+
+    if (definition) {
+      this.loadFromDefinition(definition);
+    }
+
+    if (config?.autoDetectCycles && this.checkForCycles()) {
+      throw new Error("Cycle detected in the worflow");
+    }
+  }
+  /**
+   * Loads a worflow structure from a definition object.
+   * @private
+   * @param {WorkflowDefinition<T>} definition - The worflow definition
+   */
+  private loadFromDefinition(definition: WorkflowDefinition<T>): void {
+    Object.entries(definition.nodes).forEach(([_, nodeConfig]) => {
+      this.addNode(nodeConfig, {
+        condition: nodeConfig.condition,
+        next: nodeConfig.next,
+      });
+    });
+  }
+
+  /**
+   * 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
+   */
+  private isCyclic(
+    nodeName: string,
+    visited: Set<string>,
+    recStack: Set<string>
+  ): boolean {
+    if (!visited.has(nodeName)) {
+      visited.add(nodeName);
+      recStack.add(nodeName);
+
+      const currentNode = this.nodes.get(nodeName);
+      if (currentNode?.next) {
+        for (const nextNode of currentNode.next) {
+          if (
+            !visited.has(nextNode) &&
+            this.isCyclic(nextNode, visited, recStack)
+          ) {
+            return true;
+          } else if (recStack.has(nextNode)) {
+            return true;
+          }
+        }
+      }
+    }
+    recStack.delete(nodeName);
+    return false;
+  }
+
+  /**
+   * Checks if the worflow contains any cycles.
+   * @returns {boolean} True if cycles are detected, false otherwise
+   */
+  checkForCycles(): boolean {
+    const visited = new Set<string>();
+    const recStack = new Set<string>();
+
+    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.next] - Array of next node names
+   * @param {string[]} [options.events] - Array of event names to listen for
+   */
+  addNode(
+    node: Node<T>,
+    {
+      condition,
+      next,
+      events,
+    }: {
+      condition?: (state: SharedState<T>) => boolean;
+      next?: string[];
+      events?: string[];
+    }
+  ): void {
+    node.next = next;
+    node.condition = condition;
+
+    if (events) {
+      events.forEach((event) => {
+        this.eventEmitter.on(event, async (data) => {
+          console.log(`Event "${event}" received by node "${node.name}"`);
+          const state = data.state || {};
+          await 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: string, data: any): void {
+    console.log(`Event "${eventName}" emitted with data:`, data);
+    this.eventEmitter.emit(eventName, data);
+  }
+
+  /**
+   * Adds a subworflow as a node in the current worflow.
+   * @param {Workflow<T>} subWorkflow - The subworflow to add
+   * @param {string} entryNode - The entry node name in the subworflow
+   * @param {string} name - The name for the subworflow node
+   */
+  addSubWorkflow(
+    subWorkflow: Workflow<T>,
+    entryNode: string,
+    name: string
+  ): void {
+    const subWorkflowNode: Node<T> = {
+      name,
+      execute: async (state) => {
+        console.log(`Executing subworflow: ${name}`);
+        await subWorkflow.execute(state, entryNode);
+        return state;
+      },
+    };
+    this.nodes.set(name, subWorkflowNode);
+  }
+
+  /**
+   * Updates the worflow structure with a new definition.
+   * @param {WorkflowDefinition<T>} definition - The new worflow definition
+   */
+  updateWorkflow(definition: WorkflowDefinition<T>): void {
+    Object.entries(definition.nodes).forEach(([_, nodeConfig]) => {
+      if (this.nodes.has(nodeConfig.name)) {
+        const existingNode = this.nodes.get(nodeConfig.name)!;
+        existingNode.next = nodeConfig.next || existingNode.next;
+        existingNode.condition = nodeConfig.condition || existingNode.condition;
+      } else {
+        this.addNode(nodeConfig, {
+          condition: nodeConfig.condition,
+          next: nodeConfig.next,
+        });
+      }
+    });
+  }
+
+  /**
+   * Replace the worflow with a new definition.
+   * @param {WorkflowDefinition<T>} definition - The new worflow definition
+   */
+  replaceWorkflow(definition: WorkflowDefinition<T>): void {
+    this.nodes.clear();
+    this.loadFromDefinition(definition);
+  }
+
+  /**
+   * 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
+   */
+  async execute(
+    state: SharedState<T>,
+    startNode: string,
+    onStream?: (state: SharedState<T>) => void,
+    onError?: (error: Error, nodeName: string, state: SharedState<T>) => void
+  ): Promise<void> {
+    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(state)) {
+        console.log(
+          `Condition for node "${currentNodeName}" not met. Ending Workflow.`
+        );
+        break;
+      }
+
+      try {
+        if (this.notifier) {
+          this.notifier.notify("nodeExecutionStarted", {
+            worflow: this.name,
+            node: currentNodeName,
+          });
+        }
+
+        console.log(`Executing node: ${currentNodeName}`);
+        const newState = await currentNode.execute(state);
+        Object.assign(state, mergeState(state, newState));
+
+        if (onStream) onStream(state);
+
+        if (this.persistence) {
+          await this.persistence.saveState(this.name, state, currentNodeName);
+        }
+
+        if (this.notifier) {
+          await this.notifier.notify("nodeExecutionCompleted", {
+            worflow: this.name,
+            node: currentNodeName,
+            state,
+          });
+        }
+      } catch (error) {
+        console.error(`Error in node ${currentNodeName}:`, error);
+        if (onError) onError(error as Error, currentNodeName, state);
+        if (this.notifier) {
+          this.notifier.notify("nodeExecutionFailed", {
+            worflow: this.name,
+            node: currentNodeName,
+            state,
+            error,
+          });
+        }
+        break;
+      }
+
+      const nextNodes = currentNode.next || [];
+      if (nextNodes.length > 1) {
+        await Promise.all(
+          nextNodes.map((nextNode) =>
+            this.execute(state, nextNode, onStream, onError)
+          )
+        );
+        break;
+      } else {
+        currentNodeName = nextNodes[0] || "";
+      }
+    }
+
+    console.log(`Workflow completed for node: ${startNode}`);
+  }
+
+  /**
+   * 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
+   */
+  async executeParallel(
+    state: SharedState<T>,
+    nodeNames: string[],
+    concurrencyLimit: number = 5,
+    onStream?: (state: SharedState<T>) => void,
+    onError?: (error: Error, nodeName: string, state: SharedState<T>) => void
+  ): Promise<void> {
+    console.log(`Executing nodes in parallel: ${nodeNames.join(", ")}`);
+
+    const executeWithLimit = async (nodeName: string) => {
+      await 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) {
+      await Promise.all(chunk.map(executeWithLimit));
+    }
+  }
+
+  /**
+   * 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: string, value: any): void {
+    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: string): any {
+    return this.globalContext.get(key);
+  }
+
+  /**
+   * Removes a value from the global context.
+   * @param {string} key - The key to remove
+   */
+  removeFromContext(key: string): void {
+    this.globalContext.delete(key);
+  }
+
+  /**
+   * Sets the persistence layer for the worflow.
+   * @param {Persistence<T>} persistence - The persistence implementation
+   */
+  setPersistence(persistence: Persistence<T>): void {
+    this.persistence = persistence;
+  }
+
+  /**
+   * Sets the real-time notifier for the worflow.
+   * @param {RealTimeNotifier} notifier - The notifier implementation
+   */
+  setNotifier(notifier: RealTimeNotifier): void {
+    this.notifier = notifier;
+  }
+
+  /**
+   * 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?: string): string {
+    const lines: string[] = ["worflow TD"];
+
+    if (title) {
+      lines.push(`  subworflow ${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.next) {
+        node.next.forEach((nextNode) => {
+          let connectionStyle = "";
+          if (node.condition) {
+            connectionStyle = "---|condition|"; // Add label for conditional connections
+          } else {
+            connectionStyle = "-->"; // Normal connection
+          }
+          lines.push(`  ${nodeName} ${connectionStyle} ${nextNode}`);
+        });
+      }
 
-export * from "./graph/controller";
-export * from "./graph/index";
-export * from "./modules/memory";
-export * from "./modules/memory/adapters/meilisearch";
-export * from "./modules/memory/adapters/redis";
+      // 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");
+      }
+    });
 
-export * from "./interfaces";
-export * from "./modules/agenda";
-export * from "./modules/agenda/adapters/node-cron";
-export * from "./modules/embedding";
-export * from "./modules/embedding/adapters/ai";
+    if (title) {
+      lines.push("  end");
+    }
 
-export * from "./types";
+    return lines.join("\n");
+  }
 
-export * from "./utils/generate-action-schema";
-export * from "./utils/header-builder";
+  /**
+   * 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?: string): void {
+    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");
+  }
+}

package/package copy.json

@@ -0,0 +1,21 @@
+{
+  "name": "@ai.ntellect/workflow",
+  "version": "1.0.0",
+  "description": "A robust framework for managing and executing workflows, supporting dynamic decision-making, conditional paths, event-driven execution, and state persistence.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "rm -rf dist && tsc"
+  },
+  "keywords": [],
+  "author": "Lorcann Rauzduel",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-ntellect/workflow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ai-ntellect/workflow/issues"
+  },
+  "homepage": "https://github.com/ai-ntellect/workflow#readme"
+}

package/package.json

@@ -1,54 +1,19 @@
 {
   "name": "@ai.ntellect/core",
-  "version": "0.7.7",
-  "description": "",
-  "main": "dist/index.js",
+  "version": "1.0.0",
+  "description": "A robust framework for managing and executing workflows, supporting dynamic decision-making, conditional paths, event-driven execution, and state persistence.",
+  "main": "index.js",
   "scripts": {
-    "build": "rm -rf dist && tsc",
-    "prepare": "npm run build",
-    "prepublishOnly": "npm run build",
-    "test": "mocha -r ./node_modules/ts-node/register",
-    "test:all": "mocha -r ./node_modules/ts-node/register 'test/**/*.test.ts'",
-    "test:coverage": "nyc --reporter=text --reporter=html pnpm test",
-    "test:watch": "mocha --require ./node_modules/ts-node/register 'test/**/*.test.ts' --watch --watch-files ./**/*.ts,test/**/*.ts",
-    "test:watch:graph": "mocha --require ./node_modules/ts-node/register 'test/graph/**/*.test.ts' --watch --watch-files ./graph/**/*.ts test/**/*.ts"
-  },
-  "keywords": [],
-  "author": "Lorcann Rauzduel",
-  "license": "ISC",
-  "dependencies": {
-    "@types/node-cron": "^3.0.11",
-    "ai": "^3.0.0",
-    "node-cron": "^3.0.3",
-    "redis": "^4.7.0",
-    "rxjs": "^7.8.1",
-    "zod": "^3.24.1"
-  },
-  "devDependencies": {
-    "@types/chai": "^4.3.20",
-    "@types/chai-as-promised": "^8.0.1",
-    "@types/mocha": "^10.0.10",
-    "@types/node": "^20",
-    "@types/sinon": "^17.0.3",
-    "chai": "^4.5.0",
-    "chai-as-promised": "^8.0.1",
-    "mocha": "^10.0.0",
-    "nyc": "^17.1.0",
-    "redis": "^4.6.13",
-    "sinon": "^19.0.2",
-    "ts-node": "10.9.1",
-    "typescript": "^5.7.2"
+    "test": "echo \"Error: no test specified\" && exit 1"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/ai-ntellect/core.git"
+    "url": "git+https://github.com/ai-ntellect/workflow.git"
   },
+  "author": "",
+  "license": "ISC",
   "bugs": {
-    "url": "https://github.com/ai-ntellect/core/issues"
+    "url": "https://github.com/ai-ntellect/workflow/issues"
   },
-  "homepage": "https://github.com/ai-ntellect/core#readme",
-  "bin": {
-    "wallet-assistant": "./dist/examples/index.js",
-    "workflow": "./dist/cli.js"
-  }
+  "homepage": "https://github.com/ai-ntellect/workflow#readme"
 }