@ai.ntellect/core 0.6.17 → 0.6.20

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

package/modules/memory/adapters/in-memory/index.ts

@@ -0,0 +1,203 @@
+import { ICronJob, IMemoryAdapter } from "interfaces";
+import { BaseMemoryType, CreateMemoryInput, ScheduledRequest } from "types";
+
+/**
+ * @module InMemoryAdapter
+ * @description In-memory implementation of the memory storage adapter.
+ * Provides a simple Map-based storage solution
+ * @implements {IMemoryAdapter}
+ */
+export class InMemoryAdapter implements IMemoryAdapter {
+  /** Internal storage using Map structure for jobs and requests */
+  private jobs: Map<string, ICronJob>;
+  /** Internal storage using Map structure for requests */
+  private requests: Map<string, ScheduledRequest>;
+  /** Internal storage using Map structure */
+  private storage: Map<string, BaseMemoryType[]>;
+
+  /**
+   * Creates an instance of InMemoryAdapter
+   */
+  constructor() {
+    this.storage = new Map();
+    this.jobs = new Map();
+    this.requests = new Map();
+  }
+
+  /**
+   * Initializes storage for a room
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<void>}
+   */
+  async init(roomId: string): Promise<void> {
+    if (!this.storage.has(roomId)) {
+      this.storage.set(roomId, []);
+    }
+  }
+
+  /**
+   * Creates a new memory entry
+   * @param {CreateMemoryInput & { embedding?: number[] }} input - Memory data with optional embedding
+   * @returns {Promise<BaseMemoryType | undefined>} Created memory or existing memory if duplicate
+   */
+  async createMemory(
+    input: CreateMemoryInput & { embedding?: number[] }
+  ): Promise<BaseMemoryType | undefined> {
+    await this.init(input.roomId);
+
+    // Check if memory already exists
+    const memories = this.storage.get(input.roomId) || [];
+    const existingMemory = memories.find((m) => m.data === input.data);
+    if (existingMemory) {
+      return existingMemory;
+    }
+
+    // Create new memory
+    const memory: BaseMemoryType = {
+      id: input.id || crypto.randomUUID(),
+      data: input.data,
+      embedding: input.embedding,
+      roomId: input.roomId,
+      createdAt: new Date(),
+    };
+
+    memories.push(memory);
+    this.storage.set(input.roomId, memories);
+    return memory;
+  }
+
+  /**
+   * 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
+   */
+  async getMemoryById(
+    id: string,
+    roomId: string
+  ): Promise<BaseMemoryType | null> {
+    const memories = this.storage.get(roomId) || [];
+    return memories.find((m) => m.id === id) || null;
+  }
+
+  /**
+   * Searches for memories based on query and options
+   * @param {string} query - Search query
+   * @param {Object} options - Search options
+   * @param {string} options.roomId - Room identifier
+   * @param {number} [options.limit] - Maximum number of results
+   * @returns {Promise<BaseMemoryType[]>} Array of matching memories
+   */
+  async getMemoryByIndex(
+    query: string,
+    options: { roomId: string; limit?: number }
+  ): Promise<BaseMemoryType[]> {
+    const memories = this.storage.get(options.roomId) || [];
+    const filtered = memories.filter((m) => m.data.includes(query));
+    return filtered.slice(0, options.limit || filtered.length);
+  }
+
+  /**
+   * Retrieves all memories for a room
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<BaseMemoryType[]>} Array of all memories
+   */
+  async getAllMemories(roomId: string): Promise<BaseMemoryType[]> {
+    return this.storage.get(roomId) || [];
+  }
+
+  /**
+   * Deletes a specific memory
+   * @param {string} id - Memory identifier
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<void>}
+   */
+  async clearMemoryById(id: string, roomId: string): Promise<void> {
+    const memories = this.storage.get(roomId) || [];
+    const filtered = memories.filter((m) => m.id !== id);
+    this.storage.set(roomId, filtered);
+  }
+
+  /**
+   * Clears all memories across all rooms
+   * @returns {Promise<void>}
+   */
+  async clearAllMemories(): Promise<void> {
+    this.storage.clear();
+    this.jobs.clear();
+    this.requests.clear();
+  }
+
+  /**
+   * Saves a job to the internal storage
+   * @param {string} id - Job identifier
+   * @param {ICronJob} job - Job data
+   * @returns {Promise<void>}
+   */
+  async saveJob(id: string, job: ICronJob): Promise<void> {
+    this.jobs.set(id, job);
+  }
+
+  /**
+   * Saves a request to the internal storage
+   * @param {string} id - Request identifier
+   * @param {ScheduledRequest} request - Request data
+   * @returns {Promise<void>}
+   */
+  async saveRequest(id: string, request: ScheduledRequest): Promise<void> {
+    this.requests.set(id, request);
+  }
+
+  /**
+   * Retrieves a job by ID
+   * @param {string} id - Job identifier
+   * @returns {Promise<ICronJob | undefined>} Job data or undefined if not found
+   */
+  async getJob(id: string): Promise<ICronJob | undefined> {
+    return this.jobs.get(id);
+  }
+
+  /**
+   * Retrieves a request by ID
+   * @param {string} id - Request identifier
+   * @returns {Promise<ScheduledRequest | undefined>} Request data or undefined if not found
+   */
+  async getRequest(id: string): Promise<ScheduledRequest | undefined> {
+    return this.requests.get(id);
+  }
+
+  /**
+   * Deletes a job by ID
+   * @param {string} id - Job identifier
+   * @returns {Promise<void>}
+   */
+  async deleteJob(id: string): Promise<void> {
+    this.jobs.delete(id);
+  }
+
+  /**
+   * Deletes a request by ID
+   * @param {string} id - Request identifier
+   * @returns {Promise<void>}
+   */
+  async deleteRequest(id: string): Promise<void> {
+    this.requests.delete(id);
+  }
+
+  /**
+   * Retrieves all requests
+   * @returns {Promise<ScheduledRequest[]>} Array of all requests
+   */
+  async getAllRequests(): Promise<ScheduledRequest[]> {
+    return Array.from(this.requests.values());
+  }
+
+  /**
+   * Clears all jobs and requests
+   * @returns {Promise<void>}
+   */
+  async clear(): Promise<void> {
+    this.jobs.clear();
+    this.requests.clear();
+  }
+}

package/{memory → modules/memory}/adapters/meilisearch/index.ts

@@ -1,12 +1,27 @@
-import {
-  BaseMemoryType,
-  CreateMemoryInput,
-  MeilisearchConfig,
-} from "../../../types";
+import { IMemoryAdapter } from "interfaces";
+import { BaseMemoryType, CreateMemoryInput, MeilisearchConfig } from "types";
 
-export class MeilisearchAdapter {
+/**
+ * @module MeilisearchAdapter
+ * @description Adapter implementation for Meilisearch as a memory storage solution.
+ * Provides integration with Meilisearch for storing and retrieving memory entries.
+ * @implements {IMemoryAdapter}
+ */
+export class MeilisearchAdapter implements IMemoryAdapter {
+  /**
+   * Creates an instance of MeilisearchAdapter
+   * @param {MeilisearchConfig} config - Configuration for Meilisearch connection
+   */
   constructor(private readonly config: MeilisearchConfig) {}
 
+  /**
+   * Makes an HTTP request to the Meilisearch API
+   * @private
+   * @param {string} path - API endpoint path
+   * @param {RequestInit} [options] - Fetch request options
+   * @returns {Promise<any>} Response data
+   * @throws {Error} If the request fails
+   */
   private async makeRequest(path: string, options?: RequestInit) {
     try {
       const url = `${this.config.host}${path}`;
@@ -37,7 +52,13 @@ export class MeilisearchAdapter {
     }
   }
 
-  async initializeStorage(roomId: string): Promise<void> {
+  /**
+   * Initializes a storage index for a room
+   * @private
+   * @param {string} roomId - Room identifier to create index for
+   * @returns {Promise<void>}
+   */
+  private async initializeStorage(roomId: string): Promise<void> {
     try {
       let indexExists = false;
 
@@ -82,7 +103,14 @@ export class MeilisearchAdapter {
     }
   }
 
-  async addDocuments(
+  /**
+   * Adds documents to the Meilisearch index
+   * @private
+   * @param {BaseMemoryType[]} documents - Documents to add
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<void>}
+   */
+  private async addDocuments(
     documents: BaseMemoryType[],
     roomId: string
   ): Promise<void> {
@@ -91,13 +119,24 @@ export class MeilisearchAdapter {
       body: JSON.stringify(documents),
     });
   }
-  async deleteStorage(roomId: string): Promise<void> {
+
+  /**
+   * Deletes a storage index for a room
+   * @private
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<void>}
+   */
+  private async deleteStorage(roomId: string): Promise<void> {
     await this.makeRequest(`/indexes/${roomId}`, {
       method: "DELETE",
     });
   }
 
-  // Required BaseMemory implementations
+  /**
+   * Initializes the adapter for a specific room
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<void>}
+   */
   async init(roomId: string): Promise<void> {
     try {
       // Initialize the default "memories" index
@@ -110,7 +149,17 @@ export class MeilisearchAdapter {
     }
   }
 
-  async search(
+  /**
+   * Performs a search in the Meilisearch index
+   * @private
+   * @param {string} query - Search query
+   * @param {string} roomId - Room identifier
+   * @param {Object} [options] - Search options
+   * @param {number} [options.limit] - Maximum number of results
+   * @param {number} [options.threshold] - Minimum score threshold
+   * @returns {Promise<SearchResult[]>} Search results
+   */
+  private async search(
     query: string,
     roomId: string,
     options?: { limit?: number; threshold?: number }
@@ -123,6 +172,10 @@ export class MeilisearchAdapter {
       }),
     });
 
+    if (!searchResults.hits) {
+      return [];
+    }
+
     return searchResults.hits.map((hit: any) => ({
       document: {
         id: hit.id,
@@ -135,17 +188,30 @@ export class MeilisearchAdapter {
     }));
   }
 
+  /**
+   * Creates a new memory entry
+   * @param {CreateMemoryInput & { embedding?: number[] }} input - Memory data with optional embedding
+   * @returns {Promise<BaseMemoryType | undefined>} Created memory or undefined
+   */
   async createMemory(
     input: CreateMemoryInput & { embedding?: number[] }
   ): Promise<BaseMemoryType | undefined> {
     // Initialize storage for this roomId if needed
     await this.initializeStorage(input.roomId);
 
+    // Check if the memory already exists
+    const existingMemory = await this.search(input.data, input.roomId, {
+      limit: 1,
+    });
+    if (existingMemory.length > 0) {
+      return existingMemory[0].document;
+    }
+
     // If not found, create new memory
     const memory: BaseMemoryType = {
       id: input.id || crypto.randomUUID(),
       data: input.data,
-      embedding: input.embedding || null,
+      embedding: input.embedding,
       roomId: input.roomId,
       createdAt: new Date(),
     };
@@ -154,6 +220,12 @@ export class MeilisearchAdapter {
     return memory;
   }
 
+  /**
+   * 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
+   */
   async getMemoryById(
     id: string,
     roomId: string
@@ -176,6 +248,14 @@ export class MeilisearchAdapter {
     }
   }
 
+  /**
+   * Searches for memories based on query and options
+   * @param {string} query - Search query
+   * @param {Object} options - Search options
+   * @param {string} options.roomId - Room identifier
+   * @param {number} [options.limit] - Maximum number of results
+   * @returns {Promise<BaseMemoryType[]>} Array of matching memories
+   */
   async getMemoryByIndex(
     query: string,
     options: { roomId: string; limit?: number }
@@ -194,6 +274,11 @@ export class MeilisearchAdapter {
       }));
   }
 
+  /**
+   * Retrieves all memories for a room
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<BaseMemoryType[]>} Array of all memories
+   */
   async getAllMemories(roomId: string): Promise<BaseMemoryType[]> {
     const results = await this.makeRequest(`/indexes/${roomId}/documents`);
     if (results.total === 0) {
@@ -209,6 +294,12 @@ export class MeilisearchAdapter {
     }));
   }
 
+  /**
+   * Deletes a specific memory
+   * @param {string} id - Memory identifier
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<void>}
+   */
   async clearMemoryById(id: string, roomId: string): Promise<void> {
     try {
       // Ensure the index exists before attempting to delete
@@ -230,6 +321,10 @@ export class MeilisearchAdapter {
     }
   }
 
+  /**
+   * Clears all memories across all rooms
+   * @returns {Promise<void>}
+   */
   async clearAllMemories(): Promise<void> {
     try {
       // Get all indexes
@@ -248,8 +343,15 @@ export class MeilisearchAdapter {
   }
 }
 
+/**
+ * @interface SearchResult
+ * @description Interface for search results from Meilisearch
+ */
 interface SearchResult {
+  /** The matched document */
   document?: any;
+  /** Relevance score of the match */
   score?: number;
+  /** Array of additional results */
   results?: any[];
 }

package/modules/memory/adapters/redis/index.ts

@@ -0,0 +1,164 @@
+import { IMemoryAdapter } from "interfaces";
+import { createClient } from "redis";
+import { BaseMemoryType, CreateMemoryInput } from "types";
+
+/**
+ * @module RedisAdapter
+ * @description Adapter implementation for Redis as a memory storage solution.
+ * Provides integration with Redis for storing and retrieving memory entries with TTL support.
+ * @implements {IMemoryAdapter}
+ */
+export class RedisAdapter implements IMemoryAdapter {
+  private redis;
+  private readonly cachePrefix: string;
+  private readonly cacheTTL: number;
+
+  /**
+   * Creates an instance of RedisAdapter
+   * @param {string} redisUrl - Redis connection URL
+   * @param {Object} options - Configuration options
+   * @param {string} [options.cachePrefix="memory:"] - Prefix for Redis keys
+   * @param {number} [options.cacheTTL=3600] - Default TTL in seconds
+   */
+  constructor(
+    private readonly redisUrl: string,
+    options: {
+      cachePrefix?: string;
+      cacheTTL?: number;
+    }
+  ) {
+    this.cachePrefix = options.cachePrefix || "memory:";
+    this.cacheTTL = options.cacheTTL || 3600;
+    this.redis = createClient({
+      url: redisUrl,
+      socket: {
+        tls: true,
+        rejectUnauthorized: true,
+      },
+    });
+  }
+
+  /**
+   * Initializes the Redis connection
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<void>}
+   */
+  async init(roomId: string): Promise<void> {
+    this.redis.on("error", (err) => console.error("Redis Client Error:", err));
+    await this.redis.connect();
+  }
+
+  /**
+   * Creates a new memory entry in Redis
+   * @param {CreateMemoryInput & { embedding?: number[] }} input - Memory data with optional embedding
+   * @returns {Promise<BaseMemoryType | undefined>} Created memory or undefined
+   */
+  async createMemory(
+    input: CreateMemoryInput & { embedding?: number[] }
+  ): Promise<BaseMemoryType | undefined> {
+    const memory: BaseMemoryType = {
+      id: input.id || crypto.randomUUID(),
+      data: input.data,
+      embedding: input.embedding,
+      roomId: input.roomId,
+      createdAt: new Date(),
+    };
+
+    const key = memory.roomId
+      ? `${this.cachePrefix}${memory.roomId}:${memory.id}`
+      : `${this.cachePrefix}${memory.id}`;
+
+    await this.redis.set(key, JSON.stringify(memory), {
+      EX: this.cacheTTL,
+    });
+
+    return memory;
+  }
+
+  /**
+   * Retrieves a memory by ID and room ID from Redis
+   * @param {string} id - Memory identifier
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<BaseMemoryType | null>} Memory entry or null if not found
+   */
+  async getMemoryById(
+    id: string,
+    roomId: string
+  ): Promise<BaseMemoryType | null> {
+    const key = `${this.cachePrefix}${roomId}:${id}`;
+    const data = await this.redis.get(key);
+    return data ? JSON.parse(data) : null;
+  }
+
+  /**
+   * Searches for memories in Redis based on pattern matching
+   * @param {string} query - Search query
+   * @param {Object} options - Search options
+   * @param {string} options.roomId - Room identifier
+   * @param {number} [options.limit] - Maximum number of results
+   * @returns {Promise<BaseMemoryType[]>} Array of matching memories
+   */
+  async getMemoryByIndex(
+    query: string,
+    options: { roomId: string; limit?: number }
+  ): Promise<BaseMemoryType[]> {
+    const pattern = `${this.cachePrefix}${options.roomId}:*`;
+    const keys = await this.redis.keys(pattern);
+    const memories = await Promise.all(
+      keys.map(async (key) => {
+        const data = await this.redis.get(key);
+        return data ? JSON.parse(data) : null;
+      })
+    );
+    return memories.filter(Boolean).slice(0, options.limit || 10);
+  }
+
+  /**
+   * Retrieves all memories for a room from Redis
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<BaseMemoryType[]>} Array of all memories
+   */
+  async getAllMemories(roomId: string): Promise<BaseMemoryType[]> {
+    const pattern = `${this.cachePrefix}${roomId}:*`;
+    const keys = await this.redis.keys(pattern);
+    const memories = await Promise.all(
+      keys.map(async (key) => {
+        const data = await this.redis.get(key);
+        return data ? JSON.parse(data) : null;
+      })
+    );
+    return memories.filter(Boolean);
+  }
+
+  /**
+   * Deletes a specific memory from Redis
+   * @param {string} id - Memory identifier
+   * @param {string} roomId - Room identifier
+   * @returns {Promise<void>}
+   */
+  async clearMemoryById(id: string, roomId: string): Promise<void> {
+    const key = `${this.cachePrefix}${roomId}:${id}`;
+    await this.redis.del(key);
+  }
+
+  /**
+   * Clears all memories across all rooms from Redis
+   * @returns {Promise<void>}
+   */
+  async clearAllMemories(): Promise<void> {
+    const keys = await this.redis.keys(`${this.cachePrefix}*`);
+    if (keys.length > 0) {
+      await this.redis.del(keys);
+    }
+  }
+
+  /**
+   * Closes the Redis connection
+   * @returns {Promise<void>}
+   */
+  async quit(): Promise<void> {
+    if (this.redis) {
+      await this.redis.quit();
+    }
+  }
+}