vecbox 0.2.2 → 0.2.3

package/README.md

@@ -5,7 +5,6 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
 **One API, multiple providers.** Switch between OpenAI, Gemini, Mistral, or run locally with Llama.cpp using native N-API performance.
-
 ```typescript
 import { autoEmbed } from 'vecbox';
 
@@ -15,47 +14,53 @@ console.log(result.embedding); // [0.1, 0.2, ...]
 console.log(result.provider);  // 'llamacpp' | 'openai' | 'gemini' | 'mistral'
 ```
 
-## Installation
+## Why Vecbox?
+
+**Universal API** - Write once, run anywhere. Switch providers without changing code.
+
+**Local-First** - Runs on your machine with Llama.cpp. No API costs, no data leaving your server, full privacy.
 
+**Production Ready** - Cloud APIs (OpenAI, Gemini, Mistral) available when you need scale or specific models.
+
+**Native Speed** - C++ bindings via N-API make local embeddings 10x faster than HTTP-based solutions.
+
+## Installation
 ```bash
 npm install vecbox
 # or
 pnpm add vecbox
 ```
 
-**Zero setup required!** Everything is included - native N-API module automatically compiled during installation.
+The native module compiles automatically during installation. No manual build steps required.
 
 ## Quick Start
 
-### Auto-detection (Recommended)
+### Auto Mode (Recommended)
 
+Let Vecbox choose the best available provider:
 ```typescript
 import { autoEmbed } from 'vecbox';
 
-// Automatically picks the best available provider
-const result = await autoEmbed({ text: 'Your text' });
-console.log(result.embedding); // [0.1, 0.2, ...]
-console.log(result.provider);  // 'llamacpp' | 'openai' | 'gemini' | 'mistral'
+const result = await autoEmbed({ text: 'Your text here' });
+console.log(result.embedding);  // [0.1, 0.2, ...]
+console.log(result.provider);   // Shows which provider was used
 ```
 
-### Specific Provider
+Priority order: Llama.cpp (local) → OpenAI → Gemini → Mistral
 
+### Specific Provider
 ```typescript
 import { embed } from 'vecbox';
 
-// Use specific provider
+// OpenAI
 const result = await embed(
   { provider: 'openai', apiKey: process.env.OPENAI_API_KEY },
   { text: 'Your text' }
 );
 ```
 
-### File Input
-
+### From Files
 ```typescript
-import { embed } from 'vecbox';
-
-// Embed text from files
 const result = await embed(
   { provider: 'gemini', apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY },
   { filePath: './document.txt' }
@@ -63,14 +68,11 @@ const result = await embed(
 ```
 
 ### Batch Processing
-
 ```typescript
-import { embed } from 'vecbox';
-
 const inputs = [
-  { text: 'First text' },
-  { text: 'Second text' },
-  { text: 'Third text' }
+  { text: 'First document' },
+  { text: 'Second document' },
+  { text: 'Third document' }
 ];
 
 const result = await embed(
@@ -81,60 +83,60 @@ const result = await embed(
 console.log(result.embeddings.length); // 3
 ```
 
-## 🚀 Local Llama.cpp with Native N-API
+## Providers
 
-**Automatic Native Detection:**
-```typescript
-import { autoEmbed } from 'vecbox';
+### Llama.cpp (Local - Free & Private)
 
-// Automatically uses native N-API when available
-const result = await autoEmbed({ text: 'Your text' });
-console.log(result.provider); // 'llamacpp' (native)
+**Advantages:**
+- ✅ Zero API costs
+- ✅ Full privacy (data never leaves your machine)
+- ✅ Works offline
+- ✅ Native C++ performance via N-API
+
+**Setup:**
+```bash
+# 1. Download a GGUF embedding model
+wget https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.Q4_K_M.gguf
+
+# 2. Place in your project
+mkdir models
+mv nomic-embed-text-v1.5.Q4_K_M.gguf models/
 ```
 
-**Manual Native Configuration:**
+**Usage:**
 ```typescript
-import { embed } from 'vecbox';
+// Auto-detect (uses local model automatically)
+const result = await autoEmbed({ text: 'Your text' });
 
-// Force native module usage
+// Explicit path
 const result = await embed(
   { provider: 'llamacpp', model: './models/nomic-embed-text-v1.5.Q4_K_M.gguf' },
   { text: 'Your text' }
 );
 ```
 
-**Setup for Local Models:**
-```bash
-# Download a GGUF embedding model
-wget https://huggingface.co/nomic-ai/nomic-embed-text-v1.5-GGUF/resolve/main/nomic-embed-text-v1.5.Q4_K_M.gguf
-
-# Place it in your project directory
-mkdir models && mv nomic-embed-text-v1.5.Q4_K_M.gguf models/
-```
-
-## 🌍 Environment Variables
-
-```bash
-# .env file
-OPENAI_API_KEY=sk-...
-GOOGLE_GENERATIVE_AI_API_KEY=...
-MISTRAL_API_KEY=...
-```
-
-## 📚 Providers
+**Recommended Models:**
+- `nomic-embed-text-v1.5.Q4_K_M.gguf` (81MB) - Best overall
+- `bge-base-en-v1.5.Q4_K_M.gguf` (133MB) - Higher quality
+- `bge-small-en-v1.5.Q4_0.gguf` (33MB) - Fastest, smaller
 
 ### OpenAI
 ```typescript
 await embed(
   {
     provider: 'openai',
-    model: 'text-embedding-3-small', // or text-embedding-3-large
+    model: 'text-embedding-3-small', // or 'text-embedding-3-large'
     apiKey: process.env.OPENAI_API_KEY
   },
   { text: 'Your text' }
 );
 ```
-**Setup:** Get API key at [platform.openai.com](https://platform.openai.com)
+
+**Setup:** Get API key at [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
+
+**Models:**
+- `text-embedding-3-small` - Fast, cost-effective
+- `text-embedding-3-large` - Highest quality
 
 ### Google Gemini
 ```typescript
@@ -147,9 +149,10 @@ await embed(
   { text: 'Your text' }
 );
 ```
-**Setup:** Get API key at [aistudio.google.com](https://aistudio.google.com)
 
-### Mistral
+**Setup:** Get API key at [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
+
+### Mistral AI
 ```typescript
 await embed(
   {
@@ -160,59 +163,39 @@ await embed(
   { text: 'Your text' }
 );
 ```
-**Setup:** Get API key at [mistral.ai](https://mistral.ai)
 
-### Llama.cpp (Local)
-```typescript
-await embed(
-  { provider: 'llamacpp', model: './models/nomic-embed-text-v1.5.Q4_K_M.gguf' },
-  { text: 'Your text' }
-);
-```
-**Setup:** Download GGUF model and place in your project directory
+**Setup:** Get API key at [console.mistral.ai](https://console.mistral.ai)
 
-## 🚀 Features
+## Environment Variables
 
-- **🎯 One API, Multiple Providers** - Switch between OpenAI, Gemini, Mistral, or local Llama.cpp
-- **🤖 Auto-Detection** - Automatically picks the best available provider
-- **⚡ Native Performance** - Llama.cpp integration with N-API (10x faster than HTTP)
-- **🔄 Smart Fallbacks** - Never fails, always has a backup provider
-- **📁 File Support** - Embed text from files directly
-- **📦 Batch Processing** - Process multiple texts efficiently
-- **🛡️ Type Safe** - Full TypeScript support
-- **🌍 Zero Dependencies** - No external downloads or setup required
+Create a `.env` file in your project root:
+```bash
+# Optional - only needed for cloud providers
+OPENAI_API_KEY=sk-...
+GOOGLE_GENERATIVE_AI_API_KEY=...
+MISTRAL_API_KEY=...
+```
 
-## 📖 API Reference
+Vecbox works without any API keys when using Llama.cpp locally.
 
-### `autoEmbed(input)`
+## API Reference
 
-Auto-detects best provider in priority order:
-1. **Llama.cpp** (Local & Free)
-2. **OpenAI** (if API key available)
-3. **Gemini** (if API key available)
-4. **Mistral** (if API key available)
+### `autoEmbed(input: Input): Promise<Result>`
 
-```typescript
-await autoEmbed({ text: string } | { filePath: string })
-```
-
-### `embed(config, input)`
+Automatically selects the best available provider.
 
-Explicit provider selection.
+**Input:**
 ```typescript
-await embed(
-  { provider, model?, apiKey?, baseUrl?, timeout?, maxRetries? },
-  { text: string } | { filePath: string } | Array
-)
+{ text: string } | { filePath: string }
 ```
 
 **Returns:**
 ```typescript
 {
-  embedding: number[],
-  dimensions: number,
-  provider: string,
-  model: string,
+  embedding: number[];      // The embedding vector
+  dimensions: number;       // Vector dimensions
+  provider: string;         // Which provider was used
+  model: string;           // Model name
   usage?: {
     promptTokens?: number;
     totalTokens?: number;
@@ -220,94 +203,215 @@ await embed(
 }
 ```
 
-## 🧪 Examples
+### `embed(config: Config, input: Input | Input[]): Promise<Result>`
+
+Use a specific provider.
+
+**Config:**
+```typescript
+{
+  provider: 'llamacpp' | 'openai' | 'gemini' | 'mistral';
+  model?: string;          // Provider-specific model
+  apiKey?: string;         // Required for cloud providers
+  baseUrl?: string;        // Custom API endpoint
+  timeout?: number;        // Request timeout in ms
+  maxRetries?: number;     // Retry attempts
+}
+```
+
+**Input:**
+```typescript
+{ text: string } | { filePath: string } | Array<{text: string} | {filePath: string}>
+```
+
+**Returns:** Same as `autoEmbed`, but `embeddings: number[][]` for batch inputs.
+
+## Examples
 
 ### Semantic Search
 ```typescript
-function cosineSimilarity(vecA: number[], vecB: number[]): number {
-  const dotProduct = vecA.reduce((sum, val, i) => sum + val * vecB[i], 0);
-  const magnitudeA = Math.sqrt(vecA.reduce((sum, val) => sum + val * val, 0));
-  const magnitudeB = Math.sqrt(vecB.reduce((sum, val) => sum + val * val, 0));
-  return dotProduct / (magnitudeA * magnitudeB);
+import { autoEmbed } from 'vecbox';
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  const dotProduct = a.reduce((sum, val, i) => sum + val * b[i], 0);
+  const magA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
+  const magB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
+  return dotProduct / (magA * magB);
 }
 
-const query = await autoEmbed({ text: 'machine learning' });
-const docs = await Promise.all(
-  documents.map(doc => autoEmbed({ text: doc }))
-);
+// Embed query and documents
+const query = await autoEmbed({ text: 'machine learning tutorials' });
+const docs = await Promise.all([
+  autoEmbed({ text: 'Introduction to neural networks' }),
+  autoEmbed({ text: 'Python web scraping guide' }),
+  autoEmbed({ text: 'Deep learning fundamentals' })
+]);
 
-// Find most similar
-const scores = docs.map(doc => 
+// Calculate similarity scores
+const similarities = docs.map(doc => 
   cosineSimilarity(query.embedding, doc.embedding)
 );
-const mostSimilar = scores.indexOf(Math.max(...scores));
-console.log(`Best match: ${documents[mostSimilar]}`);
+
+// Find best match
+const bestIdx = similarities.indexOf(Math.max(...similarities));
+console.log(`Best match: Document ${bestIdx + 1} (score: ${similarities[bestIdx].toFixed(3)})`);
 ```
 
-### File Processing
+### Batch File Processing
 ```typescript
+import { embed } from 'vecbox';
 import { readdir } from 'fs/promises';
 import { join } from 'path';
 
-async function embedAllFiles(dirPath: string) {
+async function embedDirectory(dirPath: string) {
   const files = await readdir(dirPath);
-  const textFiles = files.filter(file => file.endsWith('.txt'));
+  const textFiles = files.filter(f => f.endsWith('.txt'));
   
-  const inputs = textFiles.map(file => ({
-    filePath: join(dirPath, file)
-  }));
-  
-  const results = await embed(
+  // Process all files in one batch
+  const result = await embed(
     { provider: 'llamacpp' },
-    inputs
+    textFiles.map(file => ({ filePath: join(dirPath, file) }))
   );
   
-  return textFiles.map((file, index) => ({
-    file,
-    embedding: results.embeddings[index]
+  return textFiles.map((file, i) => ({
+    filename: file,
+    embedding: result.embeddings[i]
   }));
 }
 
-const embeddings = await embedAllFiles('./documents');
-console.log(`Processed ${embeddings.length} files`);
+const results = await embedDirectory('./documents');
+console.log(`Embedded ${results.length} files`);
 ```
 
-## 🐛 Troubleshooting
+### Document Clustering
+```typescript
+import { autoEmbed } from 'vecbox';
+
+const documents = [
+  'The cat sat on the mat',
+  'Dogs are loyal pets',
+  'Python is a programming language',
+  'JavaScript runs in browsers',
+  'Birds can fly high'
+];
+
+// Get embeddings
+const embeddings = await Promise.all(
+  documents.map(doc => autoEmbed({ text: doc }))
+);
+
+// Simple clustering by similarity threshold
+function findClusters(embeddings: number[][], threshold = 0.7) {
+  const clusters: number[][] = [];
+  const assigned = new Set<number>();
+  
+  embeddings.forEach((emb, i) => {
+    if (assigned.has(i)) return;
+    
+    const cluster = [i];
+    assigned.add(i);
+    
+    embeddings.forEach((other, j) => {
+      if (i !== j && !assigned.has(j)) {
+        const sim = cosineSimilarity(emb, other);
+        if (sim > threshold) {
+          cluster.push(j);
+          assigned.add(j);
+        }
+      }
+    });
+    
+    clusters.push(cluster);
+  });
+  
+  return clusters;
+}
+
+const clusters = findClusters(embeddings.map(e => e.embedding));
+console.log('Clusters:', clusters);
+// Output: [[0, 1, 4], [2, 3]] - animals vs programming
+```
+
+## Troubleshooting
 
 ### Native Module Issues
 
-**Problem:** `binding.createModel is not a function`
+**Error: `Cannot find module './build/Release/vecbox.node'`**
+
+The native module failed to compile. Rebuild it:
 ```bash
-# Solution: Rebuild native module
 npm run build:native
+# or
+node-gyp rebuild
+```
+
+**Error: `binding.createModel is not a function`**
+
+Your native module is outdated. Clean and rebuild:
+```bash
+rm -rf build/
+npm install
 ```
 
-**Problem:** Model file not found
+### Model Loading Issues
+
+**Error: `Model file not found`**
+
+Check that the model path is correct:
 ```bash
-# Solution: Check model path
-ls -la models/  # Verify model exists
+ls -la models/           # Verify model exists
+pwd                      # Check current directory
+```
+
+Use absolute paths if relative paths fail:
+```typescript
+const path = require('path');
+const modelPath = path.join(__dirname, 'models', 'model.gguf');
 ```
 
-### Performance Issues
+### Performance
 
-**Slow embeddings:**
-- Check model size (smaller = faster)
-- Use batch processing for multiple texts
-- Ensure native module is being used (not HTTP fallback)
+**Embeddings are slow:**
+- Use smaller quantized models (Q4_K_M is recommended)
+- Process texts in batches instead of one-by-one
+- Verify native module is loaded (check `result.provider === 'llamacpp'`)
 
-## 📄 License
+**High memory usage:**
+- Models stay loaded in memory for performance
+- Use smaller models (bge-small instead of bge-large)
+- Process files in chunks for very large datasets
+
+## Features
+
+- **🎯 Provider Agnostic** - One API for all embedding providers
+- **🤖 Smart Auto-Detection** - Automatically uses the best available option
+- **⚡ Native Performance** - C++ via N-API for maximum speed
+- **🔄 Automatic Fallbacks** - Seamlessly switches providers if one fails
+- **📁 File Support** - Read and embed text files directly
+- **📦 Batch Processing** - Efficient multi-document embedding
+- **🛡️ TypeScript First** - Full type safety and IDE autocomplete
+- **🌍 Zero Setup** - Native module compiles automatically on install
+- **🔒 Privacy-First** - Local processing keeps your data private
+
+## License
 
 MIT License - see [LICENSE](LICENSE) file for details.
 
-## 🙏 Acknowledgments
+## Credits
+
+Built on top of excellent open-source projects:
+
+- [llama.cpp](https://github.com/ggml-org/llama.cpp) - High-performance LLM inference
+- [OpenAI](https://openai.com/) - text-embedding-3 models
+- [Google Gemini](https://ai.google.dev/) - gemini-embedding models
+- [Mistral AI](https://mistral.ai/) - mistral-embed model
+
+## Contributing
 
-- [Llama.cpp](https://github.com/ggml-org/llama.cpp) - Core embedding engine
-- [OpenAI](https://openai.com/) - Embedding API
-- [Google Gemini](https://ai.google.dev/) - Embedding API
-- [Mistral AI](https://mistral.ai/) - Embedding API
+Issues and pull requests welcome at [github.com/box-safe/vecbox](https://github.com/box-safe/vecbox)
 
 ---
 
-**⭐ Star us on GitHub!** [github.com/box-safe/vecbox](https://github.com/box-safe/vecbox)
+**⭐ If Vecbox saves you time, star us on GitHub!**
 
-**Made with ❤️ by the Vecbox Team**
+**Made with ❤️ for developers who value simplicity and performance**