@yamo/memory-mesh 2.3.2 → 3.0.0

package/lib/{embeddings/service.js → memory/embeddings/service.ts}

@@ -10,38 +10,93 @@
  */
 
 import crypto from "crypto";
-import {
-  ConfigurationError,
-  EmbeddingError,
-  StorageError,
-  QueryError
-} from "../lancedb/errors.js";
+import { ConfigurationError, EmbeddingError } from "../adapters/errors.js";
+
+/**
+ * Service configuration interface
+ */
+
+export interface ServiceConfig {
+  modelType?: "local" | "ollama" | "openai" | "cohere";
+  modelName?: string;
+  baseUrl?: string;
+  dimension?: number;
+  batchSize?: number;
+  normalize?: boolean;
+  cacheMaxSize?: number;
+  apiKey?: string;
+  priority?: number; // Used by factory
+}
+
+export interface ServiceStats {
+  modelType: string;
+  modelName: string;
+  dimension: number;
+  initialized: boolean;
+  totalEmbeddings: number;
+  cacheHits: number;
+  cacheMisses: number;
+  cacheSize: number;
+  cacheMaxSize: number;
+  cacheHitRate: number;
+  batchCount: number;
+  batchSize: number;
+  normalize: boolean;
+}
 
 /**
  * EmbeddingService provides a unified interface for generating text embeddings
  * using multiple backend providers (local ONNX models or cloud APIs).
  */
-class EmbeddingService {
+export class EmbeddingService {
+  modelType: string;
+  modelName: string;
+  baseUrl: string;
+  dimension: number;
+  batchSize: number;
+  normalize: boolean;
+  apiKey?: string;
+  model: any;
+  cache: Map<string, number[]>;
+  cacheMaxSize: number;
+  initialized: boolean;
+  stats: {
+    totalEmbeddings: number;
+    cacheHits: number;
+    cacheMisses: number;
+    batchCount: number;
+  };
+
   /**
    * Create a new EmbeddingService instance
    * @param {Object} [config={}] - Configuration options
-   * @param {string} [config.modelType] - Type of model ('local', 'ollama', 'openai', 'cohere')
-   * @param {string} [config.modelName] - Name of the model to use
-   * @param {string} [config.baseUrl] - Base URL for Ollama (default: http://localhost:11434)
-   * @param {number} [config.dimension] - Embedding dimension
-   * @param {number} [config.batchSize] - Maximum batch size for processing
-   * @param {boolean} [config.normalize] - Whether to normalize embeddings to unit length
-   * @param {number} [config.cacheMaxSize] - Maximum size of LRU cache
-   * @param {string} [config.apiKey] - API key for cloud providers
    */
-  // @ts-ignore
-  constructor(config = {}) {
-    this.modelType = (config && config.modelType) || process.env.EMBEDDING_MODEL_TYPE || 'local';
-    this.modelName = (config && config.modelName) || process.env.EMBEDDING_MODEL_NAME || 'Xenova/all-MiniLM-L6-v2';
-    this.baseUrl = (config && config.baseUrl) || process.env.OLLAMA_BASE_URL || process.env.EMBEDDING_BASE_URL || 'http://localhost:11434';
-    this.dimension = (config && config.dimension) || parseInt(process.env.EMBEDDING_DIMENSION || '384') || 384;
-    this.batchSize = (config && config.batchSize) || parseInt(process.env.EMBEDDING_BATCH_SIZE || '32') || 32;
-    this.normalize = (config && config.normalize !== undefined) ? config.normalize : (process.env.EMBEDDING_NORMALIZE !== 'false');
+  constructor(config: ServiceConfig = {}) {
+    this.modelType =
+      (config && config.modelType) ||
+      process.env.EMBEDDING_MODEL_TYPE ||
+      "local";
+    this.modelName =
+      (config && config.modelName) ||
+      process.env.EMBEDDING_MODEL_NAME ||
+      "Xenova/all-MiniLM-L6-v2";
+    this.baseUrl =
+      (config && config.baseUrl) ||
+      process.env.OLLAMA_BASE_URL ||
+      process.env.EMBEDDING_BASE_URL ||
+      "http://localhost:11434";
+    this.dimension =
+      (config && config.dimension) ||
+      parseInt(process.env.EMBEDDING_DIMENSION || "384") ||
+      384;
+    this.batchSize =
+      (config && config.batchSize) ||
+      parseInt(process.env.EMBEDDING_BATCH_SIZE || "32") ||
+      32;
+    this.normalize =
+      config && config.normalize !== undefined
+        ? config.normalize
+        : process.env.EMBEDDING_NORMALIZE !== "false";
 
     this.apiKey = (config && config.apiKey) || process.env.EMBEDDING_API_KEY;
 
@@ -55,7 +110,7 @@ class EmbeddingService {
       totalEmbeddings: 0,
       cacheHits: 0,
       cacheMisses: 0,
-      batchCount: 0
+      batchCount: 0,
     };
   }
 
@@ -63,25 +118,25 @@ class EmbeddingService {
    * Initialize the embedding model
    * Loads the model based on modelType (local, ollama, openai, cohere)
    */
-  async init() {
+  async init(): Promise<void> {
     try {
       switch (this.modelType) {
-        case 'local':
+        case "local":
           await this._initLocalModel();
           break;
-        case 'ollama':
-          await this._initOllama();
+        case "ollama":
+          this._initOllama();
           break;
-        case 'openai':
+        case "openai":
           await this._initOpenAI();
           break;
-        case 'cohere':
+        case "cohere":
           await this._initCohere();
           break;
         default:
           throw new ConfigurationError(
             `Unknown model type: ${this.modelType}. Must be 'local', 'ollama', 'openai', or 'cohere'`,
-            { modelType: this.modelType }
+            { modelType: this.modelType },
           );
       }
 
@@ -93,7 +148,11 @@ class EmbeddingService {
       const message = error instanceof Error ? error.message : String(error);
       throw new EmbeddingError(
         `Failed to initialize embedding service: ${message}`,
-        { modelType: this.modelType, modelName: this.modelName, originalError: message }
+        {
+          modelType: this.modelType,
+          modelName: this.modelName,
+          originalError: message,
+        },
       );
     }
   }
@@ -104,19 +163,21 @@ class EmbeddingService {
    * @param {Object} options - Options for embedding generation
    * @returns {Promise<number[]>} Embedding vector
    */
-  async embed(text, options = {}) {
+  async embed(text: string, _options: any = {}): Promise<number[]> {
     if (!this.initialized) {
       throw new EmbeddingError(
-        'Embedding service not initialized. Call init() first.',
-        { modelType: this.modelType }
+        "Embedding service not initialized. Call init() first.",
+        {
+          modelType: this.modelType,
+        },
       );
     }
 
-    if (!text || typeof text !== 'string') {
-      throw new EmbeddingError(
-        'Text must be a non-empty string',
-        { text, textType: typeof text }
-      );
+    if (!text || typeof text !== "string") {
+      throw new EmbeddingError("Text must be a non-empty string", {
+        text,
+        textType: typeof text,
+      });
     }
 
     // Check cache
@@ -128,26 +189,25 @@ class EmbeddingService {
     }
 
     // Generate embedding
-    let embedding;
+    let embedding: number[];
     try {
       switch (this.modelType) {
-        case 'local':
+        case "local":
           embedding = await this._embedLocal(text);
           break;
-        case 'ollama':
+        case "ollama":
           embedding = await this._embedOllama(text);
           break;
-        case 'openai':
+        case "openai":
           embedding = await this._embedOpenAI(text);
           break;
-        case 'cohere':
+        case "cohere":
           embedding = await this._embedCohere(text);
           break;
         default:
-          throw new EmbeddingError(
-            `Unknown model type: ${this.modelType}`,
-            { modelType: this.modelType }
-          );
+          throw new EmbeddingError(`Unknown model type: ${this.modelType}`, {
+            modelType: this.modelType,
+          });
       }
 
       // Normalize if enabled
@@ -167,10 +227,10 @@ class EmbeddingService {
         throw error;
       }
       const message = error instanceof Error ? error.message : String(error);
-      throw new EmbeddingError(
-        `Failed to generate embedding: ${message}`,
-        { modelType: this.modelType, text: text.substring(0, 100) }
-      );
+      throw new EmbeddingError(`Failed to generate embedding: ${message}`, {
+        modelType: this.modelType,
+        text: text.substring(0, 100),
+      });
     }
   }
 
@@ -180,19 +240,20 @@ class EmbeddingService {
    * @param {Object} options - Options for embedding generation
    * @returns {Promise<number[][]>} Array of embedding vectors
    */
-  async embedBatch(texts, options = {}) {
+  async embedBatch(texts: string[], _options: any = {}): Promise<number[][]> {
     if (!this.initialized) {
       throw new EmbeddingError(
-        'Embedding service not initialized. Call init() first.',
-        { modelType: this.modelType }
+        "Embedding service not initialized. Call init() first.",
+        {
+          modelType: this.modelType,
+        },
       );
     }
 
     if (!Array.isArray(texts)) {
-      throw new EmbeddingError(
-        'Texts must be an array',
-        { textsType: typeof texts }
-      );
+      throw new EmbeddingError("Texts must be an array", {
+        textsType: typeof texts,
+      });
     }
 
     if (texts.length === 0) {
@@ -200,15 +261,18 @@ class EmbeddingService {
     }
 
     try {
-      const embeddings = [];
+      const embeddings: number[][] = [];
 
       // Process in batches
       for (let i = 0; i < texts.length; i += this.batchSize) {
-        const batch = texts.slice(i, Math.min(i + this.batchSize, texts.length));
+        const batch = texts.slice(
+          i,
+          Math.min(i + this.batchSize, texts.length),
+        );
 
         // Generate embeddings for batch
         const batchEmbeddings = await Promise.all(
-          batch.map(text => this.embed(text, options))
+          batch.map((text) => this.embed(text)),
         );
 
         embeddings.push(...batchEmbeddings);
@@ -223,7 +287,10 @@ class EmbeddingService {
       const message = error instanceof Error ? error.message : String(error);
       throw new EmbeddingError(
         `Failed to generate batch embeddings: ${message}`,
-        { modelType: this.modelType, batchSize: texts.length }
+        {
+          modelType: this.modelType,
+          batchSize: texts.length,
+        },
       );
     }
   }
@@ -232,36 +299,31 @@ class EmbeddingService {
    * Initialize local ONNX model using Xenova/Transformers.js
    * @private
    */
-  async _initLocalModel() {
+  async _initLocalModel(): Promise<void> {
     try {
       // Dynamic import to allow optional dependency
-      const { pipeline } = await import("@xenova/transformers");
+      const { pipeline } = (await import("@xenova/transformers")) as any;
 
       // Load feature extraction pipeline
-      // @ts-ignore
-      this.model = await pipeline(
-        'feature-extraction',
-        this.modelName,
-        {
-          quantized: true,
-          progress_callback: (progress) => {
-            // Optional: Log model download progress
-            if (progress.status === 'downloading') {
-              // Silently handle progress
-            }
+      this.model = await pipeline("feature-extraction", this.modelName, {
+        quantized: true,
+        progress_callback: (progress: any) => {
+          // Optional: Log model download progress
+          if (progress.status === "downloading") {
+            // Silently handle progress
           }
-        }
-      );
+        },
+      });
 
       // Update dimension based on model (384 for all-MiniLM-L6-v2)
-      if (this.modelName.includes('all-MiniLM-L6-v2')) {
+      if (this.modelName.includes("all-MiniLM-L6-v2")) {
         this.dimension = 384;
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ConfigurationError(
         `Failed to load local model: ${message}. Make sure @xenova/transformers is installed.`,
-        { modelName: this.modelName, error: message }
+        { modelName: this.modelName, error: message },
       );
     }
   }
@@ -271,20 +333,20 @@ class EmbeddingService {
    * Ollama runs locally and doesn't require authentication
    * @private
    */
-  async _initOllama() {
+  _initOllama(): void {
     // Ollama doesn't require initialization - it's a local HTTP API
     // Store the base URL for use in _embedOllama
     this.model = {
       baseUrl: this.baseUrl,
-      modelName: this.modelName || 'nomic-embed-text'
+      modelName: this.modelName || "nomic-embed-text",
     };
 
     // Set default dimension for common Ollama embedding models
-    if (this.modelName.includes('nomic-embed-text')) {
+    if (this.modelName.includes("nomic-embed-text")) {
       this.dimension = 768;
-    } else if (this.modelName.includes('mxbai-embed')) {
+    } else if (this.modelName.includes("mxbai-embed")) {
       this.dimension = 1024;
-    } else if (this.modelName.includes('all-MiniLM')) {
+    } else if (this.modelName.includes("all-MiniLM")) {
       this.dimension = 384;
     }
   }
@@ -293,29 +355,28 @@ class EmbeddingService {
    * Initialize OpenAI client
    * @private
    */
-  async _initOpenAI() {
+  async _initOpenAI(): Promise<void> {
     if (!this.apiKey) {
       throw new ConfigurationError(
-        'OpenAI API key is required. Set EMBEDDING_API_KEY environment variable or pass apiKey in config.',
-        { modelType: 'openai' }
+        "OpenAI API key is required. Set EMBEDDING_API_KEY environment variable or pass apiKey in config.",
+        { modelType: "openai" },
       );
     }
 
     try {
-      // Dynamic import to allow optional dependency
-      const { OpenAI } = await import("openai");
-      // @ts-ignore - OpenAI constructor
+      // Dynamic import to allow optional dependency (openai may not be installed)
+      const { OpenAI } = await import("openai" as any);
       this.model = new OpenAI({ apiKey: this.apiKey });
 
       // Update dimension for OpenAI models
-      if (this.modelName.includes('text-embedding-ada-002')) {
+      if (this.modelName.includes("text-embedding-ada-002")) {
         this.dimension = 1536;
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ConfigurationError(
         `Failed to initialize OpenAI client: ${message}. Make sure openai package is installed.`,
-        { error: message }
+        { error: message },
       );
     }
   }
@@ -324,29 +385,28 @@ class EmbeddingService {
    * Initialize Cohere client
    * @private
    */
-  async _initCohere() {
+  async _initCohere(): Promise<void> {
     if (!this.apiKey) {
       throw new ConfigurationError(
-        'Cohere API key is required. Set EMBEDDING_API_KEY environment variable or pass apiKey in config.',
-        { modelType: 'cohere' }
+        "Cohere API key is required. Set EMBEDDING_API_KEY environment variable or pass apiKey in config.",
+        { modelType: "cohere" },
       );
     }
 
     try {
-      // Dynamic import to allow optional dependency
-      const cohere = await import("cohere-ai");
-      // @ts-ignore - Cohere constructor
+      // Dynamic import to allow optional dependency (cohere-ai may not be installed)
+      const cohere = await import("cohere-ai" as any);
       this.model = new cohere.CohereClient({ token: this.apiKey });
 
       // Update dimension for Cohere models
-      if (this.modelName.includes('embed-english-v3.0')) {
+      if (this.modelName.includes("embed-english-v3.0")) {
         this.dimension = 1024;
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new ConfigurationError(
         `Failed to initialize Cohere client: ${message}. Make sure cohere-ai package is installed.`,
-        { error: message }
+        { error: message },
       );
     }
   }
@@ -357,24 +417,28 @@ class EmbeddingService {
    * @returns {Promise<number[]>} Embedding vector
    * @private
    */
-  async _embedLocal(text) {
-    if (!this.model) throw new EmbeddingError('Model not initialized');
+  async _embedLocal(text: string): Promise<number[]> {
+    if (!this.model) {
+      throw new EmbeddingError("Model not initialized");
+    }
     try {
-      // @ts-ignore - Local model call
+      // Local model call
       const output = await this.model(text, {
-        pooling: 'mean',
-        normalize: false
+        pooling: "mean",
+        normalize: false,
       });
 
       // Convert from tensor to array
       const embedding = Array.from(output.data);
-      // @ts-ignore
-      return embedding;
+      return embedding as number[];
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       throw new EmbeddingError(
         `Failed to generate local embedding: ${message}`,
-        { modelName: this.modelName, text: text.substring(0, 100) }
+        {
+          modelName: this.modelName,
+          text: text.substring(0, 100),
+        },
       );
     }
   }
@@ -385,30 +449,30 @@ class EmbeddingService {
    * @returns {Promise<number[]>} Embedding vector
    * @private
    */
-  async _embedOllama(text) {
-    if (!this.model) throw new EmbeddingError('Model not initialized');
+  async _embedOllama(text: string): Promise<number[]> {
+    if (!this.model) {
+      throw new EmbeddingError("Model not initialized");
+    }
     try {
-      // @ts-ignore - Ollama model object
       const baseUrl = this.model.baseUrl;
-      // @ts-ignore
       const modelName = this.model.modelName;
 
       const response = await fetch(`${baseUrl}/api/embeddings`, {
-        method: 'POST',
+        method: "POST",
         headers: {
-          'Content-Type': 'application/json'
+          "Content-Type": "application/json",
         },
         body: JSON.stringify({
           model: modelName,
-          prompt: text
-        })
+          prompt: text,
+        }),
       });
 
       if (!response.ok) {
         const errorText = await response.text();
         throw new EmbeddingError(
           `Ollama API error: ${response.status} ${response.statusText} - ${errorText}`,
-          { baseUrl: baseUrl, modelName: modelName }
+          { baseUrl: baseUrl, modelName: modelName },
         );
       }
 
@@ -416,8 +480,10 @@ class EmbeddingService {
 
       if (!data.embedding) {
         throw new EmbeddingError(
-          'Invalid response from Ollama API: missing embedding field',
-          { response: data }
+          "Invalid response from Ollama API: missing embedding field",
+          {
+            response: data,
+          },
         );
       }
 
@@ -427,13 +493,11 @@ class EmbeddingService {
         throw error;
       }
       const message = error instanceof Error ? error.message : String(error);
-      // @ts-ignore
       const baseUrl = this.model?.baseUrl;
-      // @ts-ignore
       const modelName = this.model?.modelName;
       throw new EmbeddingError(
         `Failed to generate Ollama embedding: ${message}. Make sure Ollama is running and the model is available.`,
-        { baseUrl, modelName, error: message }
+        { baseUrl, modelName, error: message },
       );
     }
   }
@@ -444,13 +508,14 @@ class EmbeddingService {
    * @returns {Promise<number[]>} Embedding vector
    * @private
    */
-  async _embedOpenAI(text) {
-    if (!this.model) throw new EmbeddingError('Model not initialized');
+  async _embedOpenAI(text: string): Promise<number[]> {
+    if (!this.model) {
+      throw new EmbeddingError("Model not initialized");
+    }
     try {
-      // @ts-ignore - OpenAI client
       const response = await this.model.embeddings.create({
         model: this.modelName,
-        input: text
+        input: text,
       });
 
       const embedding = response.data[0].embedding;
@@ -459,7 +524,10 @@ class EmbeddingService {
       const message = error instanceof Error ? error.message : String(error);
       throw new EmbeddingError(
         `Failed to generate OpenAI embedding: ${message}`,
-        { modelName: this.modelName, error: message }
+        {
+          modelName: this.modelName,
+          error: message,
+        },
       );
     }
   }
@@ -470,14 +538,15 @@ class EmbeddingService {
    * @returns {Promise<number[]>} Embedding vector
    * @private
    */
-  async _embedCohere(text) {
-    if (!this.model) throw new EmbeddingError('Model not initialized');
+  async _embedCohere(text: string): Promise<number[]> {
+    if (!this.model) {
+      throw new EmbeddingError("Model not initialized");
+    }
     try {
-      // @ts-ignore - Cohere client
       const response = await this.model.embed({
         model: this.modelName,
         texts: [text],
-        inputType: 'search_document'
+        inputType: "search_document",
       });
 
       const embedding = response.embeddings[0];
@@ -486,7 +555,10 @@ class EmbeddingService {
       const message = error instanceof Error ? error.message : String(error);
       throw new EmbeddingError(
         `Failed to generate Cohere embedding: ${message}`,
-        { modelName: this.modelName, error: message }
+        {
+          modelName: this.modelName,
+          error: message,
+        },
       );
     }
   }
@@ -497,10 +569,10 @@ class EmbeddingService {
    * @returns {number[]} Normalized vector
    * @private
    */
-  _normalize(vector) {
+  _normalize(vector: number[]): number[] {
     // Calculate magnitude
     const magnitude = Math.sqrt(
-      vector.reduce((sum, val) => sum + val * val, 0)
+      vector.reduce((sum, val) => sum + val * val, 0),
     );
 
     // Avoid division by zero
@@ -509,7 +581,7 @@ class EmbeddingService {
     }
 
     // Normalize
-    return vector.map(val => val / magnitude);
+    return vector.map((val) => val / magnitude);
   }
 
   /**
@@ -518,24 +590,17 @@ class EmbeddingService {
    * @returns {string} Cache key
    * @private
    */
-  _getCacheKey(text) {
-    return crypto
-      .createHash('md5')
-      .update(text)
-      .digest('hex');
+  _getCacheKey(text: string): string {
+    return crypto.createHash("md5").update(text).digest("hex");
   }
 
-  /**
-   * Set cache value with LRU eviction
-   * @param {string} key - Cache key
-   * @param {number[]} value - Embedding vector
-   * @private
-   */
-  _setCache(key, value) {
+  _setCache(key: string, value: number[]): void {
     // Evict oldest if at capacity
     if (this.cache.size >= this.cacheMaxSize) {
       const firstKey = this.cache.keys().next().value;
-      this.cache.delete(firstKey);
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
     }
 
     this.cache.set(key, value);
@@ -545,7 +610,7 @@ class EmbeddingService {
    * Get service statistics
    * @returns {Object} Statistics object
    */
-  getStats() {
+  getStats(): ServiceStats {
     return {
       modelType: this.modelType,
       modelName: this.modelName,
@@ -556,29 +621,31 @@ class EmbeddingService {
       cacheMisses: this.stats.cacheMisses,
       cacheSize: this.cache.size,
       cacheMaxSize: this.cacheMaxSize,
-      cacheHitRate: this.stats.cacheHits / (this.stats.cacheHits + this.stats.cacheMisses) || 0,
+      cacheHitRate:
+        this.stats.cacheHits /
+          (this.stats.cacheHits + this.stats.cacheMisses) || 0,
       batchCount: this.stats.batchCount,
       batchSize: this.batchSize,
-      normalize: this.normalize
+      normalize: this.normalize,
     };
   }
 
   /**
    * Clear the embedding cache
    */
-  clearCache() {
+  clearCache(): void {
     this.cache.clear();
   }
 
   /**
    * Reset statistics
    */
-  resetStats() {
+  resetStats(): void {
     this.stats = {
       totalEmbeddings: 0,
       cacheHits: 0,
       cacheMisses: 0,
-      batchCount: 0
+      batchCount: 0,
     };
   }
 }