feat: migrate embeddings to Candle WASM + remove semantic type inference

Major architectural changes:

1. EMBEDDINGS ENGINE (ONNX → Candle WASM):
   - Replace ONNX Runtime with Rust Candle compiled to WASM
   - Embedded model in WASM binary (no external downloads)
   - Quantized Q8 precision with <50MB memory footprint
   - Zero-download, offline-first operation
   - Same embedding quality (all-MiniLM-L6-v2)

2. REMOVE SEMANTIC TYPE INFERENCE:
   - Delete embeddedKeywordEmbeddings.ts (14MB of pre-computed embeddings)
   - Remove typeAwareQueryPlanner.ts and semanticTypeInference.ts
   - Remove VerbExactMatchSignal (uses keyword embeddings)
   - Update SmartRelationshipExtractor to 3 signals (55%/30%/15% weights)

API CHANGES (requires v7.0.0):
- Removed: inferTypes(), inferNouns(), inferVerbs(), inferIntent()
- Removed: getSemanticTypeInference(), SemanticTypeInference class
- Removed: TypeInference, SemanticTypeInferenceOptions types

Users can still use natural language queries in find() - they just
need to specify type explicitly for type-optimized searches.

PACKAGE SIZE IMPACT:
- Compressed: 90.1 MB → 86.2 MB (-4.3%)
- Uncompressed: 114.4 MB → 100.3 MB (-12%)
- ~448K lines of code removed

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
David Snelling 2026-01-06 12:52:34 -08:00
parent 81cd16e41b
commit da7d2ed29d
60 changed files with 3887 additions and 448557 deletions

View file

@ -4,47 +4,48 @@ Common issues and solutions for Brainy.
## 🤖 Model Loading Issues
### "Failed to load embedding model"
### "Failed to initialize Candle Embedding Engine"
**Symptoms**: Error during `brain.init()` with model loading failure.
**Symptoms**: Error during `brain.init()` with WASM loading failure.
**Causes & Solutions**:
1. **No local models + remote downloads blocked**
1. **WASM file missing**
```bash
# Solution: Download models manually
npm run download-models
# Verify WASM exists (~90MB with embedded model)
ls -lh dist/embeddings/wasm/pkg/candle_embeddings_bg.wasm
# Rebuild if missing
npm run build
```
2. **Network connectivity issues**
2. **Memory too low**
```bash
# Solution: Allow remote models
export BRAINY_ALLOW_REMOTE_MODELS=true
# Or pre-download in connected environment
npm run download-models
# Ensure at least 256MB available
# For Docker:
docker run -m 512m my-app
```
3. **Incorrect model path**
3. **Corrupted WASM**
```bash
# Check if models exist
ls ./models/Xenova/all-MiniLM-L6-v2/onnx/model.onnx
# Set correct path
export BRAINY_MODELS_PATH=/correct/path/to/models
# Rebuild the Candle WASM
npm run build:candle
npm run build
```
### Models Download Very Slowly
### Slow Initialization (>500ms)
**Symptoms**: Long wait times during first initialization.
**Symptoms**: Long wait times during first `brain.init()`.
**Cause**: WASM parsing takes ~200ms, which is normal for the 90MB file.
**Solutions**:
```bash
# Pre-download during build/CI
npm run download-models
```typescript
// Initialize once at startup, not per-request
await brain.init() // Do this once
# For Docker - download during image build
RUN npm run download-models
// Reuse for all requests
const results = await brain.find(query)
```
### Container Out of Memory During Model Load
@ -388,8 +389,8 @@ node -e "console.log(process.memoryUsage())"
# Platform info
node -e "console.log(process.platform, process.arch)"
# Brainy models
ls -la ./models/Xenova/all-MiniLM-L6-v2/
# Verify WASM file exists (model embedded inside)
ls -la dist/embeddings/wasm/pkg/candle_embeddings_bg.wasm
```
### Report Issues