ruvector 0.2.23 → 0.2.26

package/dist/index.js

@@ -0,0 +1,359 @@
+"use strict";
+/**
+ * ruvector - High-performance vector database for Node.js
+ *
+ * This package automatically detects and uses the best available implementation:
+ * 1. Native (Rust-based, fastest) - if available for your platform
+ * 2. RVF (persistent store) - if @ruvector/rvf is installed
+ * 3. Stub (testing fallback) - limited functionality
+ *
+ * Also provides safe wrappers for GNN and Attention modules that handle
+ * array type conversions automatically.
+ */
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Utils = exports.VectorIndex = exports.NativeVectorDb = exports.VectorDB = exports.VectorDb = void 0;
+exports.getImplementationType = getImplementationType;
+exports.isNative = isNative;
+exports.isRvf = isRvf;
+exports.isWasm = isWasm;
+exports.getVersion = getVersion;
+exports.getBackendInfo = getBackendInfo;
+exports.isNativeAvailable = isNativeAvailable;
+__exportStar(require("./types"), exports);
+// Export core wrappers (safe interfaces with automatic type conversion)
+__exportStar(require("./core"), exports);
+__exportStar(require("./services"), exports);
+let implementation;
+let implementationType = 'wasm';
+// Check for explicit --backend rvf flag or RUVECTOR_BACKEND env var
+const rvfRequested = process.env.RUVECTOR_BACKEND === 'rvf' ||
+    process.argv.includes('--backend') && process.argv[process.argv.indexOf('--backend') + 1] === 'rvf';
+if (rvfRequested) {
+    // Explicit rvf backend requested - fail hard if not available
+    try {
+        implementation = require('@ruvector/rvf');
+        implementationType = 'rvf';
+    }
+    catch (e) {
+        throw new Error('@ruvector/rvf is not installed.\n' +
+            '  Run: npm install @ruvector/rvf\n' +
+            '  The --backend rvf flag requires this package.');
+    }
+}
+else {
+    try {
+        // Try to load native module first
+        implementation = require('@ruvector/core');
+        implementationType = 'native';
+        // Verify it's actually working (native module exports VectorDb, not VectorDB)
+        if (typeof implementation.VectorDb !== 'function') {
+            throw new Error('Native module loaded but VectorDb class not found');
+        }
+    }
+    catch (e) {
+        // Try rvf (persistent store) as second fallback
+        try {
+            implementation = require('@ruvector/rvf');
+            implementationType = 'rvf';
+        }
+        catch (rvfErr) {
+            // Graceful fallback - don't crash, just warn
+            console.warn('[RuVector] Native module not available:', e.message);
+            console.warn('[RuVector] RVF module not available:', rvfErr.message);
+            console.warn('[RuVector] Vector operations will be limited. Install @ruvector/core or @ruvector/rvf for full functionality.');
+            // Create a stub implementation that provides basic functionality
+            implementation = {
+                VectorDb: class StubVectorDb {
+                    constructor() {
+                        console.warn('[RuVector] Using stub VectorDb - install @ruvector/core for native performance');
+                    }
+                    async insert() { return 'stub-id-' + Date.now(); }
+                    async insertBatch(entries) { return entries.map(() => 'stub-id-' + Date.now()); }
+                    async search() { return []; }
+                    async delete() { return true; }
+                    async get() { return null; }
+                    async len() { return 0; }
+                    async isEmpty() { return true; }
+                }
+            };
+            implementationType = 'wasm'; // Mark as fallback mode
+        }
+    }
+}
+/**
+ * Get the current implementation type
+ */
+function getImplementationType() {
+    return implementationType;
+}
+/**
+ * Check if native implementation is being used
+ */
+function isNative() {
+    return implementationType === 'native';
+}
+/**
+ * Check if RVF implementation is being used
+ */
+function isRvf() {
+    return implementationType === 'rvf';
+}
+/**
+ * Check if stub/fallback implementation is being used
+ */
+function isWasm() {
+    return implementationType === 'wasm';
+}
+/**
+ * Get version information
+ */
+function getVersion() {
+    const pkg = require('../package.json');
+    return {
+        version: pkg.version,
+        implementation: implementationType
+    };
+}
+/**
+ * Normalize a user-friendly distance metric string (`"cosine"`, `"euclidean"`,
+ * etc.) to the PascalCase variant the native `JsDistanceMetric` enum accepts.
+ * Native: { Euclidean, Cosine, DotProduct, Manhattan }.
+ */
+function normalizeMetric(metric) {
+    if (!metric)
+        return metric;
+    const m = metric.toLowerCase().replace(/[_\s-]/g, '');
+    switch (m) {
+        case 'cosine':
+            return 'Cosine';
+        case 'euclidean':
+        case 'l2':
+            return 'Euclidean';
+        case 'dot':
+        case 'dotproduct':
+        case 'innerproduct':
+            return 'DotProduct';
+        case 'manhattan':
+        case 'l1':
+            return 'Manhattan';
+        default:
+            return metric; // pass through; native will error with the variant list.
+    }
+}
+/**
+ * Wrapper class that automatically handles metadata JSON conversion
+ */
+class VectorDBWrapper {
+    constructor(options) {
+        // Accept both `distanceMetric` (canonical) and `metric` (CLI shorthand).
+        // Normalize to the PascalCase enum variant the native binding expects.
+        const distanceMetric = normalizeMetric(options.distanceMetric ?? options.metric);
+        const nativeOptions = {
+            dimensions: options.dimensions,
+            storagePath: options.storagePath,
+            hnswConfig: options.hnswConfig,
+        };
+        if (distanceMetric !== undefined) {
+            nativeOptions.distanceMetric = distanceMetric;
+        }
+        this.db = new implementation.VectorDb(nativeOptions);
+    }
+    /**
+     * Insert a vector with optional metadata (objects are auto-converted to JSON)
+     */
+    async insert(entry) {
+        const nativeEntry = {
+            id: entry.id,
+            vector: entry.vector instanceof Float32Array ? entry.vector : new Float32Array(entry.vector),
+        };
+        // Auto-convert metadata object to JSON string
+        if (entry.metadata) {
+            nativeEntry.metadata = JSON.stringify(entry.metadata);
+        }
+        return this.db.insert(nativeEntry);
+    }
+    /**
+     * Insert multiple vectors in batch
+     */
+    async insertBatch(entries) {
+        const nativeEntries = entries.map(entry => ({
+            id: entry.id,
+            vector: entry.vector instanceof Float32Array ? entry.vector : new Float32Array(entry.vector),
+            metadata: entry.metadata ? JSON.stringify(entry.metadata) : undefined,
+        }));
+        return this.db.insertBatch(nativeEntries);
+    }
+    /**
+     * Search for similar vectors (metadata is auto-parsed from JSON)
+     */
+    async search(query) {
+        const nativeQuery = {
+            vector: query.vector instanceof Float32Array ? query.vector : new Float32Array(query.vector),
+            k: query.k,
+            efSearch: query.efSearch,
+        };
+        // Auto-convert filter object to JSON string
+        if (query.filter) {
+            nativeQuery.filter = JSON.stringify(query.filter);
+        }
+        const results = await this.db.search(nativeQuery);
+        // Auto-parse metadata JSON strings back to objects
+        return results.map((r) => ({
+            id: r.id,
+            score: r.score,
+            vector: r.vector,
+            metadata: r.metadata ? JSON.parse(r.metadata) : undefined,
+        }));
+    }
+    /**
+     * Get a vector by ID (metadata is auto-parsed from JSON)
+     */
+    async get(id) {
+        const entry = await this.db.get(id);
+        if (!entry)
+            return null;
+        return {
+            id: entry.id,
+            vector: entry.vector,
+            metadata: entry.metadata ? JSON.parse(entry.metadata) : undefined,
+        };
+    }
+    /**
+     * Delete a vector by ID
+     */
+    async delete(id) {
+        return this.db.delete(id);
+    }
+    /**
+     * Get the number of vectors in the database
+     */
+    async len() {
+        return this.db.len();
+    }
+    /**
+     * Check if the database is empty
+     */
+    async isEmpty() {
+        return this.db.isEmpty();
+    }
+}
+// Export the wrapper class (aliased as VectorDB for backwards compatibility)
+exports.VectorDb = VectorDBWrapper;
+exports.VectorDB = VectorDBWrapper;
+// Also export the raw native implementation for advanced users
+exports.NativeVectorDb = implementation.VectorDb;
+// ────────────────────────────────────────────────────────────────────────────
+// Backwards-compat surface used by tests and older integrations
+// ────────────────────────────────────────────────────────────────────────────
+/** High-level index class compatible with the test-suite API. */
+class VectorIndex {
+    constructor(opts) {
+        if (opts.dimension <= 0) {
+            throw new Error(`Invalid dimensions: must be positive, got ${opts.dimension}`);
+        }
+        this._dimension = opts.dimension;
+        // Use a unique temp path per instance to avoid cross-instance dimension conflicts
+        this._storagePath = require('os').tmpdir() + `/ruvector-idx-${Date.now()}-${Math.random().toString(36).slice(2)}.db`;
+        this.db = new VectorDBWrapper({ dimensions: opts.dimension, distanceMetric: opts.metric, storagePath: this._storagePath });
+    }
+    async insert(entry) {
+        return this.db.insert({ id: entry.id, vector: new Float32Array(entry.values) });
+    }
+    async insertBatch(entries, _opts) {
+        const ids = [];
+        const batchSize = _opts?.batchSize ?? entries.length;
+        for (let i = 0; i < entries.length; i += batchSize) {
+            const slice = entries.slice(i, i + batchSize);
+            const batch = slice.map(e => ({ id: e.id, vector: new Float32Array(e.values) }));
+            const batchIds = await this.db.insertBatch(batch);
+            ids.push(...batchIds);
+            _opts?.progressCallback?.(Math.min((i + batchSize) / entries.length, 1));
+        }
+        return ids;
+    }
+    async search(query, opts) {
+        return this.db.search({ vector: new Float32Array(query), k: opts.k });
+    }
+    async get(id) {
+        const r = await this.db.get(id);
+        if (!r)
+            return null;
+        return { id: r.id ?? id, values: Array.from(r.vector) };
+    }
+    async delete(id) {
+        return this.db.delete(id);
+    }
+    async stats() {
+        const count = await this.db.len();
+        return { vectorCount: count, dimension: this._dimension };
+    }
+    async clear() {
+        // Create a fresh db at a new temp path to reset state
+        const newPath = require('os').tmpdir() + `/ruvector-idx-${Date.now()}-${Math.random().toString(36).slice(2)}.db`;
+        this._storagePath = newPath;
+        this.db = new VectorDBWrapper({ dimensions: this._dimension, storagePath: newPath });
+    }
+    async optimize() {
+        // No-op: native HNSW self-optimises on insert
+    }
+}
+exports.VectorIndex = VectorIndex;
+/** Get backend info (compat with old getBackendInfo() call). */
+function getBackendInfo() {
+    const type = implementationType === 'native' ? 'native' : 'wasm';
+    const { version } = getVersion();
+    const features = type === 'native'
+        ? ['SIMD', 'Multi-threading', 'Rust-native']
+        : ['Browser-compatible', 'Cross-platform'];
+    return { type, version, features };
+}
+/** Check native availability (compat alias for isNative()). */
+function isNativeAvailable() {
+    return implementationType === 'native';
+}
+/** Vector utility functions used by tests and downstream packages. */
+exports.Utils = {
+    cosineSimilarity(a, b) {
+        if (a.length !== b.length)
+            throw new Error('Vectors must have same dimension');
+        let dot = 0, na = 0, nb = 0;
+        for (let i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            na += a[i] ** 2;
+            nb += b[i] ** 2;
+        }
+        const denom = Math.sqrt(na) * Math.sqrt(nb);
+        return denom === 0 ? 0 : dot / denom;
+    },
+    euclideanDistance(a, b) {
+        if (a.length !== b.length)
+            throw new Error('Vectors must have same dimension');
+        return Math.sqrt(a.reduce((sum, v, i) => sum + (v - b[i]) ** 2, 0));
+    },
+    normalize(v) {
+        const mag = Math.sqrt(v.reduce((s, x) => s + x * x, 0));
+        if (mag === 0)
+            return v.slice();
+        return v.map(x => x / mag);
+    },
+    randomVector(dimension) {
+        const v = Array.from({ length: dimension }, () => Math.random() * 2 - 1);
+        return exports.Utils.normalize(v);
+    },
+};
+// Export everything from the implementation
+exports.default = implementation;

package/dist/services/embedding-service.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 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.)
+ */
+/**
+ * Embedding provider interface
+ */
+export interface EmbeddingProvider {
+    /** Provider name */
+    name: string;
+    /** Generate embeddings for texts */
+    embed(texts: string[]): Promise<number[][]>;
+    /** Get embedding dimensions */
+    getDimensions(): number;
+}
+/**
+ * Embedding service configuration
+ */
+export interface EmbeddingServiceConfig {
+    /** Default provider to use */
+    defaultProvider?: string;
+    /** Maximum cache size */
+    maxCacheSize?: number;
+    /** Cache TTL in milliseconds */
+    cacheTtl?: number;
+    /** Batch size for embedding generation */
+    batchSize?: number;
+}
+/**
+ * Mock embedding provider for testing
+ */
+export declare class MockEmbeddingProvider implements EmbeddingProvider {
+    name: string;
+    private dimensions;
+    constructor(dimensions?: number);
+    embed(texts: string[]): Promise<number[][]>;
+    getDimensions(): number;
+}
+/**
+ * Simple local embedding using character n-grams
+ * This is a fallback when no external provider is available
+ */
+export declare class LocalNGramProvider implements EmbeddingProvider {
+    name: string;
+    private dimensions;
+    private ngramSize;
+    constructor(dimensions?: number, ngramSize?: number);
+    embed(texts: string[]): Promise<number[][]>;
+    private embedSingle;
+    private hashNgram;
+    getDimensions(): number;
+}
+/**
+ * Embedding service with caching and batching
+ */
+export declare class EmbeddingService {
+    private providers;
+    private cache;
+    private config;
+    constructor(config?: EmbeddingServiceConfig);
+    /**
+     * Register an embedding provider
+     */
+    registerProvider(provider: EmbeddingProvider): void;
+    /**
+     * Get a registered provider
+     */
+    getProvider(name?: string): EmbeddingProvider;
+    /**
+     * Generate embeddings for texts with caching
+     *
+     * @param texts - Texts to embed
+     * @param provider - Provider name (uses default if not specified)
+     * @returns Array of embeddings
+     */
+    embed(texts: string[], provider?: string): Promise<number[][]>;
+    /**
+     * Generate a single embedding
+     */
+    embedOne(text: string, provider?: string): Promise<number[]>;
+    /**
+     * Add entry to cache with LRU eviction
+     */
+    private addToCache;
+    /**
+     * Compute cosine similarity between two embeddings
+     */
+    cosineSimilarity(a: number[], b: number[]): number;
+    /**
+     * Find most similar texts from a corpus
+     */
+    findSimilar(query: string, corpus: string[], k?: number, provider?: string): Promise<{
+        text: string;
+        similarity: number;
+        index: number;
+    }[]>;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+        hitRate: number;
+    };
+    /**
+     * Clear the cache
+     */
+    clearCache(): void;
+    /**
+     * Get embedding dimensions for a provider
+     */
+    getDimensions(provider?: string): number;
+    /**
+     * List available providers
+     */
+    listProviders(): string[];
+}
+/**
+ * Create an embedding service instance
+ */
+export declare function createEmbeddingService(config?: EmbeddingServiceConfig): EmbeddingService;
+/**
+ * Get the default embedding service instance
+ */
+export declare function getDefaultEmbeddingService(): EmbeddingService;
+declare const _default: {
+    EmbeddingService: typeof EmbeddingService;
+    LocalNGramProvider: typeof LocalNGramProvider;
+    MockEmbeddingProvider: typeof MockEmbeddingProvider;
+    createEmbeddingService: typeof createEmbeddingService;
+    getDefaultEmbeddingService: typeof getDefaultEmbeddingService;
+};
+export default _default;
+//# sourceMappingURL=embedding-service.d.ts.map

package/dist/services/embedding-service.d.ts.map

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