@ai.ntellect/core 0.6.20 → 0.7.0

package/.mocharc.json

@@ -1,4 +1,5 @@
 {
   "extension": ["ts"],
-  "require": ["ts-node/register"]
+  "require": ["./node_modules/ts-node/register"],
+  "timeout": 5000
 }

package/README.md

@@ -1,192 +1,131 @@
-# **@ai.ntellect/core Documentation**
+# @ai.ntellect/core
 
-## **1. Introduction**
+@ai.ntellect/core is a modular and event-driven framework designed to orchestrate and execute intelligent workflows using execution graphs. It enables automation of complex tasks, seamless integration with external services, and the creation of AI-driven agents in a flexible and scalable way.
 
-The **`@ai.ntellect/core`** framework is a powerful tool designed to **model, execute, and manage dynamic interaction flows** using **graph structures**. Unlike traditional **Directed Acyclic Graphs (DAGs)**, this framework supports cycles, enabling nodes to be executed multiple times and allowing for loop-based workflows.
+## Features
 
-### **Key Features**
+- **GraphFlow** – Graph-based execution engine for automating business processes
+- **Event-Driven** – Nodes can react to real-time events and trigger actions dynamically
+- **Modular** – Plug-and-play modules and adapters for memory, scheduling, and external APIs
+- **Extensible** – Custom nodes, adapters, and interactions with third-party services
+- **Observable** – Complete state and event monitoring
 
-- Dynamic workflow execution
-- Cyclic and acyclic graph support
-- Strong typing with Zod validation
-- Event-driven architecture
-- Built-in error handling and retries
-- Conditional execution paths
-- Parameter validation
-- State management
+## Installation
 
-### **Common Use Cases**
+### Prerequisites
 
-- **AI Agents**: Building conversational AI systems that can maintain context and make decisions
-- **Transaction Processing**: Managing complex financial workflows with validation chains
-- **Task Orchestration**: Coordinating multiple dependent operations
-- **Decision Trees**: Implementing complex business logic with multiple branches
-- **State Machines**: Managing application state transitions
-- **Event Processing**: Handling and responding to system events
+- Node.js (LTS version recommended)
+- TypeScript
+- Zod (for data validation)
 
-## **2. Core Concepts**
+Verify your installation:
 
-### **2.1 Graph Theory Foundation**
-
-A directed graph in our framework is defined as **G = (V, E)** where:
-
-- **V**: Set of nodes (vertices)
-- **E**: Set of directed edges
-
-Each node represents an executable action, and edges represent conditional transitions between actions.
-
-#### Example Graph Structure:
-
-```
-(ValidateInput) → (ProcessData) → (SaveResult)
-       ↓                              ↑
-    (RetryInput) ──────────────────────
-```
-
-### **2.2 Node Types**
-
-#### **Basic Node**
-
-```typescript
-const basicNode: Node<ContextType> = {
-  name: "processData",
-  execute: async (context) => {
-    // Process data
-  },
-  next: ["saveResult"],
-};
-```
-
-#### **Conditional Node**
-
-```typescript
-const conditionalNode: Node<ContextType> = {
-  name: "validateInput",
-  condition: (context) => context.isValid,
-  execute: async (context) => {
-    // Validation logic
-  },
-  next: ["processData"],
-};
+```sh
+node -v
+npm -v
 ```
 
-## **3. Advanced Features**
-
-### **3.1 Event-Driven Execution**
-
-Nodes can respond to system events:
+### Installing the framework
 
-```typescript
-const eventNode: Node<ContextType> = {
-  name: "handleUserInput",
-  events: ["userSubmitted"],
-  execute: async (context) => {
-    // Handle user input
-  },
-};
+```sh
+npm install @ai.ntellect/core zod
 ```
 
-### **3.2 Retry Mechanisms**
-
-Built-in retry support for handling transient failures:
+## Example
 
 ```typescript
-const retryableNode: Node<ContextType> = {
-  name: "apiCall",
-  retry: {
-    maxAttempts: 3,
-    delay: 1000, // ms
-  },
-  execute: async (context) => {
-    // API call logic
-  },
-};
-```
+import { z } from "zod";
+import { GraphFlow } from "@ai.ntellect/core";
 
-## **4. Real-World Examples**
-
-### **4.1 AI Agent Workflow**
+// Define context schema
+const ContextSchema = z.object({
+  message: z.string(),
+  counter: z.number(),
+});
 
-```typescript
-const aiAgentGraph = new Graph<AIContextType>("AIAgent", {
+// Create graph instance
+const graph = new GraphFlow<typeof ContextSchema>("MyGraph", {
+  name: "MyGraph",
+  schema: ContextSchema,
+  context: { message: "Hello", counter: 0 },
   nodes: [
     {
-      name: "analyzeInput",
+      name: "incrementCounter",
       execute: async (context) => {
-        context.intent = await analyzeUserIntent(context.input);
+        context.counter++;
       },
-      next: ["selectAction"],
+      next: ["checkThreshold"],
     },
     {
-      name: "selectAction",
+      name: "checkThreshold",
+      condition: (context) => context.counter < 5,
       execute: async (context) => {
-        context.selectedAction = determineNextAction(context.intent);
+        if (context.counter >= 5) {
+          context.message = "Threshold reached!";
+        }
       },
-      next: ["validateResponse"],
-    },
-    {
-      name: "generateResponse",
-      execute: async (context) => {
-        context.response = await generateAIResponse(context);
+      next: ["incrementCounter"],
+      retry: {
+        maxAttempts: 3,
+        delay: 1000,
       },
-      next: ["validateResponse"],
     },
   ],
 });
+
+// Observe state changes
+(async () => {
+  // Execute the graph
+  graph.execute("incrementCounter");
+  graph.observe().state().subscribe(console.log);
+})();
 ```
 
-### **4.2 Transaction Processing**
+## Features
+
+### Event handling
 
 ```typescript
-const transactionGraph = new Graph<TransactionContext>("TransactionProcessor", {
-  nodes: [
-    {
-      name: "validateFunds",
-      execute: async (context) => {
-        context.hasSufficientFunds = await checkBalance(context.amount);
-      },
-      next: ["processPayment"],
-    },
-    {
-      name: "processPayment",
-      retry: {
-        maxAttempts: 3,
-        delay: 1000,
-      },
-      condition: (context) => context.hasSufficientFunds,
-      execute: async (context) => {
-        await processPayment(context.transactionData);
-      },
-      next: ["notifyUser"],
-    },
-  ],
-});
+// Event-driven node
+{
+  name: "waitForEvent",
+  events: ["dataReceived"],
+  execute: async (context, event) => {
+    context.data = event.payload;
+  }
+}
+
+// Emit events
+graph.emit("dataReceived", { value: 42 });
 ```
 
-## **5. Event Listeners**
+### State observation
 
 ```typescript
-graph.on("nodeStarted", ({ name, context }) => {
-  console.log(`Node ${name} started with context:`, context);
-});
+// Observe specific node
+graph.observe().node("myNode").subscribe(console.log);
 
-graph.on("nodeCompleted", ({ name, context }) => {
-  console.log(`Node ${name} completed with context:`, context);
-});
+// Observe specific properties
+graph.observe().property("counter").subscribe(console.log);
 
-graph.on("nodeError", ({ name, error }) => {
-  console.error(`Error in node ${name}:`, error);
-});
+// Observe events
+graph.observe().event("nodeCompleted").subscribe(console.log);
 ```
 
-## **6. Future Developments**
+## Documentation
+
+For complete documentation, visit our [GitBook](https://ai-ntellect.gitbook.io/core).
+
+## Contributing
+
+Contributions are welcome! To suggest an improvement or report an issue:
 
-Planned features include:
+- Join our [Discord community](https://discord.gg/kEc5gWXJ)
+- Explore the [GitBook documentation](https://ai-ntellect.gitbook.io/core)
+- Open an issue on GitHub
 
-- Advanced memory management for AI agents
-- Graph composition and nesting
-- Real-time monitoring dashboard
-- Performance analytics
-- Distributed execution support
+## Useful links
 
-For more information and updates, visit the official documentation or join our community discussions.
+- Documentation: [GitBook](https://ai-ntellect.gitbook.io/core)
+- Community: [Discord](https://discord.gg/kEc5gWXJ)
+- GitHub Repository: [@ai.ntellect/core](https://github.com/ai-ntellect/core)

package/graph/controller.ts

@@ -6,7 +6,7 @@ import { GraphFlow } from "./index";
  * Controller class for managing the execution of graph flows
  * Handles both sequential and parallel execution of multiple graphs
  */
-export class GraphController {
+export class GraphFlowController {
   /**
    * Executes multiple graphs sequentially
    * @param graphs - Array of GraphFlow instances to execute

package/graph/event-manager.ts

@@ -0,0 +1,288 @@
+import { Observable, Subject, filter } from "rxjs";
+import { ZodSchema } from "zod";
+import { IEventEmitter } from "../interfaces";
+import { GraphContext, GraphEvent, Node } from "../types";
+import { GraphNode } from "./node";
+
+/**
+ * Manages event handling and routing for a graph
+ * Coordinates event emission, listening, and execution of event-driven nodes
+ * @template T - The Zod schema type for validation
+ */
+export class GraphEventManager<T extends ZodSchema> {
+  private eventSubject: Subject<GraphEvent<T>> = new Subject();
+  private nodeStreams: Map<string, Observable<GraphEvent<T>>> = new Map();
+  private context: GraphContext<T>;
+  private name: string;
+  private graphEvents?: string[];
+  private entryNode?: string;
+  private globalErrorHandler?: (error: Error, context: GraphContext<T>) => void;
+
+  /**
+   * Creates a new GraphEventManager instance
+   * @param eventEmitter - The event emitter implementation to use
+   * @param nodes - Map of all nodes in the graph
+   * @param name - Name of the graph
+   * @param context - Initial graph context
+   * @param graphEvents - List of events the graph should listen to
+   * @param entryNode - Name of the entry node for graph events
+   * @param globalErrorHandler - Global error handling function
+   * @param nodeExecutor - GraphNode instance for executing nodes
+   */
+  constructor(
+    private eventEmitter: IEventEmitter,
+    private nodes: Map<string, Node<T, any>>,
+    name: string,
+    context: GraphContext<T>,
+    graphEvents?: string[],
+    entryNode?: string,
+    globalErrorHandler?: (error: Error, context: GraphContext<T>) => void,
+    private nodeExecutor?: GraphNode<T>
+  ) {
+    this.name = name;
+    this.context = context;
+    this.graphEvents = graphEvents;
+    this.entryNode = entryNode;
+    this.globalErrorHandler = globalErrorHandler;
+    this.setupEventStreams();
+  }
+
+  /**
+   * Sets up event streams for all nodes that listen to events
+   */
+  public setupEventStreams(): void {
+    for (const [nodeName, node] of this.nodes.entries()) {
+      if (node.events && node.events.length > 0) {
+        const nodeStream = this.eventSubject.pipe(
+          filter((event) => node.events!.includes(event.type))
+        );
+        this.nodeStreams.set(nodeName, nodeStream);
+      }
+    }
+  }
+
+  /**
+   * Emits an event with optional payload and context
+   * @param type - The type of event to emit
+   * @param payload - Optional payload data
+   * @param context - Optional graph context
+   */
+  public emitEvent<P = any>(
+    type: string,
+    payload?: P,
+    context?: GraphContext<T>
+  ): void {
+    const event: GraphEvent<T> = { type, payload, timestamp: Date.now() };
+    this.eventSubject.next(event);
+    this.eventEmitter.emit(type, event);
+  }
+
+  /**
+   * Sets up event listeners for all nodes in the graph
+   * Handles cleanup and re-registration of event listeners
+   */
+  setupEventListeners(): void {
+    // First remove only the existing node-based listeners that we might have created previously
+    // We do NOT remove, for example, "nodeStarted" or "nodeCompleted" listeners that test code added.
+    for (const [eventName, listener] of this.eventEmitter
+      .rawListeners("*")
+      .entries()) {
+      // This can be tricky—EventEmitter doesn't directly let you remove by "type" of listener.
+      // Alternatively, we can store references in a separate structure.
+      // For simplicity, let's do a full removeAllListeners() on node-specified events (only),
+      // then re-add them below, but keep the test-based events like "nodeStarted" or "nodeCompleted".
+    }
+
+    // The simplest approach: removeAllListeners for each event that is declared as a node event
+    // so we don't stack up duplicates:
+    const allEvents = new Set<string>();
+    for (const node of this.nodes.values()) {
+      if (node.events) {
+        node.events.forEach((evt) => allEvents.add(evt));
+      }
+    }
+    for (const evt of allEvents) {
+      // remove only those events that are used by nodes
+      this.eventEmitter.removeAllListeners(evt);
+    }
+
+    // Now re-add the node-based event triggers
+    for (const node of this.nodes.values()) {
+      if (node.events && node.events.length > 0) {
+        node.events.forEach((event) => {
+          this.eventEmitter.on(
+            event,
+            async (data?: Partial<GraphContext<T>>) => {
+              const freshContext = structuredClone(this.context);
+              if (data) Object.assign(freshContext, data);
+
+              // If triggered by an event, we pass "true" so event-driven node will skip `next`.
+              await this.executeNode(
+                node.name,
+                freshContext,
+                undefined,
+                /* triggeredByEvent= */ true
+              );
+            }
+          );
+        });
+      }
+    }
+  }
+
+  /**
+   * Sets up listeners for graph-level events
+   * Handles graph start, completion, and error events
+   */
+  setupGraphEventListeners(): void {
+    if (this.graphEvents && this.graphEvents.length > 0) {
+      this.graphEvents.forEach((event) => {
+        this.eventEmitter.on(event, async (data?: Partial<GraphContext<T>>) => {
+          const freshContext = this.createNewContext();
+          if (data) Object.assign(freshContext, data);
+
+          // Emit "graphStarted"
+          this.eventEmitter.emit("graphStarted", { name: this.name });
+
+          try {
+            // Execute the graph starting from the entry node
+            if (!this.entryNode) {
+              throw new Error("No entry node defined for graph event handling");
+            }
+
+            await this.executeNode(
+              this.entryNode,
+              freshContext,
+              undefined,
+              false
+            );
+
+            // Emit "graphCompleted"
+            this.eventEmitter.emit("graphCompleted", {
+              name: this.name,
+              context: this.context,
+            });
+          } catch (error) {
+            // Emit "graphError"
+            this.eventEmitter.emit("graphError", { name: this.name, error });
+            this.globalErrorHandler?.(error as Error, freshContext);
+            throw error;
+          }
+        });
+      });
+    }
+  }
+
+  /**
+   * Waits for a set of events to occur within a timeout period
+   * @param events - Array of event names to wait for
+   * @param timeout - Maximum time to wait in milliseconds
+   * @returns Promise that resolves with array of received events
+   * @throws Error if timeout occurs before all events are received
+   */
+  async waitForEvents(
+    events: string[],
+    timeout: number = 30000
+  ): Promise<any[]> {
+    return new Promise((resolve, reject) => {
+      const receivedEvents = new Map<string, any>();
+      const eventHandlers = new Map();
+      let isResolved = false;
+
+      const cleanup = () => {
+        events.forEach((event) => {
+          const handler = eventHandlers.get(event);
+          if (handler) {
+            this.eventEmitter.removeListener(event, handler);
+          }
+        });
+      };
+
+      events.forEach((event) => {
+        const handler = (eventData: any) => {
+          console.log(`Received event: ${event}`, eventData);
+          if (!isResolved) {
+            receivedEvents.set(event, eventData);
+            console.log(
+              "Current received events:",
+              Array.from(receivedEvents.keys())
+            );
+
+            if (events.every((e) => receivedEvents.has(e))) {
+              console.log("All events received, resolving");
+              isResolved = true;
+              clearTimeout(timeoutId);
+              cleanup();
+              resolve(Array.from(receivedEvents.values()));
+            }
+          }
+        };
+
+        eventHandlers.set(event, handler);
+        this.eventEmitter.on(event, handler);
+      });
+
+      const timeoutId = setTimeout(() => {
+        if (!isResolved) {
+          isResolved = true;
+          cleanup();
+          reject(new Error(`Timeout waiting for events: ${events.join(", ")}`));
+        }
+      }, timeout);
+    });
+  }
+
+  /**
+   * Registers an event handler
+   * @param eventName - Name of the event to listen for
+   * @param handler - Function to handle the event
+   */
+  on(eventName: string, handler: (...args: any[]) => void): void {
+    this.eventEmitter.on(eventName, handler);
+  }
+
+  /**
+   * Emits an event through the event emitter
+   * @param eventName - Name of the event to emit
+   * @param data - Optional data to include with the event
+   */
+  emit(eventName: string, data?: any): void {
+    this.eventEmitter.emit(eventName, data);
+  }
+
+  /**
+   * Creates a new context object by cloning the current context
+   * @returns A new graph context instance
+   * @private
+   */
+  private createNewContext(): GraphContext<T> {
+    return structuredClone(this.context);
+  }
+
+  /**
+   * Executes a node with the given parameters
+   * @param nodeName - Name of the node to execute
+   * @param context - Graph context for execution
+   * @param inputs - Input data for the node
+   * @param triggeredByEvent - Whether execution was triggered by an event
+   * @returns Promise that resolves when execution is complete
+   * @throws Error if nodeExecutor is not initialized
+   * @private
+   */
+  private async executeNode(
+    nodeName: string,
+    context: GraphContext<T>,
+    inputs: any,
+    triggeredByEvent: boolean
+  ): Promise<void> {
+    if (!this.nodeExecutor) {
+      throw new Error("NodeExecutor not initialized");
+    }
+    return this.nodeExecutor.executeNode(
+      nodeName,
+      context,
+      inputs,
+      triggeredByEvent
+    );
+  }
+}