{"_id":"@ruvector/rabitq-wasm","name":"@ruvector/rabitq-wasm","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ruvector/rabitq-wasm","version":"0.1.0","type":"module","description":"RaBitQ 1-bit quantized vector index in WebAssembly — 32× embedding compression with high-recall rerank, for browsers, Cloudflare Workers, Deno, and Bun","main":"ruvector_rabitq_wasm.js","types":"ruvector_rabitq_wasm.d.ts","module":"ruvector_rabitq_wasm.js","sideEffects":["./snippets/*"],"keywords":["rabitq","vector-search","ann","approximate-nearest-neighbor","quantization","1-bit-quantization","embeddings","wasm","webassembly","ai","machine-learning","rag","retrieval-augmented-generation","semantic-search","rust","browser","edge","cloudflare-workers"],"author":{"name":"RuVector Team"},"license":"MIT OR Apache-2.0","repository":{"type":"git","url":"git+https://github.com/ruvnet/RuVector.git","directory":"crates/ruvector-rabitq-wasm"},"homepage":"https://github.com/ruvnet/RuVector#readme","bugs":{"url":"https://github.com/ruvnet/RuVector/issues"},"publishConfig":{"access":"public"},"_id":"@ruvector/rabitq-wasm@0.1.0","gitHead":"3356cb3e226c8b2ef2c430b2af610994bc5bd91b","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-Uu7fupcJw8x+QBhJLKAfIK0CyH55fQ8niexJwbnSrYEtSX93ScWSOJBr/zTLR/hd0Md9Dq7ZaatzIDB7uJqazg==","shasum":"f06389474e4a5923336198474a3de8aee3adf6e2","tarball":"https://registry.npmjs.org/@ruvector/rabitq-wasm/-/rabitq-wasm-0.1.0.tgz","fileCount":6,"unpackedSize":98659,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDbn1Ms0uqLy/e6G9B64RsIjUQZ5177BbkHI1zT1RF7QQIhAOtJOdwp6dbsZPc0Eb3YTNQxMMCfUJ4jCu2sk+9UJ1fH"}]},"_npmUser":{"name":"ruvnet","email":"ruv@ruv.net"},"directories":{},"maintainers":[{"name":"ruvnet","email":"ruv@ruv.net"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/rabitq-wasm_0.1.0_1777238805041_0.3132844443349678"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-26T21:26:44.946Z","0.1.0":"2026-04-26T21:26:45.158Z","modified":"2026-04-26T21:26:45.424Z"},"maintainers":[{"name":"ruvnet","email":"ruv@ruv.net"}],"description":"RaBitQ 1-bit quantized vector index in WebAssembly — 32× embedding compression with high-recall rerank, for browsers, Cloudflare Workers, Deno, and Bun","homepage":"https://github.com/ruvnet/RuVector#readme","keywords":["rabitq","vector-search","ann","approximate-nearest-neighbor","quantization","1-bit-quantization","embeddings","wasm","webassembly","ai","machine-learning","rag","retrieval-augmented-generation","semantic-search","rust","browser","edge","cloudflare-workers"],"repository":{"type":"git","url":"git+https://github.com/ruvnet/RuVector.git","directory":"crates/ruvector-rabitq-wasm"},"author":{"name":"RuVector Team"},"bugs":{"url":"https://github.com/ruvnet/RuVector/issues"},"license":"MIT OR Apache-2.0","readme":"# @ruvector/rabitq-wasm\n\n**RaBitQ 1-bit quantized vector index in WebAssembly.** Compress embeddings 32× and run approximate nearest-neighbor search in the browser, Cloudflare Workers, Deno, or Bun.\n\n[![npm](https://img.shields.io/npm/v/@ruvector/rabitq-wasm.svg)](https://www.npmjs.com/package/@ruvector/rabitq-wasm)\n[![License](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue)](https://github.com/ruvnet/RuVector#license)\n\n## What is RaBitQ?\n\nRaBitQ is a rotation-based 1-bit vector quantization scheme that compresses each f32 embedding into a single bit per dimension while preserving rank order under L2 distance. A small \"rerank pool\" of exact-distance computations on the top candidates restores recall.\n\nFor a 768-dimensional embedding (~3 KB raw), RaBitQ stores **96 bytes** of quantized code plus the rotation matrix — a 32× memory reduction. Search runs in two phases:\n\n1. **Hamming-distance scan** over the 1-bit codes — fast, branch-free, ~10× more vectors per cache line than f32.\n2. **Exact L2² rerank** of the top `rerank_factor × k` candidates — restores recall.\n\nThe rotation is **deterministic** from `(seed, dim, vectors)`, so the same input always produces bit-identical codes whether you build on x86_64, aarch64, or wasm32.\n\n## Install\n\n```bash\nnpm install @ruvector/rabitq-wasm\n```\n\n## Usage (browser)\n\n```js\nimport init, { RabitqIndex } from \"@ruvector/rabitq-wasm\";\n\nawait init();\n\nconst dim = 768;\nconst n = 10_000;\nconst vectors = new Float32Array(n * dim);\n// ... populate `vectors` with your embeddings (n × dim, row-major) ...\n\n// seed = 42 for reproducibility; rerank_factor = 20 is the typical default\nconst idx = RabitqIndex.build(vectors, dim, 42n, 20);\n\nconst query = new Float32Array(dim);\n// ... fill query ...\n\nconst results = idx.search(query, 10);\n// → [{ id: 7421, distance: 0.0023 }, { id: 9011, distance: 0.0041 }, ...]\n```\n\n## Usage (Node.js / Bun)\n\n```js\nimport { RabitqIndex } from \"@ruvector/rabitq-wasm/node/ruvector_rabitq_wasm.js\";\n// no `init()` needed for the node target\n\nconst idx = RabitqIndex.build(vectors, 768, 42n, 20);\nconst results = idx.search(query, 10);\n```\n\n## Usage (bundlers — Vite, Webpack, Rollup)\n\n```js\nimport { RabitqIndex } from \"@ruvector/rabitq-wasm/bundler/ruvector_rabitq_wasm.js\";\n// the bundler handles the .wasm import transparently\n```\n\n## API\n\n### `class RabitqIndex`\n\n#### `RabitqIndex.build(vectors, dim, seed, rerankFactor)`\n\nBuild an index from a flat `Float32Array` of length `n * dim`.\n\n| Parameter | Type | Description |\n|---|---|---|\n| `vectors` | `Float32Array` | Row-major matrix of `n` vectors, each of length `dim`. |\n| `dim` | `number` | Vector dimensionality. |\n| `seed` | `bigint` | Random rotation seed. Same `(seed, dim, vectors)` triple → bit-identical codes. |\n| `rerankFactor` | `number` | Multiplier on `k` for the exact-L2² rerank pool. Typical: 20. |\n\nThrows if `dim == 0`, `vectors` is empty, or `vectors.length` is not a multiple of `dim`.\n\n#### `idx.search(query, k)`\n\nFind the `k` nearest neighbors of `query`. Returns an array of `SearchResult` ordered ascending by distance.\n\n#### `idx.len` (getter, number)\n\nNumber of vectors indexed.\n\n#### `idx.isEmpty` (getter, boolean)\n\n`true` iff no vectors have been indexed.\n\n### `interface SearchResult`\n\n```ts\n{\n  id: number;       // caller-supplied vector id (its row index in `build`)\n  distance: number; // approximate L2² distance after rerank\n}\n```\n\n### `version()`\n\nReturns the crate version baked at build time.\n\n## Why use this in the browser\n\n- **32× smaller indices.** A 100 K × 768 embedding store is ~9.6 MB instead of ~300 MB — fits comfortably in any browser tab.\n- **Cache-line-friendly hamming scan.** The 1-bit codes pack 64 dimensions into one `u64`, so the hot path runs at memory bandwidth.\n- **Deterministic across architectures.** Builds on your x86_64 build server, runs identically on the user's ARM phone or in a Cloudflare Worker.\n- **No server.** Run RAG, semantic search, or recommendation lookup entirely client-side.\n\n## Sister packages\n\n- [`@ruvector/acorn-wasm`](https://www.npmjs.com/package/@ruvector/acorn-wasm) — predicate-agnostic filtered HNSW (when you also need to filter results by metadata).\n- [`@ruvector/graph-wasm`](https://www.npmjs.com/package/@ruvector/graph-wasm) — Cypher-compatible hypergraph database in WASM.\n- [`ruvector`](https://www.npmjs.com/package/ruvector), [`@ruvector/core`](https://www.npmjs.com/package/@ruvector/core) — Node.js NAPI bindings for the full ruvector engine.\n\n## Source\n\n- **Rust crate**: [`crates/ruvector-rabitq-wasm/`](https://github.com/ruvnet/RuVector/tree/main/crates/ruvector-rabitq-wasm)\n- **Algorithm crate**: [`crates/ruvector-rabitq/`](https://github.com/ruvnet/RuVector/tree/main/crates/ruvector-rabitq)\n- **ADR**: [ADR-154 RaBitQ rotation-based 1-bit quantization](https://github.com/ruvnet/RuVector/blob/main/docs/adr/ADR-154-rabitq-rotation-based-1bit-quantization.md)\n- **Packaging ADR**: [ADR-161 — `ruvector-rabitq-wasm` npm package](https://github.com/ruvnet/RuVector/blob/main/docs/adr/ADR-161-rabitq-wasm-npm-package.md)\n- **Repository**: [github.com/ruvnet/RuVector](https://github.com/ruvnet/RuVector)\n\n## License\n\nMIT OR Apache-2.0\n","readmeFilename":"README.md","_rev":"1-e8ac9707c5b60ca8d13b754ab67ffddd"}