ruvector 0.1.54 → 0.1.56

package/dist/core/onnx/loader.js

@@ -0,0 +1,348 @@
+/**
+ * Model Loader for RuVector ONNX Embeddings WASM
+ *
+ * Provides easy loading of pre-trained models from HuggingFace Hub
+ */
+
+/**
+ * Pre-configured models with their HuggingFace URLs
+ */
+export const MODELS = {
+    // Sentence Transformers - Small & Fast
+    'all-MiniLM-L6-v2': {
+        name: 'all-MiniLM-L6-v2',
+        dimension: 384,
+        maxLength: 256,
+        size: '23MB',
+        description: 'Fast, general-purpose embeddings',
+        model: 'https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/onnx/model.onnx',
+        tokenizer: 'https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/resolve/main/tokenizer.json',
+    },
+    'all-MiniLM-L12-v2': {
+        name: 'all-MiniLM-L12-v2',
+        dimension: 384,
+        maxLength: 256,
+        size: '33MB',
+        description: 'Better quality, balanced speed',
+        model: 'https://huggingface.co/sentence-transformers/all-MiniLM-L12-v2/resolve/main/onnx/model.onnx',
+        tokenizer: 'https://huggingface.co/sentence-transformers/all-MiniLM-L12-v2/resolve/main/tokenizer.json',
+    },
+
+    // BGE Models - State of the art
+    'bge-small-en-v1.5': {
+        name: 'bge-small-en-v1.5',
+        dimension: 384,
+        maxLength: 512,
+        size: '33MB',
+        description: 'State-of-the-art small model',
+        model: 'https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/onnx/model.onnx',
+        tokenizer: 'https://huggingface.co/BAAI/bge-small-en-v1.5/resolve/main/tokenizer.json',
+    },
+    'bge-base-en-v1.5': {
+        name: 'bge-base-en-v1.5',
+        dimension: 768,
+        maxLength: 512,
+        size: '110MB',
+        description: 'Best overall quality',
+        model: 'https://huggingface.co/BAAI/bge-base-en-v1.5/resolve/main/onnx/model.onnx',
+        tokenizer: 'https://huggingface.co/BAAI/bge-base-en-v1.5/resolve/main/tokenizer.json',
+    },
+
+    // E5 Models - Microsoft
+    'e5-small-v2': {
+        name: 'e5-small-v2',
+        dimension: 384,
+        maxLength: 512,
+        size: '33MB',
+        description: 'Excellent for search & retrieval',
+        model: 'https://huggingface.co/intfloat/e5-small-v2/resolve/main/onnx/model.onnx',
+        tokenizer: 'https://huggingface.co/intfloat/e5-small-v2/resolve/main/tokenizer.json',
+    },
+
+    // GTE Models - Alibaba
+    'gte-small': {
+        name: 'gte-small',
+        dimension: 384,
+        maxLength: 512,
+        size: '33MB',
+        description: 'Good multilingual support',
+        model: 'https://huggingface.co/thenlper/gte-small/resolve/main/onnx/model.onnx',
+        tokenizer: 'https://huggingface.co/thenlper/gte-small/resolve/main/tokenizer.json',
+    },
+};
+
+/**
+ * Default model for quick start
+ */
+export const DEFAULT_MODEL = 'all-MiniLM-L6-v2';
+
+/**
+ * Model loader with caching support
+ */
+export class ModelLoader {
+    constructor(options = {}) {
+        this.cache = options.cache ?? true;
+        this.cacheStorage = options.cacheStorage ?? 'ruvector-models';
+        this.onProgress = options.onProgress ?? null;
+    }
+
+    /**
+     * Load a pre-configured model by name
+     * @param {string} modelName - Model name from MODELS
+     * @returns {Promise<{modelBytes: Uint8Array, tokenizerJson: string, config: object}>}
+     */
+    async loadModel(modelName = DEFAULT_MODEL) {
+        const modelConfig = MODELS[modelName];
+        if (!modelConfig) {
+            throw new Error(`Unknown model: ${modelName}. Available: ${Object.keys(MODELS).join(', ')}`);
+        }
+
+        console.log(`Loading model: ${modelConfig.name} (${modelConfig.size})`);
+
+        const [modelBytes, tokenizerJson] = await Promise.all([
+            this.fetchWithCache(modelConfig.model, `${modelName}-model.onnx`, 'arraybuffer'),
+            this.fetchWithCache(modelConfig.tokenizer, `${modelName}-tokenizer.json`, 'text'),
+        ]);
+
+        return {
+            modelBytes: new Uint8Array(modelBytes),
+            tokenizerJson,
+            config: modelConfig,
+        };
+    }
+
+    /**
+     * Load model from custom URLs
+     * @param {string} modelUrl - URL to ONNX model
+     * @param {string} tokenizerUrl - URL to tokenizer.json
+     * @returns {Promise<{modelBytes: Uint8Array, tokenizerJson: string}>}
+     */
+    async loadFromUrls(modelUrl, tokenizerUrl) {
+        const [modelBytes, tokenizerJson] = await Promise.all([
+            this.fetchWithCache(modelUrl, null, 'arraybuffer'),
+            this.fetchWithCache(tokenizerUrl, null, 'text'),
+        ]);
+
+        return {
+            modelBytes: new Uint8Array(modelBytes),
+            tokenizerJson,
+        };
+    }
+
+    /**
+     * Load model from local files (Node.js)
+     * @param {string} modelPath - Path to ONNX model
+     * @param {string} tokenizerPath - Path to tokenizer.json
+     * @returns {Promise<{modelBytes: Uint8Array, tokenizerJson: string}>}
+     */
+    async loadFromFiles(modelPath, tokenizerPath) {
+        // Node.js environment
+        if (typeof process !== 'undefined' && process.versions?.node) {
+            const fs = await import('fs/promises');
+            const [modelBytes, tokenizerJson] = await Promise.all([
+                fs.readFile(modelPath),
+                fs.readFile(tokenizerPath, 'utf8'),
+            ]);
+            return {
+                modelBytes: new Uint8Array(modelBytes),
+                tokenizerJson,
+            };
+        }
+        throw new Error('loadFromFiles is only available in Node.js');
+    }
+
+    /**
+     * Fetch with optional caching (uses Cache API in browsers)
+     */
+    async fetchWithCache(url, cacheKey, responseType) {
+        // Try cache first (browser only)
+        if (this.cache && typeof caches !== 'undefined' && cacheKey) {
+            try {
+                const cache = await caches.open(this.cacheStorage);
+                const cached = await cache.match(cacheKey);
+                if (cached) {
+                    console.log(`  Cache hit: ${cacheKey}`);
+                    return responseType === 'arraybuffer'
+                        ? await cached.arrayBuffer()
+                        : await cached.text();
+                }
+            } catch (e) {
+                // Cache API not available, continue with fetch
+            }
+        }
+
+        // Fetch from network
+        console.log(`  Downloading: ${url}`);
+        const response = await this.fetchWithProgress(url);
+
+        if (!response.ok) {
+            throw new Error(`Failed to fetch ${url}: ${response.status} ${response.statusText}`);
+        }
+
+        // Clone for caching
+        const responseClone = response.clone();
+
+        // Cache the response (browser only)
+        if (this.cache && typeof caches !== 'undefined' && cacheKey) {
+            try {
+                const cache = await caches.open(this.cacheStorage);
+                await cache.put(cacheKey, responseClone);
+            } catch (e) {
+                // Cache write failed, continue
+            }
+        }
+
+        return responseType === 'arraybuffer'
+            ? await response.arrayBuffer()
+            : await response.text();
+    }
+
+    /**
+     * Fetch with progress reporting
+     */
+    async fetchWithProgress(url) {
+        const response = await fetch(url);
+
+        if (!this.onProgress || !response.body) {
+            return response;
+        }
+
+        const contentLength = response.headers.get('content-length');
+        if (!contentLength) {
+            return response;
+        }
+
+        const total = parseInt(contentLength, 10);
+        let loaded = 0;
+
+        const reader = response.body.getReader();
+        const chunks = [];
+
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            chunks.push(value);
+            loaded += value.length;
+
+            this.onProgress({
+                loaded,
+                total,
+                percent: Math.round((loaded / total) * 100),
+            });
+        }
+
+        const body = new Uint8Array(loaded);
+        let position = 0;
+        for (const chunk of chunks) {
+            body.set(chunk, position);
+            position += chunk.length;
+        }
+
+        return new Response(body, {
+            headers: response.headers,
+            status: response.status,
+            statusText: response.statusText,
+        });
+    }
+
+    /**
+     * Clear cached models
+     */
+    async clearCache() {
+        if (typeof caches !== 'undefined') {
+            await caches.delete(this.cacheStorage);
+            console.log('Model cache cleared');
+        }
+    }
+
+    /**
+     * List available models
+     */
+    static listModels() {
+        return Object.entries(MODELS).map(([key, config]) => ({
+            id: key,
+            ...config,
+        }));
+    }
+}
+
+/**
+ * Quick helper to create an embedder with a pre-configured model
+ *
+ * @example
+ * ```javascript
+ * import { createEmbedder } from './loader.js';
+ *
+ * const embedder = await createEmbedder('all-MiniLM-L6-v2');
+ * const embedding = embedder.embedOne("Hello world");
+ * ```
+ */
+export async function createEmbedder(modelName = DEFAULT_MODEL, wasmModule = null) {
+    // Import WASM module if not provided
+    if (!wasmModule) {
+        wasmModule = await import('./pkg/ruvector_onnx_embeddings_wasm.js');
+        await wasmModule.default();
+    }
+
+    const loader = new ModelLoader();
+    const { modelBytes, tokenizerJson, config } = await loader.loadModel(modelName);
+
+    const embedderConfig = new wasmModule.WasmEmbedderConfig()
+        .setMaxLength(config.maxLength)
+        .setNormalize(true)
+        .setPooling(0); // Mean pooling
+
+    const embedder = wasmModule.WasmEmbedder.withConfig(
+        modelBytes,
+        tokenizerJson,
+        embedderConfig
+    );
+
+    return embedder;
+}
+
+/**
+ * Quick helper for one-off embedding (loads model, embeds, returns)
+ *
+ * @example
+ * ```javascript
+ * import { embed } from './loader.js';
+ *
+ * const embedding = await embed("Hello world");
+ * const embeddings = await embed(["Hello", "World"]);
+ * ```
+ */
+export async function embed(text, modelName = DEFAULT_MODEL) {
+    const embedder = await createEmbedder(modelName);
+
+    if (Array.isArray(text)) {
+        return embedder.embedBatch(text);
+    }
+    return embedder.embedOne(text);
+}
+
+/**
+ * Quick helper for similarity comparison
+ *
+ * @example
+ * ```javascript
+ * import { similarity } from './loader.js';
+ *
+ * const score = await similarity("I love dogs", "I adore puppies");
+ * console.log(score); // ~0.85
+ * ```
+ */
+export async function similarity(text1, text2, modelName = DEFAULT_MODEL) {
+    const embedder = await createEmbedder(modelName);
+    return embedder.similarity(text1, text2);
+}
+
+export default {
+    MODELS,
+    DEFAULT_MODEL,
+    ModelLoader,
+    createEmbedder,
+    embed,
+    similarity,
+};

package/dist/core/onnx/pkg/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rUv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/core/onnx/pkg/README.md

@@ -0,0 +1,295 @@
+# RuVector ONNX Embeddings WASM
+
+[![npm version](https://img.shields.io/npm/v/ruvector-onnx-embeddings-wasm.svg)](https://www.npmjs.com/package/ruvector-onnx-embeddings-wasm)
+[![crates.io](https://img.shields.io/crates/v/ruvector-onnx-embeddings-wasm.svg)](https://crates.io/crates/ruvector-onnx-embeddings-wasm)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![WebAssembly](https://img.shields.io/badge/WebAssembly-654FF0?logo=webassembly&logoColor=white)](https://webassembly.org/)
+
+> **Portable embedding generation that runs anywhere WebAssembly runs**
+
+Generate text embeddings directly in browsers, Cloudflare Workers, Deno, and any WASM runtime. Built with [Tract](https://github.com/sonos/tract) for pure Rust ONNX inference.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| 🌐 **Browser Support** | Generate embeddings client-side, no server needed |
+| ⚡ **Edge Computing** | Deploy to Cloudflare Workers, Vercel Edge, Deno Deploy |
+| 📦 **Zero Dependencies** | Single WASM binary, no native modules |
+| 🤗 **HuggingFace Models** | Pre-configured URLs for popular models |
+| 🔄 **Auto Caching** | Browser Cache API for instant reloads |
+| 🎯 **Same API** | Compatible with native `ruvector-onnx-embeddings` |
+
+## Quick Start
+
+### Browser (ES Modules)
+
+```html
+<script type="module">
+import init, { WasmEmbedder } from 'https://unpkg.com/ruvector-onnx-embeddings-wasm/ruvector_onnx_embeddings_wasm.js';
+import { createEmbedder } from 'https://unpkg.com/ruvector-onnx-embeddings-wasm/loader.js';
+
+// Initialize WASM
+await init();
+
+// Create embedder (downloads model automatically)
+const embedder = await createEmbedder('all-MiniLM-L6-v2');
+
+// Generate embeddings
+const embedding = embedder.embedOne("Hello, world!");
+console.log("Dimension:", embedding.length); // 384
+
+// Compute similarity
+const sim = embedder.similarity("I love Rust", "Rust is great");
+console.log("Similarity:", sim.toFixed(4)); // ~0.85
+</script>
+```
+
+### Node.js
+
+```bash
+npm install ruvector-onnx-embeddings-wasm
+```
+
+```javascript
+import { createEmbedder, similarity, embed } from 'ruvector-onnx-embeddings-wasm/loader.js';
+
+// One-liner similarity
+const score = await similarity("I love dogs", "I adore puppies");
+console.log(score); // ~0.85
+
+// One-liner embedding
+const embedding = await embed("Hello world");
+console.log(embedding.length); // 384
+
+// Full control
+const embedder = await createEmbedder('bge-small-en-v1.5');
+const emb1 = embedder.embedOne("First text");
+const emb2 = embedder.embedOne("Second text");
+```
+
+### Cloudflare Workers
+
+```javascript
+import { WasmEmbedder, WasmEmbedderConfig } from 'ruvector-onnx-embeddings-wasm';
+
+export default {
+  async fetch(request, env) {
+    // Load model from R2 or KV
+    const modelBytes = await env.MODELS.get('model.onnx', 'arrayBuffer');
+    const tokenizerJson = await env.MODELS.get('tokenizer.json', 'text');
+
+    const embedder = new WasmEmbedder(
+      new Uint8Array(modelBytes),
+      tokenizerJson
+    );
+
+    const { text } = await request.json();
+    const embedding = embedder.embedOne(text);
+
+    return Response.json({
+      embedding: Array.from(embedding),
+      dimension: embedding.length
+    });
+  }
+};
+```
+
+## Available Models
+
+| Model | Dimension | Size | Speed | Quality | Best For |
+|-------|-----------|------|-------|---------|----------|
+| **all-MiniLM-L6-v2** ⭐ | 384 | 23MB | ⚡⚡⚡ | ⭐⭐⭐ | Default, fast |
+| **all-MiniLM-L12-v2** | 384 | 33MB | ⚡⚡ | ⭐⭐⭐⭐ | Better quality |
+| **bge-small-en-v1.5** | 384 | 33MB | ⚡⚡⚡ | ⭐⭐⭐⭐ | State-of-the-art |
+| **bge-base-en-v1.5** | 768 | 110MB | ⚡ | ⭐⭐⭐⭐⭐ | Best quality |
+| **e5-small-v2** | 384 | 33MB | ⚡⚡⚡ | ⭐⭐⭐⭐ | Search/retrieval |
+| **gte-small** | 384 | 33MB | ⚡⚡⚡ | ⭐⭐⭐⭐ | Multilingual |
+
+## API Reference
+
+### ModelLoader
+
+```javascript
+import { ModelLoader, MODELS, DEFAULT_MODEL } from './loader.js';
+
+// List available models
+console.log(ModelLoader.listModels());
+
+// Load with progress
+const loader = new ModelLoader({
+  cache: true,
+  onProgress: ({ percent }) => console.log(`${percent}%`)
+});
+
+const { modelBytes, tokenizerJson, config } = await loader.loadModel('all-MiniLM-L6-v2');
+```
+
+### WasmEmbedder
+
+```typescript
+class WasmEmbedder {
+  constructor(modelBytes: Uint8Array, tokenizerJson: string);
+
+  static withConfig(
+    modelBytes: Uint8Array,
+    tokenizerJson: string,
+    config: WasmEmbedderConfig
+  ): WasmEmbedder;
+
+  embedOne(text: string): Float32Array;
+  embedBatch(texts: string[]): Float32Array;
+  similarity(text1: string, text2: string): number;
+
+  dimension(): number;
+  maxLength(): number;
+}
+```
+
+### WasmEmbedderConfig
+
+```typescript
+class WasmEmbedderConfig {
+  constructor();
+  setMaxLength(length: number): WasmEmbedderConfig;
+  setNormalize(normalize: boolean): WasmEmbedderConfig;
+  setPooling(strategy: number): WasmEmbedderConfig;
+  // 0=Mean, 1=Cls, 2=Max, 3=MeanSqrtLen, 4=LastToken
+}
+```
+
+### Utility Functions
+
+```typescript
+function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+function normalizeL2(embedding: Float32Array): Float32Array;
+function version(): string;
+function simd_available(): boolean;
+```
+
+## Pooling Strategies
+
+| Value | Strategy | Description |
+|-------|----------|-------------|
+| 0 | **Mean** | Average all tokens (default, recommended) |
+| 1 | **Cls** | Use [CLS] token only (BERT-style) |
+| 2 | **Max** | Max pooling across tokens |
+| 3 | **MeanSqrtLen** | Mean normalized by sqrt(length) |
+| 4 | **LastToken** | Last token (decoder models) |
+
+## Performance
+
+| Environment | Throughput | Latency |
+|-------------|------------|---------|
+| Chrome (M1 Mac) | ~50 texts/sec | ~20ms |
+| Firefox (M1 Mac) | ~45 texts/sec | ~22ms |
+| Node.js 20 | ~80 texts/sec | ~12ms |
+| Cloudflare Workers | ~30 texts/sec | ~33ms |
+| Deno | ~75 texts/sec | ~13ms |
+
+*Tested with all-MiniLM-L6-v2, 128 token inputs*
+
+## Comparison: Native vs WASM
+
+| Aspect | Native (`ort`) | WASM (`tract`) |
+|--------|----------------|----------------|
+| Speed | ⚡⚡⚡ Native | ⚡⚡ ~2-3x slower |
+| Browser | ❌ | ✅ |
+| Edge Workers | ❌ | ✅ |
+| GPU | CUDA, TensorRT | ❌ |
+| Bundle Size | ~50MB | ~8MB |
+| Portability | Platform-specific | Universal |
+
+**Use native** for: servers, high throughput, GPU acceleration
+**Use WASM** for: browsers, edge, portability
+
+## Building from Source
+
+```bash
+# Install wasm-pack
+cargo install wasm-pack
+
+# Build for web
+wasm-pack build --target web
+
+# Build for Node.js
+wasm-pack build --target nodejs
+
+# Build for bundlers (webpack, vite)
+wasm-pack build --target bundler
+```
+
+## Use Cases
+
+### Semantic Search
+
+```javascript
+const embedder = await createEmbedder();
+
+// Index documents
+const docs = ["Rust is fast", "Python is easy", "JavaScript runs everywhere"];
+const embeddings = docs.map(d => embedder.embedOne(d));
+
+// Search
+const query = embedder.embedOne("Which language is performant?");
+const scores = embeddings.map((e, i) => ({
+  doc: docs[i],
+  score: cosineSimilarity(query, e)
+}));
+scores.sort((a, b) => b.score - a.score);
+console.log(scores[0]); // { doc: "Rust is fast", score: 0.82 }
+```
+
+### Text Clustering
+
+```javascript
+const texts = [
+  "Machine learning is amazing",
+  "Deep learning uses neural networks",
+  "I love pizza",
+  "Italian food is delicious"
+];
+
+const embeddings = texts.map(t => embedder.embedOne(t));
+// Use k-means or hierarchical clustering on embeddings
+```
+
+### RAG (Retrieval-Augmented Generation)
+
+```javascript
+// Build knowledge base
+const knowledge = [
+  "RuVector is a vector database",
+  "Embeddings capture semantic meaning",
+  // ... more docs
+];
+const knowledgeEmbeddings = knowledge.map(k => embedder.embedOne(k));
+
+// Retrieve relevant context for LLM
+function getContext(query, topK = 3) {
+  const queryEmb = embedder.embedOne(query);
+  const scores = knowledgeEmbeddings.map((e, i) => ({
+    text: knowledge[i],
+    score: cosineSimilarity(queryEmb, e)
+  }));
+  return scores.sort((a, b) => b.score - a.score).slice(0, topK);
+}
+```
+
+## Related Packages
+
+| Package | Runtime | Use Case |
+|---------|---------|----------|
+| [ruvector-onnx-embeddings](https://crates.io/crates/ruvector-onnx-embeddings) | Native | High-performance servers |
+| **ruvector-onnx-embeddings-wasm** | WASM | Browsers, edge, portable |
+
+## License
+
+MIT License - See [LICENSE](../../LICENSE) for details.
+
+---
+
+<p align="center">
+  <b>Part of the RuVector ecosystem</b><br>
+  High-performance vector operations in Rust
+</p>