@ai.ntellect/core 0.6.10 → 0.6.12

package/graph/engine.ts

@@ -1,793 +0,0 @@
-import { Persistence, RealTimeNotifier } from "@/interfaces";
-import { Action, GraphDefinition, Node, SharedState } from "@/types";
-import EventEmitter from "events";
-import { z } from "zod";
-
-interface GraphOptions<T> {
-  initialState?: SharedState<T>;
-  schema?: z.ZodSchema<T>;
-  autoDetectCycles?: boolean;
-}
-
-/**
- * Représente un workflow dirigé capable d’exécuter des noeuds en séquence ou en parallèle.
- *
- * @template T - Le type de données stockées dans le contexte du workflow
- */
-export class GraphEngine<T> {
-  /** Données globales accessibles à tous les nœuds */
-  public globalContext: Map<string, any>;
-
-  /** Event emitter pour gérer les événements du workflow */
-  private eventEmitter: EventEmitter;
-
-  /** Map de tous les nœuds du workflow */
-  public nodes: Map<string, Node<T>>;
-
-  /** Ensemble des nœuds déjà exécutés */
-  public executedNodes: Set<string>;
-
-  /** Nom du workflow */
-  public name: string;
-
-  /** Couche de persistance optionnelle pour sauvegarder l'état du workflow */
-  private persistence: Persistence<T> | null;
-
-  /** Notifier en temps réel optionnel */
-  private notifier: RealTimeNotifier | null;
-
-  /** Schéma global Zod pour valider l’état ou le contexte du workflow */
-  private schema?: z.ZodSchema<T>;
-
-  /** État interne actuel du workflow */
-  private currentState: SharedState<T>;
-
-  /**
-   * Crée une nouvelle instance de GraphEngine.
-   *
-   * @param {GraphDefinition<T>} [definition] - La définition initiale du workflow
-   * @param {GraphOptions<T>} [options] - Options de configuration
-   */
-  constructor(definition?: GraphDefinition<T>, options?: GraphOptions<T>) {
-    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;
-    this.schema = options?.schema;
-    this.currentState = {} as SharedState<T>;
-
-    if (definition) {
-      this.loadFromDefinition(definition);
-    }
-
-    if (options?.autoDetectCycles && this.checkForCycles()) {
-      throw new Error("Cycle détecté dans le workflow");
-    }
-
-    if (options?.initialState) {
-      this.setState(options.initialState);
-    }
-  }
-
-  /**
-   * Ajoute un élément au contexte global.
-   * @param {string} key - La clé
-   * @param {any} value - La valeur
-   */
-  addToContext(key: string, value: any): void {
-    this.globalContext.set(key, value);
-  }
-
-  /**
-   * Récupère un élément du contexte global.
-   * @param {string} key - La clé
-   */
-  getContext(key: string): any {
-    return this.globalContext.get(key);
-  }
-
-  /**
-   * Supprime un élément du contexte global.
-   * @param {string} key - La clé
-   */
-  removeFromContext(key: string): void {
-    this.globalContext.delete(key);
-  }
-
-  /**
-   * Définit la couche de persistance.
-   * @param {Persistence<T>} persistence
-   */
-  setPersistence(persistence: Persistence<T>): void {
-    this.persistence = persistence;
-  }
-
-  /**
-   * Définit le notifier en temps réel.
-   * @param {RealTimeNotifier} notifier
-   */
-  setNotifier(notifier: RealTimeNotifier): void {
-    this.notifier = notifier;
-  }
-  /**
-   * Charge un workflow à partir d'une définition.
-   * @private
-   * @param {GraphDefinition<T>} definition
-   */
-  private loadFromDefinition(definition: GraphDefinition<T>): void {
-    Object.entries(definition.nodes).forEach(([_, nodeConfig]) => {
-      this.addNode(nodeConfig);
-    });
-  }
-
-  /**
-   * Vérifie récursivement s’il existe un cycle dans le workflow.
-   * @param {string} nodeName
-   * @param {Set<string>} visited
-   * @param {Set<string>} recStack
-   * @returns {boolean}
-   */
-  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?.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;
-  }
-
-  /**
-   * Vérifie si le workflow contient des cycles.
-   * @returns {boolean}
-   */
-  public 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;
-  }
-
-  /**
-   * Ajoute un nouveau nœud au workflow.
-   * @param {Node<T>} node
-   */
-  addNode(node: Node<T>): void {
-    if (node.relationships) {
-      node.relationships.forEach((relationship) => {
-        this.nodes.get(relationship.name)?.relationships?.push(relationship);
-      });
-    }
-
-    if (node.events) {
-      node.events.forEach((event) => {
-        this.eventEmitter.on(event, async (data) => {
-          const state = data.state || {};
-          await this.execute(state, node.name);
-        });
-      });
-    }
-
-    this.nodes.set(node.name, node);
-  }
-
-  /**
-   * Émet un événement sur l'event emitter du workflow.
-   * @param {string} eventName
-   * @param {any} data
-   */
-  public emit(eventName: string, data: any): void {
-    this.eventEmitter.emit(eventName, data);
-  }
-
-  /**
-   * Ajoute un sous-graph (GraphEngine) comme un nœud dans le workflow courant.
-   * @param {GraphEngine<T>} subGraph
-   * @param {string} entryNode - Le nom du nœud de démarrage dans le sous-graph
-   * @param {string} name - Le nom symbolique à donner au sous-graph
-   */
-  addSubGraph(subGraph: GraphEngine<T>, entryNode: string, name: string): void {
-    const subGraphNode: Node<T> = {
-      name: name,
-      execute: async (state) => {
-        await subGraph.execute(state, entryNode);
-        return state;
-      },
-    };
-    this.nodes.set(name, subGraphNode);
-  }
-
-  /**
-   * Exécute le workflow à partir d’un nœud donné.
-   * @param {SharedState<T>} state
-   * @param {string} startNode
-   * @param {(state: SharedState<T>) => void} [onStream] - Callback sur l’évolution de l’état
-   * @param {(error: Error, nodeName: string, state: SharedState<T>) => void} [onError] - Callback sur erreur
-   */
-  async execute(
-    state: SharedState<T>,
-    startNode: string,
-    onStream?: (graph: GraphEngine<T>) => void,
-    onError?: (error: Error, nodeName: string, state: SharedState<T>) => void
-  ): Promise<SharedState<T>> {
-    try {
-      // Valide l'état initial via le schéma global (si défini)
-      if (this.schema) {
-        try {
-          this.schema.parse(state);
-        } catch (error) {
-          const validationError = new Error(
-            `Échec de la validation de l'état initial: ${
-              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} introuvable.`);
-        }
-
-        // Vérification de condition (si présente)
-        if (
-          currentNode.condition &&
-          !currentNode.condition(this.currentState)
-        ) {
-          break;
-        }
-
-        try {
-          // Notifier : début d'exécution du nœud
-          if (this.notifier) {
-            this.notifier.notify("nodeExecutionStarted", {
-              workflow: this.name,
-              node: currentNodeName,
-            });
-          }
-
-          const newState = await currentNode.execute(this.currentState);
-          if (newState) {
-            this.setState(newState);
-            if (onStream) onStream(this);
-          }
-
-          // Sauvegarde via la persistence (optionnel)
-          if (this.persistence) {
-            await this.persistence.saveState(
-              this.name,
-              this.currentState,
-              currentNodeName
-            );
-          }
-
-          // Notifier : fin d'exécution du nœud
-          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;
-        }
-
-        // Gestion des relations (branchements)
-        const relationsNodes = currentNode.relationships || [];
-        if (relationsNodes.length > 1) {
-          // Exécution parallèle des branches
-          await Promise.all(
-            relationsNodes.map((relation) =>
-              this.execute(this.currentState, relation.name, onStream, onError)
-            )
-          );
-          // Après exécution en parallèle, on arrête la boucle
-          break;
-        } else {
-          // Cas normal : un seul chemin
-          currentNodeName = relationsNodes[0]?.name || "";
-        }
-      }
-
-      return this.getState();
-    } catch (error) {
-      if (onError) {
-        onError(error as Error, startNode, state);
-      }
-      throw error;
-    }
-  }
-
-  /**
-   * Exécute plusieurs nœuds en parallèle au sein du même workflow, avec une limite de concurrence.
-   * @param {SharedState<T>} state
-   * @param {string[]} nodeNames
-   * @param {number} [concurrencyLimit=5]
-   */
-  async executeParallel(
-    state: SharedState<T>,
-    nodeNames: string[],
-    concurrencyLimit: number = 5,
-    onStream?: (graph: GraphEngine<T>) => void,
-    onError?: (error: Error, nodeName: string, state: SharedState<T>) => void
-  ): Promise<void> {
-    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));
-    }
-  }
-
-  /**
-   * Met à jour le workflow avec une nouvelle définition (mise à jour des nœuds existants ou ajout de nouveaux).
-   * @param {GraphDefinition<T>} definition
-   */
-  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.relationships =
-          nodeConfig.relationships || existingNode.relationships;
-        existingNode.condition = nodeConfig.condition || existingNode.condition;
-        existingNode.events = nodeConfig.events || existingNode.events;
-      } else {
-        this.addNode(nodeConfig);
-      }
-    });
-  }
-
-  /**
-   * Remplace complètement le workflow par une nouvelle définition.
-   * @param {GraphDefinition<T>} definition
-   */
-  replaceGraph(definition: GraphDefinition<T>): void {
-    this.nodes.clear();
-    this.loadFromDefinition(definition);
-  }
-
-  /**
-   * Génère un diagramme Mermaid pour visualiser le workflow.
-   * @param {string} [title]
-   * @returns {string}
-   */
-  generateMermaidDiagram(title?: string): string {
-    const lines: string[] = ["flowchart TD"];
-
-    if (title) {
-      lines.push(`  subgraph ${title}`);
-    }
-
-    // Ajout des nœuds
-    this.nodes.forEach((node, nodeName) => {
-      const hasEvents = node.events && node.events.length > 0;
-      const hasCondition = !!node.condition;
-
-      // Style selon les propriétés
-      let style = "";
-      if (hasEvents) {
-        style = "style " + nodeName + " fill:#FFD700,stroke:#DAA520"; // Jaune pour event
-      } else if (hasCondition) {
-        style = "style " + nodeName + " fill:#FFA500,stroke:#FF8C00"; // Orange pour condition
-      }
-
-      lines.push(`  ${nodeName}[${nodeName}]`);
-      if (style) {
-        lines.push(`  ${style}`);
-      }
-    });
-
-    // Ajout des connexions
-    this.nodes.forEach((node, nodeName) => {
-      if (node.relationships) {
-        node.relationships.forEach((relationsNode) => {
-          let connectionStyle = "";
-          if (node.condition) {
-            connectionStyle = "---|condition|";
-          } else {
-            connectionStyle = "-->";
-          }
-          lines.push(`  ${nodeName} ${connectionStyle} ${relationsNode}`);
-        });
-      }
-
-      // Gestion des events
-      if (node.events && node.events.length > 0) {
-        node.events.forEach((event: string) => {
-          const eventNodeId = `${event}_event`;
-          lines.push(`  ${eventNodeId}((${event})):::event`);
-          lines.push(`  ${eventNodeId} -.->|trigger| ${nodeName}`);
-        });
-        lines.push("  classDef event fill:#FFD700,stroke:#DAA520");
-      }
-    });
-
-    if (title) {
-      lines.push("  end");
-    }
-
-    return lines.join("\n");
-  }
-
-  /**
-   * Affiche le diagramme Mermaid dans la console.
-   * @param {string} [title]
-   */
-  visualize(title?: string): void {
-    const diagram = this.generateMermaidDiagram(title);
-    console.log(
-      "Pour visualiser ce workflow, utilisez un rendu compatible Mermaid avec la syntaxe suivante :"
-    );
-    console.log("\n```mermaid");
-    console.log(diagram);
-    console.log("```\n");
-  }
-
-  /**
-   * Exporte la définition du workflow au format JSON (pour debug ou documentation).
-   * @param {GraphDefinition<T>} workflow
-   * @returns {string} JSON string
-   */
-  exportGraphToJson(workflow: GraphDefinition<T>): string {
-    const result = {
-      workflowName: workflow.name,
-      entryNode: workflow.entryNode,
-      nodes: Object.entries(workflow.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;
-      }, {} as Record<string, any>),
-    };
-    return JSON.stringify(result, null, 2);
-  }
-
-  /**
-   * Génère une représentation textuelle (console) du schéma du workflow.
-   * @returns {string}
-   */
-  visualizeSchema(): string {
-    const output: string[] = [];
-
-    output.push(`📋 Graph: ${this.name}`);
-    output.push("=".repeat(50));
-
-    // Schéma global
-    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("");
-    }
-
-    // Détails des nœuds
-    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) {
-        const rels = node.relationships.map((r) => r.name).join(", ");
-        output.push(`Next nodes: ${rels}`);
-      }
-
-      output.push("");
-    });
-
-    return output.join("\n");
-  }
-
-  /**
-   * Décrit récursivement un type Zod pour l'affichage.
-   * @param {z.ZodType} type
-   * @param {number} indent
-   * @returns {string}
-   */
-  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";
-  }
-
-  /**
-   * Met à jour le contexte du workflow pour un nœud, en renvoyant un nouvel état.
-   * @param {SharedState<T>} state
-   * @param {Partial<T>} updates
-   * @returns {SharedState<T>}
-   */
-  protected updateNodeState(state: SharedState<T>, updates: Partial<T>) {
-    return {
-      ...state,
-      ...updates,
-    };
-  }
-
-  /**
-   * Récupère l'état courant du workflow.
-   * @returns {SharedState<T>}
-   */
-  public getState(): SharedState<T> {
-    return this.currentState;
-  }
-
-  /**
-   * Définit le nouvel état courant du workflow et met à jour le contexte global.
-   * @param {Partial<SharedState<T>>} state
-   */
-  public setState(state: Partial<SharedState<T>>): void {
-    this.currentState = this.mergeStates(this.currentState, state);
-
-    if (state) {
-      Object.entries(state).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 || {}),
-        };
-      }
-    }
-  }
-
-  /**
-   * Fusionne deux états.
-   * @param {SharedState<T>} currentState
-   * @param {Partial<SharedState<T>>} newState
-   * @returns {SharedState<T>}
-   */
-  private mergeStates(
-    currentState: SharedState<T>,
-    newState: Partial<SharedState<T>>
-  ): SharedState<T> {
-    return {
-      ...currentState,
-      ...(newState || {}),
-    };
-  }
-
-  /**
-   * Met à jour l'état courant et le renvoie.
-   * @param {Partial<T>} updates
-   * @returns {SharedState<T>}
-   */
-  public updateState(updates: Partial<T>): SharedState<T> {
-    const currentState = this.getState();
-    const newState: SharedState<T> = {
-      ...currentState,
-      ...updates,
-    };
-    this.setState(newState);
-    return newState;
-  }
-
-  /* =============================================
-     =   MÉTHODES STATIQUES POUR PLUSIEURS GRAPHES  =
-     ============================================= */
-
-  /**
-   * Exécute plusieurs GraphEngine en **séquence** (l'un après l'autre).
-   * @param graphs Liste des graphes à exécuter
-   * @param startNodes Noms des nœuds de départ correspondants
-   * @param initialStates États initiaux correspondants
-   * @param onStream Callback d'avancement
-   * @param onError Callback d'erreur
-   * @returns Tableau des états finaux de chaque graphe
-   */
-  public static async executeGraphsInSequence<U>(
-    graphs: GraphEngine<U>[],
-    startNodes: string[],
-    initialStates: SharedState<U>[],
-    actions: Action[], // Pass actions here
-    onStream?: (graph: GraphEngine<U>) => void,
-    onError?: (error: Error, nodeName: string, state: SharedState<U>) => void
-  ): Promise<Action[]> {
-    // Return updated actions directly
-    const finalStates: { name: string; result: SharedState<U> }[] = [];
-
-    for (let i = 0; i < graphs.length; i++) {
-      const graph = graphs[i];
-      const startNode = startNodes[i];
-      const initialState = initialStates[i];
-      const result = await graph.execute(
-        initialState,
-        startNode,
-        onStream,
-        onError
-      );
-      finalStates.push({
-        name: graph.name,
-        result,
-      });
-    }
-
-    // Map results to actions
-    return actions.map((action) => {
-      const result = finalStates.find((state) => state.name === action.name);
-      return {
-        ...action,
-        result: result ? result.result : null,
-      };
-    });
-  }
-
-  /**
-   * Exécute plusieurs GraphEngine en **parallèle** (sans limite de concurrence).
-   * @param graphs Liste des graphes
-   * @param startNodes Noms des nœuds de départ
-   * @param initialStates États initiaux
-   * @param onStream Callback d'avancement
-   * @param onError Callback d'erreur
-   * @returns Tableau des états finaux de chaque graphe
-   */
-  public static async executeGraphsInParallel<U>(
-    graphs: GraphEngine<U>[],
-    startNodes: string[],
-    initialStates: SharedState<U>[],
-    onStream?: (graph: GraphEngine<U>) => void,
-    onError?: (error: Error, nodeName: string, state: SharedState<U>) => void
-  ): Promise<SharedState<U>[]> {
-    const promises = graphs.map((graph, index) =>
-      graph.execute(initialStates[index], startNodes[index], onStream, onError)
-    );
-    return Promise.all(promises);
-  }
-
-  /**
-   * Exécute plusieurs GraphEngine en parallèle **avec une limite de concurrence**.
-   * @param graphs Liste des graphes
-   * @param startNodes Noms des nœuds de départ
-   * @param initialStates États initiaux
-   * @param concurrencyLimit Limite de concurrence
-   * @param onStream Callback d'avancement
-   * @param onError Callback d'erreur
-   * @returns Tableau des états finaux de chaque graphe
-   */
-  public static async executeGraphsWithConcurrencyLimit<U>(
-    graphs: GraphEngine<U>[],
-    startNodes: string[],
-    initialStates: SharedState<U>[],
-    concurrencyLimit: number,
-    onStream?: (graph: GraphEngine<U>) => void,
-    onError?: (error: Error, nodeName: string, state: SharedState<U>) => void
-  ): Promise<SharedState<U>[]> {
-    const results: SharedState<U>[] = [];
-
-    for (let i = 0; i < graphs.length; i += concurrencyLimit) {
-      const chunkGraphs = graphs.slice(i, i + concurrencyLimit);
-      const chunkStartNodes = startNodes.slice(i, i + concurrencyLimit);
-      const chunkInitialStates = initialStates.slice(i, i + concurrencyLimit);
-
-      const chunkPromises = chunkGraphs.map((graph, index) => {
-        return graph.execute(
-          chunkInitialStates[index],
-          chunkStartNodes[index],
-          onStream,
-          onError
-        );
-      });
-      const chunkResults = await Promise.all(chunkPromises);
-      results.push(...chunkResults);
-    }
-
-    return results;
-  }
-}