feat: add optional Q8 quantized model support

- Add Q8 quantized models (75% smaller than FP32)
- Enhance download scripts with model variant selection
- Add smart model loading with availability detection
- Implement runtime warnings for Q8 compatibility
- Update documentation with Q8 usage examples
- Maintain 100% backward compatibility (FP32 default)

BREAKING CHANGE: None - FP32 remains default

🧠 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

src/embeddings/model-manager.ts

@@ -36,14 +36,18 @@ const MODEL_SOURCES = {
   }
 }
 
-// Model verification files - minimal set needed for transformers.js
-const MODEL_FILES = [
+// Model verification files - BOTH fp32 and q8 variants
+const REQUIRED_FILES = [
   'config.json',
   'tokenizer.json',
-  'tokenizer_config.json',
-  'onnx/model.onnx'
+  'tokenizer_config.json'
 ]
 
+const MODEL_VARIANTS = {
+  fp32: 'onnx/model.onnx',
+  q8: 'onnx/model_quantized.onnx'
+}
+
 export class ModelManager {
   private static instance: ModelManager
   private modelsPath: string
@@ -126,14 +130,53 @@ export class ModelManager {
   }
   
   private async verifyModelFiles(modelPath: string): Promise<boolean> {
-    // Check if essential model files exist
-    for (const file of MODEL_FILES) {
+    // Check if essential files exist
+    for (const file of REQUIRED_FILES) {
       const fullPath = join(modelPath, file)
       if (!existsSync(fullPath)) {
         return false
       }
     }
-    return true
+    // At least one model variant must exist (fp32 or q8)
+    const fp32Exists = existsSync(join(modelPath, MODEL_VARIANTS.fp32))
+    const q8Exists = existsSync(join(modelPath, MODEL_VARIANTS.q8))
+    return fp32Exists || q8Exists
+  }
+  
+  /**
+   * Check which model variants are available locally
+   */
+  public getAvailableModels(modelName: string = 'Xenova/all-MiniLM-L6-v2'): { fp32: boolean, q8: boolean } {
+    const modelPath = join(this.modelsPath, modelName)
+    return {
+      fp32: existsSync(join(modelPath, MODEL_VARIANTS.fp32)),
+      q8: existsSync(join(modelPath, MODEL_VARIANTS.q8))
+    }
+  }
+  
+  /**
+   * Get the best available model variant based on preference and availability
+   */
+  public getBestAvailableModel(preferredType: 'fp32' | 'q8' = 'fp32', modelName: string = 'Xenova/all-MiniLM-L6-v2'): 'fp32' | 'q8' | null {
+    const available = this.getAvailableModels(modelName)
+    
+    // If preferred type is available, use it
+    if (available[preferredType]) {
+      return preferredType
+    }
+    
+    // Otherwise fall back to what's available
+    if (preferredType === 'q8' && available.fp32) {
+      console.warn('⚠️ Q8 model requested but not available, falling back to FP32')
+      return 'fp32'
+    }
+    
+    if (preferredType === 'fp32' && available.q8) {
+      console.warn('⚠️ FP32 model requested but not available, falling back to Q8')  
+      return 'q8'
+    }
+    
+    return null
   }
   
   private async tryModelSource(name: string, source: { host: string, pathTemplate: string, testFile?: string }, modelName: string): Promise<boolean> {

src/utils/embedding.ts

@@ -128,12 +128,25 @@ export class TransformerEmbedding implements EmbeddingModel {
       verbose: this.verbose,
       cacheDir: options.cacheDir || './models',
       localFilesOnly: localFilesOnly,
-      dtype: options.dtype || 'fp32',  // Use fp32 by default as quantized models aren't available on CDN
+      dtype: options.dtype || 'fp32',  // CRITICAL: fp32 default for backward compatibility
       device: options.device || 'auto'
     }
     
+    // ULTRA-CAREFUL: Runtime warnings for q8 usage
+    if (this.options.dtype === 'q8') {
+      const confirmed = process.env.BRAINY_Q8_CONFIRMED === 'true'
+      if (!confirmed && this.verbose) {
+        console.warn('🚨 Q8 MODEL WARNING:')
+        console.warn('   • Q8 creates different embeddings than fp32')  
+        console.warn('   • Q8 is incompatible with existing fp32 data')
+        console.warn('   • Only use q8 for new projects or when explicitly migrating')
+        console.warn('   • Set BRAINY_Q8_CONFIRMED=true to silence this warning')
+        console.warn('   • Q8 model is 75% smaller but may have slightly reduced accuracy')
+      }
+    }
+    
     if (this.verbose) {
-      this.logger('log', `Embedding config: localFilesOnly=${localFilesOnly}, model=${this.options.model}, cacheDir=${this.options.cacheDir}`)
+      this.logger('log', `Embedding config: dtype=${this.options.dtype}, localFilesOnly=${localFilesOnly}, model=${this.options.model}`)
     }
 
     // Configure transformers.js environment
@@ -258,11 +271,23 @@ export class TransformerEmbedding implements EmbeddingModel {
       
       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 as 'fp32' | 'q8', 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)`)
+      }
+      
       // Load the feature extraction pipeline with memory optimizations
       const pipelineOptions: any = {
         cache_dir: cacheDir,
         local_files_only: isBrowser() ? false : this.options.localFilesOnly,
-        dtype: this.options.dtype || 'fp32',  // Use fp32 model as quantized models aren't available on CDN
+        dtype: actualType,  // Use the actual available model type
         // CRITICAL: ONNX memory optimizations
         session_options: {
           enableCpuMemArena: false,  // Disable pre-allocated memory arena