@soulcraft/brainy 2.8.0 → 2.10.0

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

@@ -107,7 +107,7 @@ export class UniversalMemoryManager {
             const { TransformerEmbedding } = await import('../utils/embedding.js');
             this.embeddingFunction = new TransformerEmbedding({
                 verbose: false,
-                dtype: 'fp32',
+                precision: 'fp32',
                 localFilesOnly: process.env.BRAINY_ALLOW_REMOTE_MODELS !== 'true'
             });
             await this.embeddingFunction.init();

package/dist/embeddings/worker-embedding.js

@@ -13,7 +13,7 @@ async function initModel() {
     if (!model) {
         model = new TransformerEmbedding({
             verbose: false,
-            dtype: 'fp32',
+            precision: 'fp32',
             localFilesOnly: process.env.BRAINY_ALLOW_REMOTE_MODELS !== 'true'
         });
         await model.init();

package/dist/index.d.ts

@@ -11,6 +11,7 @@
 import { BrainyData, BrainyDataConfig } from './brainyData.js';
 export { BrainyData };
 export type { BrainyDataConfig };
+export { PresetName, ModelPrecision, StorageOption, FeatureSet, DistributedRole, PresetCategory, BrainyZeroConfig, StorageProvider, registerStorageAugmentation, registerPresetAugmentation, getPreset, isValidPreset, getPresetsByCategory, getAllPresetNames, getPresetDescription } from './config/index.js';
 export { Cortex, cortex } from './cortex.js';
 export { NeuralImport } from './cortex/neuralImport.js';
 export type { NeuralAnalysisResult, DetectedEntity, DetectedRelationship, NeuralInsight, NeuralImportOptions } from './cortex/neuralImport.js';

package/dist/index.js

@@ -11,6 +11,22 @@
 // Export main BrainyData class and related types
 import { BrainyData } from './brainyData.js';
 export { BrainyData };
+// Export zero-configuration types and enums
+export { 
+// Preset names
+PresetName, 
+// Model configuration
+ModelPrecision, 
+// Storage configuration  
+StorageOption, 
+// Feature configuration
+FeatureSet, 
+// Distributed roles
+DistributedRole, 
+// Categories
+PresetCategory, registerStorageAugmentation, registerPresetAugmentation, 
+// Preset utilities
+getPreset, isValidPreset, getPresetsByCategory, getAllPresetNames, getPresetDescription } from './config/index.js';
 // Export Cortex (the orchestrator)
 export { Cortex, cortex } from './cortex.js';
 // Export Neural Import (AI data understanding)

package/dist/utils/embedding.d.ts

@@ -25,8 +25,8 @@ export interface TransformerEmbeddingOptions {
     cacheDir?: string;
     /** Force local files only (no downloads) */
     localFilesOnly?: boolean;
-    /** Quantization setting (fp32, fp16, q8, q4) */
-    dtype?: 'fp32' | 'fp16' | 'q8' | 'q4';
+    /** Model precision: 'q8' = 75% smaller quantized model, 'fp32' = full precision (default) */
+    precision?: 'fp32' | 'q8';
     /** Device to run inference on - 'auto' detects best available */
     device?: 'auto' | 'cpu' | 'webgpu' | 'cuda' | 'gpu';
 }

package/dist/utils/embedding.js

@@ -4,6 +4,8 @@
  */
 import { isBrowser } from './environment.js';
 import { ModelManager } from '../embeddings/model-manager.js';
+import { join } from 'path';
+import { existsSync } from 'fs';
 // @ts-ignore - Transformers.js is now the primary embedding library
 import { pipeline, env } from '@huggingface/transformers';
 // CRITICAL: Disable ONNX memory arena to prevent 4-8GB allocation
@@ -11,9 +13,10 @@ import { pipeline, env } from '@huggingface/transformers';
 if (typeof process !== 'undefined' && process.env) {
     process.env.ORT_DISABLE_MEMORY_ARENA = '1';
     process.env.ORT_DISABLE_MEMORY_PATTERN = '1';
-    // Also limit ONNX thread count for more predictable memory usage
-    process.env.ORT_INTRA_OP_NUM_THREADS = '2';
-    process.env.ORT_INTER_OP_NUM_THREADS = '2';
+    // Force single-threaded operation for maximum stability (Node.js 24 compatibility)
+    process.env.ORT_INTRA_OP_NUM_THREADS = '1'; // Single thread for operators
+    process.env.ORT_INTER_OP_NUM_THREADS = '1'; // Single thread for sessions
+    process.env.ORT_NUM_THREADS = '1'; // Additional safety override
 }
 /**
  * Detect the best available GPU device for the current environment
@@ -77,7 +80,7 @@ export class TransformerEmbedding {
             localFilesOnly = options.localFilesOnly;
         }
         else if (process.env.BRAINY_ALLOW_REMOTE_MODELS === 'false') {
-            // 2. Environment variable explicitly disables remote models
+            // 2. Environment variable explicitly disables remote models (legacy support)
             localFilesOnly = true;
         }
         else if (process.env.NODE_ENV === 'development') {
@@ -98,11 +101,11 @@ export class TransformerEmbedding {
             verbose: this.verbose,
             cacheDir: options.cacheDir || './models',
             localFilesOnly: localFilesOnly,
-            dtype: options.dtype || 'fp32', // CRITICAL: fp32 default for backward compatibility
+            precision: options.precision || 'fp32', // Clean and clear!
             device: options.device || 'auto'
         };
         // ULTRA-CAREFUL: Runtime warnings for q8 usage
-        if (this.options.dtype === 'q8') {
+        if (this.options.precision === 'q8') {
             const confirmed = process.env.BRAINY_Q8_CONFIRMED === 'true';
             if (!confirmed && this.verbose) {
                 console.warn('🚨 Q8 MODEL WARNING:');
@@ -114,7 +117,7 @@ export class TransformerEmbedding {
             }
         }
         if (this.verbose) {
-            this.logger('log', `Embedding config: dtype=${this.options.dtype}, localFilesOnly=${localFilesOnly}, model=${this.options.model}`);
+            this.logger('log', `Embedding config: precision=${this.options.precision}, localFilesOnly=${localFilesOnly}, model=${this.options.model}`);
         }
         // Configure transformers.js environment
         if (!isBrowser()) {
@@ -226,25 +229,40 @@ export class TransformerEmbedding {
             const startTime = Date.now();
             // Check model availability and select appropriate variant
             const available = modelManager.getAvailableModels(this.options.model);
-            const actualType = modelManager.getBestAvailableModel(this.options.dtype, this.options.model);
+            let actualType = modelManager.getBestAvailableModel(this.options.precision, this.options.model);
             if (!actualType) {
                 throw new Error(`No model variants available for ${this.options.model}. Run 'npm run download-models' to download models.`);
             }
-            if (actualType !== this.options.dtype) {
-                this.logger('log', `Using ${actualType} model (${this.options.dtype} not available)`);
+            if (actualType !== this.options.precision) {
+                this.logger('log', `Using ${actualType} model (${this.options.precision} not available)`);
+            }
+            // CRITICAL FIX: Control which model file transformers.js loads
+            // When both model.onnx and model_quantized.onnx exist, transformers.js defaults to model.onnx
+            // We need to explicitly control this based on the precision setting
+            // Set environment to control model selection BEFORE creating pipeline
+            if (actualType === 'q8') {
+                // For Q8, we want to use the quantized model
+                // transformers.js v3 doesn't have a direct flag, so we need to work around this
+                // HACK: Temporarily modify the model file preference
+                // This forces transformers.js to look for model_quantized.onnx first
+                const originalModelFileName = env.onnxModelFileName(env).onnxModelFileName = 'model_quantized';
+                this.logger('log', '🎯 Selecting Q8 quantized model (75% smaller)');
+            }
+            else {
+                this.logger('log', '📦 Using FP32 model (full precision)');
             }
             // Load the feature extraction pipeline with memory optimizations
             const pipelineOptions = {
                 cache_dir: cacheDir,
                 local_files_only: isBrowser() ? false : this.options.localFilesOnly,
-                dtype: actualType, // Use the actual available model type
+                // Remove the quantized flag - it doesn't work in transformers.js v3
                 // CRITICAL: ONNX memory optimizations
                 session_options: {
                     enableCpuMemArena: false, // Disable pre-allocated memory arena
                     enableMemPattern: false, // Disable memory pattern optimization
-                    interOpNumThreads: 2, // Limit thread count
-                    intraOpNumThreads: 2, // Limit parallelism
-                    graphOptimizationLevel: 'all'
+                    interOpNumThreads: 1, // Force single thread for V8 stability
+                    intraOpNumThreads: 1, // Force single thread for V8 stability
+                    graphOptimizationLevel: 'disabled' // Disable threading optimizations
                 }
             };
             // Add device configuration for GPU acceleration
@@ -256,6 +274,18 @@ export class TransformerEmbedding {
                 this.logger('log', `Pipeline options: ${JSON.stringify(pipelineOptions)}`);
             }
             try {
+                // For Q8 models, we need to explicitly specify the model file
+                if (actualType === 'q8') {
+                    // Check if quantized model exists
+                    const modelPath = join(cacheDir, this.options.model, 'onnx', 'model_quantized.onnx');
+                    if (existsSync(modelPath)) {
+                        this.logger('log', '✅ Q8 model found locally');
+                    }
+                    else {
+                        this.logger('warn', '⚠️ Q8 model not found, will fall back to FP32');
+                        actualType = 'fp32'; // Fall back to fp32
+                    }
+                }
                 this.extractor = await pipeline('feature-extraction', this.options.model, pipelineOptions);
             }
             catch (gpuError) {
@@ -282,8 +312,8 @@ export class TransformerEmbedding {
                             // Both local and remote failed - throw comprehensive error
                             const errorMsg = `Failed to load embedding model "${this.options.model}". ` +
                                 `Local models not found and remote download failed. ` +
-                                `To fix: 1) Set BRAINY_ALLOW_REMOTE_MODELS=true, ` +
-                                `2) Run "npm run download-models", or ` +
+                                `To fix: 1) Run "npm run download-models", ` +
+                                `2) Check your internet connection, or ` +
                                 `3) Use a custom embedding function.`;
                             throw new Error(errorMsg);
                         }

package/dist/utils/hybridModelManager.js

@@ -83,7 +83,7 @@ class HybridModelManager {
             // Smart configuration based on environment
             let options = {
                 verbose: !isTest && !isServerless,
-                dtype: 'fp32',
+                precision: 'fp32', // Use clearer precision parameter
                 device: 'cpu'
             };
             // Environment-specific optimizations
@@ -91,7 +91,7 @@ class HybridModelManager {
                 options = {
                     ...options,
                     localFilesOnly: forceLocalOnly || false, // Respect environment variable
-                    dtype: 'fp32',
+                    precision: 'fp32',
                     device: 'cpu',
                     verbose: false
                 };
@@ -100,7 +100,7 @@ class HybridModelManager {
                 options = {
                     ...options,
                     localFilesOnly: forceLocalOnly || true, // Default true for serverless, but respect env
-                    dtype: 'fp32',
+                    precision: 'fp32',
                     device: 'cpu',
                     verbose: false
                 };
@@ -109,7 +109,7 @@ class HybridModelManager {
                 options = {
                     ...options,
                     localFilesOnly: forceLocalOnly || true, // Default true for docker, but respect env
-                    dtype: 'fp32',
+                    precision: 'fp32',
                     device: 'auto',
                     verbose: false
                 };
@@ -119,7 +119,7 @@ class HybridModelManager {
                 options = {
                     ...options,
                     localFilesOnly: forceLocalOnly || false, // Respect environment variable for tests
-                    dtype: 'fp32',
+                    precision: 'fp32',
                     device: 'cpu',
                     verbose: false
                 };
@@ -128,7 +128,7 @@ class HybridModelManager {
                 options = {
                     ...options,
                     localFilesOnly: forceLocalOnly || false, // Respect environment variable for default node
-                    dtype: 'fp32',
+                    precision: 'fp32',
                     device: 'auto',
                     verbose: true
                 };
@@ -168,7 +168,7 @@ class HybridModelManager {
             // 2. If that fails, explicitly allow remote with verbose logging
             { ...options, localFilesOnly: false, verbose: true, source: 'fallback-verbose' },
             // 3. Last resort: basic configuration
-            { verbose: false, dtype: 'fp32', device: 'cpu', localFilesOnly: false, source: 'last-resort' }
+            { verbose: false, precision: 'fp32', device: 'cpu', localFilesOnly: false, source: 'last-resort' }
         ];
         let lastError = null;
         for (const attemptOptions of attempts) {

package/dist/utils/nodeVersionCheck.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Node.js Version Compatibility Check
+ *
+ * Brainy requires Node.js 22.x LTS for maximum stability with ONNX Runtime.
+ * This prevents V8 HandleScope locking issues in worker threads.
+ */
+export interface VersionInfo {
+    current: string;
+    major: number;
+    isSupported: boolean;
+    recommendation: string;
+}
+/**
+ * Check if the current Node.js version is supported
+ */
+export declare function checkNodeVersion(): VersionInfo;
+/**
+ * Enforce Node.js version requirement with helpful error messaging
+ */
+export declare function enforceNodeVersion(): void;
+/**
+ * Soft warning for version issues (non-blocking)
+ */
+export declare function warnNodeVersion(): boolean;

package/dist/utils/nodeVersionCheck.js

@@ -0,0 +1,65 @@
+/**
+ * Node.js Version Compatibility Check
+ *
+ * Brainy requires Node.js 22.x LTS for maximum stability with ONNX Runtime.
+ * This prevents V8 HandleScope locking issues in worker threads.
+ */
+/**
+ * Check if the current Node.js version is supported
+ */
+export function checkNodeVersion() {
+    const nodeVersion = process.version;
+    const majorVersion = parseInt(nodeVersion.split('.')[0].substring(1));
+    const versionInfo = {
+        current: nodeVersion,
+        major: majorVersion,
+        isSupported: majorVersion === 22,
+        recommendation: 'Node.js 22.x LTS'
+    };
+    return versionInfo;
+}
+/**
+ * Enforce Node.js version requirement with helpful error messaging
+ */
+export function enforceNodeVersion() {
+    const versionInfo = checkNodeVersion();
+    if (!versionInfo.isSupported) {
+        const errorMessage = [
+            '🚨 BRAINY COMPATIBILITY ERROR',
+            '━'.repeat(50),
+            `❌ Current Node.js: ${versionInfo.current}`,
+            `✅ Required: ${versionInfo.recommendation}`,
+            '',
+            '💡 Quick Fix:',
+            '  nvm install 22 && nvm use 22',
+            '  npm install',
+            '',
+            '📖 Why Node.js 22?',
+            '  • Maximum ONNX Runtime stability',
+            '  • Prevents V8 threading crashes',
+            '  • Optimal zero-config performance',
+            '',
+            '🔗 More info: https://github.com/soulcraftlabs/brainy#node-version',
+            '━'.repeat(50)
+        ].join('\n');
+        throw new Error(errorMessage);
+    }
+}
+/**
+ * Soft warning for version issues (non-blocking)
+ */
+export function warnNodeVersion() {
+    const versionInfo = checkNodeVersion();
+    if (!versionInfo.isSupported) {
+        console.warn([
+            '⚠️  BRAINY VERSION WARNING',
+            `   Current: ${versionInfo.current}`,
+            `   Recommended: ${versionInfo.recommendation}`,
+            '   Consider upgrading for best stability',
+            ''
+        ].join('\n'));
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=nodeVersionCheck.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soulcraft/brainy",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "Universal Knowledge Protocol™ - World's first Triple Intelligence database unifying vector, graph, and document search in one API. 31 nouns × 40 verbs for infinite expressiveness.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -55,7 +55,7 @@
     }
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": "22.x"
   },
   "scripts": {
     "build": "npm run build:patterns:if-needed && tsc",