@ai.ntellect/core 0.6.16 → 0.6.19

package/index.ts

@@ -1,11 +1,29 @@
+/**
+ * @module @ai.ntellect/core
+ * @description Core module with workflow functionality, providing graph management,
+ * memory storage, agenda scheduling, and embedding capabilities.
+ *
+ * This module exports various components:
+ * - Graph management and controller
+ * - Memory storage adapters (Meilisearch, Redis)
+ * - Agenda scheduling with node-cron adapter
+ * - Embedding functionality with AI adapter
+ * - Utility functions for action schema generation and header building
+ */
+
+export * from "./graph";
 export * from "./graph/controller";
-export * from "./graph/graph";
-export * from "./memory";
-export * from "./memory/adapters/meilisearch";
-export * from "./memory/adapters/redis";
+export * from "./modules/memory";
+export * from "./modules/memory/adapters/meilisearch";
+export * from "./modules/memory/adapters/redis";
 
 export * from "./interfaces";
-export * from "./services/agenda";
-export * from "./services/embedding";
+export * from "./modules/agenda";
+export * from "./modules/agenda/adapters/node-cron";
+export * from "./modules/embedding";
+export * from "./modules/embedding/adapters/ai";
+
 export * from "./types";
-export * from "./utils/stringifiy-zod-schema";
+
+export * from "./utils/generate-action-schema";
+export * from "./utils/header-builder";

package/interfaces/index.ts

@@ -1,37 +1,11 @@
-import { BaseMemoryType } from "@/types";
-import { SharedState } from "@/types";
-
-/* ======================== PERSISTENCE ======================== */
-
-/**
- * Interface for persisting graph execution state.
- */
-export interface Persistence<T> {
-  saveState(
-    graphName: string,
-    state: SharedState<T>,
-    currentNode: string
-  ): Promise<void>;
-  loadState(
-    graphName: string
-  ): Promise<{ state: SharedState<T>; currentNode: string } | null>;
-}
-
-/* ======================== REAL-TIME NOTIFICATIONS ======================== */
-
-/**
- * Interface for real-time notifications.
- */
-export interface RealTimeNotifier {
-  notify(event: string, data: any): void;
-}
+import { BaseMemoryType, CreateMemoryInput, ScheduledRequest } from "../types";
 
 /* ======================== EMBEDDING SERVICE ======================== */
 
 /**
  * Interface for an embedding service that processes text into vector representations.
  */
-export interface EmbeddingService {
+export interface EmbeddingModule {
   /**
    * Generates an embedding for a single text.
    * @param {string} text - The input text to embed.
@@ -117,3 +91,347 @@ export interface BaseMemoryService {
    */
   clearAllMemories(): Promise<void>;
 }
+
+/**
+ * Extended interface for memory service operations
+ * @interface
+ */
+export interface IMemoryService {
+  /**
+   * Initializes the memory service
+   * @returns {Promise<void>}
+   */
+  init(): Promise<void>;
+
+  /**
+   * Creates a new memory entry with optional embedding
+   * @param {CreateMemoryInput & { embedding?: number[] }} input - Memory data with optional embedding
+   * @returns {Promise<BaseMemoryType | undefined>} Created memory or undefined
+   */
+  createMemory(
+    input: CreateMemoryInput & { embedding?: number[] }
+  ): Promise<BaseMemoryType | undefined>;
+
+  /**
+   * Retrieves a memory by ID and room ID
+   * @param {string} id - Memory identifier
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<BaseMemoryType | null>} Memory entry or null if not found
+   */
+  getMemoryById(id: string, roomId: string): Promise<BaseMemoryType | null>;
+
+  /**
+   * Searches for memories based on query and options
+   * @param {string} query - Search query
+   * @param {Object} options - Search options
+   * @returns {Promise<BaseMemoryType[]>} Array of matching memories
+   */
+  getMemoryByIndex(
+    query: string,
+    options: { roomId: string; limit?: number }
+  ): Promise<BaseMemoryType[]>;
+
+  /**
+   * Retrieves all memories for a specific room
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<BaseMemoryType[]>} Array of all memories
+   */
+  getAllMemories(roomId: string): Promise<BaseMemoryType[]>;
+
+  /**
+   * Deletes a specific memory
+   * @param {string} id - Memory identifier
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<void>}
+   */
+  clearMemoryById(id: string, roomId: string): Promise<void>;
+
+  /**
+   * Clears all memories
+   * @returns {Promise<void>}
+   */
+  clearAllMemories(): Promise<void>;
+}
+
+/**
+ * Interface for memory adapter implementations
+ * @interface
+ */
+export interface IMemoryAdapter {
+  /**
+   * Initializes the memory adapter for a specific room
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<void>}
+   */
+  init(roomId?: string): Promise<void>;
+
+  /**
+   * Creates a new memory entry in the adapter
+   * @param {CreateMemoryInput & { embedding?: number[] }} input - Memory data with optional embedding
+   * @returns {Promise<BaseMemoryType | undefined>} Created memory or undefined
+   */
+  createMemory(
+    input: CreateMemoryInput & { embedding?: number[] }
+  ): Promise<BaseMemoryType | undefined>;
+
+  /**
+   * Stores a job in the adapter
+   * @param {string} id - Job identifier
+   * @param {ICronJob} job - Cron job instance
+   * @returns {Promise<void>}
+   */
+  saveJob?(id: string, job: ICronJob): Promise<void>;
+
+  /**
+   * Stores a scheduled request in the adapter
+   * @param {string} id - Request identifier
+   * @param {ScheduledRequest} request - Scheduled request data
+   * @returns {Promise<void>}
+   */
+  saveRequest?(id: string, request: ScheduledRequest): Promise<void>;
+
+  /**
+   * Retrieves a job by ID
+   * @param {string} id - Job identifier
+   * @returns {Promise<ICronJob | undefined>}
+   */
+  getJob?(id: string): Promise<ICronJob | undefined>;
+
+  /**
+   * Retrieves a scheduled request by ID
+   * @param {string} id - Request identifier
+   * @returns {Promise<ScheduledRequest | undefined>}
+   */
+  getRequest?(id: string): Promise<ScheduledRequest | undefined>;
+
+  /**
+   * Deletes a job by ID
+   * @param {string} id - Job identifier
+   * @returns {Promise<void>}
+   */
+  deleteJob?(id: string): Promise<void>;
+
+  /**
+   * Deletes a scheduled request by ID
+   * @param {string} id - Request identifier
+   * @returns {Promise<void>}
+   */
+  deleteRequest?(id: string): Promise<void>;
+
+  /**
+   * Retrieves all scheduled requests
+   * @returns {Promise<ScheduledRequest[]>}
+   */
+  getAllRequests?(): Promise<ScheduledRequest[]>;
+
+  /**
+   * Retrieves a memory by ID and room ID from the adapter
+   * @param {string} id - Memory identifier
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<BaseMemoryType | null>} Memory entry or null if not found
+   */
+  getMemoryById(id: string, roomId: string): Promise<BaseMemoryType | null>;
+
+  /**
+   * Searches for memories in the adapter
+   * @param {string} query - Search query
+   * @param {Object} options - Search options
+   * @returns {Promise<BaseMemoryType[]>} Array of matching memories
+   */
+  getMemoryByIndex(
+    query: string,
+    options: { roomId: string; limit?: number }
+  ): Promise<BaseMemoryType[]>;
+
+  /**
+   * Retrieves all memories for a room from the adapter
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<BaseMemoryType[]>} Array of all memories
+   */
+  getAllMemories(roomId: string): Promise<BaseMemoryType[]>;
+
+  /**
+   * Deletes a specific memory from the adapter
+   * @param {string} id - Memory identifier
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<void>}
+   */
+  clearMemoryById(id: string, roomId: string): Promise<void>;
+
+  /**
+   * Clears all memories from the adapter
+   * @returns {Promise<void>}
+   */
+  clearAllMemories(): Promise<void>;
+
+  /**
+   * Clears all jobs and requests
+   * @returns {Promise<void>}
+   */
+  clear?(): Promise<void>;
+}
+
+/**
+ * Abstract base class for memory implementations
+ * @abstract
+ */
+export abstract class BaseMemory implements IMemoryService {
+  /**
+   * Creates an instance of BaseMemory
+   * @param {IMemoryAdapter} adapter - Memory adapter implementation
+   */
+  constructor(protected readonly adapter: IMemoryAdapter) {}
+
+  abstract init(): Promise<void>;
+  abstract createMemory(
+    input: CreateMemoryInput & { embedding?: number[] }
+  ): Promise<BaseMemoryType | undefined>;
+  abstract getMemoryById(
+    id: string,
+    roomId: string
+  ): Promise<BaseMemoryType | null>;
+  abstract getMemoryByIndex(
+    query: string,
+    options: { roomId: string; limit?: number }
+  ): Promise<BaseMemoryType[]>;
+  abstract getAllMemories(roomId: string): Promise<BaseMemoryType[]>;
+  abstract clearMemoryById(id: string, roomId: string): Promise<void>;
+  abstract clearAllMemories(): Promise<void>;
+}
+
+/**
+ * Interface for event emitter functionality
+ * @interface
+ */
+export interface IEventEmitter {
+  /**
+   * Emits an event with optional arguments
+   * @param {string} event - Event name
+   * @param {...any[]} args - Event arguments
+   * @returns {boolean} Whether the event had listeners
+   */
+  emit(event: string, ...args: any[]): boolean;
+
+  /**
+   * Registers an event listener
+   * @param {string} event - Event name
+   * @param {Function} listener - Event handler
+   */
+  on(event: string, listener: (...args: any[]) => void): void;
+
+  /**
+   * Removes all listeners for an event
+   * @param {string} [event] - Optional event name
+   */
+  removeAllListeners(event?: string): void;
+
+  /**
+   * Returns raw listeners for an event
+   * @param {string} event - Event name
+   * @returns {Function[]} Array of listener functions
+   */
+  rawListeners(event: string): Function[];
+}
+
+/**
+ * Interface for cron service functionality
+ * @interface
+ */
+export interface ICronService {
+  /**
+   * Schedules a job using cron expression
+   * @param {string} expression - Cron expression
+   * @param {Function} callback - Job callback
+   * @returns {ICronJob} Cron job instance
+   */
+  schedule(expression: string, callback: () => void): ICronJob;
+}
+
+/**
+ * Interface for cron job control
+ * @interface
+ */
+export interface ICronJob {
+  /**
+   * Starts the cron job
+   */
+  start(): void;
+
+  /**
+   * Stops the cron job
+   */
+  stop(): void;
+}
+
+/**
+ * Interface for embedding model operations
+ * @interface
+ */
+export interface IEmbeddingModel {
+  /**
+   * Embeds a single text
+   * @param {string} text - Text to embed
+   * @returns {Promise<number[]>} Vector embedding
+   */
+  embed(text: string): Promise<number[]>;
+
+  /**
+   * Embeds multiple texts
+   * @param {string[]} texts - Array of texts to embed
+   * @returns {Promise<number[][]>} Array of vector embeddings
+   */
+  embedMany(texts: string[]): Promise<number[][]>;
+}
+
+/**
+ * Interface for similarity calculations
+ * @interface
+ */
+export interface ISimilarityCalculator {
+  /**
+   * Calculates similarity between two embeddings
+   * @param {number[]} embedding1 - First embedding
+   * @param {number[]} embedding2 - Second embedding
+   * @returns {number} Similarity score
+   */
+  calculate(embedding1: number[], embedding2: number[]): number;
+}
+
+/**
+ * Interface for embedding module operations
+ * @interface
+ */
+export interface IEmbeddingModule {
+  /**
+   * Embeds a single text
+   * @param {string} text - Text to embed
+   * @returns {Promise<number[]>} Vector embedding
+   */
+  embedText(text: string): Promise<number[]>;
+
+  /**
+   * Embeds multiple texts
+   * @param {string[]} texts - Array of texts to embed
+   * @returns {Promise<number[][]>} Array of vector embeddings
+   */
+  embedMany(texts: string[]): Promise<number[][]>;
+
+  /**
+   * Calculates similarity between two embeddings
+   * @param {number[]} embedding1 - First embedding
+   * @param {number[]} embedding2 - Second embedding
+   * @returns {number} Similarity score
+   */
+  calculateSimilarity(embedding1: number[], embedding2: number[]): number;
+}
+
+export interface IJobStorage {
+  saveJob(id: string, job: ICronJob): Promise<void>;
+  saveRequest(id: string, request: ScheduledRequest): Promise<void>;
+  getJob(id: string): Promise<ICronJob | undefined>;
+  getRequest(id: string): Promise<ScheduledRequest | undefined>;
+  deleteJob(id: string): Promise<void>;
+  deleteRequest(id: string): Promise<void>;
+  getAllRequests(): Promise<ScheduledRequest[]>;
+  clear(): Promise<void>;
+}

package/modules/agenda/adapters/node-cron/index.ts

@@ -0,0 +1,25 @@
+import cron from "node-cron";
+import { ICronJob, ICronService } from "../../../../interfaces";
+
+/**
+ * @module NodeCronAdapter
+ * @description Adapter implementation for node-cron service.
+ * Provides a bridge between the application's scheduling interface and the node-cron library.
+ * @implements {ICronService}
+ */
+export class NodeCronAdapter implements ICronService {
+  /**
+   * Schedules a new cron job
+   * @param {string} expression - Cron expression defining the schedule
+   * @param {Function} callback - Function to be executed when the schedule triggers
+   * @returns {ICronJob} Interface for controlling the scheduled job
+   */
+  schedule(expression: string, callback: () => void): ICronJob {
+    const job = cron.schedule(expression, callback);
+
+    return {
+      start: () => job.start(),
+      stop: () => job.stop(),
+    };
+  }
+}

package/modules/agenda/index.ts

@@ -0,0 +1,159 @@
+import { ICronService, IMemoryAdapter } from "../../interfaces";
+import { ScheduledRequest } from "../../types";
+
+/**
+ * @module Agenda
+ * @description A module for scheduling and managing cron-based tasks.
+ * Provides functionality for scheduling requests, managing their lifecycle,
+ * and handling recurring and one-time tasks.
+ */
+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
+   */
+  constructor(
+    private readonly cronService: ICronService,
+    private readonly storage: IMemoryAdapter &
+      Required<
+        Pick<
+          IMemoryAdapter,
+          | "saveJob"
+          | "saveRequest"
+          | "getJob"
+          | "getRequest"
+          | "deleteJob"
+          | "deleteRequest"
+          | "getAllRequests"
+          | "clear"
+        >
+      >
+  ) {}
+
+  /**
+   * Schedule a new request to be processed later
+   * @param {Object} request - The request configuration
+   * @param {string} request.originalRequest - The original request to be executed
+   * @param {string} request.cronExpression - The cron expression for scheduling
+   * @param {Object} [callbacks] - Optional callback functions
+   * @param {Function} [callbacks.onScheduled] - Called when request is scheduled
+   * @param {Function} [callbacks.onExecuted] - Called when request is executed
+   * @returns {Promise<string>} The ID of the scheduled request
+   */
+  async scheduleRequest(
+    request: {
+      originalRequest: string;
+      cronExpression: string;
+    },
+    callbacks?: {
+      onScheduled?: (id: string) => void;
+      onExecuted?: (id: string, originalRequest: string) => void;
+    }
+  ): Promise<string> {
+    const id = crypto.randomUUID();
+
+    const scheduledRequest: ScheduledRequest = {
+      id,
+      originalRequest: request.originalRequest,
+      cronExpression: request.cronExpression,
+      isRecurring: false,
+      createdAt: new Date(),
+    };
+
+    // Create cron job using the injected service
+    const cronJob = this.cronService.schedule(
+      request.cronExpression,
+      async () => {
+        console.log(`🔄 Executing scheduled request: ${id}`);
+
+        if (callbacks?.onExecuted) {
+          callbacks.onExecuted(id, scheduledRequest.originalRequest);
+        }
+
+        console.log(`✅ Scheduled request executed successfully: ${id}`);
+
+        // Auto-stop for non-recurring tasks
+        if (!scheduledRequest.isRecurring) {
+          await this.cancelScheduledRequest(id);
+        }
+      }
+    );
+
+    // Start job in non-running mode
+    cronJob.stop();
+
+    // Store request and job using storage service
+    await this.storage.saveRequest(id, scheduledRequest);
+    await this.storage.saveJob(id, cronJob);
+
+    if (callbacks?.onScheduled) callbacks.onScheduled(id);
+
+    // Start the job after storing
+    cronJob.start();
+
+    return id;
+  }
+
+  /**
+   * Cancels a scheduled request by its ID
+   * @param {string} requestId - The ID of the request to cancel
+   * @returns {Promise<boolean>} True if the request was found and cancelled, false otherwise
+   */
+  async cancelScheduledRequest(requestId: string): Promise<boolean> {
+    const cronJob = await this.storage.getJob(requestId);
+    if (cronJob) {
+      try {
+        cronJob.stop();
+        await this.storage.deleteJob(requestId);
+        await this.storage.deleteRequest(requestId);
+        return true;
+      } catch (error) {
+        console.error(`Failed to stop cron job ${requestId}:`, error);
+        return false;
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Retrieves all scheduled requests
+   * @returns {Promise<ScheduledRequest[]>} Array of all scheduled requests
+   */
+  async getScheduledRequests(): Promise<ScheduledRequest[]> {
+    return this.storage.getAllRequests();
+  }
+
+  /**
+   * Stops all scheduled jobs
+   * @returns {Promise<void>}
+   */
+  async stopAll(): Promise<void> {
+    const requests = await this.getScheduledRequests();
+
+    for (const request of requests) {
+      await this.cancelScheduledRequest(request.id);
+    }
+
+    await this.storage.clear();
+  }
+
+  /**
+   * Stops the agenda service
+   * @returns {Promise<void>}
+   */
+  public async stop(): Promise<void> {
+    await this.stopAll();
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+
+  /**
+   * Cancels requests matching the query
+   * @param {Object} query - Query to match requests against
+   * @returns {Promise<void>}
+   */
+  public async cancel(query: {}): Promise<void> {
+    await this.stopAll();
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+}

package/modules/embedding/adapters/ai/index.ts

@@ -0,0 +1,42 @@
+import { embed, EmbeddingModel, embedMany } from "ai";
+import { IEmbeddingModel } from "../../../../interfaces";
+
+/**
+ * @module AIEmbeddingAdapter
+ * @description Adapter implementation for AI-based embedding service.
+ * Provides integration with AI models for text embedding generation.
+ * @implements {IEmbeddingModel}
+ */
+export class AIEmbeddingAdapter implements IEmbeddingModel {
+  /**
+   * Creates an instance of AIEmbeddingAdapter
+   * @param {EmbeddingModel<string>} model - The AI embedding model to use
+   */
+  constructor(private readonly model: EmbeddingModel<string>) {}
+
+  /**
+   * Generates an embedding vector for a single text using the AI model
+   * @param {string} text - The text to embed
+   * @returns {Promise<number[]>} The generated embedding vector
+   */
+  async embed(text: string): Promise<number[]> {
+    const { embedding } = await embed({
+      model: this.model,
+      value: text,
+    });
+    return embedding;
+  }
+
+  /**
+   * Generates embedding vectors for multiple texts using the AI model
+   * @param {string[]} texts - Array of texts to embed
+   * @returns {Promise<number[][]>} Array of generated embedding vectors
+   */
+  async embedMany(texts: string[]): Promise<number[][]> {
+    const { embeddings } = await embedMany({
+      model: this.model,
+      values: texts,
+    });
+    return embeddings;
+  }
+}

package/modules/embedding/index.ts

@@ -0,0 +1,45 @@
+import { cosineSimilarity } from "ai";
+import { IEmbeddingModel, IEmbeddingModule } from "../../interfaces";
+
+/**
+ * @module Embedding
+ * @description A module for generating and managing text embeddings.
+ * Provides functionality for converting text into vector representations
+ * and calculating similarities between embeddings.
+ * @implements {IEmbeddingModule}
+ */
+export class Embedding implements IEmbeddingModule {
+  /**
+   * Creates an instance of Embedding
+   * @param {IEmbeddingModel} embeddingModel - The embedding model implementation to use
+   */
+  constructor(private readonly embeddingModel: IEmbeddingModel) {}
+
+  /**
+   * Generates an embedding vector for a single text
+   * @param {string} text - The text to embed
+   * @returns {Promise<number[]>} The embedding vector
+   */
+  async embedText(text: string): Promise<number[]> {
+    return this.embeddingModel.embed(text);
+  }
+
+  /**
+   * Generates embedding vectors for multiple texts
+   * @param {string[]} texts - Array of texts to embed
+   * @returns {Promise<number[][]>} Array of embedding vectors
+   */
+  async embedMany(texts: string[]): Promise<number[][]> {
+    return this.embeddingModel.embedMany(texts);
+  }
+
+  /**
+   * Calculates the similarity score between two embeddings
+   * @param {number[]} embedding1 - First embedding vector
+   * @param {number[]} embedding2 - Second embedding vector
+   * @returns {number} Similarity score between 0 and 100
+   */
+  calculateSimilarity(embedding1: number[], embedding2: number[]): number {
+    return (cosineSimilarity(embedding1, embedding2) + 1) * 50;
+  }
+}