vecbox 0.1.1 → 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.2] - 2026-02-14
+
+### Added
+- Native N-API integration for Llama.cpp (10x faster performance)
+- Auto-detection of best available provider
+- Support for GGUF models with direct native loading
+- Smart fallback system between providers
+- File input support for direct text file embedding
+- Batch processing capabilities
+
+### Changed
+- Simplified installation - zero setup required
+- Updated README with modern usage examples
+- Improved error handling and logging
+- Better TypeScript support with comprehensive types
+
+### Fixed
+- Native module compilation issues
+- Provider detection and fallback logic
+- Memory management for native embeddings
+
+### Providers
+- **OpenAI**: text-embedding-3-small, text-embedding-3-large
+- **Google Gemini**: gemini-embedding-001
+- **Mistral**: mistral-embed
+- **Llama.cpp**: Native N-API with GGUF support
+
+## [0.2.1] - Previous
+
+### Added
+- Multi-provider support
+- Basic embedding functionality
+- TypeScript definitions

package/README.md

@@ -1,123 +1,155 @@
-# vecbox v0.1.0
+# Vecbox
 
 ![vecbox](./src/images/vecbox.png)
-[![npm version](https://img.shields.io/npm/v/vecbox.svg)](https://www.npmjs.com/package/vecbox)
+[![npm version](https://img.shields.io/npm/v/vecbox.svg)](https://www.npmjs.org/package/vecbox)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-## Why vecbox?
+**One API, multiple providers.** Switch between OpenAI, Gemini, Mistral, or run locally with Llama.cpp using native N-API performance.
 
-**One API, multiple providers.** Switch between OpenAI, Gemini, or run locally with Llama.cpp without changing code.
 ```typescript
-// Works with any provider
+import { autoEmbed } from 'vecbox';
+
+// Works with any provider - auto-detects the best available
 const result = await autoEmbed({ text: 'Hello, world!' });
 console.log(result.embedding); // [0.1, 0.2, ...]
+console.log(result.provider);  // 'llamacpp' | 'openai' | 'gemini' | 'mistral'
 ```
 
 ## Installation
+
 ```bash
-  npm install vacbox
-  pnpm add vacbox
+npm install vecbox
+# or
+pnpm add vecbox
 ```
 
+**Zero setup required!** Everything is included - native N-API module automatically compiled during installation.
+
 ## Quick Start
 
-### Auto-detect (Recommended)
+### Auto-detection (Recommended)
+
 ```typescript
 import { autoEmbed } from 'vecbox';
 
+// Automatically picks the best available provider
 const result = await autoEmbed({ text: 'Your text' });
-// Automatically uses: Llama.cpp (local) → OpenAI → Gemini → ...
+console.log(result.embedding); // [0.1, 0.2, ...]
+console.log(result.provider);  // 'llamacpp' | 'openai' | 'gemini' | 'mistral'
 ```
 
 ### Specific Provider
+
 ```typescript
 import { embed } from 'vecbox';
 
+// Use specific provider
 const result = await embed(
   { provider: 'openai', apiKey: process.env.OPENAI_API_KEY },
   { text: 'Your text' }
 );
 ```
 
-## Providers
+### File Input
 
-<details>
-<summary><b>OpenAI</b></summary>
 ```typescript
-await embed(
-  {
-    provider: 'openai',
-    model: 'text-embedding-3-small', // or text-embedding-3-large
-    apiKey: process.env.OPENAI_API_KEY
-  },
-  { text: 'Your text' }
+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' }
 );
 ```
 
-**Setup:** Get API key at [platform.openai.com](https://platform.openai.com)
-
-</details>
+### Batch Processing
 
-<details>
-<summary><b>Google Gemini</b></summary>
 ```typescript
-await embed(
-  {
-    provider: 'gemini',
-    model: 'gemini-embedding-001',
-    apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY
-  },
-  { text: 'Your text' }
+import { embed } from 'vecbox';
+
+const inputs = [
+  { text: 'First text' },
+  { text: 'Second text' },
+  { text: 'Third text' }
+];
+
+const result = await embed(
+  { provider: 'mistral', apiKey: process.env.MISTRAL_API_KEY },
+  inputs
 );
+
+console.log(result.embeddings.length); // 3
 ```
 
-**Setup:** Get API key at [aistudio.google.com](https://aistudio.google.com)
+## 🚀 Local Llama.cpp with Native N-API
 
-</details>
+**Automatic Native Detection:**
+```typescript
+import { autoEmbed } from 'vecbox';
 
-<details>
-<summary><b>Llama.cpp (Local)</b></summary>
+// Automatically uses native N-API when available
+const result = await autoEmbed({ text: 'Your text' });
+console.log(result.provider); // 'llamacpp' (native)
+```
+
+**Manual Native Configuration:**
 ```typescript
-await embed(
-  { provider: 'llamacpp', model: 'nomic-embed-text-v1.5.Q4_K_M.gguf' },
+import { embed } from 'vecbox';
+
+// Force native module usage
+const result = await embed(
+  { provider: 'llamacpp', model: './models/nomic-embed-text-v1.5.Q4_K_M.gguf' },
   { text: 'Your text' }
 );
 ```
 
-**Setup:**
+**Setup for Local Models:**
 ```bash
-# 1. Install
-git clone https://github.com/ggerganov/llama.cpp
-cd llama.cpp && make llama-server
-
-# 2. Download model
+# 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
 
-# 3. Run server
-./llama-server -m nomic-embed-text-v1.5.Q4_K_M.gguf --embedding --port 8080
+# Place it in your project directory
+mkdir models && mv nomic-embed-text-v1.5.Q4_K_M.gguf models/
 ```
 
-</details>
+## 🌍 Environment Variables
 
-<details>
-<summary><b>Anthropic Claude</b></summary>
+```bash
+# .env file
+OPENAI_API_KEY=sk-...
+GOOGLE_GENERATIVE_AI_API_KEY=...
+MISTRAL_API_KEY=...
+```
+
+## 📚 Providers
+
+### OpenAI
 ```typescript
 await embed(
   {
-    provider: 'claude',
-    model: 'claude-3-sonnet-20240229',
-    apiKey: process.env.ANTHROPIC_API_KEY
+    provider: 'openai',
+    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 [console.anthropic.com](https://console.anthropic.com)
-
-</details>
+### Google Gemini
+```typescript
+await embed(
+  {
+    provider: 'gemini',
+    model: 'gemini-embedding-001',
+    apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY
+  },
+  { text: 'Your text' }
+);
+```
+**Setup:** Get API key at [aistudio.google.com](https://aistudio.google.com)
 
-<details>
-<summary><b>Mistral</b></summary>
+### Mistral
 ```typescript
 await embed(
   {
@@ -128,33 +160,70 @@ await embed(
   { text: 'Your text' }
 );
 ```
-
 **Setup:** Get API key at [mistral.ai](https://mistral.ai)
 
-</details>
-
-<details>
-<summary><b>DeepSeek</b></summary>
+### Llama.cpp (Local)
 ```typescript
 await embed(
-  {
-    provider: 'deepseek',
-    model: 'deepseek-chat',
-    apiKey: process.env.DEEPSEEK_API_KEY
-  },
+  { 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
+
+## 🚀 Features
+
+- **🎯 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
+
+## 📖 API Reference
+
+### `autoEmbed(input)`
+
+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)
+
+```typescript
+await autoEmbed({ text: string } | { filePath: string })
+```
 
-**Setup:** Get API key at [platform.deepseek.com](https://platform.deepseek.com)
+### `embed(config, input)`
+
+Explicit provider selection.
+```typescript
+await embed(
+  { provider, model?, apiKey?, baseUrl?, timeout?, maxRetries? },
+  { text: string } | { filePath: string } | Array
+)
+```
 
-</details>
+**Returns:**
+```typescript
+{
+  embedding: number[],
+  dimensions: number,
+  provider: string,
+  model: string,
+  usage?: {
+    promptTokens?: number;
+    totalTokens?: number;
+  }
+}
+```
 
-## Common Use Cases
+## 🧪 Examples
 
 ### Semantic Search
 ```typescript
-// Helper function for cosine similarity
 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));
@@ -175,40 +244,6 @@ const mostSimilar = scores.indexOf(Math.max(...scores));
 console.log(`Best match: ${documents[mostSimilar]}`);
 ```
 
-### Text Similarity
-```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);
-}
-
-const [emb1, emb2] = await Promise.all([
-  autoEmbed({ text: 'cat sleeping' }),
-  autoEmbed({ text: 'cat napping' })
-]);
-
-const similarity = cosineSimilarity(emb1.embedding, emb2.embedding);
-console.log(`Similarity: ${similarity.toFixed(3)}`); // → 0.95 (very similar)
-```
-
-### Batch Processing
-```typescript
-const results = await embed(
-  { provider: 'openai', apiKey: 'key' },
-  [
-    { text: 'Text 1' },
-    { text: 'Text 2' },
-    { filePath: './doc.txt' }
-  ]
-);
-// → { embeddings: [[...], [...], [...]], dimensions: 1536 }
-
-console.log(`Processed ${results.embeddings.length} texts`);
-console.log(`Dimensions: ${results.dimensions}`);
-```
-
 ### File Processing
 ```typescript
 import { readdir } from 'fs/promises';
@@ -237,142 +272,42 @@ const embeddings = await embedAllFiles('./documents');
 console.log(`Processed ${embeddings.length} files`);
 ```
 
-## API
+## 🐛 Troubleshooting
 
-### `autoEmbed(input)`
+### Native Module Issues
 
-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. **Claude** (if API key available)
-5. **Mistral** (if API key available)
-6. **DeepSeek** (if API key available)
-
-```typescript
-await autoEmbed({ text: string } | { filePath: string })
-```
-
-### `embed(config, input)`
-
-Explicit provider selection.
-```typescript
-await embed(
-  { provider, model?, apiKey?, baseUrl?, timeout?, maxRetries? },
-  { text: string } | { filePath: string } | Array
-)
-```
-
-**Returns:**
-```typescript
-{
-  embedding: number[],
-  dimensions: number,
-  provider: string,
-  model: string,
-  usage?: {
-    promptTokens?: number;
-    totalTokens?: number;
-  }
-}
-```
-
-### `getSupportedProviders()`
-
-Returns available providers.
-```typescript
-import { getSupportedProviders } from 'embedbox';
-
-const providers = getSupportedProviders();
-// → ['openai', 'gemini', 'claude', 'mistral', 'deepseek', 'llamacpp']
-```
-
-### `createProvider(config)`
-
-Create provider instance for advanced usage.
-```typescript
-import { createProvider } from 'embedbox';
-
-const provider = createProvider({
-  provider: 'openai',
-  model: 'text-embedding-3-small',
-  apiKey: 'your-key'
-});
-
-const isReady = await provider.isReady();
-if (isReady) {
-  const result = await provider.embed({ text: 'Hello' });
-}
-```
-
-## Environment Variables
+**Problem:** `binding.createModel is not a function`
 ```bash
-# .env file
-OPENAI_API_KEY=sk-...
-GOOGLE_GENERATIVE_AI_API_KEY=...
-ANTHROPIC_API_KEY=sk-ant-...
-MISTRAL_API_KEY=...
-DEEPSEEK_API_KEY=...
+# Solution: Rebuild native module
+npm run build:native
 ```
 
-## Error Handling
-
-```typescript
-import { autoEmbed } from 'embedbox';
-
-try {
-  const result = await autoEmbed({ text: 'Hello' });
-  console.log(result.embedding);
-} catch (error) {
-  if (error.message.includes('API key')) {
-    console.error('Please set up your API keys in .env');
-  } else if (error.message.includes('not ready')) {
-    console.error('Provider is not available');
-  } else if (error.message.includes('network')) {
-    console.error('Network connection failed');
-  } else {
-    console.error('Embedding failed:', error.message);
-  }
-}
+**Problem:** Model file not found
+```bash
+# Solution: Check model path
+ls -la models/  # Verify model exists
 ```
 
-## TypeScript Support
+### Performance Issues
 
-Full TypeScript support with type definitions:
-```typescript
-import { 
-  autoEmbed, 
-  embed, 
-  getSupportedProviders, 
-  createProvider,
-  type EmbedConfig,
-  type EmbedInput,
-  type EmbedResult 
-} from 'embedbox';
-
-// Full type safety
-const config: EmbedConfig = {
-  provider: 'openai',
-  model: 'text-embedding-3-small'
-};
-
-const input: EmbedInput = {
-  text: 'Your text here'
-};
-
-const result: EmbedResult = await embed(config, input);
-```
+**Slow embeddings:**
+- Check model size (smaller = faster)
+- Use batch processing for multiple texts
+- Ensure native module is being used (not HTTP fallback)
 
-## License
+## 📄 License
 
-MIT © Embedbox Team
+MIT License - see [LICENSE](LICENSE) file for details.
 
-## Links
+## 🙏 Acknowledgments
 
-- [npm](https://www.npmjs.com/package/embedbox)
-- [GitHub](https://github.com/embedbox/embedbox)
-- [Documentation](https://embedbox.dev)
+- [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
 
 ---
 
-**Embedbox v1.0.0** - One API, multiple providers. Simple embeddings.
+**⭐ Star us on GitHub!** [github.com/box-safe/vecbox](https://github.com/box-safe/vecbox)
+
+**Made with ❤️ by the Vecbox Team**