@soulcraft/brainy 1.2.0 → 1.4.0

package/dist/utils/modelManager.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Model Manager - CRITICAL SINGLETON for preventing multiple model loads
+ *
+ * This ensures that ONNX/Transformer models are loaded ONCE and reused across:
+ * - All BrainyData instances
+ * - All test cases
+ * - All embedding operations
+ * - Neural intelligence operations
+ */
+import { TransformerEmbedding } from './embedding.js';
+import { EmbeddingFunction } from '../coreTypes.js';
+/**
+ * Global singleton model manager
+ * CRITICAL: This prevents multiple model loads which cause:
+ * - Test timeouts
+ * - Memory bloat
+ * - Performance degradation
+ * - ONNX runtime conflicts
+ */
+declare class ModelManager {
+    private static instance;
+    private primaryModel;
+    private modelPromise;
+    private isInitialized;
+    private constructor();
+    static getInstance(): ModelManager;
+    /**
+     * Get the primary embedding model - LOADS ONCE, REUSES FOREVER
+     */
+    getPrimaryModel(): Promise<TransformerEmbedding>;
+    /**
+     * Initialize the primary model ONCE - WORKS IN ALL ENVIRONMENTS
+     */
+    private initializePrimaryModel;
+    /**
+     * Get embedding function that reuses the singleton model
+     */
+    getEmbeddingFunction(): Promise<EmbeddingFunction>;
+    /**
+     * Check if model is ready (loaded and initialized)
+     */
+    isModelReady(): boolean;
+    /**
+     * Force model reload (for testing or recovery)
+     */
+    reloadModel(): Promise<void>;
+    /**
+     * Get model status for debugging
+     */
+    getModelStatus(): {
+        loaded: boolean;
+        ready: boolean;
+        modelType: string;
+    };
+    /**
+     * Cleanup method for testing
+     */
+    cleanup(): void;
+}
+export declare const modelManager: ModelManager;
+/**
+ * Get the singleton embedding function - USE THIS EVERYWHERE!
+ */
+export declare function getSingletonEmbeddingFunction(): Promise<EmbeddingFunction>;
+/**
+ * Optimized default embedding function that reuses singleton model
+ */
+export declare const optimizedDefaultEmbeddingFunction: EmbeddingFunction;
+/**
+ * Preload model for tests or production - CALL THIS ONCE AT START
+ */
+export declare function preloadModel(): Promise<void>;
+/**
+ * Get model readiness status
+ */
+export declare function isModelReady(): boolean;
+export {};

package/dist/utils/modelManager.js

@@ -0,0 +1,219 @@
+/**
+ * Model Manager - CRITICAL SINGLETON for preventing multiple model loads
+ *
+ * This ensures that ONNX/Transformer models are loaded ONCE and reused across:
+ * - All BrainyData instances
+ * - All test cases
+ * - All embedding operations
+ * - Neural intelligence operations
+ */
+import { TransformerEmbedding } from './embedding.js';
+/**
+ * Global singleton model manager
+ * CRITICAL: This prevents multiple model loads which cause:
+ * - Test timeouts
+ * - Memory bloat
+ * - Performance degradation
+ * - ONNX runtime conflicts
+ */
+class ModelManager {
+    constructor() {
+        this.primaryModel = null;
+        this.modelPromise = null;
+        this.isInitialized = false;
+    }
+    static getInstance() {
+        if (!ModelManager.instance) {
+            ModelManager.instance = new ModelManager();
+        }
+        return ModelManager.instance;
+    }
+    /**
+     * Get the primary embedding model - LOADS ONCE, REUSES FOREVER
+     */
+    async getPrimaryModel() {
+        // If already initialized, return immediately
+        if (this.primaryModel && this.isInitialized) {
+            return this.primaryModel;
+        }
+        // If initialization is in progress, wait for it
+        if (this.modelPromise) {
+            return await this.modelPromise;
+        }
+        // Start initialization
+        this.modelPromise = this.initializePrimaryModel();
+        return await this.modelPromise;
+    }
+    /**
+     * Initialize the primary model ONCE - WORKS IN ALL ENVIRONMENTS
+     */
+    async initializePrimaryModel() {
+        try {
+            // Environment detection for optimal configuration
+            const isTest = globalThis.__BRAINY_TEST_ENV__ || process.env.NODE_ENV === 'test';
+            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 isDocker = typeof process !== 'undefined' && (process.env.DOCKER_CONTAINER ||
+                process.env.KUBERNETES_SERVICE_HOST);
+            // Smart configuration based on environment
+            let options = {
+                verbose: !isTest && !isServerless, // Quiet in tests and serverless
+                dtype: 'q8', // Balanced performance/size
+                device: 'cpu' // Most compatible across all environments
+            };
+            // Environment-specific optimizations
+            if (isBrowser) {
+                // Browser: Prioritize compatibility and size
+                options = {
+                    ...options,
+                    localFilesOnly: false, // Allow CDN downloads
+                    dtype: 'q8', // Smaller models for bandwidth
+                    device: 'cpu', // WebGPU support varies widely
+                    verbose: false // Never verbose in browser
+                };
+            }
+            else if (isServerless) {
+                // Serverless: Prioritize cold start performance
+                options = {
+                    ...options,
+                    localFilesOnly: true, // Assume models are pre-deployed
+                    dtype: 'q8', // Faster loading
+                    device: 'cpu', // Consistent across platforms
+                    verbose: false // No console noise in serverless
+                };
+            }
+            else if (isDocker) {
+                // Docker: Assume models are in container
+                options = {
+                    ...options,
+                    localFilesOnly: true, // Models should be baked in
+                    dtype: 'fp32', // Use full precision if available
+                    device: 'auto', // Let it detect GPU in container
+                    verbose: false // Quiet for container logs
+                };
+            }
+            else if (isTest) {
+                // Test: Optimize for reliability and speed
+                options = {
+                    ...options,
+                    localFilesOnly: false, // Allow downloads in development
+                    dtype: 'q8', // Faster test execution
+                    device: 'cpu', // Consistent test results
+                    verbose: false // Clean test output
+                };
+            }
+            else {
+                // Development/Production Node.js: Full features
+                options = {
+                    ...options,
+                    localFilesOnly: false, // Allow downloads
+                    dtype: 'q8', // Good balance
+                    device: 'auto', // Use best available
+                    verbose: true // Helpful for development
+                };
+            }
+            // Graceful logging based on environment
+            const environmentName = isBrowser ? 'browser' :
+                isServerless ? 'serverless' :
+                    isDocker ? 'container' :
+                        isTest ? 'test' : 'node';
+            if (options.verbose) {
+                console.log(`🧠 Loading embedding model (${environmentName} mode)...`);
+            }
+            this.primaryModel = new TransformerEmbedding(options);
+            await this.primaryModel.init();
+            this.isInitialized = true;
+            this.modelPromise = null; // Clear the promise
+            if (options.verbose) {
+                console.log(`✅ Embedding model loaded successfully in ${environmentName} environment`);
+            }
+            return this.primaryModel;
+        }
+        catch (error) {
+            this.modelPromise = null; // Clear failed promise
+            // Enhanced error reporting with environment context
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const environmentInfo = typeof window !== 'undefined' ? 'browser' :
+                typeof process !== 'undefined' ? `node (${process.version})` : 'unknown';
+            throw new Error(`Failed to initialize embedding model in ${environmentInfo} environment: ${errorMessage}. ` +
+                `This is critical for all Brainy operations. Please check model availability and network connectivity.`);
+        }
+    }
+    /**
+     * Get embedding function that reuses the singleton model
+     */
+    async getEmbeddingFunction() {
+        const model = await this.getPrimaryModel();
+        return async (data) => {
+            return await model.embed(data);
+        };
+    }
+    /**
+     * Check if model is ready (loaded and initialized)
+     */
+    isModelReady() {
+        return this.isInitialized && this.primaryModel !== null;
+    }
+    /**
+     * Force model reload (for testing or recovery)
+     */
+    async reloadModel() {
+        this.primaryModel = null;
+        this.isInitialized = false;
+        this.modelPromise = null;
+        await this.getPrimaryModel();
+    }
+    /**
+     * Get model status for debugging
+     */
+    getModelStatus() {
+        return {
+            loaded: this.primaryModel !== null,
+            ready: this.isInitialized,
+            modelType: 'TransformerEmbedding (ONNX)'
+        };
+    }
+    /**
+     * Cleanup method for testing
+     */
+    cleanup() {
+        // Note: We don't actually destroy the model in cleanup
+        // because other parts of the system might still be using it
+        // This is mainly for status reset
+        console.log('🧹 Model manager cleanup requested (model remains loaded)');
+    }
+}
+ModelManager.instance = null;
+// Export singleton instance
+export const modelManager = ModelManager.getInstance();
+/**
+ * Get the singleton embedding function - USE THIS EVERYWHERE!
+ */
+export async function getSingletonEmbeddingFunction() {
+    return await modelManager.getEmbeddingFunction();
+}
+/**
+ * Optimized default embedding function that reuses singleton model
+ */
+export const optimizedDefaultEmbeddingFunction = async (data) => {
+    const embeddingFn = await getSingletonEmbeddingFunction();
+    return await embeddingFn(data);
+};
+/**
+ * Preload model for tests or production - CALL THIS ONCE AT START
+ */
+export async function preloadModel() {
+    console.log('🚀 Preloading embedding model...');
+    await modelManager.getPrimaryModel();
+    console.log('✅ Model preloaded and ready!');
+}
+/**
+ * Get model readiness status
+ */
+export function isModelReady() {
+    return modelManager.isModelReady();
+}
+//# sourceMappingURL=modelManager.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Multi-Dimensional AI Database - Vector similarity, graph relationships, metadata facets with HNSW indexing and OPFS storage",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -142,7 +142,10 @@
     "_workflow:major": "node scripts/release-workflow.js major",
     "_workflow:dry-run": "npm run build && npm test && npm run _release:dry-run",
     "_dry-run": "npm pack --dry-run",
-    "download-models": "node scripts/download-models.cjs"
+    "download-models": "node scripts/download-models.cjs",
+    "prepare-models": "node scripts/prepare-models.js",
+    "models:verify": "node scripts/ensure-models.js",
+    "models:download": "BRAINY_ALLOW_REMOTE_MODELS=true node scripts/download-models.cjs"
   },
   "keywords": [
     "vector-database",