@ai.ntellect/core 0.8.3 → 1.1.0

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;
+}

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/index.ts

@@ -11,22 +11,49 @@
  * - Utility functions for action schema generation and header building
  */
 
-export * from "./modules/agent/agent";
-export * from "./modules/agent/prompt-builder";
+export * from "./agent/agent";
+export * from "./agent/prompt-builder";
 
-export * from "./graph/controller";
-export * from "./graph/event-manager";
-export * from "./graph/index";
-export * from "./graph/node";
-export * from "./graph/observer";
-export * from "./graph/visualizer";
+export * from "./execution/controller";
+export * from "./execution/event-manager";
+export * from "./execution/index";
+export * from "./execution/node";
+export * from "./execution/observer";
+export * from "./execution/visualizer";
+export * from "./execution/registry";
+export * from "./execution/planner";
+export * from "./execution/compiler";
 
 export * from "./interfaces";
 export * from "./modules/agenda";
 export * from "./modules/embedding";
 export * from "./modules/memory";
 
+// Persistence barrel — unified storage layer
+export * from "./persistence";
+
 export * from "./types";
 
 export * from "./utils/generate-action-schema";
 export * from "./utils/header-builder";
+
+export { AgentRegistry, type AgentRegistration } from "./agent/registry";
+export { createHandoffTool, createCommand } from "./agent/handoff";
+export { OrchestratorAgent, type OrchestratorConfig } from "./agent/orchestrator";
+
+export { startCLI, runCLI, type CLIConfig } from "./modules/cli";
+
+// PetriNet core — deterministic routing engine (thesis backbone)
+export { PetriNet } from "./routing/index";
+export { CortexFlowOrchestrator } from "./routing/orchestrator";
+export type { Session, FallbackLLM } from "./routing/orchestrator";
+export { IntentClassifier, HybridIntentClassifier } from "./routing/intent-classifier";
+export type { IntentResult, IntentClassifierFn } from "./routing/intent-classifier";
+export type { Token, Place, Transition, Guard, TransitionAction, TransitionResult, PetriNetState } from "./routing/types";
+export { IPetriCheckpointAdapter, InMemoryPetriCheckpointAdapter } from "./routing/checkpoint-adapter";
+export { RedisPetriCheckpointAdapter } from "./routing/redis-checkpoint-adapter";
+export { PostgresPetriCheckpointAdapter } from "./routing/postgres-checkpoint-adapter";
+
+// Pipeline - High-level abstraction for agent orchestration
+export { AgentPipeline, priceZone } from "./pipeline/agent-pipeline";
+export type { Stage, PriceTrigger, AgentPipelineConfig } from "./pipeline/agent-pipeline";

package/interfaces/index.ts

@@ -2,6 +2,7 @@ import { Observable } from "rxjs";
 import { ZodSchema } from "zod";
 import {
   BaseMemoryType,
+  Checkpoint,
   CreateMemoryInput,
   GraphContext,
   GraphEvent,
@@ -558,3 +559,39 @@ export interface NLPNodeConfig<T extends ZodSchema>
   };
   intentHandlers?: Record<string, (data: any) => Promise<any>>;
 }
+
+/* ======================== CHECKPOINT ======================== */
+
+/**
+ * Interface for checkpoint persistence adapters
+ */
+export interface ICheckpointAdapter {
+  save(checkpoint: Checkpoint): Promise<void>;
+  load(id: string): Promise<Checkpoint | null>;
+  list(graphName: string): Promise<Checkpoint[]>;
+  delete(id: string): Promise<void>;
+  clear(graphName?: string): Promise<void>;
+}
+
+export interface MemoryRelation {
+  fromId: string;
+  toId: string;
+  type: string;
+  properties?: Record<string, any>;
+  roomId: string;
+}
+
+export interface IGraphMemoryAdapter extends IMemoryAdapter {
+  addRelation(relation: MemoryRelation): Promise<void>;
+  removeRelation(fromId: string, toId: string, type: string, roomId: string): Promise<void>;
+  getRelated(
+    id: string,
+    options: {
+      roomId: string;
+      relationTypes?: string[];
+      direction?: "in" | "out" | "both";
+      depth?: number;
+      limit?: number;
+    }
+  ): Promise<Array<{ memory: BaseMemoryType; relationPath: string[] }>>;
+}