mirror of
https://github.com/ruvnet/RuVector.git
synced 2026-05-26 07:44:05 +00:00
Merge pull request #178 from ruvnet/feat/rvf-cli-release
feat: RVF CLI cross-platform release binaries
This commit is contained in:
rUv
GitHub
commit
91f78415fd
2 changed files with 371 additions and 24 deletions
171
.github/workflows/release-rvf-cli.yml
vendored
Normal file
171
.github/workflows/release-rvf-cli.yml
vendored
Normal file
|
|
@ -0,0 +1,171 @@
|
|||
name: Release RVF CLI
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- 'rvf-v*'
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
tag:
|
||||
description: 'Release tag (e.g. rvf-v0.1.0)'
|
||||
required: true
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
|
||||
jobs:
|
||||
build:
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- target: x86_64-unknown-linux-gnu
|
||||
os: ubuntu-22.04
|
||||
name: rvf-linux-x64
|
||||
ext: ''
|
||||
- target: aarch64-unknown-linux-gnu
|
||||
os: ubuntu-22.04
|
||||
name: rvf-linux-arm64
|
||||
ext: ''
|
||||
cross: true
|
||||
- target: x86_64-apple-darwin
|
||||
os: macos-14
|
||||
name: rvf-darwin-x64
|
||||
ext: ''
|
||||
- target: aarch64-apple-darwin
|
||||
os: macos-14
|
||||
name: rvf-darwin-arm64
|
||||
ext: ''
|
||||
- target: x86_64-pc-windows-msvc
|
||||
os: windows-2022
|
||||
name: rvf-windows-x64
|
||||
ext: .exe
|
||||
|
||||
name: Build ${{ matrix.name }}
|
||||
runs-on: ${{ matrix.os }}
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Setup Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
toolchain: stable
|
||||
targets: ${{ matrix.target }}
|
||||
|
||||
- name: Cache Rust
|
||||
uses: Swatinem/rust-cache@v2
|
||||
with:
|
||||
key: rvf-cli-${{ matrix.target }}
|
||||
|
||||
- name: Install cross-compilation tools (Linux ARM64)
|
||||
if: matrix.cross
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
|
||||
|
||||
- name: Build
|
||||
shell: bash
|
||||
run: cargo build -p rvf-cli --release --target ${{ matrix.target }}
|
||||
env:
|
||||
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
|
||||
|
||||
- name: Package
|
||||
shell: bash
|
||||
run: |
|
||||
BINARY="target/${{ matrix.target }}/release/rvf${{ matrix.ext }}"
|
||||
ARCHIVE="${{ matrix.name }}${{ matrix.ext }}"
|
||||
|
||||
if [ "${{ matrix.ext }}" = ".exe" ]; then
|
||||
cp "$BINARY" "$ARCHIVE"
|
||||
else
|
||||
chmod +x "$BINARY"
|
||||
cp "$BINARY" "$ARCHIVE"
|
||||
fi
|
||||
|
||||
ls -lh "$ARCHIVE"
|
||||
|
||||
- name: Upload artifact
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: ${{ matrix.name }}
|
||||
path: ${{ matrix.name }}${{ matrix.ext }}
|
||||
if-no-files-found: error
|
||||
|
||||
release:
|
||||
name: Create GitHub Release
|
||||
needs: build
|
||||
runs-on: ubuntu-22.04
|
||||
if: startsWith(github.ref, 'refs/tags/rvf-v') || github.event_name == 'workflow_dispatch'
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Download all artifacts
|
||||
uses: actions/download-artifact@v4
|
||||
with:
|
||||
path: artifacts
|
||||
|
||||
- name: Prepare release assets
|
||||
run: |
|
||||
mkdir -p release
|
||||
for dir in artifacts/*/; do
|
||||
name=$(basename "$dir")
|
||||
file=$(ls "$dir" | head -1)
|
||||
cp "$dir/$file" "release/$file"
|
||||
done
|
||||
ls -lh release/
|
||||
|
||||
- name: Compute checksums
|
||||
working-directory: release
|
||||
run: |
|
||||
sha256sum * > checksums-sha256.txt
|
||||
cat checksums-sha256.txt
|
||||
|
||||
- name: Determine tag
|
||||
id: tag
|
||||
run: |
|
||||
if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
|
||||
echo "tag=${{ github.event.inputs.tag }}" >> "$GITHUB_OUTPUT"
|
||||
else
|
||||
echo "tag=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
- name: Create Release
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
tag_name: ${{ steps.tag.outputs.tag }}
|
||||
name: "RVF CLI ${{ steps.tag.outputs.tag }}"
|
||||
body: |
|
||||
## RVF CLI Release
|
||||
|
||||
Standalone vector database CLI for creating, querying, and managing RVF stores.
|
||||
|
||||
### Download
|
||||
|
||||
| Platform | Binary |
|
||||
|----------|--------|
|
||||
| Linux x64 | `rvf-linux-x64` |
|
||||
| Linux ARM64 | `rvf-linux-arm64` |
|
||||
| macOS x64 (Intel) | `rvf-darwin-x64` |
|
||||
| macOS ARM64 (Apple Silicon) | `rvf-darwin-arm64` |
|
||||
| Windows x64 | `rvf-windows-x64.exe` |
|
||||
|
||||
### Quick start
|
||||
|
||||
```bash
|
||||
# Download (macOS ARM64 example)
|
||||
curl -L -o rvf https://github.com/ruvnet/ruvector/releases/download/${{ steps.tag.outputs.tag }}/rvf-darwin-arm64
|
||||
chmod +x rvf
|
||||
|
||||
# Create a store and query
|
||||
./rvf create mydb.rvf --dimension 128 --metric cosine
|
||||
./rvf status mydb.rvf
|
||||
```
|
||||
|
||||
See the [CLI README](https://github.com/ruvnet/ruvector/tree/main/crates/rvf/rvf-cli) for full documentation.
|
||||
files: release/*
|
||||
draft: false
|
||||
prerelease: false
|
||||
|
|
@ -1,20 +1,130 @@
|
|||
# rvf-cli
|
||||
# rvf — RuVector Format CLI
|
||||
|
||||
Unified command-line interface for RuVector Format operations.
|
||||
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
|
||||
cargo install --path crates/rvf/rvf-cli
|
||||
# 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/
|
||||
```
|
||||
|
||||
Or build from source:
|
||||
**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)
|
||||
```
|
||||
|
||||
The binary is named `rvf`.
|
||||
## 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
|
||||
|
||||
|
|
@ -23,23 +133,31 @@ The binary is named `rvf`.
|
|||
Create a new empty RVF store.
|
||||
|
||||
```bash
|
||||
rvf create store.rvf --dimension 128 --metric cosine --profile 0
|
||||
rvf create store.rvf -d 128 -m l2 --json
|
||||
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 JSON, CSV, or TSV files.
|
||||
Import vectors from a JSON file.
|
||||
|
||||
```bash
|
||||
# JSON format: [{"id": 0, "vector": [1.0, 0.0, ...]}, ...]
|
||||
rvf ingest store.rvf --input data.json --format json
|
||||
rvf ingest store.rvf --input data.json
|
||||
rvf ingest store.rvf -i data.json --batch-size 500 --json
|
||||
```
|
||||
|
||||
# CSV format: each row is a vector (auto-assigned IDs)
|
||||
rvf ingest store.rvf --input data.csv --format csv
|
||||
|
||||
# TSV
|
||||
rvf ingest store.rvf --input data.tsv --format tsv --json
|
||||
Input JSON format:
|
||||
```json
|
||||
[
|
||||
{"id": 1, "vector": [0.1, 0.2, 0.3, ...]},
|
||||
{"id": 2, "vector": [0.4, 0.5, 0.6, ...]}
|
||||
]
|
||||
```
|
||||
|
||||
### query
|
||||
|
|
@ -47,17 +165,23 @@ rvf ingest store.rvf --input data.tsv --format tsv --json
|
|||
Search for k nearest neighbors.
|
||||
|
||||
```bash
|
||||
rvf query store.rvf --vector "1.0,0.0,0.0,0.0" --k 10
|
||||
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.
|
||||
Delete vectors by ID or filter.
|
||||
|
||||
```bash
|
||||
rvf delete store.rvf --ids 1,2,3
|
||||
rvf delete store.rvf --ids 42 --json
|
||||
rvf delete store.rvf --filter '{"gt":{"field":0,"value":{"u64":100}}}'
|
||||
```
|
||||
|
||||
### status
|
||||
|
|
@ -84,16 +208,42 @@ Reclaim dead space from deleted vectors.
|
|||
|
||||
```bash
|
||||
rvf compact store.rvf
|
||||
rvf compact store.rvf --json
|
||||
rvf compact store.rvf --strip-unknown --json
|
||||
```
|
||||
|
||||
### derive
|
||||
|
||||
Create a derived child store from a parent.
|
||||
Create a derived child store (COW branching).
|
||||
|
||||
```bash
|
||||
rvf derive parent.rvf child.rvf --derivation-type filter
|
||||
rvf derive parent.rvf child.rvf --derivation-type snapshot --json
|
||||
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
|
||||
|
|
@ -105,9 +255,35 @@ cargo build -p rvf-cli --features serve
|
|||
rvf serve store.rvf --port 8080
|
||||
```
|
||||
|
||||
## JSON Output
|
||||
### launch
|
||||
|
||||
All commands support `--json` for machine-readable output suitable for piping to `jq` or other tools.
|
||||
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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue