@ai.ntellect/core 1.0.0 → 1.1.1

package/execution/registry.ts

@@ -0,0 +1,86 @@
+import { GraphFlow } from './index';
+import { ParallelNodeConfig } from './types.parallel';
+
+// ========== Parallel Node Registry (legacy) ==========
+
+export const nodeRegistry = {
+  executeFunctions: new Map<string, Function>(),
+  nodeConfigs: new Map<string, ParallelNodeConfig<any>>(),
+  subgraphs: new Map<string, GraphFlow<any>>(),
+
+  registerParallel(nodeConfig: ParallelNodeConfig<any>) {
+    this.nodeConfigs.set(nodeConfig.name, nodeConfig);
+    if (nodeConfig.execute) {
+      this.executeFunctions.set(nodeConfig.name, nodeConfig.execute);
+    }
+  },
+
+  registerSubgraph(name: string, graph: GraphFlow<any>) {
+    this.subgraphs.set(name, graph);
+  },
+
+  getSubgraph(name: string) {
+    return this.subgraphs.get(name);
+  },
+
+  getExecuteFunction(nodeName: string) {
+    return this.executeFunctions.get(nodeName);
+  },
+
+  getNodeConfig(nodeName: string) {
+    return this.nodeConfigs.get(nodeName);
+  },
+
+  clear() {
+    this.executeFunctions.clear();
+    this.nodeConfigs.clear();
+    this.subgraphs.clear();
+  },
+};
+
+// ========== Tool Registry for Plan → Compile → Execute ==========
+
+export interface RegisteredTool {
+  name: string;
+  description: string;
+  graph: GraphFlow<any>;
+  startNode: string;
+}
+
+export interface PlanStep {
+  node: string;
+  params?: Record<string, any>;
+  description?: string;
+}
+
+export class ToolRegistry {
+  private tools = new Map<string, RegisteredTool>();
+
+  register(tool: RegisteredTool) {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool ${tool.name} already registered`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+
+  get(name: string) {
+    return this.tools.get(name);
+  }
+
+  list() {
+    return Array.from(this.tools.values()).map(({ name, description }) => ({
+      name,
+      description,
+    }));
+  }
+
+  validateSteps(steps: PlanStep[]) {
+    const errors: string[] = [];
+    steps.forEach((step, index) => {
+      if (!this.tools.has(step.node)) {
+        errors.push(`Step ${index}: Unknown node ${step.node}`);
+      }
+    });
+    return { valid: errors.length === 0, errors };
+  }
+}

package/execution/send-api.ts

@@ -0,0 +1,58 @@
+import { GraphContext } from "../types";
+import { Send } from "./types.parallel";
+
+/**
+ * Send API pour fan-out dynamique (pattern LangGraph)
+ * Permet de créer N branches au runtime selon les données
+ */
+export class SendAPI {
+  /**
+   * Traite un tableau de Send et prépare l'exécution parallèle
+   */
+  static async processSends(
+    sends: Send[],
+    context: GraphContext<any>,
+    executor: (nodeName: string, ctx: any) => Promise<void>
+  ): Promise<Array<{ branchId: string; context: any }>> {
+    const results = await Promise.all(
+      sends.map(async (send) => {
+        const branchContext = {
+          ...structuredClone(context),
+          ...send.input,
+          _branchId: send.branchId || send.to,
+        };
+        
+        await executor(send.to, branchContext);
+        
+        return {
+          branchId: send.branchId || send.to,
+          context: branchContext,
+        };
+      })
+    );
+    
+    return results;
+  }
+
+  /**
+   * Helper pour créer un Send vers un node
+   */
+  static to(nodeName: string, input: any, branchId?: string): Send {
+    return { to: nodeName, input, branchId };
+  }
+
+  /**
+   * Helper pour fan-out sur une liste (comme map())
+   */
+  static map<T>(
+    nodeName: string,
+    items: T[],
+    mapFn?: (item: T, index: number) => any
+  ): Send[] {
+    return items.map((item, i) => ({
+      to: nodeName,
+      input: mapFn ? mapFn(item, i) : { item, index: i },
+      branchId: `${nodeName}_${i}`,
+    }));
+  }
+}

package/execution/types.parallel.ts

@@ -0,0 +1,81 @@
+import { ZodSchema } from "zod";
+import { GraphContext, GraphNodeConfig } from "../types";
+
+// ====== FORK-JOIN MODEL ======
+
+export type ParallelConfig = {
+  /** Active le parallélisme Fork-Join */
+  enabled: boolean;
+  /** Point de convergence (node qui attend toutes les branches) */
+  joinNode?: string;
+  /** Stratégie de merge (utilise les reducers si non spécifié) */
+  mergeStrategy?: "reducer" | "deep-merge" | "isolated";
+  /** Timeout pour toutes les branches */
+  timeout?: number;
+};
+
+// ====== SEND API (Fan-out dynamique) ======
+
+export type Send = {
+  /** Node cible (peut être un sous-graphe) */
+  to: string;
+  /** Contexte initial pour cette branche */
+  input: any;
+  /** ID unique de la branche (pour le suivi) */
+  branchId?: string;
+};
+
+export type SendFunction = (context: GraphContext<any>) => Send[];
+
+// ====== COMMAND PATTERN (Handoff) ======
+
+export type Command = {
+  /** Node cible pour le handoff */
+  goto: string;
+  /** Mise à jour de l'état avant le handoff */
+  update?: Record<string, any>;
+  /** Graph parent (pour handoff inter-graphes) */
+  graph?: "PARENT" | string;
+  /** Métadonnées (pour traçage) */
+  metadata?: Record<string, any>;
+};
+
+// ====== STATE REDUCERS ======
+
+export type ReducerFunction<T = any> = (acc: T, branchResult: T) => T;
+
+export type StateReducer = {
+  /** Clé du contexte */
+  key: string;
+  /** Fonction de réduction (ex: concat, merge, sum) */
+  reducer: ReducerFunction;
+  /** Valeur initiale */
+  initial?: any;
+};
+
+// ====== WORKER CONFIG ======
+
+export type WorkerConfig = {
+  /** Utiliser un worker thread (pour CPU-bound uniquement) */
+  useWorker: boolean;
+  /** Worker script personnalisé */
+  workerScript?: string;
+  /** Timeout worker */
+  timeout?: number;
+};
+
+// ====== TYPES ÉTENDUS ======
+
+export interface ParallelNodeConfig<T extends ZodSchema, P = any>
+  extends GraphNodeConfig<T, P> {
+  /** Configuration parallèle */
+  parallel?: ParallelConfig;
+  /** Send API pour fan-out dynamique (retourne plusieurs Send) */
+  send?: SendFunction;
+  /** Worker pour CPU-bound */
+  worker?: WorkerConfig;
+  /** Reducers pour ce node */
+  reducers?: StateReducer[];
+  /** Handoff via retour Command */
+  handoff?: boolean;
+}

package/execution/visualizer.ts

@@ -0,0 +1,158 @@
+import { ZodSchema } from "zod";
+import { GraphNodeConfig } from "../types";
+
+interface NodeVisualData {
+  id: string;
+  label: string;
+  type?: string;
+  events?: string[];
+  contextChanges?: string[];
+}
+
+interface EdgeVisualData {
+  from: string;
+  to: string;
+  condition?: string;
+}
+
+interface NextNode {
+  node: string;
+  condition: (context: any) => boolean;
+}
+
+export class GraphVisualizer<T extends ZodSchema> {
+  private nodes: NodeVisualData[] = [];
+  private edges: EdgeVisualData[] = [];
+
+  constructor(private graphNodes: Map<string, GraphNodeConfig<T, any>>) {
+    this.processNodes();
+  }
+
+  private humanizeCondition(condition: string): string {
+    return (
+      condition
+        // Remplacer les opérateurs logiques
+        .replace(/\|\|/g, "or")
+        .replace(/&&/g, "and")
+        .replace(/!/g, "not")
+        // Remplacer les opérateurs de comparaison
+        .replace(/>=/g, "is greater or equal to")
+        .replace(/<=/g, "is less or equal to ")
+        .replace(/>/g, "is greater than")
+        .replace(/</g, "is less than")
+        .replace(/===/g, "equals")
+        .replace(/==/g, "equals")
+        .replace(/!==?/g, "is not")
+        // Nettoyer la syntaxe
+        .replace(/ctx\./g, "")
+        .replace(/context\./g, "")
+        .replace(/[{}]/g, "")
+        .trim()
+    );
+  }
+
+  private processNodes(): void {
+    this.graphNodes.forEach((node, nodeName) => {
+      // Extraire les modifications de contexte depuis la fonction execute
+      const contextChanges: string[] = [];
+      const executeStr = node.execute.toString();
+      const contextAssignments = executeStr.match(/context\.\w+\s*=/g) || [];
+      contextAssignments.forEach((assignment) => {
+        const variable = assignment
+          .replace("context.", "")
+          .replace("=", "")
+          .trim();
+        contextChanges.push(variable);
+      });
+
+      this.nodes.push({
+        id: nodeName,
+        label: nodeName,
+        events: node.events,
+        contextChanges,
+      });
+
+      if (node.next) {
+        if (Array.isArray(node.next)) {
+          node.next.forEach((nextNode: string | NextNode) => {
+            if (typeof nextNode === "string") {
+              this.edges.push({ from: nodeName, to: nextNode });
+            } else {
+              const conditionStr = nextNode.condition
+                .toString()
+                .replace(/.*=> /, "");
+
+              this.edges.push({
+                from: nodeName,
+                to: nextNode.node,
+                condition: this.humanizeCondition(conditionStr),
+              });
+            }
+          });
+        } else if (typeof node.next === "string") {
+          this.edges.push({ from: nodeName, to: node.next });
+        } else if (typeof node.next === "function") {
+          // Gérer le cas où next est une fonction
+          const nextStr = node.next.toString();
+          if (nextStr.includes("=>")) {
+            const conditionPart = nextStr.split("=>")[1].trim();
+            this.edges.push({
+              from: nodeName,
+              to: "nextNode", // Il faudrait extraire le vrai nom du nœud suivant
+              condition: this.humanizeCondition(conditionPart),
+            });
+          }
+        }
+      }
+    });
+  }
+
+  /**
+   * Generates a Mermaid flowchart representation of the graph
+   */
+  public toMermaid(): string {
+    let mmd = "flowchart TD\n";
+
+    // Ajouter les nœuds avec leurs modifications de contexte
+    this.nodes.forEach((node) => {
+      let nodeLabel = node.label;
+
+      // Améliorer l'affichage des modifications de contexte
+      if (node.contextChanges?.length) {
+        nodeLabel += `\nUpdates:`;
+        node.contextChanges.forEach((change) => {
+          nodeLabel += `\n• ${change}`;
+        });
+      }
+
+      // Améliorer l'affichage des événements
+      if (node.events?.length) {
+        node.events.forEach((event) => {
+          mmd += `    ${event}((${event}))\n`;
+          mmd += `    ${node.id} -.->|listens to| ${event}\n`;
+        });
+      }
+
+      mmd += `    ${node.id}["${nodeLabel}"]\n`;
+    });
+
+    // Ajouter les connexions avec les conditions humanisées
+    this.edges.forEach((edge) => {
+      const escapedCondition = edge.condition?.replace(/[|]/g, "\\|");
+      const arrow = escapedCondition ? `-->|${escapedCondition}|` : "-->";
+      mmd += `    ${edge.from} ${arrow} ${edge.to}\n`;
+    });
+
+    return mmd;
+  }
+
+  /**
+   * Returns the nodes and edges data
+   */
+  public getVisualizationData() {
+    return {
+      nodes: this.nodes,
+      edges: this.edges,
+    };
+  }
+}