@ai.ntellect/core 0.6.21 → 0.7.0

package/graph/observer.ts

@@ -0,0 +1,361 @@
+import { GraphObservable } from "interfaces";
+import {
+  BehaviorSubject,
+  Observable,
+  Subject,
+  combineLatest,
+  firstValueFrom,
+} from "rxjs";
+import {
+  distinctUntilChanged,
+  filter,
+  map,
+  share,
+  startWith,
+  take,
+  takeUntil,
+  timeout,
+} from "rxjs/operators";
+import { ZodSchema } from "zod";
+import { GraphContext, GraphEvent } from "../types";
+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>
+  ) {}
+
+  /**
+   * Observes the entire graph state changes
+   * @param options Configuration options for the observation
+   * @param options.debounce Debounce time in milliseconds
+   * @param options.delay Delay between emissions in milliseconds
+   * @param options.stream If true, streams the specified properties letter by letter
+   * @param options.properties List of properties to stream
+   * @param options.onStreamLetter Callback for each letter emitted during streaming
+   * @param options.onStreamComplete Callback when streaming is complete
+   * @returns An Observable that emits the complete graph context whenever it changes
+   */
+  state(
+    options: {
+      debounce?: number;
+      delay?: number;
+      stream?: boolean;
+      properties?: (keyof GraphContext<T>)[];
+      onStreamLetter?: (data: { letter: string; property: string }) => void;
+      onStreamComplete?: () => void;
+    } = {}
+  ): GraphObservable<T> {
+    const baseObservable = new Observable<any>((subscriber) => {
+      const subscription = this.eventSubject
+        .pipe(
+          filter(
+            (event) =>
+              event.type === "nodeStateChanged" ||
+              event.type === "nodeStarted" ||
+              event.type === "nodeCompleted"
+          ),
+          map((event) => event.payload.context),
+          startWith(this.stateSubject.getValue()),
+          distinctUntilChanged(
+            (prev, curr) => JSON.stringify(prev) === JSON.stringify(curr)
+          )
+        )
+        .subscribe(subscriber);
+
+      // Stream the specified properties if specified
+      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();
+    });
+
+    // Extend the observable with our custom methods
+    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>;
+  }
+
+  /**
+   * Observes state changes for a specific node
+   * @param name - The name of the node to observe
+   * @returns An Observable that emits the graph context when the specified node changes
+   */
+  node(name: string): Observable<GraphContext<T>> {
+    return this.eventSubject.pipe(
+      filter(
+        (event) =>
+          event.type === "nodeStateChanged" && event.payload?.name === name
+      ),
+      map((event) => event.payload.context),
+      distinctUntilChanged(
+        (prev, curr) => JSON.stringify(prev) === JSON.stringify(curr)
+      ),
+      takeUntil(this.destroySubject),
+      share()
+    );
+  }
+
+  /**
+   * Observes state changes for multiple nodes
+   * @param names - Array of node names to observe
+   * @returns An Observable that emits the graph context when any of the specified nodes change
+   */
+  nodes(names: string[]): Observable<GraphContext<T>> {
+    return this.eventSubject.pipe(
+      filter(
+        (event) =>
+          names.includes(event.payload?.name ?? "") &&
+          event.type === "nodeStateChanged"
+      ),
+      map(() => this.graph.getContext()),
+      distinctUntilChanged(
+        (prev, curr) => JSON.stringify(prev) === JSON.stringify(curr)
+      ),
+      takeUntil(this.destroySubject),
+      share()
+    );
+  }
+
+  /**
+   * Observes specific properties of the graph context
+   * @param keys - Single or multiple property keys to observe
+   * @returns An Observable that emits an object containing only the specified properties
+   * @template K - The key of the property to observe from GraphContext<T>
+   */
+  property<K extends keyof GraphContext<T>>(
+    keys: K | K[]
+  ): Observable<{ [P in K]: GraphContext<T>[P] } & { name: string }> {
+    const properties = Array.isArray(keys) ? keys : [keys];
+
+    return this.eventSubject.pipe(
+      filter(
+        (event) =>
+          event.type === "nodeStateChanged" &&
+          properties.some((key) => event.payload?.property === key)
+      ),
+      map((event) => ({
+        ...properties.reduce(
+          (obj, key) => ({
+            ...obj,
+            [key]: event.payload.context[key],
+          }),
+          {} as { [P in K]: GraphContext<T>[P] }
+        ),
+        name: event.payload.name as string,
+      })),
+      startWith({
+        ...properties.reduce(
+          (obj, key) => ({
+            ...obj,
+            [key]: this.stateSubject.value[key],
+          }),
+          {}
+        ),
+        name: "initial",
+      } as { [P in K]: GraphContext<T>[P] } & { name: string }),
+      distinctUntilChanged(
+        (prev, curr) => JSON.stringify(prev) === JSON.stringify(curr)
+      ),
+      share()
+    );
+  }
+
+  /**
+   * Observes specific events in the graph
+   * @param type - The type of event to observe
+   * @returns An Observable that emits events of the specified type
+   */
+  event(type: string): Observable<GraphEvent<T>> {
+    return this.eventSubject.pipe(
+      filter((event) => event.type === type),
+      map((event) => event),
+      takeUntil(this.destroySubject),
+      share()
+    );
+  }
+
+  /**
+   * Waits for a specific condition to be met on an observable
+   * @param observable - The Observable to watch
+   * @param predicate - A function that returns true when the desired condition is met
+   * @returns A Promise that resolves with the value when the predicate returns true
+   * @template R - The type of value emitted by the observable
+   */
+  until<R>(
+    observable: Observable<R>,
+    predicate: (value: R) => boolean
+  ): Promise<R> {
+    return new Promise((resolve) => {
+      const subscription = observable.subscribe({
+        next: (value) => {
+          if (predicate(value)) {
+            subscription.unsubscribe();
+            resolve(value);
+          }
+        },
+      });
+    });
+  }
+
+  /**
+   * 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 duration in milliseconds
+   * @param correlationFn - Function to validate the correlation between events
+   * @returns Promise that resolves when all correlated events are received
+   */
+  waitForCorrelatedEvents(
+    eventTypes: string[],
+    timeoutMs: number,
+    correlationFn: (events: GraphEvent<T>[]) => boolean
+  ): Promise<GraphEvent<T>[]> {
+    return new Promise((resolve, reject) => {
+      const eventObservables = eventTypes.map((eventType) =>
+        this.eventSubject.pipe(
+          filter((event): event is GraphEvent<T> => {
+            return event.type === eventType && "timestamp" in event;
+          }),
+          take(1)
+        )
+      );
+
+      combineLatest(eventObservables)
+        .pipe(timeout(timeoutMs), take(1))
+        .subscribe({
+          next: (events) => {
+            if (correlationFn(events)) {
+              resolve(events);
+            } else {
+              reject(new Error(`Correlation validation failed`));
+            }
+          },
+          error: (error) => reject(error),
+        });
+    });
+  }
+
+  /**
+   * Observes the current state of the graph
+   * @returns Observable that emits the current graph context
+   */
+  observeState(): Observable<GraphContext<T>> {
+    return this.stateSubject.asObservable().pipe(
+      takeUntil(this.destroySubject),
+      distinctUntilChanged(
+        (prev, curr) => JSON.stringify(prev) === JSON.stringify(curr)
+      )
+    );
+  }
+
+  /**
+   * Observes specific event types in the graph
+   * @param eventType - The type of event to observe
+   * @returns Observable that emits events of the specified type
+   */
+  observeEvents(eventType: string): Observable<GraphEvent<T>> {
+    return this.eventSubject.asObservable().pipe(
+      takeUntil(this.destroySubject),
+      filter((event) => event.type === eventType)
+    );
+  }
+
+  /**
+   * Observes state changes for a specific node
+   * @param nodeName - The name of the node to observe
+   * @returns Observable that emits the graph context when the specified node changes
+   */
+  observeNodeState(nodeName: string): Observable<GraphContext<T>> {
+    return this.eventSubject.asObservable().pipe(
+      takeUntil(this.destroySubject),
+      filter(
+        (event) =>
+          event.type === "nodeStateChanged" && event.payload?.name === nodeName
+      ),
+      map(() => this.stateSubject.value)
+    );
+  }
+
+  /**
+   * Streams a message letter by letter with a specified delay
+   * @param message - The message to stream
+   * @param delayMs - The delay in milliseconds between each letter
+   * @param property - The property name being streamed
+   * @returns An Observable that emits each letter of the message along with its property
+   */
+  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/interfaces/index.ts

@@ -1,4 +1,12 @@
-import { BaseMemoryType, CreateMemoryInput, ScheduledRequest } from "../types";
+import { Observable } from "rxjs";
+import { ZodSchema } from "zod";
+import {
+  BaseMemoryType,
+  CreateMemoryInput,
+  GraphContext,
+  GraphEvent,
+  ScheduledRequest,
+} from "../types";
 
 /* ======================== EMBEDDING SERVICE ======================== */
 
@@ -151,6 +159,15 @@ export interface IMemoryService {
    * @returns {Promise<void>}
    */
   clearAllMemories(): Promise<void>;
+
+  saveJob(id: string, job: any): Promise<void>;
+  saveRequest(id: string, request: any): Promise<void>;
+  getJob(id: string): Promise<any>;
+  getRequest(id: string): Promise<any>;
+  deleteJob(id: string): Promise<void>;
+  deleteRequest(id: string): Promise<void>;
+  getAllRequests(): Promise<any[]>;
+  clear(): Promise<void>;
 }
 
 /**
@@ -297,6 +314,38 @@ export abstract class BaseMemory implements IMemoryService {
   abstract getAllMemories(roomId: string): Promise<BaseMemoryType[]>;
   abstract clearMemoryById(id: string, roomId: string): Promise<void>;
   abstract clearAllMemories(): Promise<void>;
+
+  async saveJob(id: string, job: any): Promise<void> {
+    await this.adapter.saveJob?.(id, job);
+  }
+
+  async saveRequest(id: string, request: any): Promise<void> {
+    await this.adapter.saveRequest?.(id, request);
+  }
+
+  async getJob(id: string): Promise<any> {
+    return this.adapter.getJob?.(id);
+  }
+
+  async getRequest(id: string): Promise<any> {
+    return this.adapter.getRequest?.(id);
+  }
+
+  async deleteJob(id: string): Promise<void> {
+    await this.adapter.deleteJob?.(id);
+  }
+
+  async deleteRequest(id: string): Promise<void> {
+    await this.adapter.deleteRequest?.(id);
+  }
+
+  async getAllRequests(): Promise<any[]> {
+    return this.adapter.getAllRequests?.() || [];
+  }
+
+  async clear(): Promise<void> {
+    await this.adapter.clear?.();
+  }
 }
 
 /**
@@ -338,6 +387,13 @@ export interface IEventEmitter {
    * @param {Function} listener - Event handler
    */
   once(event: string, listener: (...args: any[]) => void): void;
+
+  /**
+   * Removes a specific listener for an event
+   * @param {string} event - Event name
+   * @param {Function} listener - Event handler
+   */
+  removeListener(event: string, listener: (...args: any[]) => void): void;
 }
 
 /**
@@ -442,3 +498,48 @@ export interface IJobStorage {
   getAllRequests(): Promise<ScheduledRequest[]>;
   clear(): Promise<void>;
 }
+
+/**
+ * Interface defining the extended functionality of a graph observable
+ * @template T - The Zod schema type that defines the structure of the graph data
+ */
+export interface GraphObservable<T extends ZodSchema> extends Observable<any> {
+  /**
+   * Observes the entire graph state
+   */
+  state(): Observable<GraphContext<T>>;
+
+  /**
+   * Observes a specific node's state
+   * @param nodeName - The name of the node to observe
+   */
+  node(nodeName: string): Observable<any>;
+
+  /**
+   * Observes multiple nodes' states
+   * @param nodeNames - Array of node names to observe
+   */
+  nodes(nodeNames: string[]): Observable<any>;
+
+  /**
+   * Observes specific properties of the graph context
+   * @param prop - Property or array of properties to observe
+   */
+  property(prop: string | string[]): Observable<any>;
+
+  /**
+   * Observes specific events in the graph
+   * @param eventName - The name of the event to observe
+   */
+  event(eventName: string): Observable<GraphEvent<T>>;
+
+  /**
+   * Waits for a specific condition to be met
+   * @param observable - The observable to watch
+   * @param predicate - Function that determines when the condition is met
+   */
+  until(
+    observable: Observable<any>,
+    predicate: (state: any) => boolean
+  ): Promise<any>;
+}

package/modules/agenda/index.ts

@@ -1,4 +1,4 @@
-import { ICronService, IMemoryAdapter } from "../../interfaces";
+import { ICronService, IMemoryService } from "../../interfaces";
 import { ScheduledRequest } from "../../types";
 
 /**
@@ -11,24 +11,11 @@ export class Agenda {
   /**
    * Creates an instance of Agenda
    * @param {ICronService} cronService - The cron service implementation
-   * @param {IMemoryAdapter} storage - The storage service for jobs and requests
+   * @param {IMemoryService} storage - The storage service for jobs and requests
    */
   constructor(
     private readonly cronService: ICronService,
-    private readonly storage: IMemoryAdapter &
-      Required<
-        Pick<
-          IMemoryAdapter,
-          | "saveJob"
-          | "saveRequest"
-          | "getJob"
-          | "getRequest"
-          | "deleteJob"
-          | "deleteRequest"
-          | "getAllRequests"
-          | "clear"
-        >
-      >
+    private readonly storage: IMemoryService
   ) {}
 
   /**

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@ai.ntellect/core",
-  "version": "0.6.21",
+  "version": "0.7.0",
   "description": "",
   "main": "dist/index.js",
   "scripts": {
     "build": "rm -rf dist && tsc",
-    "test": "mocha --require ts-node/register",
+    "test": "mocha -r ./node_modules/ts-node/register",
+    "test:all": "mocha -r ./node_modules/ts-node/register 'test/**/*.test.ts'",
     "test:coverage": "nyc --reporter=text --reporter=html pnpm test",
-    "test:watch": "mocha --require ts-node/register 'test/**/*.test.ts' --watch"
+    "test:watch": "mocha --require ./node_modules/ts-node/register 'test/**/*.test.ts' --watch --watch-files ./**/*.ts,test/**/*.ts",
+    "test:watch:graph": "mocha --require ./node_modules/ts-node/register 'test/graph/**/*.test.ts' --watch --watch-files ./graph/**/*.ts test/**/*.ts"
   },
   "keywords": [],
   "author": "Lorcann Rauzduel",
@@ -17,18 +19,20 @@
     "ai": "^3.0.0",
     "node-cron": "^3.0.3",
     "redis": "^4.7.0",
+    "rxjs": "^7.8.1",
     "zod": "^3.24.1"
   },
   "devDependencies": {
     "@types/chai": "^4.3.20",
     "@types/mocha": "^10.0.10",
+    "@types/node": "^20",
     "@types/sinon": "^17.0.3",
     "chai": "^4.5.0",
     "mocha": "^10.0.0",
     "nyc": "^17.1.0",
     "redis": "^4.6.13",
     "sinon": "^19.0.2",
-    "ts-node": "^10.9.0",
+    "ts-node": "10.9.1",
     "typescript": "^5.7.2"
   },
   "repository": {
@@ -40,6 +44,7 @@
   },
   "homepage": "https://github.com/ai-ntellect/core#readme",
   "bin": {
-    "wallet-assistant": "./dist/examples/index.js"
+    "wallet-assistant": "./dist/examples/index.js",
+    "workflow": "./dist/cli.js"
   }
 }