@soulcraft/brainy 6.5.0 → 6.6.0

package/dist/embeddings/EmbeddingManager.js

@@ -2,39 +2,34 @@
  * Unified Embedding Manager
  *
  * THE single source of truth for all embedding operations in Brainy.
- * Combines model management, precision configuration, and embedding generation
- * into one clean, maintainable class.
+ * Uses direct ONNX WASM inference for universal compatibility.
  *
  * Features:
  * - Singleton pattern ensures ONE model instance
- * - Automatic Q8 (default) or FP32 precision
- * - Model downloading and caching
- * - Thread-safe initialization
+ * - Direct ONNX WASM (no transformers.js dependency)
+ * - Bundled model (no runtime downloads)
+ * - Works everywhere: Node.js, Bun, Bun --compile, browsers
  * - Memory monitoring
- *
- * This replaces: SingletonModelManager, TransformerEmbedding, ModelPrecisionManager,
- * hybridModelManager, universalMemoryManager, and more.
  */
-import { pipeline, env } from '@huggingface/transformers';
-import { isNode } from '../utils/environment.js';
+import { WASMEmbeddingEngine } from './wasm/index.js';
 // Global state for true singleton across entire process
 let globalInstance = null;
 let globalInitPromise = null;
 /**
  * Unified Embedding Manager - Clean, simple, reliable
+ *
+ * Now powered by direct ONNX WASM for universal compatibility.
  */
 export class EmbeddingManager {
     constructor() {
-        this.model = null;
-        this.modelName = 'Xenova/all-MiniLM-L6-v2';
+        this.precision = 'q8';
+        this.modelName = 'all-MiniLM-L6-v2';
         this.initialized = false;
         this.initTime = null;
         this.embedCount = 0;
         this.locked = false;
-        this.modelsPathCache = null;
-        // Always use Q8 for optimal size/performance (99% accuracy, 75% smaller)
-        this.precision = 'q8';
-        console.log(`🎯 EmbeddingManager: Using Q8 precision`);
+        this.engine = WASMEmbeddingEngine.getInstance();
+        console.log('🎯 EmbeddingManager: Using Q8 precision (WASM)');
     }
     /**
      * Get the singleton instance
@@ -50,9 +45,10 @@ export class EmbeddingManager {
      */
     async init() {
         // In unit test mode, skip real model initialization
-        const isTestMode = process.env.BRAINY_UNIT_TEST === 'true' || globalThis.__BRAINY_UNIT_TEST__;
+        const isTestMode = process.env.BRAINY_UNIT_TEST === 'true' ||
+            globalThis.__BRAINY_UNIT_TEST__;
         if (isTestMode) {
-            // Production safeguard: Warn if mock mode is active but NODE_ENV is production
+            // Production safeguard
             if (process.env.NODE_ENV === 'production') {
                 throw new Error('CRITICAL: Mock embeddings detected in production environment! ' +
                     'BRAINY_UNIT_TEST or __BRAINY_UNIT_TEST__ is set while NODE_ENV=production. ' +
@@ -66,7 +62,7 @@ export class EmbeddingManager {
             return;
         }
         // Already initialized
-        if (this.initialized && this.model) {
+        if (this.initialized && this.engine.isInitialized()) {
             return;
         }
         // Initialization in progress
@@ -88,62 +84,20 @@ export class EmbeddingManager {
      */
     async performInit() {
         const startTime = Date.now();
-        console.log(`🚀 Initializing embedding model (${this.precision.toUpperCase()})...`);
         try {
-            // Configure transformers.js environment
-            const modelsPath = this.getModelsPath();
-            env.cacheDir = modelsPath;
-            env.allowLocalModels = true;
-            env.useFSCache = true;
-            // Check if models exist locally (only in Node.js)
-            if (isNode()) {
-                try {
-                    const nodeRequire = typeof require !== 'undefined' ? require : null;
-                    if (nodeRequire) {
-                        const path = nodeRequire('node:path');
-                        const fs = nodeRequire('node:fs');
-                        const modelPath = path.join(modelsPath, ...this.modelName.split('/'));
-                        const hasLocalModels = fs.existsSync(modelPath);
-                        if (hasLocalModels) {
-                            console.log('✅ Using cached models from:', modelPath);
-                        }
-                    }
-                }
-                catch {
-                    // Silently continue if require fails
-                }
-            }
-            // Configure pipeline options for the selected precision
-            const pipelineOptions = {
-                cache_dir: modelsPath,
-                local_files_only: false,
-                // Always use Q8 precision
-                dtype: 'q8',
-                quantized: true,
-                // Memory optimizations
-                session_options: {
-                    enableCpuMemArena: false,
-                    enableMemPattern: false,
-                    interOpNumThreads: 1,
-                    intraOpNumThreads: 1,
-                    graphOptimizationLevel: 'disabled'
-                }
-            };
-            // Load the model
-            this.model = await pipeline('feature-extraction', this.modelName, pipelineOptions);
+            // Initialize WASM engine (handles all model loading)
+            await this.engine.initialize();
             // Lock precision after successful initialization
             this.locked = true;
             this.initialized = true;
             this.initTime = Date.now() - startTime;
             // Log success
             const memoryMB = this.getMemoryUsage();
-            console.log(`✅ Model loaded in ${this.initTime}ms`);
             console.log(`📊 Precision: Q8 | Memory: ${memoryMB}MB`);
-            console.log(`🔒 Configuration locked`);
+            console.log('🔒 Configuration locked');
         }
         catch (error) {
             this.initialized = false;
-            this.model = null;
             throw new Error(`Failed to initialize embedding model: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
@@ -151,10 +105,10 @@ export class EmbeddingManager {
      * Generate embeddings
      */
     async embed(text) {
-        // Check for unit test environment - use mocks to prevent ONNX conflicts
-        const isTestMode = process.env.BRAINY_UNIT_TEST === 'true' || globalThis.__BRAINY_UNIT_TEST__;
+        // Check for unit test environment
+        const isTestMode = process.env.BRAINY_UNIT_TEST === 'true' ||
+            globalThis.__BRAINY_UNIT_TEST__;
         if (isTestMode) {
-            // Production safeguard
             if (process.env.NODE_ENV === 'production') {
                 throw new Error('CRITICAL: Mock embeddings in production!');
             }
@@ -162,38 +116,26 @@ export class EmbeddingManager {
         }
         // Ensure initialized
         await this.init();
-        if (!this.model) {
-            throw new Error('Model not initialized');
-        }
-        // CRITICAL FIX: Ensure input is always a string
+        // Normalize input to string
         let input;
         if (Array.isArray(text)) {
-            // Join array elements, converting each to string first
-            input = text.map(t => typeof t === 'string' ? t : String(t)).join(' ');
+            input = text.map((t) => (typeof t === 'string' ? t : String(t))).join(' ');
         }
         else if (typeof text === 'string') {
             input = text;
         }
         else if (typeof text === 'object') {
-            // Convert object to string representation
             input = JSON.stringify(text);
         }
         else {
-            // This shouldn't happen but let's be defensive
             console.warn('EmbeddingManager.embed received unexpected input type:', typeof text);
             input = String(text);
         }
-        // Generate embedding
-        const output = await this.model(input, {
-            pooling: 'mean',
-            normalize: true
-        });
-        // Extract embedding vector
-        const embedding = Array.from(output.data);
+        // Generate embedding using WASM engine
+        const embedding = await this.engine.embed(input);
         // Validate dimensions
         if (embedding.length !== 384) {
             console.warn(`Unexpected embedding dimension: ${embedding.length}`);
-            // Pad or truncate
             if (embedding.length < 384) {
                 return [...embedding, ...new Array(384 - embedding.length).fill(0)];
             }
@@ -208,7 +150,6 @@ export class EmbeddingManager {
      * Generate mock embeddings for unit tests
      */
     getMockEmbedding(text) {
-        // Use the same mock logic as setup-unit.ts for consistency
         const input = Array.isArray(text) ? text.join(' ') : text;
         const str = typeof input === 'string' ? input : JSON.stringify(input);
         const vector = new Array(384).fill(0);
@@ -220,7 +161,6 @@ export class EmbeddingManager {
         for (let i = 0; i < 384; i++) {
             vector[i] += Math.sin(i * 0.1 + str.length) * 0.1;
         }
-        // Track mock embedding count
         this.embedCount++;
         return vector;
     }
@@ -232,55 +172,6 @@ export class EmbeddingManager {
             return await this.embed(data);
         };
     }
-    /**
-     * Get models directory path
-     * Note: In browser environments, returns a simple default path
-     * In Node.js, checks multiple locations for the models directory
-     */
-    getModelsPath() {
-        // In browser environments, use a default path
-        if (!isNode()) {
-            return './models';
-        }
-        // Node.js-specific model path resolution
-        // Cache the result for performance
-        if (!this.modelsPathCache) {
-            this.modelsPathCache = this.resolveModelsPathSync();
-        }
-        return this.modelsPathCache;
-    }
-    resolveModelsPathSync() {
-        // For Node.js environments, we can safely assume these modules exist
-        // TypeScript will handle the imports at build time
-        // At runtime, these will only be called if isNode() is true
-        // Default fallback path
-        const defaultPath = './models';
-        try {
-            // Create a conditional require function that only works in Node
-            const nodeRequire = typeof require !== 'undefined' ? require : null;
-            if (!nodeRequire)
-                return defaultPath;
-            const fs = nodeRequire('node:fs');
-            const path = nodeRequire('node:path');
-            const paths = [
-                process.env.BRAINY_MODELS_PATH,
-                './models',
-                path.join(process.cwd(), 'models'),
-                path.join(process.env.HOME || '', '.brainy', 'models')
-            ];
-            for (const p of paths) {
-                if (p && fs.existsSync(p)) {
-                    return p;
-                }
-            }
-            // Default Node.js path
-            return path.join(process.cwd(), 'models');
-        }
-        catch {
-            // Fallback if require fails
-            return defaultPath;
-        }
-    }
     /**
      * Get memory usage in MB
      */
@@ -295,13 +186,14 @@ export class EmbeddingManager {
      * Get current statistics
      */
     getStats() {
+        const engineStats = this.engine.getStats();
         return {
             initialized: this.initialized,
             precision: this.precision,
             modelName: this.modelName,
-            embedCount: this.embedCount,
+            embedCount: this.embedCount + engineStats.embedCount,
             initTime: this.initTime,
-            memoryMB: this.getMemoryUsage()
+            memoryMB: this.getMemoryUsage(),
         };
     }
     /**

package/dist/embeddings/wasm/AssetLoader.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Asset Loader
+ *
+ * Resolves paths to model files (ONNX model, vocabulary) across environments.
+ * Handles Node.js, Bun, and bundled scenarios.
+ *
+ * Asset Resolution Order:
+ * 1. Environment variable: BRAINY_MODEL_PATH
+ * 2. Package-relative: node_modules/@soulcraft/brainy/assets/models/
+ * 3. Project-relative: ./assets/models/
+ */
+/**
+ * Asset loader for model files
+ */
+export declare class AssetLoader {
+    private modelDir;
+    /**
+     * Get the model directory path
+     */
+    getModelDir(): Promise<string>;
+    /**
+     * Resolve the model directory across environments
+     */
+    private resolveModelDir;
+    /**
+     * Get package root path (Node.js/Bun only)
+     */
+    private getPackageRootPath;
+    /**
+     * Check if path exists (works in Node.js/Bun)
+     */
+    private pathExists;
+    /**
+     * Get path to ONNX model file
+     */
+    getModelPath(): Promise<string>;
+    /**
+     * Get path to vocabulary file
+     */
+    getVocabPath(): Promise<string>;
+    /**
+     * Load vocabulary from JSON file
+     */
+    loadVocab(): Promise<Record<string, number>>;
+    /**
+     * Load model as ArrayBuffer (for ONNX session)
+     */
+    loadModel(): Promise<ArrayBuffer>;
+    /**
+     * Verify all required assets exist
+     */
+    verifyAssets(): Promise<{
+        valid: boolean;
+        modelPath: string;
+        vocabPath: string;
+        errors: string[];
+    }>;
+    /**
+     * Clear cached paths (for testing)
+     */
+    clearCache(): void;
+}
+/**
+ * Create asset loader instance
+ */
+export declare function createAssetLoader(): AssetLoader;
+export declare function getAssetLoader(): AssetLoader;

package/dist/embeddings/wasm/AssetLoader.js

@@ -0,0 +1,238 @@
+/**
+ * Asset Loader
+ *
+ * Resolves paths to model files (ONNX model, vocabulary) across environments.
+ * Handles Node.js, Bun, and bundled scenarios.
+ *
+ * Asset Resolution Order:
+ * 1. Environment variable: BRAINY_MODEL_PATH
+ * 2. Package-relative: node_modules/@soulcraft/brainy/assets/models/
+ * 3. Project-relative: ./assets/models/
+ */
+import { MODEL_CONSTANTS } from './types.js';
+// Cache resolved paths
+let cachedModelDir = null;
+let cachedVocab = null;
+/**
+ * Asset loader for model files
+ */
+export class AssetLoader {
+    constructor() {
+        this.modelDir = null;
+    }
+    /**
+     * Get the model directory path
+     */
+    async getModelDir() {
+        if (this.modelDir) {
+            return this.modelDir;
+        }
+        if (cachedModelDir) {
+            this.modelDir = cachedModelDir;
+            return cachedModelDir;
+        }
+        // Try to resolve model directory
+        const resolved = await this.resolveModelDir();
+        this.modelDir = resolved;
+        cachedModelDir = resolved;
+        return resolved;
+    }
+    /**
+     * Resolve the model directory across environments
+     */
+    async resolveModelDir() {
+        // 1. Check environment variable
+        if (typeof process !== 'undefined' && process.env?.BRAINY_MODEL_PATH) {
+            const envPath = process.env.BRAINY_MODEL_PATH;
+            if (await this.pathExists(envPath)) {
+                return envPath;
+            }
+        }
+        // 2. Try common locations
+        const modelName = MODEL_CONSTANTS.MODEL_NAME + '-q8';
+        const possiblePaths = [
+            // Package assets (when installed as dependency)
+            `./assets/models/${modelName}`,
+            `./node_modules/@soulcraft/brainy/assets/models/${modelName}`,
+            // Development paths
+            `../assets/models/${modelName}`,
+            // Absolute from package root
+            this.getPackageRootPath(`assets/models/${modelName}`),
+        ].filter(Boolean);
+        for (const path of possiblePaths) {
+            if (await this.pathExists(path)) {
+                return path;
+            }
+        }
+        // If no path found, return default (will error on use)
+        return `./assets/models/${modelName}`;
+    }
+    /**
+     * Get package root path (Node.js/Bun only)
+     */
+    getPackageRootPath(relativePath) {
+        if (typeof process === 'undefined') {
+            return null;
+        }
+        try {
+            // Use __dirname equivalent
+            const url = new URL(import.meta.url);
+            const currentDir = url.pathname.replace(/\/[^/]*$/, '');
+            // Go up from src/embeddings/wasm to package root
+            const packageRoot = currentDir.replace(/\/src\/embeddings\/wasm$/, '');
+            return `${packageRoot}/${relativePath}`;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Check if path exists (works in Node.js/Bun)
+     */
+    async pathExists(path) {
+        if (typeof process === 'undefined') {
+            // Browser - check via fetch
+            try {
+                const response = await fetch(path, { method: 'HEAD' });
+                return response.ok;
+            }
+            catch {
+                return false;
+            }
+        }
+        // Node.js/Bun
+        try {
+            const fs = await import('node:fs/promises');
+            await fs.access(path);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Get path to ONNX model file
+     */
+    async getModelPath() {
+        const dir = await this.getModelDir();
+        return `${dir}/model.onnx`;
+    }
+    /**
+     * Get path to vocabulary file
+     */
+    async getVocabPath() {
+        const dir = await this.getModelDir();
+        return `${dir}/vocab.json`;
+    }
+    /**
+     * Load vocabulary from JSON file
+     */
+    async loadVocab() {
+        if (cachedVocab) {
+            return cachedVocab;
+        }
+        const vocabPath = await this.getVocabPath();
+        if (typeof process !== 'undefined') {
+            // Node.js/Bun - read from filesystem
+            try {
+                const fs = await import('node:fs/promises');
+                const content = await fs.readFile(vocabPath, 'utf-8');
+                cachedVocab = JSON.parse(content);
+                return cachedVocab;
+            }
+            catch (error) {
+                throw new Error(`Failed to load vocabulary from ${vocabPath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        else {
+            // Browser - fetch
+            try {
+                const response = await fetch(vocabPath);
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                cachedVocab = await response.json();
+                return cachedVocab;
+            }
+            catch (error) {
+                throw new Error(`Failed to fetch vocabulary from ${vocabPath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    /**
+     * Load model as ArrayBuffer (for ONNX session)
+     */
+    async loadModel() {
+        const modelPath = await this.getModelPath();
+        if (typeof process !== 'undefined') {
+            // Node.js/Bun - read from filesystem
+            try {
+                const fs = await import('node:fs/promises');
+                const buffer = await fs.readFile(modelPath);
+                // Convert Node.js Buffer to ArrayBuffer
+                return new Uint8Array(buffer).buffer;
+            }
+            catch (error) {
+                throw new Error(`Failed to load model from ${modelPath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        else {
+            // Browser - fetch
+            try {
+                const response = await fetch(modelPath);
+                if (!response.ok) {
+                    throw new Error(`HTTP ${response.status}`);
+                }
+                return await response.arrayBuffer();
+            }
+            catch (error) {
+                throw new Error(`Failed to fetch model from ${modelPath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    /**
+     * Verify all required assets exist
+     */
+    async verifyAssets() {
+        const errors = [];
+        const modelPath = await this.getModelPath();
+        const vocabPath = await this.getVocabPath();
+        if (!(await this.pathExists(modelPath))) {
+            errors.push(`Model file not found: ${modelPath}`);
+        }
+        if (!(await this.pathExists(vocabPath))) {
+            errors.push(`Vocabulary file not found: ${vocabPath}`);
+        }
+        return {
+            valid: errors.length === 0,
+            modelPath,
+            vocabPath,
+            errors,
+        };
+    }
+    /**
+     * Clear cached paths (for testing)
+     */
+    clearCache() {
+        this.modelDir = null;
+        cachedModelDir = null;
+        cachedVocab = null;
+    }
+}
+/**
+ * Create asset loader instance
+ */
+export function createAssetLoader() {
+    return new AssetLoader();
+}
+/**
+ * Singleton asset loader
+ */
+let singletonLoader = null;
+export function getAssetLoader() {
+    if (!singletonLoader) {
+        singletonLoader = new AssetLoader();
+    }
+    return singletonLoader;
+}
+//# sourceMappingURL=AssetLoader.js.map

package/dist/embeddings/wasm/EmbeddingPostProcessor.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Embedding Post-Processor
+ *
+ * Converts raw ONNX model output to final embedding vectors.
+ * Implements mean pooling and L2 normalization as used by sentence-transformers.
+ *
+ * Pipeline:
+ * 1. Mean Pooling: Average token embeddings (weighted by attention mask)
+ * 2. L2 Normalization: Normalize to unit length for cosine similarity
+ */
+/**
+ * Post-processor for converting ONNX output to sentence embeddings
+ */
+export declare class EmbeddingPostProcessor {
+    private hiddenSize;
+    constructor(hiddenSize?: number);
+    /**
+     * Mean pool token embeddings weighted by attention mask
+     *
+     * @param hiddenStates - Raw model output [seqLen * hiddenSize] flattened
+     * @param attentionMask - Attention mask [seqLen] (1 for real tokens, 0 for padding)
+     * @param seqLen - Sequence length
+     * @returns Mean-pooled embedding [hiddenSize]
+     */
+    meanPool(hiddenStates: Float32Array, attentionMask: number[], seqLen: number): Float32Array;
+    /**
+     * L2 normalize embedding to unit length
+     *
+     * @param embedding - Input embedding
+     * @returns Normalized embedding with ||x|| = 1
+     */
+    normalize(embedding: Float32Array): Float32Array;
+    /**
+     * Full post-processing pipeline: mean pool then normalize
+     *
+     * @param hiddenStates - Raw model output [seqLen * hiddenSize]
+     * @param attentionMask - Attention mask [seqLen]
+     * @param seqLen - Sequence length
+     * @returns Final normalized embedding [hiddenSize]
+     */
+    process(hiddenStates: Float32Array, attentionMask: number[], seqLen: number): Float32Array;
+    /**
+     * Process batch of embeddings
+     *
+     * @param hiddenStates - Raw model output [batchSize * seqLen * hiddenSize]
+     * @param attentionMasks - Attention masks [batchSize][seqLen]
+     * @param batchSize - Number of sequences in batch
+     * @param seqLen - Sequence length (same for all in batch due to padding)
+     * @returns Array of normalized embeddings
+     */
+    processBatch(hiddenStates: Float32Array, attentionMasks: number[][], batchSize: number, seqLen: number): Float32Array[];
+    /**
+     * Convert Float32Array to number array
+     */
+    toNumberArray(embedding: Float32Array): number[];
+}
+/**
+ * Create a post-processor with default configuration
+ */
+export declare function createPostProcessor(): EmbeddingPostProcessor;