{"_id":"@aigentic/core","_rev":"3-4870b4e7bb7ec6ffefbcd2b7c1801028","name":"@aigentic/core","dist-tags":{"latest":"0.1.32"},"versions":{"0.1.31":{"name":"@aigentic/core","version":"0.1.31","keywords":["vector-database","vector-search","similarity-search","semantic-search","hnsw","ann","approximate-nearest-neighbor","embedding-database","ai","machine-learning","ml","llm","rag","retrieval-augmented-generation","native","napi","rust","simd","fast","performance","ruv","ruvector"],"author":{"url":"https://ruv.io","name":"ruv.io Team","email":"info@ruv.io"},"license":"MIT","_id":"@aigentic/core@0.1.31","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://ruv.io","bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"dist":{"shasum":"4c3a8e7db736ba45151dbc39cd48e5bd34dd2ae7","tarball":"https://registry.npmjs.org/@aigentic/core/-/core-0.1.31.tgz","fileCount":4,"integrity":"sha512-d7Zl/BEdgFBRm4D474zRrIg9VrhYLnW9mfgWKbFDPnKQ4x2R3DImFejy1DGLex9Q8jx+ieu0IFdXzcQ0s7rh5Q==","signatures":[{"sig":"MEYCIQDhdDQrldBcur4sBJQo6pXP+JQwoDnxg57FnixRxmXYZwIhAIIIgzIg0RhB+o0uaH2zQUL8jSECwBueZ7QdihMSI1vT","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11416},"main":"index.js","types":"index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"06426cbc6e70f09762e996a98517b0b1fd1c7c4e","scripts":{"test":"node test.js","build:napi":"napi build --platform --release --cargo-cwd ../../../crates/ruvector-node","publish:platforms":"node scripts/publish-platforms.js"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git","directory":"npm/packages/core"},"_npmVersion":"11.12.0","description":"High-performance vector database with HNSW indexing - 50k+ inserts/sec, built in Rust for AI/ML similarity search and semantic search applications","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@napi-rs/cli":"^2.18.0"},"optionalDependencies":{"ruvector-core-darwin-x64":"0.1.29","ruvector-core-darwin-arm64":"0.1.29","ruvector-core-linux-x64-gnu":"0.1.29","ruvector-core-win32-x64-msvc":"0.1.29","ruvector-core-linux-arm64-gnu":"0.1.29"},"_npmOperationalInternal":{"tmp":"tmp/core_0.1.31_1779091120909_0.4998532139574763","host":"s3://npm-registry-packages-npm-production"}},"0.1.32":{"name":"@aigentic/core","version":"0.1.32","keywords":["vector-database","vector-search","similarity-search","semantic-search","hnsw","ann","approximate-nearest-neighbor","embedding-database","ai","machine-learning","ml","llm","rag","retrieval-augmented-generation","native","napi","rust","simd","fast","performance","ruv","ruvector"],"author":{"url":"https://ruv.io","name":"ruv.io Team","email":"info@ruv.io"},"license":"MIT","_id":"@aigentic/core@0.1.32","maintainers":[{"name":"aigentic","email":"engineering@aigentic.net"}],"homepage":"https://ruv.io","bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"dist":{"shasum":"9b7a8162ebcd991180fd10293a4b7d85a78e43a8","tarball":"https://registry.npmjs.org/@aigentic/core/-/core-0.1.32.tgz","fileCount":4,"integrity":"sha512-BMo4j2Z+pXwG993GlbNl/i/d7Guo/giTU9u+OIoH7QCJTDQ2vmneFA9ETd0GbM19mJRI/wrye7uymkZcKChNGw==","signatures":[{"sig":"MEYCIQCoQgLMF2K8M0DmBCLkCCTh/3SXRY8Ivt9GCP+iuFFS0gIhAKiJQdLpjMLezJxopa0DryCzrohJVJkOPA9M0nVq3Vbj","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":11416},"main":"index.js","types":"index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"06426cbc6e70f09762e996a98517b0b1fd1c7c4e","scripts":{"test":"node test.js","build:napi":"napi build --platform --release --cargo-cwd ../../../crates/ruvector-node","publish:platforms":"node scripts/publish-platforms.js"},"_npmUser":{"name":"aigentic","email":"engineering@aigentic.net"},"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git","directory":"npm/packages/core"},"_npmVersion":"11.12.0","description":"High-performance vector database with HNSW indexing - 50k+ inserts/sec, built in Rust for AI/ML similarity search and semantic search applications","directories":{},"_nodeVersion":"22.22.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@napi-rs/cli":"^2.18.0"},"optionalDependencies":{"ruvector-core-darwin-x64":"0.1.29","ruvector-core-darwin-arm64":"0.1.29","ruvector-core-linux-x64-gnu":"0.1.29","ruvector-core-win32-x64-msvc":"0.1.29","ruvector-core-linux-arm64-gnu":"0.1.29"},"_npmOperationalInternal":{"tmp":"tmp/core_0.1.32_1779092828840_0.006628614894061302","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-05-18T07:58:40.790Z","modified":"2026-09-13T15:30:29.657Z","0.1.31":"2026-05-18T07:58:41.039Z","0.1.32":"2026-05-18T08:27:08.999Z"},"bugs":{"url":"https://github.com/ruvnet/ruvector/issues"},"author":{"url":"https://ruv.io","name":"ruv.io Team","email":"info@ruv.io"},"license":"MIT","homepage":"https://ruv.io","keywords":["vector-database","vector-search","similarity-search","semantic-search","hnsw","ann","approximate-nearest-neighbor","embedding-database","ai","machine-learning","ml","llm","rag","retrieval-augmented-generation","native","napi","rust","simd","fast","performance","ruv","ruvector"],"repository":{"url":"git+https://github.com/ruvnet/ruvector.git","type":"git","directory":"npm/packages/core"},"description":"High-performance vector database with HNSW indexing - 50k+ inserts/sec, built in Rust for AI/ML similarity search and semantic search applications","maintainers":[{"email":"engineering@aigentic.net","name":"aiggy"}],"readme":"# ruvector-core\n\n[![npm version](https://badge.fury.io/js/ruvector-core.svg)](https://www.npmjs.com/package/ruvector-core)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node Version](https://img.shields.io/node/v/ruvector-core)](https://nodejs.org)\n[![Downloads](https://img.shields.io/npm/dm/ruvector-core)](https://www.npmjs.com/package/ruvector-core)\n\n**High-performance vector database with HNSW indexing, built in Rust with Node.js bindings**\n\nRuvector is a blazingly fast, memory-efficient vector database designed for AI/ML applications, semantic search, and similarity matching. Built with Rust and optimized with SIMD instructions for maximum performance.\n\n🌐 **[Visit ruv.io](https://ruv.io)** for more AI infrastructure tools\n\n## Features\n\n- 🚀 **Ultra-Fast Performance** - 50,000+ inserts/sec, 10,000+ searches/sec\n- 🎯 **HNSW Indexing** - State-of-the-art approximate nearest neighbor search\n- ⚡ **SIMD Optimized** - Hardware-accelerated vector operations\n- 🧵 **Multi-threaded** - Async operations with Tokio runtime\n- 💾 **Memory Efficient** - ~50 bytes per vector with optional quantization\n- 🔒 **Type-Safe** - Full TypeScript definitions included\n- 🌍 **Cross-Platform** - Linux, macOS (Intel & Apple Silicon), Windows\n- 🦀 **Rust Core** - Memory safety with zero-cost abstractions\n\n## Quick Start\n\n### Installation\n\n```bash\nnpm install ruvector-core\n```\n\nThe correct platform-specific native module is automatically installed.\n\n### Basic Usage\n\n```javascript\nconst { VectorDb } = require('ruvector-core');\n\nasync function example() {\n  // Create database with 128 dimensions\n  const db = new VectorDb({\n    dimensions: 128,\n    maxElements: 10000,\n    storagePath: './vectors.db'\n  });\n\n  // Insert a vector\n  const vector = new Float32Array(128).map(() => Math.random());\n  const id = await db.insert({\n    id: 'doc_1',\n    vector: vector,\n    metadata: { title: 'Example Document' }\n  });\n\n  // Search for similar vectors\n  const results = await db.search({\n    vector: vector,\n    k: 10\n  });\n\n  console.log('Top 10 similar vectors:', results);\n  // Output: [{ id: 'doc_1', score: 1.0, metadata: {...} }, ...]\n}\n\nexample();\n```\n\n### TypeScript\n\nFull TypeScript support with complete type definitions:\n\n```typescript\nimport { VectorDb, VectorEntry, SearchQuery, SearchResult } from 'ruvector-core';\n\nconst db = new VectorDb({\n  dimensions: 128,\n  maxElements: 10000,\n  storagePath: './vectors.db'\n});\n\n// Fully typed operations\nconst entry: VectorEntry = {\n  id: 'doc_1',\n  vector: new Float32Array(128),\n  metadata: { title: 'Example' }\n};\n\nconst results: SearchResult[] = await db.search({\n  vector: new Float32Array(128),\n  k: 10\n});\n```\n\n## API Reference\n\n### Constructor\n\n```typescript\nnew VectorDb(options: {\n  dimensions: number;        // Vector dimensionality (required)\n  maxElements?: number;      // Max vectors (default: 10000)\n  storagePath?: string;      // Persistent storage path\n  ef_construction?: number;  // HNSW construction parameter (default: 200)\n  m?: number;               // HNSW M parameter (default: 16)\n})\n```\n\n### Methods\n\n- `insert(entry: VectorEntry): Promise<string>` - Insert a vector\n- `search(query: SearchQuery): Promise<SearchResult[]>` - Find similar vectors\n- `delete(id: string): Promise<boolean>` - Remove a vector\n- `len(): Promise<number>` - Count total vectors\n- `get(id: string): Promise<VectorEntry | null>` - Retrieve vector by ID\n\n## Performance Benchmarks\n\nTested on AMD Ryzen 9 5950X, 128-dimensional vectors:\n\n| Operation | Throughput | Latency (p50) | Latency (p99) |\n|-----------|------------|---------------|---------------|\n| Insert    | 52,341 ops/sec | 0.019 ms | 0.045 ms |\n| Search (k=10) | 11,234 ops/sec | 0.089 ms | 0.156 ms |\n| Search (k=100) | 8,932 ops/sec | 0.112 ms | 0.203 ms |\n| Delete    | 45,678 ops/sec | 0.022 ms | 0.051 ms |\n\n**Memory Usage**: ~50 bytes per 128-dim vector (including index)\n\n### Comparison with Alternatives\n\n| Database | Insert (ops/sec) | Search (ops/sec) | Memory per Vector |\n|----------|------------------|------------------|-------------------|\n| **Ruvector** | **52,341** | **11,234** | **50 bytes** |\n| Faiss (HNSW) | 38,200 | 9,800 | 68 bytes |\n| Hnswlib | 41,500 | 10,200 | 62 bytes |\n| Milvus | 28,900 | 7,600 | 95 bytes |\n\n*Benchmarks measured with 100K vectors, 128 dimensions, k=10*\n\n## Platform Support\n\nAutomatically installs the correct native module for:\n\n- **Linux**: x64, ARM64 (GNU libc)\n- **macOS**: x64 (Intel), ARM64 (Apple Silicon)\n- **Windows**: x64 (MSVC)\n\nNode.js 18+ required.\n\n## Advanced Configuration\n\n### HNSW Parameters\n\n```javascript\nconst db = new VectorDb({\n  dimensions: 384,\n  maxElements: 1000000,\n  ef_construction: 200,  // Higher = better recall, slower build\n  m: 16,                 // Higher = better recall, more memory\n  storagePath: './large-db.db'\n});\n```\n\n### Distance Metrics\n\n```javascript\nconst db = new VectorDb({\n  dimensions: 128,\n  distanceMetric: 'cosine' // 'cosine', 'euclidean', or 'dot'\n});\n```\n\n### Persistence\n\n```javascript\n// Auto-save to disk\nconst db = new VectorDb({\n  dimensions: 128,\n  storagePath: './persistent.db'\n});\n\n// In-memory only\nconst db = new VectorDb({\n  dimensions: 128\n  // No storagePath = in-memory\n});\n```\n\n## Building from Source\n\n```bash\n# Install Rust toolchain\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\n\n# Build native module\nnpm run build:napi\n```\n\nRequires:\n- Rust 1.77+\n- Node.js 18+\n- Cargo\n\n## Use Cases\n\n- **Semantic Search** - Find similar documents, images, or embeddings\n- **RAG Systems** - Retrieval-Augmented Generation for LLMs\n- **Recommendation Engines** - Content and product recommendations\n- **Duplicate Detection** - Find similar items in large datasets\n- **Anomaly Detection** - Identify outliers in vector space\n- **Image Similarity** - Visual search and image matching\n\n## Examples\n\n### Semantic Text Search\n\n```javascript\nconst { VectorDb } = require('ruvector-core');\nconst openai = require('openai');\n\nconst db = new VectorDb({ dimensions: 1536 }); // OpenAI ada-002\n\nasync function indexDocuments(texts) {\n  for (const text of texts) {\n    const embedding = await openai.embeddings.create({\n      model: 'text-embedding-ada-002',\n      input: text\n    });\n\n    await db.insert({\n      id: text.slice(0, 20),\n      vector: new Float32Array(embedding.data[0].embedding),\n      metadata: { text }\n    });\n  }\n}\n\nasync function search(query) {\n  const embedding = await openai.embeddings.create({\n    model: 'text-embedding-ada-002',\n    input: query\n  });\n\n  return await db.search({\n    vector: new Float32Array(embedding.data[0].embedding),\n    k: 5\n  });\n}\n```\n\n### Image Similarity Search\n\n```javascript\nconst { VectorDb } = require('ruvector-core');\nconst clip = require('@xenova/transformers');\n\nconst db = new VectorDb({ dimensions: 512 }); // CLIP embedding size\n\nasync function indexImages(imagePaths) {\n  const model = await clip.CLIPModel.from_pretrained('openai/clip-vit-base-patch32');\n\n  for (const path of imagePaths) {\n    const embedding = await model.encode_image(path);\n    await db.insert({\n      id: path,\n      vector: new Float32Array(embedding),\n      metadata: { path }\n    });\n  }\n}\n```\n\n## Resources\n\n- 🏠 [Homepage](https://ruv.io)\n- 📦 [GitHub Repository](https://github.com/ruvnet/ruvector)\n- 📚 [Documentation](https://github.com/ruvnet/ruvector/tree/main/docs)\n- 🐛 [Issue Tracker](https://github.com/ruvnet/ruvector/issues)\n- 💬 [Discussions](https://github.com/ruvnet/ruvector/discussions)\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](https://github.com/ruvnet/ruvector/blob/main/CONTRIBUTING.md) for guidelines.\n\n## License\n\nMIT License - see [LICENSE](https://github.com/ruvnet/ruvector/blob/main/LICENSE) for details.\n\n---\n\nBuilt with ❤️ by the [ruv.io](https://ruv.io) team\n","readmeFilename":"README.md"}