@ai.ntellect/core 0.8.3 → 1.1.0

package/{graph → execution}/index.ts

@@ -1,9 +1,11 @@
 import { EventEmitter } from "events";
 import { BehaviorSubject, Subject } from "rxjs";
 import { ZodSchema } from "zod";
-import { GraphObservable, IEventEmitter } from "../interfaces";
+import { GraphObservable, ICheckpointAdapter, IEventEmitter } from "../interfaces";
 import { NLPNode } from "../modules/nlp";
 import {
+  Checkpoint,
+  CheckpointConfig,
   GraphConfig,
   GraphContext,
   GraphEvent,
@@ -11,7 +13,7 @@ import {
 } from "../types";
 import { GraphEventManager } from "./event-manager";
 import { GraphLogger } from "./logger";
-import { GraphNode } from "./node";
+import { GraphNode, NodeExecutionHooks } from "./node";
 import { GraphObserver } from "./observer";
 import { GraphVisualizer } from "./visualizer";
 
@@ -30,6 +32,7 @@ import { GraphVisualizer } from "./visualizer";
  */
 export class GraphFlow<T extends ZodSchema> {
   private context: GraphContext<T>;
+  private _initialContext: GraphContext<T>;
   public validator?: T;
   private eventEmitter: IEventEmitter;
   private globalErrorHandler?: (error: Error, context: GraphContext<T>) => void;
@@ -50,6 +53,11 @@ export class GraphFlow<T extends ZodSchema> {
 
   private nlpNodes: Map<string, NLPNode<T>> = new Map();
 
+  private _interrupted = false;
+  private _interruptCheckpoint: Checkpoint | null = null;
+  private _checkpointCounter = 0;
+  private _breakpoints: Set<string> = new Set();
+
   /**
    * Creates a new instance of GraphFlow
    * @param {GraphConfig<T>} config - Configuration object containing name, nodes, schema, context, and error handlers
@@ -62,6 +70,7 @@ export class GraphFlow<T extends ZodSchema> {
     );
     this.validator = config.schema;
     this.context = config.schema.parse(config.context) as GraphContext<T>;
+    this._initialContext = structuredClone(this.context);
     this.globalErrorHandler = config.onError;
     this.eventEmitter =
       config.eventEmitter || (new EventEmitter() as IEventEmitter);
@@ -226,17 +235,21 @@ export class GraphFlow<T extends ZodSchema> {
     context?: Partial<GraphContext<T>>
   ): Promise<GraphContext<T>> {
     try {
-      // Validate and merge context if provided
       if (context) {
-        const mergedContext = { ...this.context, ...context };
+        const base = this._initialContext ? structuredClone(this._initialContext) : this.context;
+        const previousMessages = (this.context as any)?.messages;
+        const mergedContext = { ...base, ...context };
+        if (previousMessages && Array.isArray(previousMessages) && previousMessages.length > 0) {
+          (mergedContext as any).messages = previousMessages;
+        }
         const validationResult = this.validator?.safeParse(mergedContext);
         if (!validationResult?.success) {
-          const errors = validationResult?.error?.errors.map(
+          const errors = validationResult?.error?.issues.map(
             (err) => `${err.path.join(".")}: ${err.message}`
           );
           throw new Error(`Context validation failed: ${errors?.join(", ")}`);
         }
-        this.context = validationResult.data;
+        this.context = validationResult.data as GraphContext<T>;
       }
 
       this.eventEmitter.emit("graphStarted", { name: this.name });
@@ -259,6 +272,341 @@ export class GraphFlow<T extends ZodSchema> {
     }
   }
 
+  /**
+   * Executes the graph flow with automatic checkpointing at each node
+   * @param startNode - Name of the node to start execution from
+   * @param adapter - Checkpoint persistence adapter
+   * @param config - Checkpoint configuration options
+   * @returns Execution result with final context and checkpoint ID
+   */
+  public async executeWithCheckpoint(
+    startNode: string,
+    adapter: ICheckpointAdapter,
+    config: CheckpointConfig = {}
+  ): Promise<{ context: GraphContext<T>; checkpointId: string }> {
+    const {
+      saveEveryNode = true,
+      saveOnComplete = true,
+      checkpointId = crypto.randomUUID(),
+      breakpoints = [],
+      runId,
+      initialContext,
+    } = config;
+
+    this._interrupted = false;
+    this._interruptCheckpoint = null;
+    this._checkpointCounter = 0;
+    this._breakpoints = new Set(breakpoints);
+
+    if (initialContext) {
+      const base = this._initialContext ? structuredClone(this._initialContext) : this.context;
+      const previousMessages = (this.context as any)?.messages;
+      const mergedContext = { ...base, ...initialContext };
+      if (previousMessages && Array.isArray(previousMessages) && previousMessages.length > 0) {
+        (mergedContext as any).messages = previousMessages;
+      }
+      const validationResult = this.validator?.safeParse(mergedContext);
+      if (!validationResult?.success) {
+        const errors = validationResult?.error?.issues.map(
+          (err) => `${err.path.join(".")}: ${err.message}`
+        );
+        throw new Error(`Context validation failed: ${errors?.join(", ")}`);
+      }
+      this.context = validationResult.data as GraphContext<T>;
+    }
+
+    if (this.context) {
+      const validationResult = this.validator?.safeParse(this.context);
+      if (!validationResult?.success) {
+        const errors = validationResult?.error?.issues.map(
+          (err) => `${err.path.join(".")}: ${err.message}`
+        );
+        throw new Error(`Context validation failed: ${errors?.join(", ")}`);
+      }
+    }
+
+    this.eventEmitter.emit("graphStarted", { name: this.name });
+
+    const runIdResolved = runId || crypto.randomUUID();
+
+    let hooks: NodeExecutionHooks<T> | undefined;
+    if (saveEveryNode) {
+      hooks = {
+        onBeforeExecute: async (nodeName, ctx) => {
+          const isBreakpoint = this._breakpoints.has(nodeName);
+          if (isBreakpoint) {
+            const cpId = `${checkpointId}-${++this._checkpointCounter}`;
+            const cp: Checkpoint<T> = {
+              id: cpId,
+              graphName: this.name,
+              runId: runIdResolved,
+              nodeName,
+              nextNodes: [nodeName],
+              context: structuredClone(ctx),
+              metadata: {
+                createdAt: Date.now(),
+                awaitingApproval: true,
+              },
+            };
+            this._interruptCheckpoint = cp;
+            await adapter.save(cp);
+            throw new CheckpointAwaitApprovalError(
+              `Awaiting approval at breakpoint "${nodeName}"`,
+              cpId
+            );
+          }
+        },
+        onBeforeExecuteNext: async (nodeName, ctx, nextNodes) => {
+          if (this._interrupted) {
+            const cpId = `${checkpointId}-${++this._checkpointCounter}`;
+            const cp: Checkpoint<T> = {
+              id: cpId,
+              graphName: this.name,
+              runId: runIdResolved,
+              nodeName,
+              nextNodes,
+              context: this.getContext(),
+              metadata: {
+                createdAt: Date.now(),
+                interrupted: true,
+              },
+            };
+            this._interruptCheckpoint = cp;
+            await adapter.save(cp);
+            throw new CheckpointInterruptError(
+              `Execution interrupted at node "${nodeName}"`,
+              cpId
+            );
+          }
+
+          const cpId = `${checkpointId}-${++this._checkpointCounter}`;
+          const cp: Checkpoint<T> = {
+            id: cpId,
+            graphName: this.name,
+            runId: runIdResolved,
+            nodeName,
+            nextNodes,
+            context: this.getContext(),
+            metadata: { createdAt: Date.now() },
+          };
+          await adapter.save(cp);
+        },
+      };
+    }
+
+    try {
+      const node = this.nodes.get(startNode);
+      if (!node) throw new Error(`Node "${startNode}" not found`);
+
+      await this.nodeExecutor.executeNode(
+        startNode,
+        this.context,
+        false,
+        hooks
+      );
+
+      if (saveOnComplete) {
+        const cpId = `${checkpointId}-${++this._checkpointCounter}`;
+        const cp: Checkpoint<T> = {
+          id: cpId,
+          graphName: this.name,
+          runId: runIdResolved,
+          nodeName: "__completed__",
+          nextNodes: [],
+          context: this.getContext(),
+          metadata: { createdAt: Date.now() },
+        };
+        await adapter.save(cp);
+      }
+
+      this.eventEmitter.emit("graphCompleted", {
+        name: this.name,
+        context: this.context,
+      });
+
+      return { context: this.getContext(), checkpointId };
+    } catch (error) {
+      if (
+        error instanceof CheckpointInterruptError ||
+        error instanceof CheckpointAwaitApprovalError
+      ) {
+        this.eventEmitter.emit("graphError", { name: this.name, error });
+        throw error;
+      }
+      if (saveOnComplete) {
+        const cpId = `${checkpointId}-${++this._checkpointCounter}`;
+        const cp: Checkpoint<T> = {
+          id: cpId,
+          graphName: this.name,
+          runId: runIdResolved,
+          nodeName: "__error__",
+          nextNodes: [],
+          context: this.getContext(),
+          metadata: {
+            createdAt: Date.now(),
+            error: (error as Error).message,
+          },
+        };
+        await adapter.save(cp);
+      }
+      this.eventEmitter.emit("graphError", { name: this.name, error });
+      this.globalErrorHandler?.(error as Error, this.context);
+      throw error;
+    }
+  }
+
+  /**
+   * Resumes execution from a saved checkpoint
+   * @param checkpointId - ID of the checkpoint to resume from
+   * @param adapter - Checkpoint persistence adapter
+   * @returns Final context after execution
+   */
+  public async resumeFromCheckpoint(
+    checkpointId: string,
+    adapter: ICheckpointAdapter,
+    contextModifications?: Partial<Record<string, any>>
+  ): Promise<GraphContext<T>> {
+    const checkpoint = await adapter.load(checkpointId);
+    if (!checkpoint) {
+      throw new Error(`Checkpoint "${checkpointId}" not found`);
+    }
+
+    if (checkpoint.nodeName === "__completed__") {
+      return checkpoint.context as GraphContext<T>;
+    }
+
+    let resumeContext = checkpoint.context;
+    if (contextModifications) {
+      resumeContext = { ...checkpoint.context, ...contextModifications };
+    }
+
+    const validationResult = this.validator?.safeParse(resumeContext);
+    if (!validationResult?.success) {
+      const errors = validationResult?.error?.issues.map(
+        (err) => `${err.path.join(".")}: ${err.message}`
+      );
+      throw new Error(`Context validation failed: ${errors?.join(", ")}`);
+    }
+    this.context = validationResult.data as GraphContext<T>;
+
+    this.eventEmitter.emit("graphStarted", { name: this.name });
+
+    this._interrupted = false;
+    this._interruptCheckpoint = null;
+    this._checkpointCounter = 0;
+
+    const hooks: NodeExecutionHooks<T> = {
+      onBeforeExecuteNext: async (nodeName, ctx, nextNodes) => {
+        const cpId = `${checkpointId}-${++this._checkpointCounter}`;
+        if (this._interrupted) {
+          const cp: Checkpoint<T> = {
+            id: cpId,
+            graphName: this.name,
+            nodeName,
+            nextNodes,
+            context: this.getContext(),
+            metadata: { createdAt: Date.now(), interrupted: true },
+          };
+          this._interruptCheckpoint = cp;
+          await adapter.save(cp);
+          throw new CheckpointInterruptError(
+            `Execution interrupted at node "${nodeName}"`,
+            cpId
+          );
+        }
+
+        const cp: Checkpoint<T> = {
+          id: cpId,
+          graphName: this.name,
+          nodeName,
+          nextNodes,
+          context: this.getContext(),
+          metadata: { createdAt: Date.now() },
+        };
+        await adapter.save(cp);
+      },
+    };
+
+    try {
+      for (const nextNode of checkpoint.nextNodes) {
+        await this.nodeExecutor.executeNode(
+          nextNode,
+          this.context,
+          false,
+          hooks
+        );
+      }
+
+      const cpId = `${checkpointId}-${++this._checkpointCounter}`;
+      const cp: Checkpoint<T> = {
+        id: cpId,
+        graphName: this.name,
+        nodeName: "__completed__",
+        nextNodes: [],
+        context: this.getContext(),
+        metadata: { createdAt: Date.now() },
+      };
+      await adapter.save(cp);
+
+      this.eventEmitter.emit("graphCompleted", {
+        name: this.name,
+        context: this.context,
+      });
+
+      return this.getContext();
+    } catch (error) {
+      if (error instanceof CheckpointInterruptError) {
+        this.eventEmitter.emit("graphError", { name: this.name, error });
+        throw error;
+      }
+      const cpId = `${checkpointId}-${++this._checkpointCounter}`;
+      const cp: Checkpoint<T> = {
+        id: cpId,
+        graphName: this.name,
+        nodeName: "__error__",
+        nextNodes: [],
+        context: this.getContext(),
+        metadata: { createdAt: Date.now(), error: (error as Error).message },
+      };
+      await adapter.save(cp);
+      this.eventEmitter.emit("graphError", { name: this.name, error });
+      this.globalErrorHandler?.(error as Error, this.context);
+      throw error;
+    }
+  }
+
+  /**
+   * Interrupts the current execution and saves a checkpoint
+   */
+  public interrupt(): void {
+    this._interrupted = true;
+  }
+
+  /**
+   * Lists all checkpoints for this graph
+   * @param adapter - Checkpoint persistence adapter
+   * @returns Array of checkpoints sorted by creation date (newest first)
+   */
+  public async listCheckpoints(
+    adapter: ICheckpointAdapter
+  ): Promise<Checkpoint<T>[]> {
+    return adapter.list(this.name);
+  }
+
+  /**
+   * Gets checkpoint history for a specific run
+   * @param runId - Run identifier
+   * @param adapter - Checkpoint persistence adapter
+   * @returns Checkpoints for the specified run, sorted newest first
+   */
+  public async getCheckpointHistory(
+    runId: string,
+    adapter: ICheckpointAdapter
+  ): Promise<Checkpoint<T>[]> {
+    const all = await adapter.list(this.name);
+    return all.filter((cp) => cp.runId === runId);
+  }
+
   /**
    * Emits an event to trigger event-based nodes
    * @param {string} eventName - Name of the event to emit
@@ -313,12 +661,12 @@ export class GraphFlow<T extends ZodSchema> {
     // Parse the new context
     const validationResult = definition.schema.safeParse(definition.context);
     if (!validationResult.success) {
-      const errors = validationResult.error.errors.map(
+      const errors = validationResult.error.issues.map(
         (err) => `${err.path.join(".")}: ${err.message}`
       );
       throw new Error(`Context validation failed: ${errors.join(", ")}`);
     }
-    this.context = validationResult.data;
+    this.context = validationResult.data as GraphContext<T>;
     this.validator = definition.schema;
 
     // Store entry node and graph events
@@ -430,3 +778,23 @@ export class GraphFlow<T extends ZodSchema> {
     return this.execute(nodeName, { input: text });
   }
 }
+
+export class CheckpointInterruptError extends Error {
+  constructor(
+    message: string,
+    public readonly checkpointId: string
+  ) {
+    super(message);
+    this.name = "CheckpointInterruptError";
+  }
+}
+
+export class CheckpointAwaitApprovalError extends Error {
+  constructor(
+    message: string,
+    public readonly checkpointId: string
+  ) {
+    super(message);
+    this.name = "CheckpointAwaitApprovalError";
+  }
+}

package/{graph → execution}/node.ts

@@ -1,8 +1,10 @@
-import { IEventEmitter } from "interfaces";
+import { IEventEmitter, ICheckpointAdapter } from "interfaces";
 import { BehaviorSubject, Subject } from "rxjs";
 import { ZodSchema } from "zod";
-import { GraphContext, GraphEvent, GraphNodeConfig } from "../types";
+import { Checkpoint, GraphContext, GraphEvent, GraphNodeConfig } from "../types";
 import { GraphEventManager } from "./event-manager";
+import { SendAPI } from "./send-api";
+import { applyReducers } from "./reducer";
 
 /**
  * Represents a node in the graph that can execute operations and manage state
@@ -16,6 +18,15 @@ export interface GraphLogger {
   addLog: (message: string, data?: any) => void;
 }
 
+export interface NodeExecutionHooks<T extends ZodSchema> {
+  onBeforeExecute?: (nodeName: string, context: GraphContext<T>) => Promise<void>;
+  onBeforeExecuteNext?: (
+    nodeName: string,
+    context: GraphContext<T>,
+    nextNodes: string[]
+  ) => Promise<void>;
+}
+
 export class GraphNode<T extends ZodSchema> {
   private lastStateEvent: GraphEvent<T> | null = null;
   private eventEmitter: IEventEmitter;
@@ -81,16 +92,22 @@ export class GraphNode<T extends ZodSchema> {
    * @param context - The current graph context
    * @param params - Input data for the node
    * @param triggeredByEvent - Whether the execution was triggered by an event
+   * @param hooks - Optional execution hooks
    * @throws Error if the node is not found or execution fails
    */
   public async executeNode(
     nodeName: string,
     context: GraphContext<T>,
-    triggeredByEvent: boolean = false
+    triggeredByEvent: boolean = false,
+    hooks?: NodeExecutionHooks<T>
   ): Promise<void> {
     const node = this.nodes.get(nodeName);
     if (!node) throw new Error(`Node "${nodeName}" not found.`);
 
+    if (hooks?.onBeforeExecute) {
+      await hooks.onBeforeExecute(nodeName, context);
+    }
+
     const nodeContext = { ...context };
     this.emitEvent("nodeStarted", { name: nodeName, context: nodeContext });
 
@@ -105,7 +122,6 @@ export class GraphNode<T extends ZodSchema> {
           if (oldValue === value) return true;
 
           target[prop.toString()] = value;
-          // Mettre à jour le contexte global
           context[prop.toString() as keyof typeof context] = value;
 
           this.emitEvent("nodeStateChanged", {
@@ -126,14 +142,53 @@ export class GraphNode<T extends ZodSchema> {
       await this.executeWithRetry(node, contextProxy, nodeName);
       this.emitEvent("nodeCompleted", { name: nodeName, context: nodeContext });
 
-      if (!triggeredByEvent && node.next) {
+      // ====== HANDOFF / COMMAND DETECTION ======
+      const command = (context as any)._handoff || (context as any)._command;
+      if (command?.goto) {
+        if (command.graph === "PARENT") {
+          return; // Stop here; parent orchestrator checks context._handoff
+        }
+        if (this.nodes.has(command.goto)) {
+          if (command.update) Object.assign(context, command.update);
+          await this.executeNode(command.goto, context, false, hooks);
+          return;
+        }
+      }
+
+      if (!triggeredByEvent && (node.next || (node as any).send)) {
         const nextNodes =
           typeof node.next === "function" ? node.next(contextProxy) : node.next;
 
-        // Vérifier d'abord les conditions de tous les nœuds suivants
-        const nextNodeConfigs = Array.isArray(nextNodes)
-          ? nextNodes
-          : [nextNodes];
+        // ====== SEND API (Fan-out dynamique) ======
+        if ((node as any).send) {
+          const sends = (node as any).send(contextProxy);
+          const branchResults = await SendAPI.processSends(
+            sends,
+            context,
+            (nodeName: string, ctx: any) => this.executeNode(nodeName, ctx, false, hooks)
+          );
+
+          // Merge avec reducers
+          const merged = applyReducers(
+            context,
+            branchResults,
+            (node as any).reducers || []
+          );
+          Object.assign(context, merged);
+
+          // Si un joinNode est spécifié (dans parallel), l'exécuter
+          const joinNode = (node as any).parallel?.joinNode;
+          if (joinNode) {
+            await this.executeNode(joinNode, context, false, hooks);
+          }
+
+          return; // Pas de next séquentiel après Send
+        }
+
+        // Filtrer les valeurs nulles/undefined
+        const nextNodeConfigs = (Array.isArray(nextNodes) ? nextNodes : [nextNodes]).filter(
+          (n) => n != null
+        );
         const validNextNodes = nextNodeConfigs
           .map((nextNode) => {
             const nextNodeName =
@@ -143,14 +198,63 @@ export class GraphNode<T extends ZodSchema> {
             return {
               name: nextNodeName,
               condition,
-              isValid: !condition || condition(contextProxy),
+              isValid: !condition || (condition && condition(contextProxy)),
             };
           })
           .filter((n) => n.isValid);
 
-        // Sinon, exécuter les autres nœuds valides
+        const nextNodeNames = validNextNodes.map((n) => n.name);
+
+        if (hooks?.onBeforeExecuteNext) {
+          await hooks.onBeforeExecuteNext(nodeName, context, nextNodeNames);
+        }
+
+        // ====== PARALLÉLISME FORK-JOIN ======
+        if ((node as any).parallel?.enabled) {
+          const { joinNode, reducers, mergeStrategy } = (node as any).parallel;
+
+          // Fork : cloner le contexte pour chaque branche
+          const branchContexts = validNextNodes.map((n, i: number) => ({
+            nodeName: n.name,
+            context: structuredClone(context),
+            branchId: `${n.name}_${i}`,
+          }));
+
+          // Exécution parallèle (Promise.all)
+          const branchResults = await Promise.all(
+            branchContexts.map(async ({ nodeName, context: ctx, branchId }: any) => {
+              await this.executeNode(nodeName, ctx, false, hooks);
+              return { branchId, context: ctx };
+            })
+          );
+
+          // Join : merger les résultats
+          if (reducers && reducers.length > 0) {
+            const merged = applyReducers(context, branchResults, reducers);
+            Object.assign(context, merged);
+          } else if (mergeStrategy === "isolated") {
+            branchResults.forEach(({ branchId, context: ctx }: any) => {
+              (context as any)[`branch_${branchId}`] = ctx;
+            });
+          } else {
+            // deep-merge par défaut
+            const { deepMerge } = require("./reducer");
+            const merged = deepMerge(context, ...branchResults.map((r: any) => r.context));
+            Object.assign(context, merged);
+          }
+
+          // Si un joinNode est spécifié, l'exécuter
+          if (joinNode) {
+            await this.executeNode(joinNode, context, false, hooks);
+          }
+
+          return;
+        }
+
+        // ====== SÉQUENTIEL (logique existante) ======
         for (const nextNode of validNextNodes) {
-          await this.executeNode(nextNode.name, context, false);
+          await this.executeNode(nextNode.name, context, false, hooks);
+          if ((context as any)._handoff || (context as any)._command) break;
         }
       }
     } catch (error) {

package/execution/planner.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { ToolRegistry, PlanStep } from './registry';
+
+export const PlanSchema = z.object({
+  goal: z.string(),
+  steps: z.array(
+    z.object({
+      node: z.string(),
+      params: z.record(z.string(), z.any()).optional(),
+      description: z.string().optional(),
+    })
+  ),
+});
+
+export type Plan = z.infer<typeof PlanSchema>;
+
+export async function generatePlan(
+  userIntent: string,
+  registry: ToolRegistry,
+  llmCall: (prompt: string) => Promise<string>
+): Promise<Plan> {
+  const availableTools = registry.list();
+
+  const prompt = `You are a workflow planner. Generate a structured plan as JSON with "goal" (string) and "steps" (array of { node: string, params?: Record<string, any>, description?: string }).
+Only use tools from the available list.
+
+Available tools:
+${availableTools.map(t => `- ${t.name}: ${t.description}`).join('\n')}
+
+User intent: ${userIntent}
+
+Respond with valid JSON only.`;
+
+  const response = await llmCall(prompt);
+  return PlanSchema.parse(JSON.parse(response));
+}
+
+export function renderPlan(plan: Plan): string {
+  return `Goal: ${plan.goal}\nSteps:\n${plan.steps.map((s, i) => `${i + 1}. ${s.node}${s.description ? ` (${s.description})` : ''}`).join('\n')}`;
+}