@ai.ntellect/core 0.6.0 → 0.6.2

package/graph/engine.ts

@@ -1,11 +1,8 @@
 import { Persistence, RealTimeNotifier } from "@/interfaces";
-import { GraphDefinition, Node, NodeRelationship, SharedState } from "@/types";
-import { configDotenv } from "dotenv";
+import { GraphDefinition, Node, SharedState } from "@/types";
 import EventEmitter from "events";
 import { z } from "zod";
 
-configDotenv();
-
 interface GraphOptions<T> {
   initialState?: SharedState<T>;
   schema?: z.ZodSchema<T>;
@@ -13,44 +10,43 @@ interface GraphOptions<T> {
 }
 
 /**
- * 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.
+ * Représente un workflow dirigé capable d’exécuter des noeuds en séquence ou en parallèle.
  *
- * @template T - The type of data stored in the worflow's context
+ * @template T - Le type de données stockées dans le contexte du workflow
  */
 export class GraphEngine<T> {
-  /** Stores global context data accessible to all nodes */
+  /** Données globales accessibles à tous les nœuds */
   public globalContext: Map<string, any>;
 
-  /** Event emitter for handling worflow-wide events */
+  /** Event emitter pour gérer les événements du workflow */
   private eventEmitter: EventEmitter;
 
-  /** Map of all nodes in the worflow */
+  /** Map de tous les nœuds du workflow */
   public nodes: Map<string, Node<T>>;
 
-  /** Set of nodes that have been executed */
+  /** Ensemble des nœuds déjà exécutés */
   public executedNodes: Set<string>;
 
-  /** Name identifier for the worflow */
+  /** Nom du workflow */
   public name: string;
 
-  /** Optional persistence layer for saving worflow state */
+  /** Couche de persistance optionnelle pour sauvegarder l'état du workflow */
   private persistence: Persistence<T> | null;
 
-  /** Optional notifier for real-time updates */
+  /** 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>;
 
   /**
-   * Creates a new Graph instance.
+   * Crée une nouvelle instance de GraphEngine.
    *
-   * @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
+   * @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";
@@ -61,14 +57,14 @@ export class GraphEngine<T> {
     this.persistence = null;
     this.notifier = null;
     this.schema = options?.schema;
-    this.currentState = { context: {} } as SharedState<T>;
+    this.currentState = {} as SharedState<T>;
 
     if (definition) {
       this.loadFromDefinition(definition);
     }
 
     if (options?.autoDetectCycles && this.checkForCycles()) {
-      throw new Error("Cycle detected in the workflow");
+      throw new Error("Cycle détecté dans le workflow");
     }
 
     if (options?.initialState) {
@@ -77,68 +73,63 @@ export class GraphEngine<T> {
   }
 
   /**
-   * Adds a value to the global context.
-   * @param {string} key - The key to store the value under
-   * @param {any} value - The value to store
+   * 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);
   }
 
   /**
-   * Retrieves a value from the global context.
-   * @param {string} key - The key to retrieve
-   * @returns {any} The stored value, or undefined if not found
+   * Récupère un élément du contexte global.
+   * @param {string} key - La clé
    */
   getContext(key: string): any {
     return this.globalContext.get(key);
   }
 
   /**
-   * Removes a value from the global context.
-   * @param {string} key - The key to remove
+   * Supprime un élément du contexte global.
+   * @param {string} key - La clé
    */
   removeFromContext(key: string): void {
     this.globalContext.delete(key);
   }
 
   /**
-   * Sets the persistence layer for the worflow.
-   * @param {Persistence<T>} persistence - The persistence implementation
+   * Définit la couche de persistance.
+   * @param {Persistence<T>} persistence
    */
   setPersistence(persistence: Persistence<T>): void {
     this.persistence = persistence;
   }
 
   /**
-   * Sets the real-time notifier for the worflow.
-   * @param {RealTimeNotifier} notifier - The notifier implementation
+   * Définit le notifier en temps réel.
+   * @param {RealTimeNotifier} notifier
    */
   setNotifier(notifier: RealTimeNotifier): void {
     this.notifier = notifier;
   }
 
   /**
-   * Loads a worflow structure from a definition object.
+   * Charge un workflow à partir d'une définition.
    * @private
-   * @param {GraphDefinition<T>} definition - The worflow definition
+   * @param {GraphDefinition<T>} definition
    */
   private loadFromDefinition(definition: GraphDefinition<T>): void {
     Object.entries(definition.nodes).forEach(([_, nodeConfig]) => {
-      this.addNode(nodeConfig, {
-        condition: nodeConfig.condition,
-        relationships: nodeConfig.relationships,
-      });
+      this.addNode(nodeConfig);
     });
   }
 
   /**
-   * 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
+   * 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,
@@ -169,8 +160,8 @@ export class GraphEngine<T> {
   }
 
   /**
-   * Checks if the worflow contains any cycles.
-   * @returns {boolean} True if cycles are detected, false otherwise
+   * Vérifie si le workflow contient des cycles.
+   * @returns {boolean}
    */
   public checkForCycles(): boolean {
     const visited = new Set<string>();
@@ -185,30 +176,18 @@ export class GraphEngine<T> {
   }
 
   /**
-   * 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
+   * Ajoute un nouveau nœud au workflow.
+   * @param {Node<T>} node
    */
-  addNode(
-    node: Node<T>,
-    {
-      condition,
-      relationships,
-      events,
-    }: {
-      condition?: (state: SharedState<T>) => boolean;
-      relationships?: NodeRelationship[];
-      events?: string[];
+  addNode(node: Node<T>): void {
+    if (node.relationships) {
+      node.relationships.forEach((relationship) => {
+        this.nodes.get(relationship.name)?.relationships?.push(relationship);
+      });
     }
-  ): void {
-    node.relationships = relationships;
-    node.condition = condition;
 
-    if (events) {
-      events.forEach((event) => {
+    if (node.events) {
+      node.events.forEach((event) => {
         this.eventEmitter.on(event, async (data) => {
           const state = data.state || {};
           await this.execute(state, node.name);
@@ -220,19 +199,19 @@ export class GraphEngine<T> {
   }
 
   /**
-   * 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
+   * É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);
   }
 
   /**
-   * 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
+   * 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> = {
@@ -246,25 +225,26 @@ export class GraphEngine<T> {
   }
 
   /**
-   * 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
+   * 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?: (state: SharedState<T>) => void,
+    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.context);
+          this.schema.parse(state);
         } catch (error) {
           const validationError = new Error(
-            `Initial state validation failed: ${
+            `Échec de la validation de l'état initial: ${
               error instanceof Error ? error.message : error
             }`
           );
@@ -279,8 +259,11 @@ export class GraphEngine<T> {
       while (currentNodeName) {
         this.executedNodes.add(currentNodeName);
         const currentNode = this.nodes.get(currentNodeName);
-        if (!currentNode) throw new Error(`Node ${currentNodeName} not found.`);
+        if (!currentNode) {
+          throw new Error(`Nœud ${currentNodeName} introuvable.`);
+        }
 
+        // Vérification de condition (si présente)
         if (
           currentNode.condition &&
           !currentNode.condition(this.currentState)
@@ -289,6 +272,7 @@ export class GraphEngine<T> {
         }
 
         try {
+          // Notifier : début d'exécution du nœud
           if (this.notifier) {
             this.notifier.notify("nodeExecutionStarted", {
               workflow: this.name,
@@ -304,9 +288,10 @@ export class GraphEngine<T> {
 
           if (newState) {
             this.setState(newState);
-            if (onStream) onStream(this.currentState);
+            if (onStream) onStream(this);
           }
 
+          // Sauvegarde via la persistence (optionnel)
           if (this.persistence) {
             await this.persistence.saveState(
               this.name,
@@ -315,6 +300,7 @@ export class GraphEngine<T> {
             );
           }
 
+          // Notifier : fin d'exécution du nœud
           if (this.notifier) {
             await this.notifier.notify("nodeExecutionCompleted", {
               workflow: this.name,
@@ -323,8 +309,9 @@ export class GraphEngine<T> {
             });
           }
         } catch (error) {
-          if (onError)
+          if (onError) {
             onError(error as Error, currentNodeName, this.currentState);
+          }
           if (this.notifier) {
             this.notifier.notify("nodeExecutionFailed", {
               workflow: this.name,
@@ -336,15 +323,19 @@ export class GraphEngine<T> {
           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 || "";
         }
       }
@@ -359,18 +350,16 @@ export class GraphEngine<T> {
   }
 
   /**
-   * 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
+   * 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?: (state: SharedState<T>) => void,
+    onStream?: (graph: GraphEngine<T>) => void,
     onError?: (error: Error, nodeName: string, state: SharedState<T>) => void
   ): Promise<void> {
     const executeWithLimit = async (nodeName: string) => {
@@ -388,8 +377,8 @@ export class GraphEngine<T> {
   }
 
   /**
-   * Updates the worflow structure with a new definition.
-   * @param {GraphDefinition<T>} definition - The new worflow definition
+   * 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]) => {
@@ -398,18 +387,16 @@ export class GraphEngine<T> {
         existingNode.relationships =
           nodeConfig.relationships || existingNode.relationships;
         existingNode.condition = nodeConfig.condition || existingNode.condition;
+        existingNode.events = nodeConfig.events || existingNode.events;
       } else {
-        this.addNode(nodeConfig, {
-          condition: nodeConfig.condition,
-          relationships: nodeConfig.relationships,
-        });
+        this.addNode(nodeConfig);
       }
     });
   }
 
   /**
-   * Replace the worflow with a new definition.
-   * @param {GraphDefinition<T>} definition - The new worflow definition
+   * Remplace complètement le workflow par une nouvelle définition.
+   * @param {GraphDefinition<T>} definition
    */
   replaceGraph(definition: GraphDefinition<T>): void {
     this.nodes.clear();
@@ -417,14 +404,9 @@ export class GraphEngine<T> {
   }
 
   /**
-   * 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
+   * Génère un diagramme Mermaid pour visualiser le workflow.
+   * @param {string} [title]
+   * @returns {string}
    */
   generateMermaidDiagram(title?: string): string {
     const lines: string[] = ["flowchart TD"];
@@ -433,48 +415,46 @@ export class GraphEngine<T> {
       lines.push(`  subgraph ${title}`);
     }
 
-    // Add nodes with styling
+    // Ajout des nœuds
     this.nodes.forEach((node, nodeName) => {
       const hasEvents = node.events && node.events.length > 0;
       const hasCondition = !!node.condition;
 
-      // Style nodes based on their properties
+      // Style selon les propriétés
       let style = "";
       if (hasEvents) {
-        style = "style " + nodeName + " fill:#FFD700,stroke:#DAA520"; // Yellow for event nodes
+        style = "style " + nodeName + " fill:#FFD700,stroke:#DAA520"; // Jaune pour event
       } else if (hasCondition) {
-        style = "style " + nodeName + " fill:#FFA500,stroke:#FF8C00"; // Orange for conditional nodes
+        style = "style " + nodeName + " fill:#FFA500,stroke:#FF8C00"; // Orange pour condition
       }
 
-      // Add node definition
       lines.push(`  ${nodeName}[${nodeName}]`);
       if (style) {
         lines.push(`  ${style}`);
       }
     });
 
-    // Add connections
+    // Ajout des connexions
     this.nodes.forEach((node, nodeName) => {
       if (node.relationships) {
         node.relationships.forEach((relationsNode) => {
           let connectionStyle = "";
           if (node.condition) {
-            connectionStyle = "---|condition|"; // Add label for conditional connections
+            connectionStyle = "---|condition|";
           } else {
-            connectionStyle = "-->"; // Normal connection
+            connectionStyle = "-->";
           }
           lines.push(`  ${nodeName} ${connectionStyle} ${relationsNode}`);
         });
       }
 
-      // Add event connections if any
+      // 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}`);
         });
-        // Add style class for event nodes
         lines.push("  classDef event fill:#FFD700,stroke:#DAA520");
       }
     });
@@ -487,26 +467,29 @@ export class GraphEngine<T> {
   }
 
   /**
-   * 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
+   * Affiche le diagramme Mermaid dans la console.
+   * @param {string} [title]
    */
   visualize(title?: string): void {
     const diagram = this.generateMermaidDiagram(title);
     console.log(
-      "To visualize this worflow, use a Mermaid-compatible renderer with this syntax:"
+      "Pour visualiser ce workflow, utilisez un rendu compatible Mermaid avec la syntaxe suivante :"
     );
     console.log("\n```mermaid");
     console.log(diagram);
     console.log("```\n");
   }
 
-  exportGraphToJson<T>(worflow: GraphDefinition<T>): string {
+  /**
+   * 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 = {
-      worflowName: worflow.name,
-      entryNode: worflow.entryNode,
-      nodes: Object.entries(worflow.nodes).reduce((acc, [key, node]) => {
+      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",
@@ -521,10 +504,8 @@ export class GraphEngine<T> {
   }
 
   /**
-   * 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
+   * Génère une représentation textuelle (console) du schéma du workflow.
+   * @returns {string}
    */
   visualizeSchema(): string {
     const output: string[] = [];
@@ -532,6 +513,7 @@ export class GraphEngine<T> {
     output.push(`📋 Graph: ${this.name}`);
     output.push("=".repeat(50));
 
+    // Schéma global
     if (this.schema) {
       output.push("🔷 Global Schema:");
       output.push("-".repeat(30));
@@ -547,6 +529,7 @@ export class GraphEngine<T> {
       output.push("");
     }
 
+    // Détails des nœuds
     output.push("🔷 Nodes:");
     output.push("-".repeat(30));
 
@@ -557,7 +540,8 @@ export class GraphEngine<T> {
       );
 
       if (node.relationships && node.relationships.length > 0) {
-        output.push(`Next nodes: ${node.relationships.join(", ")}`);
+        const rels = node.relationships.map((r) => r.name).join(", ");
+        output.push(`Next nodes: ${rels}`);
       }
 
       output.push("");
@@ -567,7 +551,10 @@ export class GraphEngine<T> {
   }
 
   /**
-   * Recursively describes a Zod type.
+   * 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);
@@ -623,38 +610,35 @@ export class GraphEngine<T> {
   }
 
   /**
-   * 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
+   * 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,
-      context: {
-        ...(state.context || {}),
-        ...updates,
-      },
+      ...updates,
     };
   }
 
   /**
-   * Retrieves the current state of the workflow.
-   * @returns {SharedState<T>} The current state
+   * Récupère l'état courant du workflow.
+   * @returns {SharedState<T>}
    */
   public getState(): SharedState<T> {
     return this.currentState;
   }
 
   /**
-   * Sets the state of the workflow.
-   * @param {Partial<SharedState<T>>} state - The new state
+   * 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.context) {
-      Object.entries(state.context).forEach(([key, value]) => {
+    if (state) {
+      Object.entries(state).forEach(([key, value]) => {
         this.globalContext.set(key, value);
       });
     }
@@ -664,17 +648,17 @@ export class GraphEngine<T> {
       if (node) {
         node.state = {
           ...(node.state || {}),
-          ...(state.context || {}),
+          ...(state || {}),
         };
       }
     }
   }
 
   /**
-   * Merges two states.
-   * @param {SharedState<T>} currentState - The current state
-   * @param {Partial<SharedState<T>>} newState - The new state
-   * @returns {SharedState<T>} The merged state
+   * Fusionne deux états.
+   * @param {SharedState<T>} currentState
+   * @param {Partial<SharedState<T>>} newState
+   * @returns {SharedState<T>}
    */
   private mergeStates(
     currentState: SharedState<T>,
@@ -682,28 +666,122 @@ export class GraphEngine<T> {
   ): SharedState<T> {
     return {
       ...currentState,
-      context: {
-        ...(currentState.context || {}),
-        ...(newState.context || {}),
-      },
+      ...(newState || {}),
     };
   }
 
   /**
-   * Updates the state of the workflow.
-   * @param {Partial<SharedState<T>>} updates - The updates to apply
-   * @returns {SharedState<T>} The updated state
+   * Met à jour l'état courant et le renvoie.
+   * @param {Partial<T>} updates
+   * @returns {SharedState<T>}
    */
-  public updateState(updates: Partial<SharedState<T>>): SharedState<T> {
+  public updateState(updates: Partial<T>): SharedState<T> {
     const currentState = this.getState();
-    const newState = {
+    const newState: SharedState<T> = {
       ...currentState,
-      context: {
-        ...currentState.context,
-        ...(updates.context || {}),
-      },
+      ...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>[],
+    onStream?: (graph: GraphEngine<U>) => void,
+    onError?: (error: Error, nodeName: string, state: SharedState<U>) => void
+  ): Promise<SharedState<U>[]> {
+    const finalStates: 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(result);
+    }
+
+    return finalStates;
+  }
+
+  /**
+   * 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;
+  }
 }