@ruvector/rvf 0.1.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +302 -19
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,14 +1,38 @@
|
|
|
1
1
|
# @ruvector/rvf
|
|
2
2
|
|
|
3
|
-
Unified TypeScript SDK for the RuVector Format (RVF) cognitive container
|
|
3
|
+
Unified TypeScript/JavaScript SDK for the **RuVector Format (RVF)** — a cognitive container that stores vectors, carries models, boots compute kernels, and proves everything in a single `.rvf` file.
|
|
4
|
+
|
|
5
|
+
## Platform Support
|
|
6
|
+
|
|
7
|
+
| Platform | Runtime | Backend | Status |
|
|
8
|
+
|----------|---------|---------|--------|
|
|
9
|
+
| Linux x86_64 | Node.js 18+ | Native (N-API) | Stable |
|
|
10
|
+
| Linux aarch64 | Node.js 18+ | Native (N-API) | Stable |
|
|
11
|
+
| macOS x86_64 | Node.js 18+ | Native (N-API) | Stable |
|
|
12
|
+
| macOS arm64 (Apple Silicon) | Node.js 18+ | Native (N-API) | Stable |
|
|
13
|
+
| Windows x86_64 | Node.js 18+ | Native (N-API) | Stable |
|
|
14
|
+
| Any | Deno | WASM | Supported |
|
|
15
|
+
| Any | Browser (Chrome, Firefox, Safari) | WASM | Supported |
|
|
16
|
+
| Any | Cloudflare Workers / Edge | WASM | Supported |
|
|
17
|
+
| Any | Bun | Native (N-API) | Experimental |
|
|
18
|
+
|
|
19
|
+
**Deno**: The WASM build targets `wasm32-unknown-unknown`, which runs natively in Deno. Import via `npm:` specifier or load the `.wasm` bundle directly.
|
|
20
|
+
|
|
21
|
+
**Browser**: The `@ruvector/rvf-wasm` package provides a ~46 KB control-plane WASM module plus a ~5.5 KB tile-compute module. Works in any browser with WebAssembly support.
|
|
4
22
|
|
|
5
23
|
## Install
|
|
6
24
|
|
|
7
25
|
```bash
|
|
26
|
+
# Node.js (auto-detects native or WASM)
|
|
8
27
|
npm install @ruvector/rvf
|
|
28
|
+
|
|
29
|
+
# WASM only (browser, Deno, edge)
|
|
30
|
+
npm install @ruvector/rvf-wasm
|
|
9
31
|
```
|
|
10
32
|
|
|
11
|
-
##
|
|
33
|
+
## Quick Start
|
|
34
|
+
|
|
35
|
+
### Node.js
|
|
12
36
|
|
|
13
37
|
```typescript
|
|
14
38
|
import { RvfDatabase } from '@ruvector/rvf';
|
|
@@ -27,32 +51,291 @@ console.log(db.fileId()); // unique file UUID
|
|
|
27
51
|
console.log(db.dimension()); // 384
|
|
28
52
|
console.log(db.segments()); // [{ type, id, size }]
|
|
29
53
|
|
|
54
|
+
// Derive child (COW branching)
|
|
55
|
+
const child = db.derive('child.rvf');
|
|
56
|
+
|
|
30
57
|
db.close();
|
|
31
58
|
```
|
|
32
59
|
|
|
60
|
+
### Browser (WASM)
|
|
61
|
+
|
|
62
|
+
```html
|
|
63
|
+
<script type="module">
|
|
64
|
+
import init, { RvfStore } from '@ruvector/rvf-wasm';
|
|
65
|
+
|
|
66
|
+
await init();
|
|
67
|
+
|
|
68
|
+
const store = RvfStore.create(384, 'cosine');
|
|
69
|
+
store.ingest(new Float32Array(384), 0);
|
|
70
|
+
const results = store.query(new Float32Array(384), 10);
|
|
71
|
+
console.log('Results:', results);
|
|
72
|
+
</script>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Deno
|
|
76
|
+
|
|
77
|
+
```typescript
|
|
78
|
+
// Import via npm: specifier
|
|
79
|
+
import init, { RvfStore } from "npm:@ruvector/rvf-wasm";
|
|
80
|
+
|
|
81
|
+
await init();
|
|
82
|
+
|
|
83
|
+
const store = RvfStore.create(384, 'cosine');
|
|
84
|
+
store.ingest(new Float32Array(384), 0);
|
|
85
|
+
const results = store.query(new Float32Array(384), 10);
|
|
86
|
+
console.log('Results:', results);
|
|
87
|
+
```
|
|
88
|
+
|
|
33
89
|
## What is RVF?
|
|
34
90
|
|
|
35
|
-
RVF (RuVector Format) is a universal binary substrate that merges database, model, graph engine, kernel, and attestation into a single deployable file.
|
|
91
|
+
RVF (RuVector Format) is a universal binary substrate that merges database, model, graph engine, kernel, and attestation into a single deployable file. A `.rvf` file is segmented — each segment carries a different payload type, and unknown segments are preserved by all tools.
|
|
92
|
+
|
|
93
|
+
### Segment Types
|
|
94
|
+
|
|
95
|
+
| ID | Segment | Description |
|
|
96
|
+
|----|---------|-------------|
|
|
97
|
+
| 0x00 | MANIFEST_SEG | Level0Root manifest with file metadata |
|
|
98
|
+
| 0x01 | VEC_SEG | Raw vector data (f32, f16, bf16, int8) |
|
|
99
|
+
| 0x02 | INDEX_SEG | HNSW graph for approximate nearest neighbor |
|
|
100
|
+
| 0x03 | META_SEG | Vector metadata (JSON, CBOR) |
|
|
101
|
+
| 0x04 | QUANT_SEG | Quantization codebooks |
|
|
102
|
+
| 0x05 | OVERLAY_SEG | LoRA/adapter weight overlays |
|
|
103
|
+
| 0x06 | GRAPH_SEG | Property graph adjacency data |
|
|
104
|
+
| 0x07 | TENSOR_SEG | Dense tensor data |
|
|
105
|
+
| 0x08 | WASM_SEG | Embedded WASM modules |
|
|
106
|
+
| 0x09 | MODEL_SEG | ML model weights |
|
|
107
|
+
| 0x0A | CRYPTO_SEG | Signatures and key material |
|
|
108
|
+
| 0x0B | WITNESS_SEG | Append-only witness/audit chain |
|
|
109
|
+
| 0x0C | CONFIG_SEG | Runtime configuration |
|
|
110
|
+
| 0x0D | CUSTOM_SEG | User-defined segment |
|
|
111
|
+
| 0x0E | KERNEL_SEG | Linux microkernel image |
|
|
112
|
+
| 0x0F | EBPF_SEG | eBPF programs |
|
|
113
|
+
| 0x20 | COW_MAP_SEG | Copy-on-write cluster map |
|
|
114
|
+
| 0x21 | REFCOUNT_SEG | Cluster reference counts |
|
|
115
|
+
| 0x22 | MEMBERSHIP_SEG | Branch membership filter |
|
|
116
|
+
| 0x23 | DELTA_SEG | Sparse delta patches (LoRA) |
|
|
117
|
+
|
|
118
|
+
## N-API Methods (Node.js)
|
|
119
|
+
|
|
120
|
+
19 methods on the `RvfDatabase` class:
|
|
121
|
+
|
|
122
|
+
| Method | Description |
|
|
123
|
+
|--------|-------------|
|
|
124
|
+
| `RvfDatabase.create(path, opts)` | Create new RVF file |
|
|
125
|
+
| `RvfDatabase.open(path)` | Open existing (read-write) |
|
|
126
|
+
| `RvfDatabase.openReadonly(path)` | Open existing (read-only) |
|
|
127
|
+
| `db.ingestBatch(vectors, ids)` | Insert vectors by batch |
|
|
128
|
+
| `db.query(vector, k)` | k-NN search |
|
|
129
|
+
| `db.delete(ids)` | Delete vectors by ID |
|
|
130
|
+
| `db.deleteByFilter(filter)` | Delete vectors matching filter |
|
|
131
|
+
| `db.compact()` | Compact and reclaim space |
|
|
132
|
+
| `db.status()` | File status (count, dimension, metric) |
|
|
133
|
+
| `db.close()` | Close file handle |
|
|
134
|
+
| `db.fileId()` | UUID of this file |
|
|
135
|
+
| `db.parentId()` | UUID of parent (if derived) |
|
|
136
|
+
| `db.lineageDepth()` | Derivation depth |
|
|
137
|
+
| `db.derive(path)` | COW-branch to new file |
|
|
138
|
+
| `db.embedKernel(bytes)` | Embed Linux kernel image |
|
|
139
|
+
| `db.extractKernel()` | Extract kernel image |
|
|
140
|
+
| `db.embedEbpf(bytes)` | Embed eBPF program |
|
|
141
|
+
| `db.extractEbpf()` | Extract eBPF program |
|
|
142
|
+
| `db.segments()` | List all segments |
|
|
143
|
+
|
|
144
|
+
## WASM Exports
|
|
145
|
+
|
|
146
|
+
29 exported functions for browser and edge runtimes:
|
|
147
|
+
|
|
148
|
+
**Control plane** (10): `rvf_create`, `rvf_open`, `rvf_close`, `rvf_ingest`, `rvf_query`, `rvf_delete`, `rvf_status`, `rvf_compact`, `rvf_derive`, `rvf_segments`
|
|
149
|
+
|
|
150
|
+
**Tile compute** (14): `tile_dot_f32`, `tile_cosine_f32`, `tile_l2_f32`, `tile_dot_f16`, `tile_cosine_f16`, `tile_l2_f16`, `tile_topk`, `tile_quantize_sq8`, `tile_dequantize_sq8`, `tile_scan_filtered`, `tile_merge_topk`, `tile_batch_distance`, `tile_prefetch`, `tile_accumulate`
|
|
151
|
+
|
|
152
|
+
**Segment parsing** (3): `parse_segment_header`, `parse_vec_header`, `parse_manifest`
|
|
153
|
+
|
|
154
|
+
**Memory** (2): `rvf_alloc`, `rvf_free`
|
|
155
|
+
|
|
156
|
+
## CLI (Rust)
|
|
157
|
+
|
|
158
|
+
18 subcommands available through the `rvf` binary:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
# Core operations
|
|
162
|
+
rvf create vectors.rvf --dimension 384 --metric cosine
|
|
163
|
+
rvf ingest vectors.rvf --input data.json
|
|
164
|
+
rvf query vectors.rvf --vector "[0.1,0.2,...]" --k 10
|
|
165
|
+
rvf delete vectors.rvf --ids "[1,2,3]"
|
|
166
|
+
rvf status vectors.rvf
|
|
167
|
+
rvf inspect vectors.rvf
|
|
168
|
+
rvf compact vectors.rvf
|
|
169
|
+
|
|
170
|
+
# Branching & lineage
|
|
171
|
+
rvf derive vectors.rvf --output child.rvf
|
|
172
|
+
rvf filter vectors.rvf --include "[1,2,3]"
|
|
173
|
+
rvf freeze vectors.rvf
|
|
174
|
+
rvf rebuild-refcounts vectors.rvf
|
|
175
|
+
|
|
176
|
+
# Compute containers
|
|
177
|
+
rvf serve vectors.rvf --port 8080
|
|
178
|
+
rvf launch vectors.rvf
|
|
179
|
+
rvf embed-kernel vectors.rvf --image bzImage
|
|
180
|
+
rvf embed-ebpf vectors.rvf --program filter.o
|
|
181
|
+
|
|
182
|
+
# Verification
|
|
183
|
+
rvf verify-witness vectors.rvf
|
|
184
|
+
rvf verify-attestation vectors.rvf
|
|
185
|
+
|
|
186
|
+
# Export
|
|
187
|
+
rvf export vectors.rvf --output dump.json
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Build the CLI:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
cargo install --path crates/rvf/rvf-cli
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## Example .rvf Files
|
|
197
|
+
|
|
198
|
+
45 pre-built example files are available for download (~11 MB total). These demonstrate every segment type and use case.
|
|
199
|
+
|
|
200
|
+
### Download
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
# Download a specific example
|
|
204
|
+
curl -LO https://raw.githubusercontent.com/ruvnet/ruvector/main/examples/rvf/output/basic_store.rvf
|
|
205
|
+
|
|
206
|
+
# Clone just the examples
|
|
207
|
+
git clone --depth 1 --filter=blob:none --sparse https://github.com/ruvnet/ruvector.git
|
|
208
|
+
cd ruvector && git sparse-checkout set examples/rvf/output
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
### Example Catalog
|
|
212
|
+
|
|
213
|
+
| File | Size | Description |
|
|
214
|
+
|------|------|-------------|
|
|
215
|
+
| `basic_store.rvf` | 152 KB | 1,000 vectors, dim 128, cosine metric |
|
|
216
|
+
| `semantic_search.rvf` | 755 KB | Semantic search with HNSW index |
|
|
217
|
+
| `rag_pipeline.rvf` | 303 KB | RAG pipeline with embeddings |
|
|
218
|
+
| `embedding_cache.rvf` | 755 KB | Cached embedding store |
|
|
219
|
+
| `quantization.rvf` | 1.5 MB | PQ-compressed vectors |
|
|
220
|
+
| `progressive_index.rvf` | 2.5 MB | Large-scale progressive HNSW index |
|
|
221
|
+
| `filtered_search.rvf` | 255 KB | Metadata-filtered vector search |
|
|
222
|
+
| `recommendation.rvf` | 102 KB | Recommendation engine vectors |
|
|
223
|
+
| `agent_memory.rvf` | 32 KB | AI agent episodic memory |
|
|
224
|
+
| `swarm_knowledge.rvf` | 86 KB | Multi-agent shared knowledge base |
|
|
225
|
+
| `experience_replay.rvf` | 27 KB | RL experience replay buffer |
|
|
226
|
+
| `tool_cache.rvf` | 26 KB | MCP tool call cache |
|
|
227
|
+
| `mcp_in_rvf.rvf` | 32 KB | MCP server embedded in RVF |
|
|
228
|
+
| `ruvbot.rvf` | 51 KB | Chatbot knowledge store |
|
|
229
|
+
| `claude_code_appliance.rvf` | 17 KB | Claude Code cognitive appliance |
|
|
230
|
+
| `lineage_parent.rvf` | 52 KB | COW parent file |
|
|
231
|
+
| `lineage_child.rvf` | 26 KB | COW child (derived) file |
|
|
232
|
+
| `reasoning_parent.rvf` | 5.6 KB | Reasoning chain parent |
|
|
233
|
+
| `reasoning_child.rvf` | 8.1 KB | Reasoning chain child |
|
|
234
|
+
| `reasoning_grandchild.rvf` | 162 B | Minimal derived file |
|
|
235
|
+
| `self_booting.rvf` | 31 KB | Self-booting with KERNEL_SEG |
|
|
236
|
+
| `linux_microkernel.rvf` | 15 KB | Embedded Linux microkernel |
|
|
237
|
+
| `ebpf_accelerator.rvf` | 153 KB | eBPF distance accelerator |
|
|
238
|
+
| `browser_wasm.rvf` | 14 KB | Browser WASM module embedded |
|
|
239
|
+
| `tee_attestation.rvf` | 102 KB | TEE attestation with witnesses |
|
|
240
|
+
| `zero_knowledge.rvf` | 52 KB | ZK-proof witness chain |
|
|
241
|
+
| `crypto_signed.rvf` | (see `sealed_engine.rvf`) | Signed + sealed |
|
|
242
|
+
| `sealed_engine.rvf` | 208 KB | Sealed inference engine |
|
|
243
|
+
| `access_control.rvf` | 77 KB | Permission-gated vectors |
|
|
244
|
+
| `financial_signals.rvf` | 202 KB | Financial signal vectors |
|
|
245
|
+
| `medical_imaging.rvf` | 302 KB | Medical imaging embeddings |
|
|
246
|
+
| `legal_discovery.rvf` | 903 KB | Legal document discovery |
|
|
247
|
+
| `multimodal_fusion.rvf` | 804 KB | Multi-modal embedding fusion |
|
|
248
|
+
| `hyperbolic_taxonomy.rvf` | 23 KB | Hyperbolic space taxonomy |
|
|
249
|
+
| `network_telemetry.rvf` | 16 KB | Network telemetry vectors |
|
|
250
|
+
| `postgres_bridge.rvf` | 152 KB | PostgreSQL bridge vectors |
|
|
251
|
+
| `ruvllm_inference.rvf` | 133 KB | RuvLLM inference cache |
|
|
252
|
+
| `serverless.rvf` | 509 KB | Serverless deployment bundle |
|
|
253
|
+
| `edge_iot.rvf` | 27 KB | Edge/IoT lightweight store |
|
|
254
|
+
| `dedup_detector.rvf` | 153 KB | Deduplication detector |
|
|
255
|
+
| `compacted.rvf` | 77 KB | Post-compaction example |
|
|
256
|
+
| `posix_fileops.rvf` | 52 KB | POSIX file operations test |
|
|
257
|
+
| `network_sync_a.rvf` | 52 KB | Network sync peer A |
|
|
258
|
+
| `network_sync_b.rvf` | 52 KB | Network sync peer B |
|
|
259
|
+
| `agent_handoff_a.rvf` | 31 KB | Agent handoff source |
|
|
260
|
+
| `agent_handoff_b.rvf` | 11 KB | Agent handoff target |
|
|
261
|
+
|
|
262
|
+
### Generate Examples Locally
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
cd crates/rvf
|
|
266
|
+
cargo run --example generate_all
|
|
267
|
+
ls output/ # 45 .rvf files
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
## Integration
|
|
36
271
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
272
|
+
### With `ruvector` (npx ruvector)
|
|
273
|
+
|
|
274
|
+
The `ruvector` npm package includes 8 RVF CLI commands:
|
|
275
|
+
|
|
276
|
+
```bash
|
|
277
|
+
npm install ruvector @ruvector/rvf
|
|
278
|
+
|
|
279
|
+
# Enable RVF backend
|
|
280
|
+
export RUVECTOR_BACKEND=rvf
|
|
281
|
+
|
|
282
|
+
# Or use --backend flag
|
|
283
|
+
npx ruvector --backend rvf create mydb.rvf -d 384
|
|
284
|
+
|
|
285
|
+
# RVF-specific commands
|
|
286
|
+
npx ruvector rvf create mydb.rvf -d 384
|
|
287
|
+
npx ruvector rvf ingest mydb.rvf --input data.json
|
|
288
|
+
npx ruvector rvf query mydb.rvf --vector "[0.1,...]" --k 10
|
|
289
|
+
npx ruvector rvf status mydb.rvf
|
|
290
|
+
npx ruvector rvf segments mydb.rvf
|
|
291
|
+
npx ruvector rvf derive mydb.rvf --output child.rvf
|
|
292
|
+
npx ruvector rvf compact mydb.rvf
|
|
293
|
+
npx ruvector rvf export mydb.rvf --output dump.json
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
### With `rvlite`
|
|
297
|
+
|
|
298
|
+
```bash
|
|
299
|
+
npm install rvlite @ruvector/rvf-wasm
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
When `@ruvector/rvf-wasm` is installed, rvlite can use RVF as a persistent storage backend:
|
|
303
|
+
|
|
304
|
+
```typescript
|
|
305
|
+
import { createRvLite } from 'rvlite';
|
|
306
|
+
|
|
307
|
+
// rvlite auto-detects @ruvector/rvf-wasm for persistence
|
|
308
|
+
const db = await createRvLite({ dimensions: 384 });
|
|
309
|
+
await db.insert([0.1, 0.2, ...], { text: "Hello world" });
|
|
310
|
+
const results = await db.search([0.1, 0.2, ...], 5);
|
|
311
|
+
```
|
|
47
312
|
|
|
48
313
|
## Packages
|
|
49
314
|
|
|
50
|
-
| Package | Description |
|
|
51
|
-
|
|
52
|
-
| `@ruvector/rvf` | Unified SDK (this package) |
|
|
53
|
-
| `@ruvector/rvf-node` | Native N-API bindings |
|
|
54
|
-
| `@ruvector/rvf-wasm` | WASM build
|
|
55
|
-
| `@ruvector/rvf-mcp-server` | MCP server for AI agents |
|
|
315
|
+
| Package | Description | Runtime |
|
|
316
|
+
|---------|-------------|---------|
|
|
317
|
+
| `@ruvector/rvf` | Unified SDK (this package) | Node.js |
|
|
318
|
+
| `@ruvector/rvf-node` | Native N-API bindings | Node.js |
|
|
319
|
+
| `@ruvector/rvf-wasm` | WASM build (~46 KB + ~5.5 KB tile) | Browser, Deno, Edge |
|
|
320
|
+
| `@ruvector/rvf-mcp-server` | MCP server for AI agents | Node.js |
|
|
321
|
+
|
|
322
|
+
## Crate Structure (Rust)
|
|
323
|
+
|
|
324
|
+
| Crate | Description |
|
|
325
|
+
|-------|-------------|
|
|
326
|
+
| `rvf-types` | Wire types, segment headers, `no_std` compatible |
|
|
327
|
+
| `rvf-wire` | Serialization/deserialization |
|
|
328
|
+
| `rvf-manifest` | Level0Root manifest parsing |
|
|
329
|
+
| `rvf-index` | HNSW index operations |
|
|
330
|
+
| `rvf-quant` | Quantization codebooks |
|
|
331
|
+
| `rvf-crypto` | Signing, verification, key management |
|
|
332
|
+
| `rvf-runtime` | Full runtime (store, ingest, query, derive) |
|
|
333
|
+
| `rvf-kernel` | Linux microkernel builder |
|
|
334
|
+
| `rvf-launch` | QEMU launcher for self-booting files |
|
|
335
|
+
| `rvf-ebpf` | eBPF compiler and loader |
|
|
336
|
+
| `rvf-server` | HTTP API server (axum) |
|
|
337
|
+
| `rvf-cli` | CLI binary |
|
|
338
|
+
| `rvf-import` | Import from external formats |
|
|
56
339
|
|
|
57
340
|
## License
|
|
58
341
|
|