ruvector 0.1.38 → 0.1.40

package/dist/services/embedding-service.js

@@ -0,0 +1,294 @@
+"use strict";
+/**
+ * Embedding Service - Unified embedding generation and management
+ *
+ * This service provides a unified interface for generating, caching, and
+ * managing embeddings from various sources (local models, APIs, etc.)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmbeddingService = exports.LocalNGramProvider = exports.MockEmbeddingProvider = void 0;
+exports.createEmbeddingService = createEmbeddingService;
+exports.getDefaultEmbeddingService = getDefaultEmbeddingService;
+/**
+ * Simple hash function for cache keys
+ */
+function hashText(text) {
+    let hash = 0;
+    for (let i = 0; i < text.length; i++) {
+        const char = text.charCodeAt(i);
+        hash = ((hash << 5) - hash) + char;
+        hash = hash & hash;
+    }
+    return `h${hash.toString(36)}`;
+}
+/**
+ * Mock embedding provider for testing
+ */
+class MockEmbeddingProvider {
+    constructor(dimensions = 384) {
+        this.name = 'mock';
+        this.dimensions = dimensions;
+    }
+    async embed(texts) {
+        return texts.map(text => {
+            // Generate deterministic pseudo-random embeddings based on text
+            const embedding = [];
+            let seed = 0;
+            for (let i = 0; i < text.length; i++) {
+                seed = ((seed << 5) - seed + text.charCodeAt(i)) | 0;
+            }
+            for (let i = 0; i < this.dimensions; i++) {
+                seed = (seed * 1103515245 + 12345) | 0;
+                embedding.push((seed % 1000) / 1000 - 0.5);
+            }
+            // Normalize
+            const norm = Math.sqrt(embedding.reduce((s, v) => s + v * v, 0));
+            return embedding.map(v => v / (norm || 1));
+        });
+    }
+    getDimensions() {
+        return this.dimensions;
+    }
+}
+exports.MockEmbeddingProvider = MockEmbeddingProvider;
+/**
+ * Simple local embedding using character n-grams
+ * This is a fallback when no external provider is available
+ */
+class LocalNGramProvider {
+    constructor(dimensions = 256, ngramSize = 3) {
+        this.name = 'local-ngram';
+        this.dimensions = dimensions;
+        this.ngramSize = ngramSize;
+    }
+    async embed(texts) {
+        return texts.map(text => this.embedSingle(text));
+    }
+    embedSingle(text) {
+        const embedding = new Array(this.dimensions).fill(0);
+        const normalized = text.toLowerCase().replace(/[^a-z0-9]/g, ' ');
+        // Generate n-grams and hash them into embedding dimensions
+        for (let i = 0; i <= normalized.length - this.ngramSize; i++) {
+            const ngram = normalized.slice(i, i + this.ngramSize);
+            const hash = this.hashNgram(ngram);
+            const idx = Math.abs(hash) % this.dimensions;
+            embedding[idx] += hash > 0 ? 1 : -1;
+        }
+        // Normalize
+        const norm = Math.sqrt(embedding.reduce((s, v) => s + v * v, 0));
+        return embedding.map(v => v / (norm || 1));
+    }
+    hashNgram(ngram) {
+        let hash = 0;
+        for (let i = 0; i < ngram.length; i++) {
+            hash = ((hash << 5) - hash + ngram.charCodeAt(i)) | 0;
+        }
+        return hash;
+    }
+    getDimensions() {
+        return this.dimensions;
+    }
+}
+exports.LocalNGramProvider = LocalNGramProvider;
+/**
+ * Embedding service with caching and batching
+ */
+class EmbeddingService {
+    constructor(config = {}) {
+        this.providers = new Map();
+        this.cache = new Map();
+        this.config = {
+            defaultProvider: config.defaultProvider ?? 'local-ngram',
+            maxCacheSize: config.maxCacheSize ?? 10000,
+            cacheTtl: config.cacheTtl ?? 3600000, // 1 hour
+            batchSize: config.batchSize ?? 32,
+        };
+        // Register default providers
+        this.registerProvider(new LocalNGramProvider());
+        this.registerProvider(new MockEmbeddingProvider());
+    }
+    /**
+     * Register an embedding provider
+     */
+    registerProvider(provider) {
+        this.providers.set(provider.name, provider);
+    }
+    /**
+     * Get a registered provider
+     */
+    getProvider(name) {
+        const providerName = name ?? this.config.defaultProvider;
+        const provider = this.providers.get(providerName);
+        if (!provider) {
+            throw new Error(`Provider not found: ${providerName}`);
+        }
+        return provider;
+    }
+    /**
+     * Generate embeddings for texts with caching
+     *
+     * @param texts - Texts to embed
+     * @param provider - Provider name (uses default if not specified)
+     * @returns Array of embeddings
+     */
+    async embed(texts, provider) {
+        const providerInstance = this.getProvider(provider);
+        const providerName = providerInstance.name;
+        const now = Date.now();
+        // Check cache and collect texts that need embedding
+        const results = new Array(texts.length).fill(null);
+        const uncachedIndices = [];
+        const uncachedTexts = [];
+        for (let i = 0; i < texts.length; i++) {
+            const cacheKey = `${providerName}:${hashText(texts[i])}`;
+            const cached = this.cache.get(cacheKey);
+            if (cached && now - cached.timestamp < this.config.cacheTtl) {
+                results[i] = cached.embedding;
+                cached.hits++;
+            }
+            else {
+                uncachedIndices.push(i);
+                uncachedTexts.push(texts[i]);
+            }
+        }
+        // Generate embeddings for uncached texts in batches
+        if (uncachedTexts.length > 0) {
+            const batches = [];
+            for (let i = 0; i < uncachedTexts.length; i += this.config.batchSize) {
+                batches.push(uncachedTexts.slice(i, i + this.config.batchSize));
+            }
+            let batchOffset = 0;
+            for (const batch of batches) {
+                const embeddings = await providerInstance.embed(batch);
+                for (let j = 0; j < embeddings.length; j++) {
+                    const originalIndex = uncachedIndices[batchOffset + j];
+                    results[originalIndex] = embeddings[j];
+                    // Cache the result
+                    const cacheKey = `${providerName}:${hashText(texts[originalIndex])}`;
+                    this.addToCache(cacheKey, embeddings[j], now);
+                }
+                batchOffset += batch.length;
+            }
+        }
+        return results;
+    }
+    /**
+     * Generate a single embedding
+     */
+    async embedOne(text, provider) {
+        const results = await this.embed([text], provider);
+        return results[0];
+    }
+    /**
+     * Add entry to cache with LRU eviction
+     */
+    addToCache(key, embedding, timestamp) {
+        // Evict old entries if cache is full
+        if (this.cache.size >= this.config.maxCacheSize) {
+            // Find and remove least recently used entry
+            let oldestKey = '';
+            let oldestTime = Infinity;
+            let lowestHits = Infinity;
+            for (const [k, v] of this.cache.entries()) {
+                if (v.hits < lowestHits || (v.hits === lowestHits && v.timestamp < oldestTime)) {
+                    oldestKey = k;
+                    oldestTime = v.timestamp;
+                    lowestHits = v.hits;
+                }
+            }
+            if (oldestKey) {
+                this.cache.delete(oldestKey);
+            }
+        }
+        this.cache.set(key, { embedding, timestamp, hits: 0 });
+    }
+    /**
+     * Compute cosine similarity between two embeddings
+     */
+    cosineSimilarity(a, b) {
+        if (a.length !== b.length) {
+            throw new Error('Embeddings must have same dimensions');
+        }
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        const denom = Math.sqrt(normA) * Math.sqrt(normB);
+        return denom === 0 ? 0 : dotProduct / denom;
+    }
+    /**
+     * Find most similar texts from a corpus
+     */
+    async findSimilar(query, corpus, k = 5, provider) {
+        const [queryEmbed, ...corpusEmbeds] = await this.embed([query, ...corpus], provider);
+        const results = corpusEmbeds.map((embed, i) => ({
+            text: corpus[i],
+            similarity: this.cosineSimilarity(queryEmbed, embed),
+            index: i,
+        }));
+        return results
+            .sort((a, b) => b.similarity - a.similarity)
+            .slice(0, k);
+    }
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        let totalHits = 0;
+        for (const entry of this.cache.values()) {
+            totalHits += entry.hits;
+        }
+        return {
+            size: this.cache.size,
+            maxSize: this.config.maxCacheSize,
+            hitRate: this.cache.size > 0 ? totalHits / this.cache.size : 0,
+        };
+    }
+    /**
+     * Clear the cache
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * Get embedding dimensions for a provider
+     */
+    getDimensions(provider) {
+        return this.getProvider(provider).getDimensions();
+    }
+    /**
+     * List available providers
+     */
+    listProviders() {
+        return Array.from(this.providers.keys());
+    }
+}
+exports.EmbeddingService = EmbeddingService;
+/**
+ * Create an embedding service instance
+ */
+function createEmbeddingService(config) {
+    return new EmbeddingService(config);
+}
+// Singleton instance
+let defaultService = null;
+/**
+ * Get the default embedding service instance
+ */
+function getDefaultEmbeddingService() {
+    if (!defaultService) {
+        defaultService = new EmbeddingService();
+    }
+    return defaultService;
+}
+exports.default = {
+    EmbeddingService,
+    LocalNGramProvider,
+    MockEmbeddingProvider,
+    createEmbeddingService,
+    getDefaultEmbeddingService,
+};

package/dist/services/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Services module exports
+ */
+export * from './embedding-service';
+export { default as embeddingService } from './embedding-service';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/services/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Services module exports
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.embeddingService = void 0;
+__exportStar(require("./embedding-service"), exports);
+var embedding_service_1 = require("./embedding-service");
+Object.defineProperty(exports, "embeddingService", { enumerable: true, get: function () { return __importDefault(embedding_service_1).default; } });

package/dist/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Vector entry representing a document with its embedding
+ */
+export interface VectorEntry {
+    /** Unique identifier for the vector */
+    id: string;
+    /** Vector embedding (array of floats) */
+    vector: number[];
+    /** Optional metadata associated with the vector */
+    metadata?: Record<string, any>;
+}
+/**
+ * Search query parameters
+ */
+export interface SearchQuery {
+    /** Query vector to search for */
+    vector: number[];
+    /** Number of results to return */
+    k?: number;
+    /** Optional metadata filters */
+    filter?: Record<string, any>;
+    /** Minimum similarity threshold (0-1) */
+    threshold?: number;
+}
+/**
+ * Search result containing matched vector and similarity score
+ */
+export interface SearchResult {
+    /** ID of the matched vector */
+    id: string;
+    /** Similarity score (0-1, higher is better) */
+    score: number;
+    /** Vector data */
+    vector: number[];
+    /** Associated metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Database configuration options
+ */
+export interface DbOptions {
+    /** Vector dimension size */
+    dimension: number;
+    /** Distance metric to use */
+    metric?: 'cosine' | 'euclidean' | 'dot';
+    /** Path to persist database */
+    path?: string;
+    /** Enable auto-persistence */
+    autoPersist?: boolean;
+    /** HNSW index parameters */
+    hnsw?: {
+        /** Maximum number of connections per layer */
+        m?: number;
+        /** Size of the dynamic candidate list */
+        efConstruction?: number;
+        /** Size of the dynamic candidate list for search */
+        efSearch?: number;
+    };
+}
+/**
+ * Database statistics
+ */
+export interface DbStats {
+    /** Total number of vectors */
+    count: number;
+    /** Vector dimension */
+    dimension: number;
+    /** Distance metric */
+    metric: string;
+    /** Memory usage in bytes */
+    memoryUsage?: number;
+    /** Index type */
+    indexType?: string;
+}
+/**
+ * Main VectorDB class interface
+ */
+export interface VectorDB {
+    /**
+     * Create a new vector database
+     * @param options Database configuration
+     */
+    new (options: DbOptions): VectorDB;
+    /**
+     * Insert a single vector
+     * @param entry Vector entry to insert
+     */
+    insert(entry: VectorEntry): void;
+    /**
+     * Insert multiple vectors in batch
+     * @param entries Array of vector entries
+     */
+    insertBatch(entries: VectorEntry[]): void;
+    /**
+     * Search for similar vectors
+     * @param query Search query parameters
+     * @returns Array of search results
+     */
+    search(query: SearchQuery): SearchResult[];
+    /**
+     * Get vector by ID
+     * @param id Vector ID
+     * @returns Vector entry or null
+     */
+    get(id: string): VectorEntry | null;
+    /**
+     * Delete vector by ID
+     * @param id Vector ID
+     * @returns true if deleted, false if not found
+     */
+    delete(id: string): boolean;
+    /**
+     * Update vector metadata
+     * @param id Vector ID
+     * @param metadata New metadata
+     */
+    updateMetadata(id: string, metadata: Record<string, any>): void;
+    /**
+     * Get database statistics
+     */
+    stats(): DbStats;
+    /**
+     * Save database to disk
+     * @param path Optional path (uses configured path if not provided)
+     */
+    save(path?: string): void;
+    /**
+     * Load database from disk
+     * @param path Path to database file
+     */
+    load(path: string): void;
+    /**
+     * Clear all vectors from database
+     */
+    clear(): void;
+    /**
+     * Build HNSW index for faster search
+     */
+    buildIndex(): void;
+    /**
+     * Optimize database (rebuild indices, compact storage)
+     */
+    optimize(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/examples/api-usage.js

@@ -0,0 +1,211 @@
+#!/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/');