@yamo/memory-mesh 2.3.2 → 3.0.0

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

@@ -3,11 +3,31 @@
  * Manages primary and fallback embedding services
  */
 
-import EmbeddingService from "./service.js";
-import { ConfigurationError, EmbeddingError } from "../lancedb/errors.js";
+import EmbeddingService, { ServiceConfig, ServiceStats } from "./service.js";
+import { ConfigurationError, EmbeddingError } from "../adapters/errors.js";
+import { createLogger } from "../../utils/logger.js";
+
+const logger = createLogger("embedding-factory");
+
+export interface FactoryStats {
+  configured: boolean;
+  primary: ServiceStats | null;
+  fallbacks: ServiceStats[];
+}
+
+export interface InitResult {
+  success: boolean;
+  primary: string | null;
+  fallbacks: string[];
+}
 
 class EmbeddingFactory {
-  constructor(ServiceClass = EmbeddingService) {
+  primaryService: EmbeddingService | null;
+  fallbackServices: EmbeddingService[];
+  configured: boolean;
+  ServiceClass: typeof EmbeddingService;
+
+  constructor(ServiceClass: typeof EmbeddingService = EmbeddingService) {
     this.primaryService = null;
     this.fallbackServices = [];
     this.configured = false;
@@ -19,14 +39,18 @@ class EmbeddingFactory {
    * @param {Array} configs - Array of { modelType, modelName, priority, apiKey }
    * @returns {Object} Success status
    */
-  configure(configs) {
+  configure(configs: ServiceConfig[]): { success: boolean } {
     // Sort by priority (lower = higher priority)
-    configs.sort((a, b) => a.priority - b.priority);
+    configs.sort((a, b) => (a.priority || 0) - (b.priority || 0));
 
-    this.primaryService = new this.ServiceClass(configs[0]);
+    if (configs.length > 0) {
+      this.primaryService = new this.ServiceClass(configs[0]);
+    }
 
     if (configs.length > 1) {
-      this.fallbackServices = configs.slice(1).map(c => new this.ServiceClass(c));
+      this.fallbackServices = configs
+        .slice(1)
+        .map((c) => new this.ServiceClass(c));
     }
 
     this.configured = true;
@@ -37,9 +61,11 @@ class EmbeddingFactory {
    * Initialize all configured services
    * @returns {Promise<Object>} Initialization status
    */
-  async init() {
+  async init(): Promise<InitResult> {
     if (!this.configured) {
-      throw new ConfigurationError('EmbeddingFactory not configured. Call configure() first.');
+      throw new ConfigurationError(
+        "EmbeddingFactory not configured. Call configure() first.",
+      );
     }
 
     // Initialize primary service
@@ -51,7 +77,7 @@ class EmbeddingFactory {
     return {
       success: true,
       primary: this.primaryService ? this.primaryService.modelName : null,
-      fallbacks: this.fallbackServices.map(s => s.modelName)
+      fallbacks: this.fallbackServices.map((s) => s.modelName),
     };
   }
 
@@ -61,9 +87,9 @@ class EmbeddingFactory {
    * @param {Object} options - Options
    * @returns {Promise<number[]>} Embedding vector
    */
-  async embed(text, options = {}) {
+  async embed(text: string, options: any = {}): Promise<number[]> {
     if (!this.configured || !this.primaryService) {
-      throw new ConfigurationError('EmbeddingFactory not configured');
+      throw new ConfigurationError("EmbeddingFactory not configured");
     }
 
     // Try primary service
@@ -73,8 +99,12 @@ class EmbeddingFactory {
       }
       return await this.primaryService.embed(text, options);
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      console.warn(`[EmbeddingFactory] Primary service failed: ${errorMessage}`);
+      const errorMessage =
+        error instanceof Error ? error.message : String(error);
+      logger.warn(
+        { err: error, primaryService: this.primaryService?.modelName },
+        "Primary service failed",
+      );
 
       // Try fallback services in order
       for (const fallback of this.fallbackServices) {
@@ -82,17 +112,22 @@ class EmbeddingFactory {
           if (!fallback.initialized) {
             await fallback.init();
           }
-          console.log(`[EmbeddingFactory] Using fallback: ${fallback.modelName}`);
+          logger.info(
+            { fallbackModel: fallback.modelName },
+            "Using fallback service",
+          );
           return await fallback.embed(text, options);
         } catch (fallbackError) {
-          const fallbackErrorMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
-          console.warn(`[EmbeddingFactory] Fallback ${fallback.modelName} failed: ${fallbackErrorMessage}`);
+          logger.warn(
+            { err: fallbackError, fallbackModel: fallback.modelName },
+            "Fallback service failed",
+          );
         }
       }
 
-      throw new EmbeddingError('All embedding services failed', {
+      throw new EmbeddingError("All embedding services failed", {
         primaryError: errorMessage,
-        fallbackCount: this.fallbackServices.length
+        fallbackCount: this.fallbackServices.length,
       });
     }
   }
@@ -103,9 +138,9 @@ class EmbeddingFactory {
    * @param {Object} options - Options
    * @returns {Promise<number[][]>} Array of embedding vectors
    */
-  async embedBatch(texts, options = {}) {
+  async embedBatch(texts: string[], options: any = {}): Promise<number[][]> {
     if (!this.configured || !this.primaryService) {
-      throw new ConfigurationError('EmbeddingFactory not configured');
+      throw new ConfigurationError("EmbeddingFactory not configured");
     }
 
     // Try primary service
@@ -115,10 +150,16 @@ class EmbeddingFactory {
       }
       return await this.primaryService.embedBatch(texts, options);
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      console.warn(`[EmbeddingFactory] Primary batch failed: ${errorMessage}`);
+      logger.warn(
+        {
+          err: error,
+          primaryService: this.primaryService?.modelName,
+          batchSize: texts.length,
+        },
+        "Primary batch embedding failed, falling back to individual embeddings",
+      );
       // Fallback to individual embedding with fallback services
-      const results = [];
+      const results: number[][] = [];
       for (const text of texts) {
         results.push(await this.embed(text, options));
       }
@@ -130,11 +171,11 @@ class EmbeddingFactory {
    * Get factory statistics
    * @returns {Object} Statistics
    */
-  getStats() {
+  getStats(): FactoryStats {
     const stats = {
       configured: this.configured,
       primary: this.primaryService?.getStats() || null,
-      fallbacks: this.fallbackServices.map(s => s.getStats())
+      fallbacks: this.fallbackServices.map((s) => s.getStats()),
     };
     return stats;
   }
@@ -142,9 +183,9 @@ class EmbeddingFactory {
   /**
    * Clear all caches
    */
-  clearCache() {
+  clearCache(): void {
     this.primaryService?.clearCache();
-    this.fallbackServices.forEach(s => s.clearCache());
+    this.fallbackServices.forEach((s) => s.clearCache());
   }
 }
 

package/lib/memory/embeddings/index.d.ts

@@ -0,0 +1,2 @@
+export { default as EmbeddingService } from "./service.js";
+export { default as EmbeddingFactory } from "./factory.js";

package/lib/memory/embeddings/index.js

@@ -0,0 +1,2 @@
+export { default as EmbeddingService } from "./service.js";
+export { default as EmbeddingFactory } from "./factory.js";

package/lib/memory/embeddings/index.ts

@@ -0,0 +1,2 @@
+export { default as EmbeddingService } from "./service.js";
+export { default as EmbeddingFactory } from "./factory.js";

package/lib/memory/embeddings/service.d.ts

@@ -0,0 +1,164 @@
+/**
+ * EmbeddingService - Multi-provider embedding generation service
+ *
+ * Supports:
+ * - Local models: Xenova/Transformers.js (ONNX runtime)
+ * - Ollama: Local Ollama embeddings API
+ * - API models: OpenAI, Cohere
+ *
+ * Implements TDD for Phase 3, Task 3.1 - Embedding Service Architecture
+ */
+/**
+ * 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;
+}
+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).
+ */
+export declare 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
+     */
+    constructor(config?: ServiceConfig);
+    /**
+     * Initialize the embedding model
+     * Loads the model based on modelType (local, ollama, openai, cohere)
+     */
+    init(): Promise<void>;
+    /**
+     * Generate embedding for a single text
+     * @param {string} text - Text to embed
+     * @param {Object} options - Options for embedding generation
+     * @returns {Promise<number[]>} Embedding vector
+     */
+    embed(text: string, _options?: any): Promise<number[]>;
+    /**
+     * Generate embeddings for a batch of texts
+     * @param {string[]} texts - Array of texts to embed
+     * @param {Object} options - Options for embedding generation
+     * @returns {Promise<number[][]>} Array of embedding vectors
+     */
+    embedBatch(texts: string[], _options?: any): Promise<number[][]>;
+    /**
+     * Initialize local ONNX model using Xenova/Transformers.js
+     * @private
+     */
+    _initLocalModel(): Promise<void>;
+    /**
+     * Initialize Ollama client
+     * Ollama runs locally and doesn't require authentication
+     * @private
+     */
+    _initOllama(): void;
+    /**
+     * Initialize OpenAI client
+     * @private
+     */
+    _initOpenAI(): Promise<void>;
+    /**
+     * Initialize Cohere client
+     * @private
+     */
+    _initCohere(): Promise<void>;
+    /**
+     * Generate embedding using local ONNX model
+     * @param {string} text - Text to embed
+     * @returns {Promise<number[]>} Embedding vector
+     * @private
+     */
+    _embedLocal(text: string): Promise<number[]>;
+    /**
+     * Generate embedding using Ollama API
+     * @param {string} text - Text to embed
+     * @returns {Promise<number[]>} Embedding vector
+     * @private
+     */
+    _embedOllama(text: string): Promise<number[]>;
+    /**
+     * Generate embedding using OpenAI API
+     * @param {string} text - Text to embed
+     * @returns {Promise<number[]>} Embedding vector
+     * @private
+     */
+    _embedOpenAI(text: string): Promise<number[]>;
+    /**
+     * Generate embedding using Cohere API
+     * @param {string} text - Text to embed
+     * @returns {Promise<number[]>} Embedding vector
+     * @private
+     */
+    _embedCohere(text: string): Promise<number[]>;
+    /**
+     * Normalize vector to unit length
+     * @param {number[]} vector - Vector to normalize
+     * @returns {number[]} Normalized vector
+     * @private
+     */
+    _normalize(vector: number[]): number[];
+    /**
+     * Generate cache key from text
+     * @param {string} text - Text to generate key from
+     * @returns {string} Cache key
+     * @private
+     */
+    _getCacheKey(text: string): string;
+    _setCache(key: string, value: number[]): void;
+    /**
+     * Get service statistics
+     * @returns {Object} Statistics object
+     */
+    getStats(): ServiceStats;
+    /**
+     * Clear the embedding cache
+     */
+    clearCache(): void;
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+}
+export default EmbeddingService;