ruvector 0.1.1

package/bin/cli.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const chalk = require('chalk');
+const ora = require('ora');
+const fs = require('fs');
+const path = require('path');
+
+// Import ruvector
+let VectorDB, getVersion, getImplementationType;
+try {
+  const ruvector = require('../dist/index.js');
+  VectorDB = ruvector.VectorDB;
+  getVersion = ruvector.getVersion;
+  getImplementationType = ruvector.getImplementationType;
+} catch (e) {
+  console.error(chalk.red('Error: Failed to load ruvector. Please run: npm run build'));
+  process.exit(1);
+}
+
+const program = new Command();
+
+// Version and description
+const versionInfo = getVersion();
+program
+  .name('ruvector')
+  .description(`${chalk.cyan('ruvector')} - High-performance vector database CLI\nUsing: ${chalk.yellow(versionInfo.implementation)} implementation`)
+  .version(versionInfo.version);
+
+// Create database
+program
+  .command('create <path>')
+  .description('Create a new vector database')
+  .option('-d, --dimension <number>', 'Vector dimension', '384')
+  .option('-m, --metric <type>', 'Distance metric (cosine|euclidean|dot)', 'cosine')
+  .action((dbPath, options) => {
+    const spinner = ora('Creating database...').start();
+
+    try {
+      const dimension = parseInt(options.dimension);
+      const db = new VectorDB({
+        dimension,
+        metric: options.metric,
+        path: dbPath,
+        autoPersist: true
+      });
+
+      db.save(dbPath);
+      spinner.succeed(chalk.green(`Database created: ${dbPath}`));
+      console.log(chalk.gray(`  Dimension: ${dimension}`));
+      console.log(chalk.gray(`  Metric: ${options.metric}`));
+      console.log(chalk.gray(`  Implementation: ${getImplementationType()}`));
+    } catch (error) {
+      spinner.fail(chalk.red('Failed to create database'));
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// Insert vectors
+program
+  .command('insert <database> <file>')
+  .description('Insert vectors from JSON file')
+  .option('-b, --batch-size <number>', 'Batch size for insertion', '1000')
+  .action((dbPath, file, options) => {
+    const spinner = ora('Loading database...').start();
+
+    try {
+      // Read database metadata to get dimension
+      let dimension = 384; // default
+      if (fs.existsSync(dbPath)) {
+        const dbData = fs.readFileSync(dbPath, 'utf8');
+        const parsed = JSON.parse(dbData);
+        dimension = parsed.dimension || 384;
+      }
+
+      const db = new VectorDB({ dimension });
+
+      if (fs.existsSync(dbPath)) {
+        db.load(dbPath);
+      }
+
+      spinner.text = 'Reading vectors...';
+      const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const vectors = Array.isArray(data) ? data : [data];
+
+      spinner.text = `Inserting ${vectors.length} vectors...`;
+      const batchSize = parseInt(options.batchSize);
+
+      for (let i = 0; i < vectors.length; i += batchSize) {
+        const batch = vectors.slice(i, i + batchSize);
+        db.insertBatch(batch);
+        spinner.text = `Inserted ${Math.min(i + batchSize, vectors.length)}/${vectors.length} vectors...`;
+      }
+
+      db.save(dbPath);
+      spinner.succeed(chalk.green(`Inserted ${vectors.length} vectors`));
+
+      const stats = db.stats();
+      console.log(chalk.gray(`  Total vectors: ${stats.count}`));
+    } catch (error) {
+      spinner.fail(chalk.red('Failed to insert vectors'));
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// Search vectors
+program
+  .command('search <database>')
+  .description('Search for similar vectors')
+  .requiredOption('-v, --vector <json>', 'Query vector as JSON array')
+  .option('-k, --top-k <number>', 'Number of results', '10')
+  .option('-t, --threshold <number>', 'Similarity threshold', '0.0')
+  .option('-f, --filter <json>', 'Metadata filter as JSON')
+  .action((dbPath, options) => {
+    const spinner = ora('Loading database...').start();
+
+    try {
+      // Read database metadata
+      const dbData = fs.readFileSync(dbPath, 'utf8');
+      const parsed = JSON.parse(dbData);
+      const dimension = parsed.dimension || 384;
+
+      const db = new VectorDB({ dimension });
+      db.load(dbPath);
+
+      spinner.text = 'Searching...';
+
+      const vector = JSON.parse(options.vector);
+      const query = {
+        vector,
+        k: parseInt(options.topK),
+        threshold: parseFloat(options.threshold)
+      };
+
+      if (options.filter) {
+        query.filter = JSON.parse(options.filter);
+      }
+
+      const results = db.search(query);
+      spinner.succeed(chalk.green(`Found ${results.length} results`));
+
+      console.log(chalk.cyan('\nSearch Results:'));
+      results.forEach((result, i) => {
+        console.log(chalk.white(`\n${i + 1}. ID: ${result.id}`));
+        console.log(chalk.yellow(`   Score: ${result.score.toFixed(4)}`));
+        if (result.metadata) {
+          console.log(chalk.gray(`   Metadata: ${JSON.stringify(result.metadata)}`));
+        }
+      });
+    } catch (error) {
+      spinner.fail(chalk.red('Failed to search'));
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// Show stats
+program
+  .command('stats <database>')
+  .description('Show database statistics')
+  .action((dbPath) => {
+    const spinner = ora('Loading database...').start();
+
+    try {
+      const dbData = fs.readFileSync(dbPath, 'utf8');
+      const parsed = JSON.parse(dbData);
+      const dimension = parsed.dimension || 384;
+
+      const db = new VectorDB({ dimension });
+      db.load(dbPath);
+
+      const stats = db.stats();
+      spinner.succeed(chalk.green('Database statistics'));
+
+      console.log(chalk.cyan('\nDatabase Stats:'));
+      console.log(chalk.white(`  Vector Count: ${chalk.yellow(stats.count)}`));
+      console.log(chalk.white(`  Dimension: ${chalk.yellow(stats.dimension)}`));
+      console.log(chalk.white(`  Metric: ${chalk.yellow(stats.metric)}`));
+      console.log(chalk.white(`  Implementation: ${chalk.yellow(getImplementationType())}`));
+
+      if (stats.memoryUsage) {
+        const mb = (stats.memoryUsage / (1024 * 1024)).toFixed(2);
+        console.log(chalk.white(`  Memory Usage: ${chalk.yellow(mb + ' MB')}`));
+      }
+
+      const fileStats = fs.statSync(dbPath);
+      const fileMb = (fileStats.size / (1024 * 1024)).toFixed(2);
+      console.log(chalk.white(`  File Size: ${chalk.yellow(fileMb + ' MB')}`));
+    } catch (error) {
+      spinner.fail(chalk.red('Failed to load database'));
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// Benchmark
+program
+  .command('benchmark')
+  .description('Run performance benchmarks')
+  .option('-d, --dimension <number>', 'Vector dimension', '384')
+  .option('-n, --num-vectors <number>', 'Number of vectors', '10000')
+  .option('-q, --num-queries <number>', 'Number of queries', '1000')
+  .action((options) => {
+    console.log(chalk.cyan('\nruvector Performance Benchmark'));
+    console.log(chalk.gray(`Implementation: ${getImplementationType()}\n`));
+
+    const dimension = parseInt(options.dimension);
+    const numVectors = parseInt(options.numVectors);
+    const numQueries = parseInt(options.numQueries);
+
+    let spinner = ora('Creating database...').start();
+
+    try {
+      const db = new VectorDB({ dimension, metric: 'cosine' });
+      spinner.succeed();
+
+      // Insert benchmark
+      spinner = ora(`Inserting ${numVectors} vectors...`).start();
+      const insertStart = Date.now();
+
+      const vectors = [];
+      for (let i = 0; i < numVectors; i++) {
+        vectors.push({
+          id: `vec_${i}`,
+          vector: Array.from({ length: dimension }, () => Math.random()),
+          metadata: { index: i, batch: Math.floor(i / 1000) }
+        });
+      }
+
+      db.insertBatch(vectors);
+      const insertTime = Date.now() - insertStart;
+      const insertRate = (numVectors / (insertTime / 1000)).toFixed(0);
+
+      spinner.succeed(chalk.green(`Inserted ${numVectors} vectors in ${insertTime}ms`));
+      console.log(chalk.gray(`  Rate: ${chalk.yellow(insertRate)} vectors/sec`));
+
+      // Search benchmark
+      spinner = ora(`Running ${numQueries} searches...`).start();
+      const searchStart = Date.now();
+
+      for (let i = 0; i < numQueries; i++) {
+        const query = {
+          vector: Array.from({ length: dimension }, () => Math.random()),
+          k: 10
+        };
+        db.search(query);
+      }
+
+      const searchTime = Date.now() - searchStart;
+      const searchRate = (numQueries / (searchTime / 1000)).toFixed(0);
+      const avgLatency = (searchTime / numQueries).toFixed(2);
+
+      spinner.succeed(chalk.green(`Completed ${numQueries} searches in ${searchTime}ms`));
+      console.log(chalk.gray(`  Rate: ${chalk.yellow(searchRate)} queries/sec`));
+      console.log(chalk.gray(`  Avg Latency: ${chalk.yellow(avgLatency)}ms`));
+
+      // Stats
+      const stats = db.stats();
+      console.log(chalk.cyan('\nFinal Stats:'));
+      console.log(chalk.white(`  Vector Count: ${chalk.yellow(stats.count)}`));
+      console.log(chalk.white(`  Dimension: ${chalk.yellow(stats.dimension)}`));
+      console.log(chalk.white(`  Implementation: ${chalk.yellow(getImplementationType())}`));
+
+    } catch (error) {
+      spinner.fail(chalk.red('Benchmark failed'));
+      console.error(chalk.red(error.message));
+      process.exit(1);
+    }
+  });
+
+// Info command
+program
+  .command('info')
+  .description('Show ruvector information')
+  .action(() => {
+    const info = getVersion();
+    console.log(chalk.cyan('\nruvector Information'));
+    console.log(chalk.white(`  Version: ${chalk.yellow(info.version)}`));
+    console.log(chalk.white(`  Implementation: ${chalk.yellow(info.implementation)}`));
+    console.log(chalk.white(`  Node Version: ${chalk.yellow(process.version)}`));
+    console.log(chalk.white(`  Platform: ${chalk.yellow(process.platform)}`));
+    console.log(chalk.white(`  Architecture: ${chalk.yellow(process.arch)}`));
+  });
+
+program.parse();

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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. WASM (WebAssembly, universal fallback) - works everywhere
+ */
+export * from './types';
+declare let implementation: any;
+/**
+ * Get the current implementation type
+ */
+export declare function getImplementationType(): 'native' | 'wasm';
+/**
+ * Check if native implementation is being used
+ */
+export declare function isNative(): boolean;
+/**
+ * Check if WASM implementation is being used
+ */
+export declare function isWasm(): boolean;
+/**
+ * Get version information
+ */
+export declare function getVersion(): {
+    version: string;
+    implementation: string;
+};
+export declare const VectorDB: any;
+export default implementation;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,SAAS,CAAC;AAExB,QAAA,IAAI,cAAc,EAAE,GAAG,CAAC;AA+BxB;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,QAAQ,GAAG,MAAM,CAEzD;AAED;;GAEG;AACH,wBAAgB,QAAQ,IAAI,OAAO,CAElC;AAED;;GAEG;AACH,wBAAgB,MAAM,IAAI,OAAO,CAEhC;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,CAMxE;AAGD,eAAO,MAAM,QAAQ,KAA0B,CAAC;AAGhD,eAAe,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,88 @@
+"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. WASM (WebAssembly, universal fallback) - works everywhere
+ */
+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.VectorDB = void 0;
+exports.getImplementationType = getImplementationType;
+exports.isNative = isNative;
+exports.isWasm = isWasm;
+exports.getVersion = getVersion;
+__exportStar(require("./types"), exports);
+let implementation;
+let implementationType = 'wasm';
+try {
+    // Try to load native module first
+    implementation = require('@ruvector/core');
+    implementationType = 'native';
+    // Verify it's actually working
+    if (typeof implementation.VectorDB !== 'function') {
+        throw new Error('Native module loaded but VectorDB not found');
+    }
+}
+catch (e) {
+    // Fallback to WASM
+    if (process.env.RUVECTOR_DEBUG) {
+        console.warn('[ruvector] Native module not available:', e.message);
+        console.warn('[ruvector] Falling back to WASM implementation');
+    }
+    try {
+        implementation = require('@ruvector/wasm');
+        implementationType = 'wasm';
+    }
+    catch (wasmError) {
+        throw new Error(`Failed to load ruvector: Neither native nor WASM implementation available.\n` +
+            `Native error: ${e.message}\n` +
+            `WASM error: ${wasmError.message}`);
+    }
+}
+/**
+ * Get the current implementation type
+ */
+function getImplementationType() {
+    return implementationType;
+}
+/**
+ * Check if native implementation is being used
+ */
+function isNative() {
+    return implementationType === 'native';
+}
+/**
+ * Check if WASM 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
+    };
+}
+// Export the VectorDB class
+exports.VectorDB = implementation.VectorDB;
+// Export everything from the implementation
+exports.default = implementation;

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":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,kCAAkC;IAClC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC7B,yCAAyC;IACzC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,KAAK,CAAC;IACxC,+BAA+B;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,4BAA4B;IAC5B,IAAI,CAAC,EAAE;QACL,8CAA8C;QAC9C,CAAC,CAAC,EAAE,MAAM,CAAC;QACX,yCAAyC;QACzC,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,oDAAoD;QACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,KAAI,OAAO,EAAE,SAAS,GAAG,QAAQ,CAAC;IAElC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IAEjC;;;OAGG;IACH,WAAW,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAE1C;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,EAAE,CAAC;IAE3C;;;;OAIG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAAC;IAEpC;;;;OAIG;IACH,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAE5B;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAEhE;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC;IAEjB;;;OAGG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1B;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;OAEG;IACH,UAAU,IAAI,IAAI,CAAC;IAEnB;;OAEG;IACH,QAAQ,IAAI,IAAI,CAAC;CAClB"}

package/dist/types.js

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