ruvector 0.1.99 → 0.2.0

package/PACKAGE_SUMMARY.md

@@ -1,409 +0,0 @@
-# ruvector Package Summary
-
-## Overview
-
-The main `ruvector` package provides a unified interface for high-performance vector database operations in Node.js, with automatic platform detection and smart fallback between native (Rust) and WASM implementations.
-
-## Package Structure
-
-```
-/workspaces/ruvector/npm/packages/ruvector/
-├── src/                    # TypeScript source
-│   ├── index.ts           # Smart loader with platform detection
-│   └── types.ts           # TypeScript type definitions
-├── dist/                   # Compiled JavaScript and types
-│   ├── index.js           # Main entry point
-│   ├── index.d.ts         # Type definitions
-│   ├── types.js           # Compiled types
-│   └── types.d.ts         # Type definitions
-├── bin/
-│   └── cli.js             # CLI tool
-├── test/
-│   ├── mock-implementation.js  # Mock VectorDB for testing
-│   ├── standalone-test.js      # Package structure tests
-│   └── integration.js          # Integration tests
-├── examples/
-│   ├── api-usage.js       # API usage examples
-│   └── cli-demo.sh        # CLI demonstration
-├── package.json           # NPM package configuration
-├── tsconfig.json          # TypeScript configuration
-└── README.md             # Package documentation
-```
-
-## Key Features
-
-### 1. Smart Platform Detection
-
-The package automatically detects and loads the best available implementation:
-
-```typescript
-// Tries to load in this order:
-// 1. @ruvector/core (native Rust, fastest)
-// 2. @ruvector/wasm (WebAssembly, universal fallback)
-
-import { VectorDB, getImplementationType, isNative, isWasm } from 'ruvector';
-
-console.log(getImplementationType()); // 'native' or 'wasm'
-console.log(isNative());              // true if using native
-console.log(isWasm());                // true if using WASM
-```
-
-### 2. Complete TypeScript Support
-
-Full type definitions for all APIs:
-
-```typescript
-interface VectorEntry {
-  id: string;
-  vector: number[];
-  metadata?: Record<string, any>;
-}
-
-interface SearchQuery {
-  vector: number[];
-  k?: number;
-  filter?: Record<string, any>;
-  threshold?: number;
-}
-
-interface SearchResult {
-  id: string;
-  score: number;
-  vector: number[];
-  metadata?: Record<string, any>;
-}
-
-interface DbOptions {
-  dimension: number;
-  metric?: 'cosine' | 'euclidean' | 'dot';
-  path?: string;
-  autoPersist?: boolean;
-  hnsw?: {
-    m?: number;
-    efConstruction?: number;
-    efSearch?: number;
-  };
-}
-```
-
-### 3. VectorDB API
-
-Comprehensive vector database operations:
-
-```typescript
-const db = new VectorDB({
-  dimension: 384,
-  metric: 'cosine'
-});
-
-// Insert operations
-db.insert({ id: 'doc1', vector: [...], metadata: {...} });
-db.insertBatch([...entries]);
-
-// Search operations
-const results = db.search({
-  vector: [...],
-  k: 10,
-  threshold: 0.7
-});
-
-// CRUD operations
-const entry = db.get('doc1');
-db.updateMetadata('doc1', { updated: true });
-db.delete('doc1');
-
-// Database management
-const stats = db.stats();
-db.save('./mydb.vec');
-db.load('./mydb.vec');
-db.buildIndex();
-db.optimize();
-```
-
-### 4. CLI Tools
-
-Command-line interface for database operations:
-
-```bash
-# Create database
-ruvector create mydb.vec --dimension 384 --metric cosine
-
-# Insert vectors
-ruvector insert mydb.vec vectors.json --batch-size 1000
-
-# Search
-ruvector search mydb.vec --vector "[0.1,0.2,...]" --top-k 10
-
-# Statistics
-ruvector stats mydb.vec
-
-# Benchmark
-ruvector benchmark --num-vectors 10000 --num-queries 1000
-
-# Info
-ruvector info
-```
-
-## API Reference
-
-### Constructor
-
-```typescript
-new VectorDB(options: DbOptions): VectorDB
-```
-
-### Methods
-
-- `insert(entry: VectorEntry): void` - Insert single vector
-- `insertBatch(entries: VectorEntry[]): void` - Batch insert
-- `search(query: SearchQuery): SearchResult[]` - Search similar vectors
-- `get(id: string): VectorEntry | null` - Get by ID
-- `delete(id: string): boolean` - Delete vector
-- `updateMetadata(id: string, metadata: Record<string, any>): void` - Update metadata
-- `stats(): DbStats` - Get database statistics
-- `save(path?: string): void` - Save to disk
-- `load(path: string): void` - Load from disk
-- `clear(): void` - Clear all vectors
-- `buildIndex(): void` - Build HNSW index
-- `optimize(): void` - Optimize database
-
-### Utility Functions
-
-- `getImplementationType(): 'native' | 'wasm'` - Get current implementation
-- `isNative(): boolean` - Check if using native
-- `isWasm(): boolean` - Check if using WASM
-- `getVersion(): { version: string, implementation: string }` - Get version info
-
-## Dependencies
-
-### Production Dependencies
-
-- `commander` (^11.1.0) - CLI framework
-- `chalk` (^4.1.2) - Terminal styling
-- `ora` (^5.4.1) - Spinners and progress
-
-### Optional Dependencies
-
-- `@ruvector/core` (^0.1.1) - Native Rust bindings (when available)
-- `@ruvector/wasm` (^0.1.1) - WebAssembly module (fallback)
-
-### Dev Dependencies
-
-- `typescript` (^5.3.3) - TypeScript compiler
-- `@types/node` (^20.10.5) - Node.js type definitions
-
-## Package.json Configuration
-
-```json
-{
-  "name": "ruvector",
-  "version": "0.1.1",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "ruvector": "./bin/cli.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "node test/standalone-test.js"
-  }
-}
-```
-
-## Build Process
-
-```bash
-# Install dependencies
-npm install
-
-# Build TypeScript
-npm run build
-
-# Run tests
-npm test
-
-# Package for NPM
-npm pack
-```
-
-## Testing
-
-The package includes comprehensive tests:
-
-### 1. Standalone Test (`test/standalone-test.js`)
-
-Tests package structure and API using mock implementation:
-- Package structure validation
-- TypeScript type definitions
-- VectorDB API functionality
-- CLI structure
-- Smart loader logic
-
-### 2. Integration Test (`test/integration.js`)
-
-Tests integration with real implementations when available.
-
-### 3. Mock Implementation (`test/mock-implementation.js`)
-
-JavaScript-based VectorDB implementation for testing and demonstration purposes.
-
-## Examples
-
-### API Usage (`examples/api-usage.js`)
-
-Demonstrates:
-- Basic CRUD operations
-- Batch operations
-- Semantic search
-- Different distance metrics
-- Performance benchmarking
-- Persistence
-
-### CLI Demo (`examples/cli-demo.sh`)
-
-Bash script demonstrating CLI tools.
-
-## Usage Examples
-
-### Simple Vector Search
-
-```javascript
-const { VectorDB } = require('ruvector');
-
-const db = new VectorDB({ dimension: 3 });
-
-db.insertBatch([
-  { id: 'cat', vector: [0.9, 0.1, 0.1], metadata: { animal: 'cat' } },
-  { id: 'dog', vector: [0.1, 0.9, 0.1], metadata: { animal: 'dog' } },
-  { id: 'tiger', vector: [0.8, 0.2, 0.15], metadata: { animal: 'tiger' } }
-]);
-
-const results = db.search({
-  vector: [0.9, 0.1, 0.1],
-  k: 2
-});
-
-console.log(results);
-// [
-//   { id: 'cat', score: 1.0, ... },
-//   { id: 'tiger', score: 0.97, ... }
-// ]
-```
-
-### Semantic Document Search
-
-```javascript
-const db = new VectorDB({ dimension: 768, metric: 'cosine' });
-
-// Insert documents with embeddings (from your embedding model)
-db.insertBatch([
-  { id: 'doc1', vector: embedding1, metadata: { title: 'AI Guide' } },
-  { id: 'doc2', vector: embedding2, metadata: { title: 'Web Dev' } }
-]);
-
-// Search with query embedding
-const results = db.search({
-  vector: queryEmbedding,
-  k: 10,
-  threshold: 0.7
-});
-```
-
-### Persistence
-
-```javascript
-const db = new VectorDB({
-  dimension: 384,
-  path: './vectors.db',
-  autoPersist: true
-});
-
-// Changes automatically saved
-db.insert({ id: 'doc1', vector: [...] });
-
-// Or manual save
-db.save('./backup.db');
-
-// Load from disk
-db.load('./vectors.db');
-```
-
-## Performance Characteristics
-
-### Mock Implementation (JavaScript)
-- Insert: ~1M vectors/sec (batch)
-- Search: ~400 queries/sec (1000 vectors, k=10)
-
-### Native Implementation (Rust)
-- Insert: ~10M+ vectors/sec (batch)
-- Search: ~100K+ queries/sec with HNSW index
-- 150x faster than pgvector
-
-### WASM Implementation
-- Insert: ~1M+ vectors/sec (batch)
-- Search: ~10K+ queries/sec with HNSW index
-- ~10x faster than pure JavaScript
-
-## Integration with Other Packages
-
-This package serves as the main interface and coordinates between:
-
-1. **@ruvector/core** - Native Rust bindings (napi-rs)
-   - Platform-specific native modules
-   - Maximum performance
-   - Optional dependency
-
-2. **@ruvector/wasm** - WebAssembly module
-   - Universal compatibility
-   - Near-native performance
-   - Fallback implementation
-
-## Error Handling
-
-The package provides clear error messages when implementations are unavailable:
-
-```
-Failed to load ruvector: Neither native nor WASM implementation available.
-Native error: Cannot find module '@ruvector/core'
-WASM error: Cannot find module '@ruvector/wasm'
-```
-
-## Environment Variables
-
-- `RUVECTOR_DEBUG=1` - Enable debug logging for implementation loading
-
-## Next Steps
-
-To complete the package ecosystem:
-
-1. **Create @ruvector/core**
-   - napi-rs bindings to Rust code
-   - Platform-specific builds (Linux, macOS, Windows)
-   - Native module packaging
-
-2. **Create @ruvector/wasm**
-   - wasm-pack build from Rust code
-   - WebAssembly module
-   - Universal compatibility layer
-
-3. **Update Dependencies**
-   - Add @ruvector/core as optionalDependency
-   - Add @ruvector/wasm as dependency
-   - Configure proper fallback chain
-
-4. **Publishing**
-   - Publish all three packages to npm
-   - Set up CI/CD for builds
-   - Create platform-specific releases
-
-## Version
-
-Current version: **0.1.1**
-
-## License
-
-MIT
-
-## Repository
-
-https://github.com/ruvnet/ruvector

package/examples/api-usage.js

@@ -1,211 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * ruvector API Usage Examples
- *
- * This demonstrates how to use ruvector in your Node.js applications
- */
-
-// For this demo, we use the mock implementation
-// In production, you would use: const { VectorDB } = require('ruvector');
-const { VectorDB } = require('../test/mock-implementation.js');
-
-console.log('ruvector API Examples\n');
-console.log('='.repeat(60));
-
-// Show info
-console.log('\nUsing: Mock implementation (for demo purposes)');
-console.log('In production: npm install ruvector\n');
-
-// Example 1: Basic usage
-console.log('Example 1: Basic Vector Operations');
-console.log('-'.repeat(60));
-
-const db = new VectorDB({
-  dimension: 3,
-  metric: 'cosine'
-});
-
-// Insert some vectors
-db.insert({
-  id: 'doc1',
-  vector: [1, 0, 0],
-  metadata: { title: 'First Document', category: 'A' }
-});
-
-db.insertBatch([
-  { id: 'doc2', vector: [0, 1, 0], metadata: { title: 'Second Document', category: 'B' } },
-  { id: 'doc3', vector: [0, 0, 1], metadata: { title: 'Third Document', category: 'C' } },
-  { id: 'doc4', vector: [0.7, 0.7, 0], metadata: { title: 'Fourth Document', category: 'A' } }
-]);
-
-console.log('✓ Inserted 4 vectors');
-
-// Get stats
-const stats = db.stats();
-console.log(`✓ Database has ${stats.count} vectors, dimension ${stats.dimension}`);
-
-// Search
-const results = db.search({
-  vector: [1, 0, 0],
-  k: 3
-});
-
-console.log(`✓ Search returned ${results.length} results:`);
-results.forEach((result, i) => {
-  console.log(`  ${i + 1}. ${result.id} (score: ${result.score.toFixed(4)}) - ${result.metadata.title}`);
-});
-
-// Get by ID
-const doc = db.get('doc2');
-console.log(`✓ Retrieved document: ${doc.metadata.title}`);
-
-// Update metadata
-db.updateMetadata('doc1', { updated: true, timestamp: Date.now() });
-console.log('✓ Updated metadata');
-
-// Delete
-db.delete('doc3');
-console.log('✓ Deleted doc3');
-console.log(`✓ Database now has ${db.stats().count} vectors\n`);
-
-// Example 2: Semantic Search Simulation
-console.log('Example 2: Semantic Search Simulation');
-console.log('-'.repeat(60));
-
-const semanticDb = new VectorDB({
-  dimension: 5,
-  metric: 'cosine'
-});
-
-// Simulate document embeddings
-const documents = [
-  { id: 'machine-learning', vector: [0.9, 0.8, 0.1, 0.2, 0.1], metadata: { title: 'Introduction to Machine Learning', topic: 'AI' } },
-  { id: 'deep-learning', vector: [0.85, 0.9, 0.15, 0.25, 0.1], metadata: { title: 'Deep Learning Fundamentals', topic: 'AI' } },
-  { id: 'web-dev', vector: [0.1, 0.2, 0.9, 0.8, 0.1], metadata: { title: 'Web Development Guide', topic: 'Web' } },
-  { id: 'react', vector: [0.15, 0.2, 0.85, 0.9, 0.1], metadata: { title: 'React Tutorial', topic: 'Web' } },
-  { id: 'database', vector: [0.2, 0.3, 0.3, 0.4, 0.9], metadata: { title: 'Database Design', topic: 'Data' } }
-];
-
-semanticDb.insertBatch(documents);
-console.log(`✓ Indexed ${documents.length} documents`);
-
-// Search for AI-related content
-const aiQuery = [0.9, 0.85, 0.1, 0.2, 0.1];
-const aiResults = semanticDb.search({ vector: aiQuery, k: 2 });
-
-console.log('\nQuery: AI-related content');
-console.log('Results:');
-aiResults.forEach((result, i) => {
-  console.log(`  ${i + 1}. ${result.metadata.title} (score: ${result.score.toFixed(4)})`);
-});
-
-// Search for Web-related content
-const webQuery = [0.1, 0.2, 0.9, 0.85, 0.1];
-const webResults = semanticDb.search({ vector: webQuery, k: 2 });
-
-console.log('\nQuery: Web-related content');
-console.log('Results:');
-webResults.forEach((result, i) => {
-  console.log(`  ${i + 1}. ${result.metadata.title} (score: ${result.score.toFixed(4)})`);
-});
-
-// Example 3: Different Distance Metrics
-console.log('\n\nExample 3: Distance Metrics Comparison');
-console.log('-'.repeat(60));
-
-const metrics = ['cosine', 'euclidean', 'dot'];
-const testVectors = [
-  { id: 'v1', vector: [1, 0, 0] },
-  { id: 'v2', vector: [0.7, 0.7, 0] },
-  { id: 'v3', vector: [0, 1, 0] }
-];
-
-metrics.forEach(metric => {
-  const metricDb = new VectorDB({ dimension: 3, metric });
-  metricDb.insertBatch(testVectors);
-
-  const results = metricDb.search({ vector: [1, 0, 0], k: 3 });
-
-  console.log(`\n${metric.toUpperCase()} metric:`);
-  results.forEach((result, i) => {
-    console.log(`  ${i + 1}. ${result.id}: ${result.score.toFixed(4)}`);
-  });
-});
-
-// Example 4: Batch Operations Performance
-console.log('\n\nExample 4: Batch Operations Performance');
-console.log('-'.repeat(60));
-
-const perfDb = new VectorDB({ dimension: 128, metric: 'cosine' });
-
-// Generate random vectors
-const numVectors = 1000;
-const vectors = [];
-for (let i = 0; i < numVectors; i++) {
-  vectors.push({
-    id: `vec_${i}`,
-    vector: Array.from({ length: 128 }, () => Math.random()),
-    metadata: { index: i, batch: Math.floor(i / 100) }
-  });
-}
-
-console.log(`Inserting ${numVectors} vectors...`);
-const insertStart = Date.now();
-perfDb.insertBatch(vectors);
-const insertTime = Date.now() - insertStart;
-
-console.log(`✓ Inserted ${numVectors} vectors in ${insertTime}ms`);
-console.log(`✓ Rate: ${Math.round(numVectors / (insertTime / 1000))} vectors/sec`);
-
-// Search performance
-const numQueries = 100;
-console.log(`\nRunning ${numQueries} searches...`);
-const searchStart = Date.now();
-
-for (let i = 0; i < numQueries; i++) {
-  const query = {
-    vector: Array.from({ length: 128 }, () => Math.random()),
-    k: 10
-  };
-  perfDb.search(query);
-}
-
-const searchTime = Date.now() - searchStart;
-console.log(`✓ Completed ${numQueries} searches in ${searchTime}ms`);
-console.log(`✓ Rate: ${Math.round(numQueries / (searchTime / 1000))} queries/sec`);
-console.log(`✓ Avg latency: ${(searchTime / numQueries).toFixed(2)}ms`);
-
-// Example 5: Persistence (conceptual, would need real implementation)
-console.log('\n\nExample 5: Persistence');
-console.log('-'.repeat(60));
-
-const persistDb = new VectorDB({
-  dimension: 3,
-  metric: 'cosine',
-  path: './my-vectors.db',
-  autoPersist: true
-});
-
-persistDb.insertBatch([
-  { id: 'p1', vector: [1, 0, 0], metadata: { name: 'First' } },
-  { id: 'p2', vector: [0, 1, 0], metadata: { name: 'Second' } }
-]);
-
-console.log('✓ Created database with auto-persist enabled');
-console.log('✓ Insert operations will automatically save to disk');
-console.log('✓ Use db.save(path) for manual saves');
-console.log('✓ Use db.load(path) to restore from disk');
-
-// Summary
-console.log('\n' + '='.repeat(60));
-console.log('\n✅ All examples completed successfully!');
-console.log('\nKey Features Demonstrated:');
-console.log('  • Basic CRUD operations (insert, search, get, update, delete)');
-console.log('  • Batch operations for better performance');
-console.log('  • Multiple distance metrics (cosine, euclidean, dot)');
-console.log('  • Semantic search simulation');
-console.log('  • Performance benchmarking');
-console.log('  • Metadata filtering and updates');
-console.log('  • Persistence (save/load)');
-console.log('\nFor more examples, see: /workspaces/ruvector/npm/packages/ruvector/examples/');

package/examples/cli-demo.sh

@@ -1,85 +0,0 @@
-#!/bin/bash
-
-# ruvector CLI Demo
-# This demonstrates the CLI functionality with a simple example
-
-echo "🚀 ruvector CLI Demo"
-echo "===================="
-echo ""
-
-# 1. Show version info
-echo "1. Checking ruvector info..."
-ruvector info
-echo ""
-
-# 2. Create a database
-echo "2. Creating a new database..."
-ruvector create demo.vec --dimension 3 --metric cosine
-echo ""
-
-# 3. Create sample data
-echo "3. Creating sample vectors..."
-cat > demo-vectors.json << 'EOF'
-[
-  {
-    "id": "cat",
-    "vector": [0.9, 0.1, 0.1],
-    "metadata": {"animal": "cat", "category": "feline"}
-  },
-  {
-    "id": "dog",
-    "vector": [0.1, 0.9, 0.1],
-    "metadata": {"animal": "dog", "category": "canine"}
-  },
-  {
-    "id": "tiger",
-    "vector": [0.8, 0.2, 0.15],
-    "metadata": {"animal": "tiger", "category": "feline"}
-  },
-  {
-    "id": "wolf",
-    "vector": [0.2, 0.8, 0.15],
-    "metadata": {"animal": "wolf", "category": "canine"}
-  },
-  {
-    "id": "lion",
-    "vector": [0.85, 0.15, 0.1],
-    "metadata": {"animal": "lion", "category": "feline"}
-  }
-]
-EOF
-echo "   Created demo-vectors.json with 5 animals"
-echo ""
-
-# 4. Insert vectors
-echo "4. Inserting vectors into database..."
-ruvector insert demo.vec demo-vectors.json
-echo ""
-
-# 5. Show statistics
-echo "5. Database statistics..."
-ruvector stats demo.vec
-echo ""
-
-# 6. Search for cat-like animals
-echo "6. Searching for cat-like animals (vector: [0.9, 0.1, 0.1])..."
-ruvector search demo.vec --vector "[0.9, 0.1, 0.1]" --top-k 3
-echo ""
-
-# 7. Search for dog-like animals
-echo "7. Searching for dog-like animals (vector: [0.1, 0.9, 0.1])..."
-ruvector search demo.vec --vector "[0.1, 0.9, 0.1]" --top-k 3
-echo ""
-
-# 8. Run benchmark
-echo "8. Running performance benchmark..."
-ruvector benchmark --dimension 128 --num-vectors 1000 --num-queries 100
-echo ""
-
-# Cleanup
-echo "9. Cleanup (removing demo files)..."
-rm -f demo.vec demo-vectors.json
-echo "   ✓ Demo files removed"
-echo ""
-
-echo "✅ Demo complete!"