vecbox 0.2.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,42 +1,49 @@
-# 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 vecbox
-  pnpm add vecbox
+npm install vecbox
+# or
+pnpm add vecbox
 ```
 
-**Zero setup required!** Everything is included - no need to download Llama.cpp or compile anything.
+**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';
 
-// Just works - automatically picks the best available provider
+// 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'
 ```
 
 ### 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' }
@@ -44,17 +51,19 @@ const result = await embed(
 ```
 
 ### File Input
+
 ```typescript
 import { embed } from 'vecbox';
 
 // Embed text from files
 const result = await embed(
-  { provider: 'gemini', apiKey: process.env.GEMINI_API_KEY },
+  { provider: 'gemini', apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY },
   { filePath: './document.txt' }
 );
 ```
 
 ### Batch Processing
+
 ```typescript
 import { embed } from 'vecbox';
 
@@ -72,10 +81,49 @@ const result = await embed(
 console.log(result.embeddings.length); // 3
 ```
 
-## Providers
+## 🚀 Local Llama.cpp with Native N-API
 
-<details>
-<summary><b>OpenAI</b></summary>
+**Automatic Native Detection:**
+```typescript
+import { autoEmbed } from 'vecbox';
+
+// Automatically uses native N-API when available
+const result = await autoEmbed({ text: 'Your text' });
+console.log(result.provider); // 'llamacpp' (native)
+```
+
+**Manual Native Configuration:**
+```typescript
+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 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
+
+### OpenAI
 ```typescript
 await embed(
   {
@@ -86,13 +134,9 @@ await embed(
   { text: 'Your text' }
 );
 ```
-
 **Setup:** Get API key at [platform.openai.com](https://platform.openai.com)
 
-</details>
-
-<details>
-<summary><b>Google Gemini</b></summary>
+### Google Gemini
 ```typescript
 await embed(
   {
@@ -103,37 +147,9 @@ await embed(
   { text: 'Your text' }
 );
 ```
-
 **Setup:** Get API key at [aistudio.google.com](https://aistudio.google.com)
 
-</details>
-
-<details>
-<summary><b>Llama.cpp (Local)</b></summary>
-```typescript
-await embed(
-  { provider: 'llamacpp', model: 'nomic-embed-text-v1.5.Q4_K_M.gguf' },
-  { text: 'Your text' }
-);
-```
-
-**Setup:**
-```bash
-# 1. Install
-git clone https://github.com/ggerganov/llama.cpp
-cd llama.cpp && make llama-server
-
-# 2. Download 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
-```
-
-</details>
-
-<details>
-<summary><b>Mistral</b></summary>
+### Mistral
 ```typescript
 await embed(
   {
@@ -144,10 +160,16 @@ await embed(
   { text: 'Your text' }
 );
 ```
-
 **Setup:** Get API key at [mistral.ai](https://mistral.ai)
 
-</details>
+### 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
 
 ## 🚀 Features
 
@@ -160,25 +182,48 @@ await embed(
 - **🛡️ Type Safe** - Full TypeScript support
 - **🌍 Zero Dependencies** - No external downloads or setup required
 
-## 🏆 Why Vecbox?
+## 📖 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 })
+```
+
+### `embed(config, input)`
 
-**vs Other Libraries:**
-- ✅ **Native Llama.cpp** - Others use HTTP, we use direct C++ integration
-- ✅ **Auto-Detection** - Others require manual provider selection
-- ✅ **Zero Setup** - Others need external downloads and configuration
-- ✅ **Multiple Providers** - Others are limited to one provider
-- ✅ **Smart Fallbacks** - Others fail when a provider is unavailable
+Explicit provider selection.
+```typescript
+await embed(
+  { provider, model?, apiKey?, baseUrl?, timeout?, maxRetries? },
+  { text: string } | { filePath: string } | Array
+)
+```
 
-**Performance:**
-- **Llama.cpp Native**: ~50ms per embedding
-- **Cloud Providers**: ~100-300ms per embedding
-- **HTTP Llama.cpp**: ~500ms+ per embedding
+**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));
@@ -199,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';
@@ -261,151 +272,28 @@ const embeddings = await embedAllFiles('./documents');
 console.log(`Processed ${embeddings.length} files`);
 ```
 
-## API
-
-### `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 })
-```
-
-### `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', 'mistral', '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'
-});
+## 🐛 Troubleshooting
 
-const isReady = await provider.isReady();
-if (isReady) {
-  const result = await provider.embed({ text: 'Hello' });
-}
-```
+### Native Module Issues
 
-## 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=...
-```
-
-## 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);
-  }
-}
+# Solution: Rebuild native module
+npm run build:native
 ```
 
-## TypeScript Support
-
-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);
+**Problem:** Model file not found
+```bash
+# Solution: Check model path
+ls -la models/  # Verify model exists
 ```
 
-## 📚 Documentation
-
-- **[API Reference](./API.md)** - Complete API documentation
-- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute to Vecbox
-- **[Troubleshooting](./TROUBLESHOOTING.md)** - Common issues and solutions
-- **[Examples](./examples/)** - Code examples and tutorials
-
-## 🤝 Contributing
+### Performance Issues
 
-We welcome contributions! See our [Contributing Guide](./CONTRIBUTING.md) for:
-- Adding new providers
-- Improving performance
-- Bug fixes and features
-- Documentation improvements
-
-## 🐛 Troubleshooting
-
-Having issues? Check our [Troubleshooting Guide](./TROUBLESHOOTING.md) for:
-- Installation problems
-- Runtime errors
-- Performance issues
-- Common solutions
+**Slow embeddings:**
+- Check model size (smaller = faster)
+- Use batch processing for multiple texts
+- Ensure native module is being used (not HTTP fallback)
 
 ## 📄 License
 
@@ -418,14 +306,8 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - [Google Gemini](https://ai.google.dev/) - Embedding API
 - [Mistral AI](https://mistral.ai/) - Embedding API
 
-## 📞 Support
-
-- **GitHub Issues**: [Report bugs](https://github.com/box-safe/vecbox/issues)
-- **GitHub Discussions**: [Ask questions](https://github.com/box-safe/vecbox/discussions)
-- **Documentation**: [API Reference](./API.md)
-
 ---
 
 **⭐ Star us on GitHub!** [github.com/box-safe/vecbox](https://github.com/box-safe/vecbox)
 
-**Made with ❤️ by the Vecbox Team**
+**Made with ❤️ by the Vecbox Team**