@ai.ntellect/core 1.0.0 → 1.1.0

package/execution/logger.ts

@@ -0,0 +1,70 @@
+/**
+ * Handles logging operations for a graph instance
+ * Provides methods for adding, retrieving, and managing logs with optional verbose output
+ */
+export class GraphLogger {
+  private logs: string[] = [];
+  private verbose: boolean = false;
+
+  /**
+   * Creates a new GraphLogger instance
+   * @param graphName - The name of the graph this logger is associated with
+   * @param verbose - Whether to output logs to console in real-time
+   */
+  constructor(private graphName: string, verbose: boolean = false) {
+    this.verbose = verbose;
+  }
+
+  /**
+   * Adds a new log entry with timestamp
+   * @param message - The message to log
+   */
+  public addLog(message: string): void {
+    const timestamp = new Date().toISOString();
+    const logMessage = `[${timestamp}] ${message}`;
+    this.logs.push(logMessage);
+    if (this.verbose) {
+      console.log(`${this.graphName} - ${message}`);
+    }
+  }
+
+  /**
+   * Returns a copy of all stored logs
+   * @returns Array of log messages
+   */
+  public getLogs(): string[] {
+    return [...this.logs];
+  }
+
+  /**
+   * Clears all stored logs
+   */
+  public clearLogs(): void {
+    this.logs = [];
+  }
+
+  /**
+   * Sets the verbose mode
+   * @param enabled - Whether to enable verbose mode
+   */
+  public setVerbose(enabled: boolean): void {
+    this.verbose = enabled;
+  }
+
+  /**
+   * Gets the current verbose mode status
+   * @returns Current verbose mode state
+   */
+  public isVerbose(): boolean {
+    return this.verbose;
+  }
+
+  /**
+   * Logs a message to console with graph name prefix
+   * @param message - The message to log
+   * @param data - Optional data to log
+   */
+  log(message: string, data?: any): void {
+    console.log(`[Graph ${this.graphName}] ${message}`, data);
+  }
+}

package/execution/node.ts

@@ -0,0 +1,315 @@
+import { IEventEmitter, ICheckpointAdapter } from "interfaces";
+import { BehaviorSubject, Subject } from "rxjs";
+import { ZodSchema } from "zod";
+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
+ * @template T - The Zod schema type for validation
+ */
+export interface NodeParams<T = any> {
+  [key: string]: T;
+}
+
+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;
+
+  /**
+   * Creates a new GraphNode instance
+   * @param nodes - Map of all nodes in the graph
+   * @param logger - Logger instance for tracking node operations
+   * @param eventManager - Manager for handling graph events
+   * @param eventSubject - Subject for emitting events
+   * @param stateSubject - Subject for managing graph state
+   */
+  constructor(
+    private nodes: Map<string, GraphNodeConfig<T, any>>,
+    private logger: GraphLogger,
+    private eventManager: GraphEventManager<T>,
+    private eventSubject: Subject<GraphEvent<T>>,
+    private stateSubject: BehaviorSubject<GraphContext<T>>
+  ) {
+    this.eventEmitter = eventManager["eventEmitter"];
+  }
+
+  /**
+   * Emits an event with the specified type and payload
+   * @param type - The type of event to emit
+   * @param payload - The data associated with the event
+   * @private
+   */
+  private emitEvent(type: string, payload: any) {
+    if (type === "nodeStateChanged") {
+      if (
+        this.lastStateEvent?.type === type &&
+        this.lastStateEvent.payload.property === payload.property &&
+        this.lastStateEvent.payload.newValue === payload.newValue &&
+        this.lastStateEvent.payload.nodeName === payload.nodeName
+      ) {
+        return;
+      }
+    }
+
+    const event = {
+      type,
+      payload: {
+        ...payload,
+        name: type === "nodeStateChanged" ? payload.nodeName : payload.name,
+        context: { ...payload.context },
+      },
+      timestamp: Date.now(),
+    };
+
+    this.eventSubject.next(event);
+    this.eventManager.emitEvent(type, event);
+
+    if (type === "nodeStateChanged") {
+      this.lastStateEvent = event;
+      this.stateSubject.next({ ...payload.context });
+    }
+  }
+
+  /**
+   * Executes a node with the given name and context
+   * @param nodeName - The name of the node to execute
+   * @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,
+    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 });
+
+    try {
+      if (node.when) {
+        await this.eventManager.handleNodeEvents(nodeName, node.when);
+      }
+
+      const contextProxy = new Proxy(nodeContext, {
+        set: (target: any, prop: string | symbol, value: any) => {
+          const oldValue = target[prop.toString()];
+          if (oldValue === value) return true;
+
+          target[prop.toString()] = value;
+          context[prop.toString() as keyof typeof context] = value;
+
+          this.emitEvent("nodeStateChanged", {
+            nodeName,
+            property: prop.toString(),
+            oldValue,
+            newValue: value,
+            context: { ...target },
+          });
+          return true;
+        },
+      });
+
+      if (node.condition && !node.condition(contextProxy)) {
+        return;
+      }
+
+      await this.executeWithRetry(node, contextProxy, nodeName);
+      this.emitEvent("nodeCompleted", { name: nodeName, context: nodeContext });
+
+      // ====== 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;
+
+        // ====== 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 =
+              typeof nextNode === "string" ? nextNode : nextNode.node;
+            const condition =
+              typeof nextNode === "string" ? undefined : nextNode.condition;
+            return {
+              name: nextNodeName,
+              condition,
+              isValid: !condition || (condition && condition(contextProxy)),
+            };
+          })
+          .filter((n) => n.isValid);
+
+        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, hooks);
+          if ((context as any)._handoff || (context as any)._command) break;
+        }
+      }
+    } catch (error) {
+      this.emitEvent("nodeError", {
+        name: nodeName,
+        error,
+        context: nodeContext,
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Executes a node with retry logic
+   * @param node - The node to execute
+   * @param contextProxy - The proxied graph context
+   * @param params - Input data for the node
+   * @param nodeName - The name of the node
+   * @param params - Parameters for the node
+   * @throws Error if all retry attempts fail
+   * @private
+   */
+  private async executeWithRetry(
+    node: GraphNodeConfig<T, any>,
+    contextProxy: GraphContext<T>,
+    nodeName: string
+  ): Promise<void> {
+    let attempts = 0;
+    let lastError: Error = new Error("Unknown error");
+
+    while (attempts < (node.retry?.maxAttempts || 1)) {
+      try {
+        await node.execute(contextProxy, {
+          eventEmitter: this.eventEmitter,
+        });
+        return;
+      } catch (error: any) {
+        lastError =
+          error instanceof Error
+            ? error
+            : new Error(error?.message || "Unknown error");
+        attempts++;
+
+        if (attempts === (node.retry?.maxAttempts || 1)) {
+          if (node.retry?.onRetryFailed) {
+            await node.retry.onRetryFailed(lastError, contextProxy);
+            if (node.retry.continueOnFailed) return;
+          }
+          throw lastError;
+        }
+
+        await new Promise((resolve) =>
+          setTimeout(resolve, node.retry?.delay || 0)
+        );
+      }
+    }
+  }
+}

package/execution/observer.ts

@@ -0,0 +1,192 @@
+import {
+  BehaviorSubject,
+  Observable,
+  Subject,
+  combineLatest,
+  firstValueFrom,
+} from "rxjs";
+import {
+  debounceTime,
+  distinctUntilChanged,
+  filter,
+  map,
+  share,
+  take,
+  takeUntil,
+} from "rxjs/operators";
+import { ZodSchema } from "zod";
+import { GraphObservable } from "../interfaces";
+import { GraphContext, GraphEvent, ObserverOptions } from "../types";
+import { GraphEventManager } from "./event-manager";
+import { GraphFlow } from "./index";
+
+/**
+ * GraphObserver class provides reactive observation capabilities for a GraphFlow instance
+ * It allows monitoring state changes, node updates, and specific events in the graph
+ * @template T - The Zod schema type that defines the structure of the graph data
+ */
+export class GraphObserver<T extends ZodSchema> {
+  constructor(
+    private graph: GraphFlow<T>,
+    private eventSubject: Subject<GraphEvent<T>>,
+    private stateSubject: BehaviorSubject<GraphContext<T>>,
+    private destroySubject: Subject<void>,
+    private eventManager: GraphEventManager<T>
+  ) {}
+
+  /**
+   * Observes the entire graph state changes
+   * @param options Configuration options for the observation
+   * @returns An Observable that emits the complete graph context whenever it changes
+   */
+  state(options: ObserverOptions = {}): GraphObservable<T> {
+    const baseObservable = new Observable<any>((subscriber) => {
+      const subscription = combineLatest([
+        this.eventSubject.pipe(
+          filter((event) => event.type === "nodeStateChanged"),
+          map((event) => event.payload.context),
+          distinctUntilChanged(
+            (prev, curr) => JSON.stringify(prev) === JSON.stringify(curr)
+          ),
+          debounceTime(options.debounce || 100)
+        ),
+        this.stateSubject,
+      ])
+        .pipe(
+          map(([eventContext, stateContext]) => ({
+            ...stateContext,
+            ...eventContext,
+          })),
+          distinctUntilChanged(
+            (prev, curr) => JSON.stringify(prev) === JSON.stringify(curr)
+          )
+        )
+        .subscribe(subscriber);
+
+      if (options.stream && options.properties) {
+        const context = this.stateSubject.getValue();
+        options.properties.forEach((property) => {
+          const message = context[property];
+          if (message) {
+            this.streamMessage(
+              message.toString(),
+              500,
+              property as string
+            ).subscribe({
+              next: (data) => options.onStreamLetter?.(data),
+              complete: () => options.onStreamComplete?.(),
+            });
+          }
+        });
+      }
+
+      return () => subscription.unsubscribe();
+    });
+
+    return Object.assign(baseObservable, {
+      state: () => this.stateSubject.asObservable(),
+      node: (nodeName: string) =>
+        this.stateSubject.pipe(map((state) => ({ ...state, nodeName }))),
+      nodes: (nodeNames: string[]) =>
+        this.eventSubject.pipe(
+          filter(
+            (event) =>
+              event.type === "nodeStateChanged" &&
+              nodeNames.includes(event.payload?.name ?? "")
+          ),
+          map((event) => event.payload.context),
+          distinctUntilChanged(
+            (prev, curr) => JSON.stringify(prev) === JSON.stringify(curr)
+          ),
+          takeUntil(this.destroySubject),
+          share()
+        ),
+      property: (props: string | string[]) =>
+        this.stateSubject.pipe(
+          map((state) => {
+            const properties = Array.isArray(props) ? props : [props];
+            return properties.reduce(
+              (acc, prop) => ({
+                ...acc,
+                [prop]: state[prop],
+              }),
+              {}
+            );
+          })
+        ),
+      event: (eventName: string) =>
+        this.eventSubject.pipe(filter((event) => event.type === eventName)),
+      until: (
+        observable: Observable<any>,
+        predicate: (state: any) => boolean
+      ) => firstValueFrom(observable.pipe(filter(predicate), take(1))),
+    }) as GraphObservable<T>;
+  }
+
+  /**
+   * Waits for correlated events to occur and validates them using a correlation function
+   * @param eventTypes - Array of event types to wait for
+   * @param timeoutMs - Timeout in milliseconds
+   * @param correlationFn - Function to validate event correlation
+   * @returns Promise that resolves with the correlated events
+   */
+  waitForCorrelatedEvents(
+    eventTypes: string[],
+    timeoutMs: number,
+    correlationFn: (events: GraphEvent<T>[]) => boolean
+  ): Promise<GraphEvent<T>[]> {
+    return new Promise((resolve, reject) => {
+      const events: GraphEvent<T>[] = [];
+      const timeout = setTimeout(() => {
+        reject(
+          new Error(
+            `Timeout waiting for correlated events: ${eventTypes.join(", ")}`
+          )
+        );
+      }, timeoutMs);
+
+      const subscription = this.eventSubject
+        .pipe(
+          filter((event) => eventTypes.includes(event.type)),
+          takeUntil(this.destroySubject)
+        )
+        .subscribe({
+          next: (event) => {
+            events.push(event);
+            if (events.length === eventTypes.length && correlationFn(events)) {
+              clearTimeout(timeout);
+              subscription.unsubscribe();
+              resolve(events);
+            }
+          },
+          error: (error) => {
+            clearTimeout(timeout);
+            subscription.unsubscribe();
+            reject(error);
+          },
+        });
+    });
+  }
+
+  /**
+   * Streams a message letter by letter with a specified delay
+   */
+  private streamMessage(
+    message: string,
+    delayMs: number,
+    property: string
+  ): Observable<{ letter: string; property: string }> {
+    return new Observable<{ letter: string; property: string }>(
+      (subscriber) => {
+        for (let i = 0; i < message.length; i++) {
+          setTimeout(() => {
+            subscriber.next({ letter: message[i], property });
+            if (i === message.length - 1) {
+              subscriber.complete();
+            }
+          }, i * delayMs);
+        }
+      }
+    );
+  }
+}

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')}`;
+}

package/execution/reducer.ts

@@ -0,0 +1,73 @@
+import { StateReducer } from "./types.parallel";
+
+/**
+ * Implémentation des State Reducers (pattern LangGraph)
+ * Gère le merge des contextes après exécution parallèle
+ */
+
+// Fonction de deep merge simple (sans dépendance externe)
+export function deepMerge<T extends Record<string, any>>(...objects: T[]): T {
+  const result: any = {};
+
+  for (const obj of objects) {
+    if (obj === null || obj === undefined) continue;
+    
+    for (const key of Object.keys(obj)) {
+      const val = obj[key];
+      
+      if (val !== null && typeof val === "object" && !Array.isArray(val)) {
+        // Objet : merge récursif
+        result[key] = deepMerge(result[key] || {}, val);
+      } else if (Array.isArray(val) && Array.isArray(result[key])) {
+        // Array : concaténation
+        result[key] = [...result[key], ...val];
+      } else {
+        // Primitive ou nouvel objet : remplacement
+        result[key] = val;
+      }
+    }
+  }
+
+  return result as T;
+}
+
+export type ReducerFunction<T = any> = (acc: T, value: T) => T;
+
+export const Reducers = {
+  // Concatène les arrays
+  append: <T>(acc: T[], value: T[]): T[] => [...acc, ...value],
+  
+  // Merge profond
+  deepMerge: <T>(acc: T, value: T): T => deepMerge(acc as any, value as any) as T,
+  
+  // Dernière valeur gagne
+  lastWins: <T>(_acc: T, value: T): T => value,
+  
+  // Somme (pour nombres)
+  sum: (acc: number, value: number): number => acc + value,
+  
+  // Pour les branches isolées (ctx.branch_0, ctx.branch_1, ...)
+  isolated: (acc: Record<string, any>, value: any, branchId: string): Record<string, any> => {
+    acc[`branch_${branchId}`] = value;
+    return acc;
+  },
+};
+
+export function applyReducers(
+  context: any,
+  branchResults: Array<{ context: any; branchId: string }>,
+  reducers: StateReducer[] = []
+): any {
+  if (reducers.length === 0) {
+    // Deep merge par défaut
+    return deepMerge(context, ...branchResults.map(br => br.context));
+  }
+
+  const result = { ...context };  
+  for (const reducer of reducers) {
+    const values = branchResults.map(br => br.context[reducer.key]);
+    result[reducer.key] = values.reduce(reducer.reducer, reducer.initial);
+  }
+  
+  return result;
+}