@soulcraft/brainy 2.11.0 → 2.14.0

package/dist/embeddings/SingletonModelManager.js

@@ -0,0 +1,220 @@
+/**
+ * Singleton Model Manager - THE ONLY SOURCE OF EMBEDDING MODELS
+ *
+ * This is the SINGLE, UNIFIED model initialization system that ensures:
+ * - Only ONE model instance exists across the entire system
+ * - Precision is configured once and locked
+ * - All components share the same model
+ * - No possibility of mixed precisions
+ *
+ * CRITICAL: This manager is used by EVERYTHING:
+ * - Storage operations (add, update)
+ * - Search operations (search, find)
+ * - Public API (embed, cluster)
+ * - Neural API (all neural.* methods)
+ * - Internal operations (deduplication, indexing)
+ */
+import { TransformerEmbedding } from '../utils/embedding.js';
+import { getModelPrecision, lockModelPrecision } from '../config/modelPrecisionManager.js';
+// Global state - ensures true singleton across entire process
+let globalModelInstance = null;
+let globalInitPromise = null;
+let globalInitialized = false;
+/**
+ * The ONE TRUE model manager
+ */
+export class SingletonModelManager {
+    constructor() {
+        this.stats = {
+            initialized: false,
+            precision: 'unknown',
+            initCount: 0,
+            embedCount: 0,
+            lastUsed: null
+        };
+        // Private constructor enforces singleton
+        this.stats.precision = getModelPrecision();
+        console.log(`🔐 SingletonModelManager initialized with ${this.stats.precision.toUpperCase()} precision`);
+    }
+    /**
+     * Get the singleton instance
+     */
+    static getInstance() {
+        if (!SingletonModelManager.instance) {
+            SingletonModelManager.instance = new SingletonModelManager();
+        }
+        return SingletonModelManager.instance;
+    }
+    /**
+     * Get the model instance - creates if needed, reuses if exists
+     * This is THE ONLY way to get a model in the entire system
+     */
+    async getModel() {
+        // If already initialized, return immediately
+        if (globalModelInstance && globalInitialized) {
+            this.stats.lastUsed = new Date();
+            return globalModelInstance;
+        }
+        // If initialization is in progress, wait for it
+        if (globalInitPromise) {
+            console.log('⏳ Model initialization already in progress, waiting...');
+            return await globalInitPromise;
+        }
+        // Start initialization (only happens once ever)
+        globalInitPromise = this.initializeModel();
+        try {
+            const model = await globalInitPromise;
+            globalInitialized = true;
+            return model;
+        }
+        catch (error) {
+            // Reset on error to allow retry
+            globalInitPromise = null;
+            throw error;
+        }
+    }
+    /**
+     * Initialize the model - happens exactly once
+     */
+    async initializeModel() {
+        console.log('🚀 Initializing singleton model instance...');
+        // Get precision from central manager
+        const precision = getModelPrecision();
+        console.log(`📊 Using ${precision.toUpperCase()} precision (${precision === 'q8' ? '23MB, 99% accuracy' : '90MB, 100% accuracy'})`);
+        // Detect environment for optimal settings
+        const isNode = typeof process !== 'undefined' && process.versions?.node;
+        const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
+        const isServerless = typeof process !== 'undefined' && (process.env.VERCEL ||
+            process.env.NETLIFY ||
+            process.env.AWS_LAMBDA_FUNCTION_NAME ||
+            process.env.FUNCTIONS_WORKER_RUNTIME);
+        const isTest = globalThis.__BRAINY_TEST_ENV__ || process.env.NODE_ENV === 'test';
+        // Create optimized options based on environment
+        const options = {
+            precision: precision,
+            verbose: !isTest && !isServerless && !isBrowser,
+            device: 'cpu', // CPU is most compatible
+            localFilesOnly: process.env.BRAINY_ALLOW_REMOTE_MODELS === 'false',
+            model: 'Xenova/all-MiniLM-L6-v2'
+        };
+        try {
+            // Create the ONE model instance
+            globalModelInstance = new TransformerEmbedding(options);
+            // Initialize it
+            await globalModelInstance.init();
+            // CRITICAL: Lock the precision after successful initialization
+            // This prevents any future changes to precision
+            lockModelPrecision();
+            console.log('🔒 Model precision locked at:', precision.toUpperCase());
+            // Update stats
+            this.stats.initialized = true;
+            this.stats.initCount++;
+            this.stats.lastUsed = new Date();
+            // Log memory usage if available
+            if (isNode && process.memoryUsage) {
+                const usage = process.memoryUsage();
+                this.stats.memoryFootprint = Math.round(usage.heapUsed / 1024 / 1024);
+                console.log(`💾 Model loaded, memory usage: ${this.stats.memoryFootprint}MB`);
+            }
+            console.log('✅ Singleton model initialized successfully');
+            return globalModelInstance;
+        }
+        catch (error) {
+            console.error('❌ Failed to initialize singleton model:', error);
+            globalModelInstance = null;
+            throw new Error(`Singleton model initialization failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Get embedding function that uses the singleton model
+     */
+    async getEmbeddingFunction() {
+        const model = await this.getModel();
+        return async (data) => {
+            this.stats.embedCount++;
+            this.stats.lastUsed = new Date();
+            return await model.embed(data);
+        };
+    }
+    /**
+     * Direct embed method for convenience
+     */
+    async embed(data) {
+        const model = await this.getModel();
+        this.stats.embedCount++;
+        this.stats.lastUsed = new Date();
+        return await model.embed(data);
+    }
+    /**
+     * Check if model is initialized
+     */
+    isInitialized() {
+        return globalInitialized && globalModelInstance !== null;
+    }
+    /**
+     * Get current statistics
+     */
+    getStats() {
+        return {
+            ...this.stats,
+            precision: getModelPrecision()
+        };
+    }
+    /**
+     * Validate precision consistency
+     * Throws error if attempting to use different precision
+     */
+    validatePrecision(requestedPrecision) {
+        const currentPrecision = getModelPrecision();
+        if (requestedPrecision && requestedPrecision !== currentPrecision) {
+            throw new Error(`❌ Precision mismatch! System is using ${currentPrecision.toUpperCase()} ` +
+                `but ${requestedPrecision.toUpperCase()} was requested. ` +
+                `All operations must use the same precision.`);
+        }
+    }
+    /**
+     * Force cleanup (for testing only)
+     * WARNING: This will break consistency - use only in tests
+     */
+    async _testOnlyCleanup() {
+        if (process.env.NODE_ENV !== 'test') {
+            throw new Error('Cleanup only allowed in test environment');
+        }
+        if (globalModelInstance && 'dispose' in globalModelInstance) {
+            await globalModelInstance.dispose();
+        }
+        globalModelInstance = null;
+        globalInitPromise = null;
+        globalInitialized = false;
+        this.stats.initialized = false;
+        console.log('🧹 Singleton model cleaned up (test only)');
+    }
+}
+// Export the singleton instance getter
+export const singletonModelManager = SingletonModelManager.getInstance();
+/**
+ * THE ONLY embedding function that should be used anywhere
+ * This ensures all operations use the same model instance
+ */
+export async function getUnifiedEmbeddingFunction() {
+    return await singletonModelManager.getEmbeddingFunction();
+}
+/**
+ * Direct embed function for convenience
+ */
+export async function unifiedEmbed(data) {
+    return await singletonModelManager.embed(data);
+}
+/**
+ * Check if model is ready
+ */
+export function isModelReady() {
+    return singletonModelManager.isInitialized();
+}
+/**
+ * Get model statistics
+ */
+export function getModelStats() {
+    return singletonModelManager.getStats();
+}
+//# sourceMappingURL=SingletonModelManager.js.map

package/dist/embeddings/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Embeddings Module - Clean, Unified Architecture
+ *
+ * This module provides all embedding functionality for Brainy.
+ *
+ * Main Components:
+ * - EmbeddingManager: Core embedding generation with Q8/FP32 support
+ * - CachedEmbeddings: Performance optimization layer with pre-computed embeddings
+ */
+export { EmbeddingManager, embeddingManager, embed, getEmbeddingFunction, getEmbeddingStats, type ModelPrecision } from './EmbeddingManager.js';
+export { CachedEmbeddings, cachedEmbeddings } from './CachedEmbeddings.js';
+export { embeddingManager as default } from './EmbeddingManager.js';

package/dist/embeddings/index.js

@@ -0,0 +1,16 @@
+/**
+ * Embeddings Module - Clean, Unified Architecture
+ *
+ * This module provides all embedding functionality for Brainy.
+ *
+ * Main Components:
+ * - EmbeddingManager: Core embedding generation with Q8/FP32 support
+ * - CachedEmbeddings: Performance optimization layer with pre-computed embeddings
+ */
+// Core embedding functionality
+export { EmbeddingManager, embeddingManager, embed, getEmbeddingFunction, getEmbeddingStats } from './EmbeddingManager.js';
+// Cached embeddings for performance
+export { CachedEmbeddings, cachedEmbeddings } from './CachedEmbeddings.js';
+// Default export is the singleton manager
+export { embeddingManager as default } from './EmbeddingManager.js';
+//# sourceMappingURL=index.js.map

package/dist/embeddings/lightweight-embedder.d.ts

@@ -8,7 +8,6 @@
  */
 import { Vector } from '../coreTypes.js';
 export declare class LightweightEmbedder {
-    private onnxEmbedder;
     private stats;
     embed(text: string | string[]): Promise<Vector | Vector[]>;
     private embedSingle;

package/dist/embeddings/lightweight-embedder.js

@@ -6,6 +6,7 @@
  *
  * This reduces memory usage by 90% for typical queries
  */
+import { singletonModelManager } from './SingletonModelManager.js';
 // Pre-computed embeddings for top 10,000 common terms
 // In production, this would be loaded from a file
 const PRECOMPUTED_EMBEDDINGS = {
@@ -59,7 +60,6 @@ function computeSimpleEmbedding(text) {
 }
 export class LightweightEmbedder {
     constructor() {
-        this.onnxEmbedder = null;
         this.stats = {
             precomputedHits: 0,
             simpleComputes: 0,
@@ -92,18 +92,10 @@ export class LightweightEmbedder {
             this.stats.simpleComputes++;
             return computeSimpleEmbedding(normalized);
         }
-        // 4. Last resort: Load ONNX model (only if really needed)
-        if (!this.onnxEmbedder) {
-            console.log('⚠️ Loading ONNX model for complex text...');
-            const { TransformerEmbedding } = await import('../utils/embedding.js');
-            this.onnxEmbedder = new TransformerEmbedding({
-                precision: 'fp32',
-                verbose: false
-            });
-            await this.onnxEmbedder.init();
-        }
+        // 4. Last resort: Use SingletonModelManager for complex text
+        console.log('⚠️ Using singleton model for complex text...');
         this.stats.onnxComputes++;
-        return await this.onnxEmbedder.embed(text);
+        return await singletonModelManager.embed(text);
     }
     getStats() {
         return {

package/dist/embeddings/universal-memory-manager.js

@@ -4,6 +4,7 @@
  * Works in ALL environments: Node.js, browsers, serverless, workers
  * Solves transformers.js memory leak with environment-specific strategies
  */
+import { getModelPrecision } from '../config/modelPrecisionManager.js';
 // Environment detection
 const isNode = typeof process !== 'undefined' && process.versions?.node;
 const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
@@ -107,7 +108,7 @@ export class UniversalMemoryManager {
             const { TransformerEmbedding } = await import('../utils/embedding.js');
             this.embeddingFunction = new TransformerEmbedding({
                 verbose: false,
-                precision: 'fp32',
+                precision: getModelPrecision(), // Use centrally managed precision
                 localFilesOnly: process.env.BRAINY_ALLOW_REMOTE_MODELS !== 'true'
             });
             await this.embeddingFunction.init();
@@ -119,49 +120,15 @@ export class UniversalMemoryManager {
     }
     async cleanup() {
         const startTime = Date.now();
-        try {
-            // Strategy-specific cleanup
-            switch (this.strategy) {
-                case 'node-worker':
-                    if (this.embeddingFunction?.forceRestart) {
-                        await this.embeddingFunction.forceRestart();
-                    }
-                    break;
-                case 'serverless-restart':
-                    // In serverless, create new instance
-                    if (this.embeddingFunction?.dispose) {
-                        this.embeddingFunction.dispose();
-                    }
-                    this.embeddingFunction = null;
-                    break;
-                case 'browser-dispose':
-                    // In browser, try disposal
-                    if (this.embeddingFunction?.dispose) {
-                        this.embeddingFunction.dispose();
-                    }
-                    // Force garbage collection if available
-                    if (typeof window !== 'undefined' && window.gc) {
-                        window.gc();
-                    }
-                    break;
-                default:
-                    // Fallback: dispose and recreate
-                    if (this.embeddingFunction?.dispose) {
-                        this.embeddingFunction.dispose();
-                    }
-                    this.embeddingFunction = null;
-            }
-            this.embedCount = 0;
-            this.restartCount++;
-            this.lastRestart = Date.now();
-            const cleanupTime = Date.now() - startTime;
-            console.log(`🧹 Memory cleanup completed in ${cleanupTime}ms (strategy: ${this.strategy})`);
-        }
-        catch (error) {
-            console.warn('⚠️ Cleanup failed:', error instanceof Error ? error.message : String(error));
-            // Force null assignment as last resort
-            this.embeddingFunction = null;
-        }
+        // SingletonModelManager persists - we just reset our counters
+        // The singleton model stays alive for consistency across all operations
+        // Reset counters
+        this.embedCount = 0;
+        this.restartCount++;
+        this.lastRestart = Date.now();
+        const cleanupTime = Date.now() - startTime;
+        console.log(`🧹 Memory counters reset in ${cleanupTime}ms (strategy: ${this.strategy})`);
+        console.log('ℹ️ Singleton model persists for consistency across all operations');
     }
     getMemoryStats() {
         let memoryUsage = 'unknown';
@@ -182,12 +149,8 @@ export class UniversalMemoryManager {
         };
     }
     async dispose() {
-        if (this.embeddingFunction) {
-            if (this.embeddingFunction.dispose) {
-                await this.embeddingFunction.dispose();
-            }
-            this.embeddingFunction = null;
-        }
+        // SingletonModelManager persists - nothing to dispose
+        console.log('ℹ️ Universal Memory Manager: Singleton model persists');
     }
 }
 // Export singleton instance

package/dist/embeddings/worker-embedding.js

@@ -6,6 +6,7 @@
  */
 import { TransformerEmbedding } from '../utils/embedding.js';
 import { parentPort } from 'worker_threads';
+import { getModelPrecision } from '../config/modelPrecisionManager.js';
 let model = null;
 let requestCount = 0;
 const MAX_REQUESTS = 100; // Restart worker after 100 requests to prevent memory leak
@@ -13,7 +14,7 @@ async function initModel() {
     if (!model) {
         model = new TransformerEmbedding({
             verbose: false,
-            precision: 'fp32',
+            precision: getModelPrecision(), // Use centrally managed precision
             localFilesOnly: process.env.BRAINY_ALLOW_REMOTE_MODELS !== 'true'
         });
         await model.init();
@@ -37,13 +38,8 @@ if (parentPort) {
                     }
                     break;
                 case 'dispose':
-                    if (model) {
-                        // This doesn't fully free memory (known issue), but try anyway
-                        if ('dispose' in model && typeof model.dispose === 'function') {
-                            model.dispose();
-                        }
-                        model = null;
-                    }
+                    // SingletonModelManager persists - just acknowledge
+                    console.log('ℹ️ Worker: Singleton model persists');
                     parentPort.postMessage({ id, success: true });
                     break;
                 case 'restart':