@ai.ntellect/core 0.4.0 → 0.5.0

package/README.FR.md

@@ -14,11 +14,15 @@ Ce framework est conçu pour exécuter des workflows complexes à l'aide d'une o
 ## Table des matières
 
 1. [Composants d'architecture](#composants-darchitecture)
-   - [Runtime de l'agent](#runtime-de-lagent)
+
+   - [Workflow](#workflow)
    - [Orchestrateur](#orchestrateur)
    - [Gestionnaire de file d'attente](#gestionnaire-de-file-dattente)
    - [Interpréteur](#interpréteur)
    - [Système de mémoire](#système-de-mémoire)
+   - [Listeners](#listeners)
+   - [Schedulers](#schedulers)
+
 2. [Définir et exécuter des actions](#définir-et-exécuter-des-actions)
 3. [Gestion de l'état et récursivité](#gestion-de-letat-et-recursivité)
 4. [Installation et configuration](#installation-et-configuration)
@@ -29,32 +33,581 @@ Ce framework est conçu pour exécuter des workflows complexes à l'aide d'une o
 
 ## Composants d'architecture
 
-### Runtime de l'agent
+import { configDotenv } from "dotenv";
+import EventEmitter from "events";
+import {
+GraphDefinition,
+mergeState,
+Node,
+Persistence,
+RealTimeNotifier,
+SharedState,
+} from "../types";
+import { WorkflowExecutor } from "./workflow-executor";
+
+configDotenv();
+
+/\*\*
+
+- Represents a directed graph structure capable of executing nodes in sequence or parallel.
+- The graph can handle state management, event emissions, and conditional execution paths.
+-
+- @template T - The type of data stored in the graph's context
+  _/
+  export class Workflow<T> {
+  /\*\* Stores global context data accessible to all nodes _/
+  public globalContext: Map<string, any>;
+
+/\*_ Event emitter for handling graph-wide events _/
+private eventEmitter: EventEmitter;
+
+/\*_ Map of all nodes in the graph _/
+public nodes: Map<string, Node<T>>;
+
+/\*_ Set of nodes that have been executed _/
+public executedNodes: Set<string>;
+
+/\*_ Name identifier for the graph _/
+public name: string;
+
+/\*_ Optional persistence layer for saving graph state _/
+private persistence: Persistence<T> | null;
+
+/\*_ Optional notifier for real-time updates _/
+private notifier: RealTimeNotifier | null;
+
+/\*\*
+
+- Creates a new Graph instance.
+-
+- @param {GraphDefinition<T>} [definition] - Initial graph 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?: GraphDefinition<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 graph");
+    }
+
+}
+
+/\*\*
+
+- 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 graph.
+- @param {Persistence<T>} persistence - The persistence implementation
+  \*/
+  setPersistence(persistence: Persistence<T>): void {
+  this.persistence = persistence;
+  }
+
+/\*\*
+
+- Sets the real-time notifier for the graph.
+- @param {RealTimeNotifier} notifier - The notifier implementation
+  \*/
+  setNotifier(notifier: RealTimeNotifier): void {
+  this.notifier = notifier;
+  }
+
+/\*\*
+
+- Loads a graph structure from a definition object.
+- @private
+- @param {GraphDefinition<T>} definition - The graph definition
+  \*/
+  private loadFromDefinition(definition: GraphDefinition<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 graph contains any cycles.
+- @returns {boolean} True if cycles are detected, false otherwise
+  \*/
+  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;
+
+}
+
+/\*\*
+
+- Adds a new node to the graph.
+- @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 graph's event emitter.
+- @param {string} eventName - Name of the event to emit
+- @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 subgraph as a node in the current graph.
+- @param {Graph<T>} subGraph - The subgraph to add
+- @param {string} entryNode - The entry node name in the subgraph
+- @param {string} name - The name for the subgraph node
+  \*/
+  addSubGraph(subGraph: Workflow<T>, entryNode: string, name: string): void {
+  const subGraphNode: Node<T> = {
+  name,
+  execute: async (state) => {
+  console.log(`Executing subgraph: ${name}`);
+  await subGraph.execute(state, entryNode);
+  return state;
+  },
+  };
+  this.nodes.set(name, subGraphNode);
+  }
+
+/\*\*
+
+- Executes the graph 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 Graph.`
+        );
+        break;
+      }
+
+      try {
+        if (this.notifier) {
+          this.notifier.notify("nodeExecutionStarted", {
+            graph: 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", {
+            graph: 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", {
+            graph: 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(`Graph completed for node: ${startNode}`);
+
+}
 
-Le `AgentRuntime` est le moteur principal qui coordonne le workflow global. Il connecte tous les composants et garantit que les tâches sont exécutées efficacement.
+/\*\*
+
+- 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);
+    };
 
-**Responsabilités :**
+    const chunks = [];
+    for (let i = 0; i < nodeNames.length; i += concurrencyLimit) {
+      chunks.push(nodeNames.slice(i, i + concurrencyLimit));
+    }
 
-- Construire un contexte pour l'état actuel à l'aide des systèmes de mémoire (RAG et CAG).
-- Orchestrer les actions à l'aide du gestionnaire de file d'attente.
-- Exploiter les interpréteurs pour analyser les résultats et générer des réponses.
+    for (const chunk of chunks) {
+      await Promise.all(chunk.map(executeWithLimit));
+    }
 
-#### Construction du contexte
+}
 
-La méthode `buildContext` crée un contexte complet en :
+/\*\*
+
+- Updates the graph structure with a new definition.
+- @param {GraphDefinition<T>} definition - The new graph 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.next = nodeConfig.next || existingNode.next;
+  existingNode.condition = nodeConfig.condition || existingNode.condition;
+  } else {
+  this.addNode(nodeConfig, {
+  condition: nodeConfig.condition,
+  next: nodeConfig.next,
+  });
+  }
+  });
+  }
+
+/\*\*
+
+- Replace the graph with a new definition.
+- @param {GraphDefinition<T>} definition - The new graph definition
+  \*/
+  replaceGraph(definition: GraphDefinition<T>): void {
+  this.nodes.clear();
+  this.loadFromDefinition(definition);
+  }
+
+/\*\*
+
+- Generates a visual representation of the graph 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 graph
+  \*/
+  generateMermaidDiagram(title?: string): string {
+  const lines: string[] = ["graph TD"];
+
+
+    if (title) {
+      lines.push(`  subgraph ${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}`);
+        });
+      }
+
+      // 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");
+      }
+    });
+
+    if (title) {
+      lines.push("  end");
+    }
+
+    return lines.join("\n");
 
-1. Ajoutant les outils et les demandes utilisateur.
-2. Récupérant les actions récentes via la mémoire cache (CAG).
-3. Cherchant les connaissances pertinentes dans la mémoire persistante (RAG).
-4. Incluant les interpréteurs disponibles pour la demande.
+}
+
+/\*\*
+
+- Renders the graph visualization using Mermaid syntax.
+- This method can be used to visualize the graph 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 graph, use a Mermaid-compatible renderer with this syntax:"
+  );
+  console.log("\n`mermaid");
+  console.log(diagram);
+  console.log("`\n");
+  }
+
+exportGraphToJson<T>(graph: GraphDefinition<T>): string {
+const result = {
+graphName: graph.name,
+entryNode: graph.entryNode,
+nodes: Object.entries(graph.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",
+next: node.next || [],
+};
+return acc;
+}, {} as Record<string, any>),
+};
+return JSON.stringify(result, null, 2);
+}
+}
+// Création des workflows
+const workflowA = new Workflow({
+name: "WorkflowA",
+entryNode: "node1",
+nodes: {
+node1: {
+name: "node1",
+execute: async (state: any) => {
+console.log("WorkflowA node1 executed", state);
+return Promise.resolve({});
+},
+},
+node2: {
+name: "node2",
+execute: async (state: any) => {
+console.log("WorkflowA node2 executed", state);
+return Promise.resolve({});
+},
+events: ["event1"],
+},
+},
+});
+
+const workflowB = new Workflow({
+name: "WorkflowB",
+entryNode: "node1",
+nodes: {
+node1: {
+name: "node1",
+execute: async (state: any) => {
+console.log("WorkflowB node1 executed", state);
+state.exampleData = "test2";
+return Promise.resolve({});
+},
+},
+},
+});
 
-#### Traitement des workflows
+// Initialisation du gestionnaire d'exécution
+const executor = new WorkflowExecutor();
 
-La méthode `process` :
+workflowA.emit("event1", { exampleData: "test" });
 
-1. Génère des réponses basées sur le contexte à l'aide d'un modèle de langage.
-2. Gère les workflows récursifs pour l'exécution des actions.
-3. Sélectionne les interpréteurs appropriés pour analyser les résultats.
+// Ajout des workflows
+executor.addWorkflow("WorkflowA", workflowA);
+executor.addWorkflow("WorkflowB", workflowB);
+
+// Exécution des workflows en parallèle
+executor.executeWorkflowsInParallel(
+["WorkflowA", "WorkflowB"],
+{
+exampleData: "test",
+},
+2
+);
 
 ---
 
@@ -138,6 +691,59 @@ L'architecture mémoire combine une mémoire à court terme et une mémoire à l
 
 ---
 
+### Listeners
+
+Les **listeners** permettent de se connecter à des événements externes via WebSocket. Ils écoutent les mises à jour en temps réel et déclenchent des actions ou des callbacks spécifiques en réponse aux événements.
+
+**Caractéristiques principales :**
+
+- Connexion à des WebSockets pour écouter les événements.
+- Gestion des abonnements avec des messages personnalisés.
+- Déclenchement de callbacks pour traiter les données reçues.
+
+**Exemple d'utilisation :**
+
+```typescript
+agent.addListener(
+  "listener-id",
+  "wss://example.com/socket",
+  () => JSON.stringify({ action: "subscribe" }),
+  async (data) => {
+    console.log("Data reçue :", data);
+  }
+);
+```
+
+---
+
+### Schedulers
+
+Les **schedulers** permettent de planifier des tâches ou actions pour une exécution ultérieure. Ils utilisent des expressions cron pour définir les intervalles de planification.
+
+**Caractéristiques principales :**
+
+- Planification basée sur des expressions cron.
+- Support des tâches récurrentes et non récurrentes.
+- Gestion et annulation des tâches planifiées.
+
+**Exemple d'utilisation :**
+
+```typescript
+const scheduler = new TaskScheduler(agentRuntime, redisCache);
+
+const taskId = await scheduler.scheduleRequest({
+  originalRequest: "Analyse de marché",
+  cronExpression: "0 9 * * *", // Tous les jours à 9h
+});
+
+console.log(`Tâche planifiée avec ID : ${taskId}`);
+
+// Annuler la tâche si nécessaire
+scheduler.cancelScheduledRequest(taskId);
+```
+
+---
+
 ## Définir et exécuter des actions
 
 ### Qu'est-ce qu'une action ?