mirror of
https://github.com/ruvnet/RuVector.git
synced 2026-05-29 19:33:34 +00:00
d5e3019b62
Iter 123 closed the ruview side (CSI UDP → cluster). This iter closes
the ruvllm side without waiting for the HEF compile pipeline: a thin
host-side bin that any ruvllm process can spawn as a subprocess and
talk to via line-delimited JSON, no gRPC client library required.
When the HEF lands later (vendor-tool blocker), the cluster's
HailoEmbedder serves real semantic vectors instead of FNV-1a placeholders;
this bridge's input/output contract doesn't change.
New crates/ruvector-hailo-cluster/src/bin/ruvllm-bridge.rs (~260 LOC):
Input (one JSON object per stdin line):
{"text": "input string to embed"}
{"text": "another", "request_id": "01HRZK..."} # optional ID
# (propagated as
# the cluster's
# ULID; iter 109)
Output (one JSON object per stdout line, matches input order):
{"dim": 384, "latency_us": 8147, "vector": [0.012, -0.045, ...]}
{"dim": 384, "latency_us": 5432, "request_id": "01HRZK...",
"vector": [...]}
{"error": "cluster unreachable: ..."}
Closing stdin = clean exit 0. Errors per request don't kill the bin —
every failure surfaces as a `{"error":"..."}` line and the loop
continues. Lets long-running ruvllm sessions ride out transient
cluster hiccups.
Same flag set as the other two bridges:
--workers <csv> REQUIRED (--workers without --fingerprint
refused by the §2a gate unless
--allow-empty-fingerprint is set)
--fingerprint --dim --allow-empty-fingerprint --quiet
--tls-ca --tls-domain --tls-client-cert --tls-client-key
(§1a / §1b parity, gated on --features tls)
Hand-rolled JSON parser + emitter for the request/response shape
(avoids pulling serde_json's mid-line reader into stdin handling
and keeps the bin's link surface small). Handles \", \\, \n, \t
and \uXXXX escapes; passthrough for everything else. Sufficient
for real prompt content.
Live verification (3 cases against fakeworker on ephemeral port):
$ echo '{"text":"hello world from ruvllm"}' | \
ruvllm-bridge --workers 127.0.0.1:NNN --dim 4 --fingerprint fp:llm-demo --quiet
{"dim":4,"latency_us":1358,"vector":[-0.873,-0.923,0.427,-0.220]}
$ printf '{"text":"first"}\n{"text":"second","request_id":"01HRZK..."}\n' | \
ruvllm-bridge ...
{"dim":4,"latency_us":1000,"vector":[...]}
{"dim":4,"latency_us":485,"request_id":"01HRZK...","vector":[...]}
Multi-line + request_id propagation both work; vectors come back
with stable Debug-formatted float precision so the wire bytes
round-trip exactly.
Cargo.toml: new [[bin]] entry; ADR-168 updated to list 8th bin.
Validation:
- cargo build --bin ruvllm-bridge: clean (default + tls)
- clippy --all-targets -D warnings: clean for both feature configs
(Duration import only used under feature = "tls", correctly cfg-gated)
- cargo test --features tls: 20 test groups all green
Bridge ecosystem after iter 124:
ruvector-mmwave-bridge 60 GHz radar UART → cluster (iter 116)
ruview-csi-bridge WiFi CSI UDP → cluster (iter 123)
ruvllm-bridge JSONL stdin/RPC → cluster (iter 124)
Three sensor-modality entry points sharing one cluster, all hardened
under §1b mTLS / §2a fp+cache / §3b rate-limit. ADR-171 and ADR-173
seam implementations both shipped.
Co-Authored-By: claude-flow <ruv@ruv.net>
|
||
|---|---|---|
| .. | ||
| adr | ||
| analysis | ||
| api | ||
| architecture | ||
| benchmarks | ||
| cloud-architecture | ||
| cnn | ||
| code-reviews | ||
| dag | ||
| development | ||
| examples | ||
| gnn | ||
| guides | ||
| hnsw | ||
| hooks | ||
| implementation | ||
| integration | ||
| nervous-system | ||
| optimization | ||
| plans/subpolynomial-time-mincut | ||
| postgres | ||
| project-phases | ||
| publishing | ||
| research | ||
| reviews | ||
| ruvllm | ||
| rvagent | ||
| sdk | ||
| security | ||
| sparse-inference | ||
| sql | ||
| testing | ||
| training | ||
| .gitkeep | ||
| .nojekyll | ||
| agi-container.md | ||
| C2-shell-execution-hardening.md | ||
| C8_RESULT_VALIDATION_IMPLEMENTATION.md | ||
| consciousness-api.md | ||
| IMPLEMENTATION-C5.md | ||
| index.html | ||
| INDEX.md | ||
| moe-routing-optimization-analysis.md | ||
| README.md | ||
| REPO_STRUCTURE.md | ||
| research-openfang.md | ||
RuVector Documentation
Complete documentation for RuVector, the high-performance Rust vector database with global scale capabilities.
📚 Documentation Structure
docs/
├── adr/ # Architecture Decision Records
├── analysis/ # Research & analysis docs
├── api/ # API references (Rust, Node.js, Cypher)
├── architecture/ # System design docs
├── benchmarks/ # Performance benchmarks & results
├── cloud-architecture/ # Cloud deployment guides
├── code-reviews/ # Code review documentation
├── dag/ # DAG implementation
├── development/ # Developer guides
├── examples/ # SQL examples
├── gnn/ # GNN/Graph implementation
├── guides/ # User guides & tutorials
├── hnsw/ # HNSW index documentation
├── hooks/ # Hooks system documentation
├── implementation/ # Implementation details & summaries
├── integration/ # Integration guides
├── nervous-system/ # Nervous system architecture
├── optimization/ # Performance optimization guides
├── plans/ # Implementation plans
├── postgres/ # PostgreSQL extension docs
├── project-phases/ # Development phases
├── publishing/ # NPM publishing guides
├── research/ # Research documentation
├── ruvllm/ # RuVLLM documentation
├── security/ # Security audits & reports
├── sparse-inference/ # Sparse inference docs
├── sql/ # SQL examples
├── testing/ # Testing documentation
└── training/ # Training & LoRA docs
Getting Started
- guides/GETTING_STARTED.md - Getting started guide
- guides/BASIC_TUTORIAL.md - Basic tutorial
- guides/INSTALLATION.md - Installation instructions
- guides/AGENTICDB_QUICKSTART.md - AgenticDB quick start
- guides/wasm-api.md - WebAssembly API documentation
Architecture & Design
- architecture/ - System architecture details
- cloud-architecture/ - Global cloud deployment
- adr/ - Architecture Decision Records
- nervous-system/ - Nervous system architecture
API Reference
- api/RUST_API.md - Rust API reference
- api/NODEJS_API.md - Node.js API reference
- api/CYPHER_REFERENCE.md - Cypher query reference
Performance & Benchmarks
- benchmarks/ - Performance benchmarks & results
- optimization/ - Performance optimization guides
- analysis/ - Research & analysis docs
Security
- security/ - Security audits & reports
Implementation
- implementation/ - Implementation details & summaries
- integration/ - Integration guides
- code-reviews/ - Code review documentation
Specialized Topics
- gnn/ - GNN/Graph implementation
- hnsw/ - HNSW index documentation
- postgres/ - PostgreSQL extension docs
- ruvllm/ - RuVLLM documentation
- training/ - Training & LoRA docs
Development
- development/CONTRIBUTING.md - Contribution guidelines
- development/MIGRATION.md - Migration guide
- testing/ - Testing documentation
- publishing/ - NPM publishing guides
Research
- research/ - Research documentation
- cognitive-frontier/ - Cognitive frontier research
- gnn-v2/ - GNN v2 research
- latent-space/ - HNSW & attention research
- mincut/ - MinCut algorithm research
🚀 Quick Links
For New Users
- Start with Getting Started Guide
- Try the Basic Tutorial
- Review API Documentation
For Cloud Deployment
- Read Architecture Overview
- Follow Deployment Guide
- Apply Performance Optimizations
For Contributors
- Read Contributing Guidelines
- Review Architecture Decisions
- Check Migration Guide
For Performance Tuning
- Review Optimization Guide
- Run Benchmarks
- Check Analysis
📊 Documentation Status
| Category | Directory | Status |
|---|---|---|
| Getting Started | guides/ | ✅ Complete |
| Architecture | architecture/, adr/ | ✅ Complete |
| API Reference | api/ | ✅ Complete |
| Performance | benchmarks/, optimization/, analysis/ | ✅ Complete |
| Security | security/ | ✅ Complete |
| Implementation | implementation/, integration/ | ✅ Complete |
| Development | development/, testing/ | ✅ Complete |
| Research | research/ | 📚 Ongoing |
Total Documentation: 460+ documents across 60+ directories
🔗 External Resources
- GitHub Repository: https://github.com/ruvnet/ruvector
- Main README: ../README.md
- Changelog: ../CHANGELOG.md
- License: ../LICENSE
Last Updated: 2026-02-26 | Version: 2.0.4 (core) / 0.1.100 (npm) | Status: Production Ready