From 2238362980864d5f16802c98f395474cb3c25e8f Mon Sep 17 00:00:00 2001 From: rUv Date: Mon, 16 Feb 2026 23:19:39 +0000 Subject: [PATCH] feat(rvf-cli): add cross-platform release workflow and update README - Add release-rvf-cli.yml: builds standalone binaries for Linux x64/ARM64, macOS x64/ARM64, and Windows x64 on tag push (rvf-v*) - Creates GitHub Release with all binaries and SHA256 checksums - Update CLI README with install instructions for pre-built binaries, examples/rvf/output/ usage guide, and full command reference Co-Authored-By: claude-flow --- .github/workflows/release-rvf-cli.yml | 171 ++++++++++++++++++++ crates/rvf/rvf-cli/README.md | 224 +++++++++++++++++++++++--- 2 files changed, 371 insertions(+), 24 deletions(-) create mode 100644 .github/workflows/release-rvf-cli.yml diff --git a/.github/workflows/release-rvf-cli.yml b/.github/workflows/release-rvf-cli.yml new file mode 100644 index 00000000..dd862f27 --- /dev/null +++ b/.github/workflows/release-rvf-cli.yml @@ -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 diff --git a/crates/rvf/rvf-cli/README.md b/crates/rvf/rvf-cli/README.md index 599abeef..56fde902 100644 --- a/crates/rvf/rvf-cli/README.md +++ b/crates/rvf/rvf-cli/README.md @@ -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