@ai.ntellect/core 0.5.0 → 0.6.0

package/{services/workflow.ts → graph/engine.ts}

@@ -1,23 +1,24 @@
+import { Persistence, RealTimeNotifier } from "@/interfaces";
+import { GraphDefinition, Node, NodeRelationship, SharedState } from "@/types";
 import { configDotenv } from "dotenv";
 import EventEmitter from "events";
-import {
-  mergeState,
-  Node,
-  Persistence,
-  RealTimeNotifier,
-  SharedState,
-  WorkflowDefinition,
-} from "../types";
+import { z } from "zod";
 
 configDotenv();
 
+interface GraphOptions<T> {
+  initialState?: SharedState<T>;
+  schema?: z.ZodSchema<T>;
+  autoDetectCycles?: boolean;
+}
+
 /**
  * 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
  */
-export class Workflow<T> {
+export class GraphEngine<T> {
   /** Stores global context data accessible to all nodes */
   public globalContext: Map<string, any>;
 
@@ -39,18 +40,19 @@ export class Workflow<T> {
   /** Optional notifier for real-time updates */
   private notifier: RealTimeNotifier | null;
 
+  private schema?: z.ZodSchema<T>;
+
+  private currentState: SharedState<T>;
+
   /**
-   * Creates a new Workflow instance.
+   * Creates a new Graph instance.
    *
-   * @param {WorkflowDefinition<T>} [definition] - Initial worflow structure and configuration
+   * @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?: WorkflowDefinition<T>,
-    config?: { autoDetectCycles?: boolean }
-  ) {
+  constructor(definition?: GraphDefinition<T>, options?: GraphOptions<T>) {
     this.name = definition?.name || "anonymous";
     this.eventEmitter = new EventEmitter();
     this.globalContext = new Map();
@@ -58,13 +60,19 @@ export class Workflow<T> {
     this.executedNodes = new Set();
     this.persistence = null;
     this.notifier = null;
+    this.schema = options?.schema;
+    this.currentState = { context: {} } as SharedState<T>;
 
     if (definition) {
       this.loadFromDefinition(definition);
     }
 
-    if (config?.autoDetectCycles && this.checkForCycles()) {
-      throw new Error("Cycle detected in the worflow");
+    if (options?.autoDetectCycles && this.checkForCycles()) {
+      throw new Error("Cycle detected in the workflow");
+    }
+
+    if (options?.initialState) {
+      this.setState(options.initialState);
     }
   }
 
@@ -113,13 +121,13 @@ export class Workflow<T> {
   /**
    * Loads a worflow structure from a definition object.
    * @private
-   * @param {WorkflowDefinition<T>} definition - The worflow definition
+   * @param {GraphDefinition<T>} definition - The worflow definition
    */
-  private loadFromDefinition(definition: WorkflowDefinition<T>): void {
+  private loadFromDefinition(definition: GraphDefinition<T>): void {
     Object.entries(definition.nodes).forEach(([_, nodeConfig]) => {
       this.addNode(nodeConfig, {
         condition: nodeConfig.condition,
-        next: nodeConfig.next,
+        relationships: nodeConfig.relationships,
       });
     });
   }
@@ -142,14 +150,15 @@ export class Workflow<T> {
       recStack.add(nodeName);
 
       const currentNode = this.nodes.get(nodeName);
-      if (currentNode?.next) {
-        for (const nextNode of currentNode.next) {
+      if (currentNode?.relationships) {
+        for (const relation of currentNode.relationships) {
+          const targetNode = relation.name;
           if (
-            !visited.has(nextNode) &&
-            this.isCyclic(nextNode, visited, recStack)
+            !visited.has(targetNode) &&
+            this.isCyclic(targetNode, visited, recStack)
           ) {
             return true;
-          } else if (recStack.has(nextNode)) {
+          } else if (recStack.has(targetNode)) {
             return true;
           }
         }
@@ -180,28 +189,27 @@ export class Workflow<T> {
    * @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.relations] - Array of relations node names
    * @param {string[]} [options.events] - Array of event names to listen for
    */
   addNode(
     node: Node<T>,
     {
       condition,
-      next,
+      relationships,
       events,
     }: {
       condition?: (state: SharedState<T>) => boolean;
-      next?: string[];
+      relationships?: NodeRelationship[];
       events?: string[];
     }
   ): void {
-    node.next = next;
+    node.relationships = relationships;
     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);
         });
@@ -217,30 +225,24 @@ export class Workflow<T> {
    * @param {any} data - Data to pass with the event
    */
   public 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 {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
    */
-  addSubWorkflow(
-    subWorkflow: Workflow<T>,
-    entryNode: string,
-    name: string
-  ): void {
-    const subWorkflowNode: Node<T> = {
-      name,
+  addSubGraph(subGraph: GraphEngine<T>, entryNode: string, name: string): void {
+    const subGraphNode: Node<T> = {
+      name: name,
       execute: async (state) => {
-        console.log(`Executing subworflow: ${name}`);
-        await subWorkflow.execute(state, entryNode);
+        await subGraph.execute(state, entryNode);
         return state;
       },
     };
-    this.nodes.set(name, subWorkflowNode);
+    this.nodes.set(name, subGraphNode);
   }
 
   /**
@@ -255,75 +257,105 @@ export class Workflow<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);
+  ): Promise<SharedState<T>> {
+    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;
+        }
+      }
 
-      const currentNode = this.nodes.get(currentNodeName);
-      if (!currentNode) throw new Error(`Node ${currentNodeName} not found.`);
+      this.setState(state);
+      let currentNodeName = startNode;
 
-      if (currentNode.condition && !currentNode.condition(state)) {
-        console.log(
-          `Condition for node "${currentNodeName}" not met. Ending Workflow.`
-        );
-        break;
-      }
+      while (currentNodeName) {
+        this.executedNodes.add(currentNodeName);
+        const currentNode = this.nodes.get(currentNodeName);
+        if (!currentNode) throw new Error(`Node ${currentNodeName} not found.`);
 
-      try {
-        if (this.notifier) {
-          this.notifier.notify("nodeExecutionStarted", {
-            worflow: this.name,
-            node: currentNodeName,
-          });
+        if (
+          currentNode.condition &&
+          !currentNode.condition(this.currentState)
+        ) {
+          break;
         }
 
-        console.log(`Executing node: ${currentNodeName}`);
-        const newState = await currentNode.execute(state);
-        Object.assign(state, mergeState(state, newState));
+        try {
+          if (this.notifier) {
+            this.notifier.notify("nodeExecutionStarted", {
+              workflow: this.name,
+              node: currentNodeName,
+            });
+          }
 
-        if (onStream) onStream(state);
+          const params = currentNode.schema?.parse(this.currentState);
+          const newState = await currentNode.execute(
+            params || {},
+            this.currentState
+          );
 
-        if (this.persistence) {
-          await this.persistence.saveState(this.name, state, currentNodeName);
-        }
+          if (newState) {
+            this.setState(newState);
+            if (onStream) onStream(this.currentState);
+          }
 
-        if (this.notifier) {
-          await this.notifier.notify("nodeExecutionCompleted", {
-            worflow: this.name,
-            node: currentNodeName,
-            state,
-          });
+          if (this.persistence) {
+            await this.persistence.saveState(
+              this.name,
+              this.currentState,
+              currentNodeName
+            );
+          }
+
+          if (this.notifier) {
+            await this.notifier.notify("nodeExecutionCompleted", {
+              workflow: this.name,
+              node: currentNodeName,
+              state: this.currentState,
+            });
+          }
+        } catch (error) {
+          if (onError)
+            onError(error as Error, currentNodeName, this.currentState);
+          if (this.notifier) {
+            this.notifier.notify("nodeExecutionFailed", {
+              workflow: this.name,
+              node: currentNodeName,
+              state: this.currentState,
+              error,
+            });
+          }
+          break;
         }
-      } 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,
-          });
+
+        const relationsNodes = currentNode.relationships || [];
+        if (relationsNodes.length > 1) {
+          await Promise.all(
+            relationsNodes.map((relation) =>
+              this.execute(this.currentState, relation.name, onStream, onError)
+            )
+          );
+          break;
+        } else {
+          currentNodeName = relationsNodes[0]?.name || "";
         }
-        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] || "";
+      return this.getState();
+    } catch (error) {
+      if (onError) {
+        onError(error as Error, startNode, state);
       }
+      throw error;
     }
-
-    console.log(`Workflow completed for node: ${startNode}`);
   }
 
   /**
@@ -341,8 +373,6 @@ export class Workflow<T> {
     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);
     };
@@ -359,18 +389,19 @@ export class Workflow<T> {
 
   /**
    * Updates the worflow structure with a new definition.
-   * @param {WorkflowDefinition<T>} definition - The new worflow definition
+   * @param {GraphDefinition<T>} definition - The new worflow definition
    */
-  updateWorkflow(definition: WorkflowDefinition<T>): void {
+  updateGraph(definition: GraphDefinition<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.relationships =
+          nodeConfig.relationships || existingNode.relationships;
         existingNode.condition = nodeConfig.condition || existingNode.condition;
       } else {
         this.addNode(nodeConfig, {
           condition: nodeConfig.condition,
-          next: nodeConfig.next,
+          relationships: nodeConfig.relationships,
         });
       }
     });
@@ -378,9 +409,9 @@ export class Workflow<T> {
 
   /**
    * Replace the worflow with a new definition.
-   * @param {WorkflowDefinition<T>} definition - The new worflow definition
+   * @param {GraphDefinition<T>} definition - The new worflow definition
    */
-  replaceWorkflow(definition: WorkflowDefinition<T>): void {
+  replaceGraph(definition: GraphDefinition<T>): void {
     this.nodes.clear();
     this.loadFromDefinition(definition);
   }
@@ -396,10 +427,10 @@ export class Workflow<T> {
    * @returns {string} Mermaid diagram syntax representing the worflow
    */
   generateMermaidDiagram(title?: string): string {
-    const lines: string[] = ["worflow TD"];
+    const lines: string[] = ["flowchart TD"];
 
     if (title) {
-      lines.push(`  subworflow ${title}`);
+      lines.push(`  subgraph ${title}`);
     }
 
     // Add nodes with styling
@@ -424,21 +455,21 @@ export class Workflow<T> {
 
     // Add connections
     this.nodes.forEach((node, nodeName) => {
-      if (node.next) {
-        node.next.forEach((nextNode) => {
+      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} ${nextNode}`);
+          lines.push(`  ${nodeName} ${connectionStyle} ${relationsNode}`);
         });
       }
 
       // Add event connections if any
       if (node.events && node.events.length > 0) {
-        node.events.forEach((event) => {
+        node.events.forEach((event: string) => {
           const eventNodeId = `${event}_event`;
           lines.push(`  ${eventNodeId}((${event})):::event`);
           lines.push(`  ${eventNodeId} -.->|trigger| ${nodeName}`);
@@ -471,7 +502,7 @@ export class Workflow<T> {
     console.log("```\n");
   }
 
-  exportWorkflowToJson<T>(worflow: WorkflowDefinition<T>): string {
+  exportGraphToJson<T>(worflow: GraphDefinition<T>): string {
     const result = {
       worflowName: worflow.name,
       entryNode: worflow.entryNode,
@@ -481,11 +512,198 @@ export class Workflow<T> {
           description: node.description || "No description provided",
           execute: node.execute.name,
           condition: node.condition ? node.condition.toString() : "None",
-          next: node.next || [],
+          relationships: node.relationships || [],
         };
         return acc;
       }, {} as Record<string, any>),
     };
     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(): string {
+    const output: string[] = [];
+
+    output.push(`📋 Graph: ${this.name}`);
+    output.push("=".repeat(50));
+
+    if (this.schema) {
+      output.push("🔷 Global Schema:");
+      output.push("-".repeat(30));
+
+      if (this.schema instanceof z.ZodObject) {
+        const shape = this.schema.shape;
+        Object.entries(shape).forEach(([key, value]) => {
+          const description = this.describeZodType(value as z.ZodType, 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.
+   */
+  public describeZodType(type: z.ZodType, indent: number = 0): string {
+    const padding = "  ".repeat(indent);
+
+    if (type instanceof z.ZodObject) {
+      const shape = type.shape;
+      const lines: string[] = [];
+
+      Object.entries(shape).forEach(([key, value]) => {
+        const isOptional = value instanceof z.ZodOptional;
+        const actualType = isOptional
+          ? (value as z.ZodOptional<z.ZodType<any, any, any>>).unwrap()
+          : (value as z.ZodType<any, any, any>);
+        const description = this.describeZodType(actualType, indent + 1);
+
+        lines.push(`${padding}${key}${isOptional ? "?" : ""}: ${description}`);
+      });
+
+      return lines.join("\n");
+    }
+
+    if (type instanceof z.ZodArray) {
+      const elementType = this.describeZodType(type.element, indent);
+      return `Array<${elementType}>`;
+    }
+
+    if (type instanceof 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 z.ZodNumber) {
+      return "number";
+    }
+
+    if (type instanceof z.ZodBoolean) {
+      return "boolean";
+    }
+
+    if (type instanceof 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
+   */
+  protected updateNodeState(state: SharedState<T>, updates: Partial<T>) {
+    return {
+      ...state,
+      context: {
+        ...(state.context || {}),
+        ...updates,
+      },
+    };
+  }
+
+  /**
+   * Retrieves the current state of the workflow.
+   * @returns {SharedState<T>} The current state
+   */
+  public getState(): SharedState<T> {
+    return this.currentState;
+  }
+
+  /**
+   * Sets the state of the workflow.
+   * @param {Partial<SharedState<T>>} state - The new state
+   */
+  public setState(state: Partial<SharedState<T>>): void {
+    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 = {
+          ...(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
+   */
+  private mergeStates(
+    currentState: SharedState<T>,
+    newState: Partial<SharedState<T>>
+  ): SharedState<T> {
+    return {
+      ...currentState,
+      context: {
+        ...(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
+   */
+  public updateState(updates: Partial<SharedState<T>>): SharedState<T> {
+    const currentState = this.getState();
+    const newState = {
+      ...currentState,
+      context: {
+        ...currentState.context,
+        ...(updates.context || {}),
+      },
+    };
+    this.setState(newState);
+    return newState;
+  }
 }

package/index.ts

@@ -1,8 +1,8 @@
-export * from "./agent";
-export * from "./llm/interpreter";
-export * from "./llm/interpreter/context";
-export * from "./llm/orchestrator";
-export * from "./types";
+export * from "./graph/controller";
+export * from "./graph/engine";
+export * from "./memory";
+export * from "./memory/adapters/meilisearch";
+export * from "./memory/adapters/redis";
 
-export * from "./memory/cache";
-export * from "./memory/persistent";
+export * from "./interfaces";
+export * from "./types";