Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'
This commit is contained in:
ruv
290
vendor/ruvector/crates/rvf/rvf-cli/README.md
vendored
Normal file
290
vendor/ruvector/crates/rvf/rvf-cli/README.md
vendored
Normal file
@@ -0,0 +1,290 @@
|
||||
# rvf — RuVector Format CLI
|
||||
|
||||
Standalone command-line tool for creating, inspecting, querying, and managing RVF vector stores. Runs on Windows, macOS, and Linux with zero runtime dependencies.
|
||||
|
||||
## Install
|
||||
|
||||
### Pre-built binaries (recommended)
|
||||
|
||||
Download from [GitHub Releases](https://github.com/ruvnet/ruvector/releases):
|
||||
|
||||
```bash
|
||||
# macOS (Apple Silicon)
|
||||
curl -L -o rvf https://github.com/ruvnet/ruvector/releases/latest/download/rvf-darwin-arm64
|
||||
chmod +x rvf && sudo mv rvf /usr/local/bin/
|
||||
|
||||
# macOS (Intel)
|
||||
curl -L -o rvf https://github.com/ruvnet/ruvector/releases/latest/download/rvf-darwin-x64
|
||||
chmod +x rvf && sudo mv rvf /usr/local/bin/
|
||||
|
||||
# Linux x64
|
||||
curl -L -o rvf https://github.com/ruvnet/ruvector/releases/latest/download/rvf-linux-x64
|
||||
chmod +x rvf && sudo mv rvf /usr/local/bin/
|
||||
|
||||
# Linux ARM64
|
||||
curl -L -o rvf https://github.com/ruvnet/ruvector/releases/latest/download/rvf-linux-arm64
|
||||
chmod +x rvf && sudo mv rvf /usr/local/bin/
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
Invoke-WebRequest -Uri https://github.com/ruvnet/ruvector/releases/latest/download/rvf-windows-x64.exe -OutFile rvf.exe
|
||||
```
|
||||
|
||||
### Build from source
|
||||
|
||||
Requires [Rust](https://rustup.rs):
|
||||
|
||||
```bash
|
||||
cargo install --git https://github.com/ruvnet/ruvector.git rvf-cli
|
||||
```
|
||||
|
||||
Or clone and build:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/ruvnet/ruvector.git
|
||||
cd ruvector
|
||||
cargo build -p rvf-cli --release
|
||||
# Binary: target/release/rvf (or rvf.exe on Windows)
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# Create a 128-dimensional vector store with cosine distance
|
||||
rvf create mydb.rvf --dimension 128 --metric cosine
|
||||
|
||||
# Ingest vectors from JSON
|
||||
rvf ingest mydb.rvf --input vectors.json
|
||||
|
||||
# Search for nearest neighbors
|
||||
rvf query mydb.rvf --vector "0.1,0.2,0.3,..." --k 10
|
||||
|
||||
# Check store status
|
||||
rvf status mydb.rvf
|
||||
```
|
||||
|
||||
## Running the examples
|
||||
|
||||
The repo includes 48 pre-built `.rvf` example stores in `examples/rvf/output/`. Use the CLI to inspect, query, and manipulate them:
|
||||
|
||||
```bash
|
||||
# List all example stores
|
||||
ls examples/rvf/output/*.rvf
|
||||
|
||||
# Inspect a store
|
||||
rvf status examples/rvf/output/basic_store.rvf
|
||||
rvf inspect examples/rvf/output/basic_store.rvf
|
||||
|
||||
# Query the semantic search example (500 vectors, 384 dimensions)
|
||||
rvf status examples/rvf/output/semantic_search.rvf
|
||||
rvf inspect examples/rvf/output/semantic_search.rvf --json
|
||||
|
||||
# Inspect the RAG pipeline store
|
||||
rvf status examples/rvf/output/rag_pipeline.rvf
|
||||
|
||||
# Look at COW lineage (parent -> child)
|
||||
rvf inspect examples/rvf/output/lineage_parent.rvf
|
||||
rvf inspect examples/rvf/output/lineage_child.rvf
|
||||
|
||||
# Check financial signals store
|
||||
rvf status examples/rvf/output/financial_signals.rvf
|
||||
|
||||
# View the compacted store
|
||||
rvf status examples/rvf/output/compacted.rvf
|
||||
|
||||
# Inspect agent memory store
|
||||
rvf inspect examples/rvf/output/agent_memory.rvf
|
||||
|
||||
# View all stores at once (JSON)
|
||||
for f in examples/rvf/output/*.rvf; do
|
||||
echo "--- $(basename $f) ---"
|
||||
rvf status "$f" 2>/dev/null
|
||||
done
|
||||
```
|
||||
|
||||
### Available example stores
|
||||
|
||||
| Store | Vectors | Dim | Description |
|
||||
|-------|---------|-----|-------------|
|
||||
| `basic_store.rvf` | 100 | 384 | Basic vector store |
|
||||
| `semantic_search.rvf` | 500 | 384 | Semantic search embeddings |
|
||||
| `rag_pipeline.rvf` | 300 | 256 | RAG pipeline embeddings |
|
||||
| `embedding_cache.rvf` | 500 | 384 | Embedding cache |
|
||||
| `filtered_search.rvf` | 200 | 256 | Filtered search with metadata |
|
||||
| `financial_signals.rvf` | 100 | 512 | Financial signal vectors |
|
||||
| `recommendation.rvf` | 100 | 256 | Recommendation engine |
|
||||
| `medical_imaging.rvf` | 100 | 768 | Medical imaging features |
|
||||
| `multimodal_fusion.rvf` | 100 | 2048 | Multimodal fusion vectors |
|
||||
| `legal_discovery.rvf` | 100 | 768 | Legal document embeddings |
|
||||
| `progressive_index.rvf` | 1000 | 384 | Progressive HNSW index |
|
||||
| `quantization.rvf` | 1000 | 384 | Quantized vectors |
|
||||
| `swarm_knowledge.rvf` | 100 | 128 | Swarm intelligence KB |
|
||||
| `agent_memory.rvf` | 50 | 128 | Agent conversation memory |
|
||||
| `experience_replay.rvf` | 50 | 64 | RL experience replay buffer |
|
||||
| `lineage_parent.rvf` | — | — | COW parent (lineage demo) |
|
||||
| `lineage_child.rvf` | — | — | COW child (lineage demo) |
|
||||
| `compacted.rvf` | — | — | Post-compaction store |
|
||||
|
||||
## Commands
|
||||
|
||||
### create
|
||||
|
||||
Create a new empty RVF store.
|
||||
|
||||
```bash
|
||||
rvf create store.rvf --dimension 128 --metric cosine
|
||||
rvf create store.rvf -d 384 -m l2 --profile 1 --json
|
||||
```
|
||||
|
||||
Options:
|
||||
- `-d, --dimension` — Vector dimensionality (required)
|
||||
- `-m, --metric` — Distance metric: `l2`, `ip` (inner product), `cosine` (default: `l2`)
|
||||
- `-p, --profile` — Hardware profile 0-3 (default: `0`)
|
||||
- `--json` — Output as JSON
|
||||
|
||||
### ingest
|
||||
|
||||
Import vectors from a JSON file.
|
||||
|
||||
```bash
|
||||
rvf ingest store.rvf --input data.json
|
||||
rvf ingest store.rvf -i data.json --batch-size 500 --json
|
||||
```
|
||||
|
||||
Input JSON format:
|
||||
```json
|
||||
[
|
||||
{"id": 1, "vector": [0.1, 0.2, 0.3, ...]},
|
||||
{"id": 2, "vector": [0.4, 0.5, 0.6, ...]}
|
||||
]
|
||||
```
|
||||
|
||||
### query
|
||||
|
||||
Search for k nearest neighbors.
|
||||
|
||||
```bash
|
||||
rvf query store.rvf --vector "1.0,0.0,0.5,0.3" --k 10
|
||||
rvf query store.rvf -v "0.5,0.5,0.0,0.0" -k 5 --json
|
||||
```
|
||||
|
||||
With filters:
|
||||
```bash
|
||||
rvf query store.rvf -v "1.0,0.0" -k 10 \
|
||||
--filter '{"eq":{"field":0,"value":{"string":"category_a"}}}'
|
||||
```
|
||||
|
||||
### delete
|
||||
|
||||
Delete vectors by ID or filter.
|
||||
|
||||
```bash
|
||||
rvf delete store.rvf --ids 1,2,3
|
||||
rvf delete store.rvf --filter '{"gt":{"field":0,"value":{"u64":100}}}'
|
||||
```
|
||||
|
||||
### status
|
||||
|
||||
Show store status.
|
||||
|
||||
```bash
|
||||
rvf status store.rvf
|
||||
rvf status store.rvf --json
|
||||
```
|
||||
|
||||
### inspect
|
||||
|
||||
Inspect store segments and lineage.
|
||||
|
||||
```bash
|
||||
rvf inspect store.rvf
|
||||
rvf inspect store.rvf --json
|
||||
```
|
||||
|
||||
### compact
|
||||
|
||||
Reclaim dead space from deleted vectors.
|
||||
|
||||
```bash
|
||||
rvf compact store.rvf
|
||||
rvf compact store.rvf --strip-unknown --json
|
||||
```
|
||||
|
||||
### derive
|
||||
|
||||
Create a derived child store (COW branching).
|
||||
|
||||
```bash
|
||||
rvf derive parent.rvf child.rvf --derivation-type clone
|
||||
rvf derive parent.rvf child.rvf -t snapshot --json
|
||||
```
|
||||
|
||||
Derivation types: `clone`, `filter`, `merge`, `quantize`, `reindex`, `transform`, `snapshot`
|
||||
|
||||
### freeze
|
||||
|
||||
Snapshot-freeze the current state.
|
||||
|
||||
```bash
|
||||
rvf freeze store.rvf
|
||||
```
|
||||
|
||||
### verify-witness
|
||||
|
||||
Verify the tamper-evident witness chain.
|
||||
|
||||
```bash
|
||||
rvf verify-witness store.rvf
|
||||
```
|
||||
|
||||
### verify-attestation
|
||||
|
||||
Verify kernel binding and attestation.
|
||||
|
||||
```bash
|
||||
rvf verify-attestation store.rvf
|
||||
```
|
||||
|
||||
### serve
|
||||
|
||||
Start an HTTP server (requires `serve` feature).
|
||||
|
||||
```bash
|
||||
cargo build -p rvf-cli --features serve
|
||||
rvf serve store.rvf --port 8080
|
||||
```
|
||||
|
||||
### launch
|
||||
|
||||
Boot an RVF file in a QEMU microVM (requires `launch` feature).
|
||||
|
||||
```bash
|
||||
cargo build -p rvf-cli --features launch
|
||||
rvf launch store.rvf --port 8080 --memory-mb 256
|
||||
```
|
||||
|
||||
## JSON output
|
||||
|
||||
All commands support `--json` for machine-readable output:
|
||||
|
||||
```bash
|
||||
rvf status store.rvf --json | jq '.total_vectors'
|
||||
rvf query store.rvf -v "1,0,0,0" -k 5 --json | jq '.results[].id'
|
||||
```
|
||||
|
||||
## Platform scripts
|
||||
|
||||
Platform-specific quickstart scripts are in `examples/rvf/scripts/`:
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
bash examples/rvf/scripts/rvf-quickstart.sh
|
||||
|
||||
# Windows PowerShell
|
||||
.\examples\rvf\scripts\rvf-quickstart.ps1
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT OR Apache-2.0
|
||||
Reference in New Issue
Block a user