@ai.ntellect/core 0.6.21 → 0.7.1

package/.mocharc.json

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

package/README.md

@@ -2,13 +2,13 @@
 
 @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.
 
-## Key features
+## Features
 
-- **GraphFlow** – A 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.
-- **Scalable** – Manage multiple graphs in parallel with GraphController.
+- **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
 
 ## Installation
 
@@ -25,124 +25,100 @@ node -v
 npm -v
 ```
 
-If Node.js is not installed, download it from [nodejs.org](https://nodejs.org/).
-
 ### Installing the framework
 
-Create a new Node.js project:
-
-```sh
-mkdir ai-ntellect-demo
-cd ai-ntellect-demo
-npm init -y
-```
-
-Install TypeScript and Node.js types:
-
-```sh
-npm install --save-dev typescript @types/node
-npx tsc --init
-```
-
-Install @ai.ntellect/core and its dependencies:
-
 ```sh
 npm install @ai.ntellect/core zod
 ```
 
-## Verifying the Installation
-
-Create a new file `index.ts`:
-
-```sh
-touch index.ts
-```
+## Example
 
-Add the following code to test a simple graph execution:
-
-```ts
-import { GraphFlow } from "@ai.ntellect/core";
+```typescript
 import { z } from "zod";
+import { GraphFlow } from "@ai.ntellect/core";
 
+// Define context schema
 const ContextSchema = z.object({
   message: z.string(),
+  counter: z.number(),
 });
 
-type ContextSchema = typeof ContextSchema;
-
-const myGraph = new GraphFlow<ContextSchema>("TestGraph", {
-  name: "TestGraph",
-  context: { message: "Installation successful!" },
+// Create graph instance
+const graph = new GraphFlow<typeof ContextSchema>("MyGraph", {
+  name: "MyGraph",
   schema: ContextSchema,
+  context: { message: "Hello", counter: 0 },
   nodes: [
     {
-      name: "printMessage",
+      name: "incrementCounter",
       execute: async (context) => {
-        console.log(context.message);
+        context.counter++;
+      },
+      next: ["checkThreshold"],
+    },
+    {
+      name: "checkThreshold",
+      condition: (context) => context.counter < 5,
+      execute: async (context) => {
+        if (context.counter >= 5) {
+          context.message = "Threshold reached!";
+        }
+      },
+      next: ["incrementCounter"],
+      retry: {
+        maxAttempts: 3,
+        delay: 1000,
       },
-      next: [],
     },
   ],
 });
 
+// Observe state changes
 (async () => {
-  await myGraph.execute("printMessage");
+  // Execute the graph
+  graph.execute("incrementCounter");
+  graph.observe().state().subscribe(console.log);
 })();
 ```
 
-Run the test:
+## Features
 
-```sh
-npx ts-node index.ts
-```
+### Event handling
 
-Expected output:
+```typescript
+// Event-driven node
+{
+  name: "waitForEvent",
+  events: ["dataReceived"],
+  execute: async (context, event) => {
+    context.data = event.payload;
+  }
+}
 
+// Emit events
+graph.emit("dataReceived", { value: 42 });
 ```
-Installation successful!
-```
-
-## Core concepts
 
-### GraphFlow
+### State observation
 
-GraphFlow is the core execution engine that automates workflows through graph-based logic. Each node in the graph can:
+```typescript
+// Observe specific node
+graph.observe().node("myNode").subscribe(console.log);
 
-- Execute a specific action.
-- Wait for an event before proceeding.
-- Depend on conditional logic.
-- Modify a shared execution context.
+// Observe specific properties
+graph.observe().property("counter").subscribe(console.log);
 
-### GraphController
-
-GraphController orchestrates multiple GraphFlows, enabling:
-
-- Sequential or parallel execution of multiple graphs.
-- Inter-graph communication for complex workflows.
-- Advanced event-based automation.
-
-### Modules and Adapters
-
-The framework provides modular extensions:
-
-- **Memory Module** – Stores and retrieves contextual information.
-- **Scheduler (Agenda)** – Manages task scheduling and timed executions.
-- **Adapters** – Integrate with databases, APIs, and external services.
-
-## Tutorials
-
-Step-by-step guides are available for:
+// Observe events
+graph.observe().event("nodeCompleted").subscribe(console.log);
+```
 
-- Creating a simple graph
-- Adding conditions and handling errors
-- Waiting for events and executing multiple graphs
-- Building an AI-powered agent with @ai.ntellect/core
+## Documentation
 
-Check out the complete documentation at [GitBook](https://ai-ntellect.gitbook.io/core).
+For complete documentation, visit our [GitBook](https://ai-ntellect.gitbook.io/core).
 
 ## Contributing
 
-Contributions are welcome. To suggest an improvement or report an issue:
+Contributions are welcome! To suggest an improvement or report an issue:
 
 - Join our [Discord community](https://discord.gg/kEc5gWXJ)
 - Explore the [GitBook documentation](https://ai-ntellect.gitbook.io/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
+    );
+  }
+}