mirror of
https://github.com/ruvnet/RuVector.git
synced 2026-08-31 02:05:14 +00:00
1e1740a876
* docs(adr): ADR-252 HelixDB vs RuVector comparison and improvement opportunities Compares HelixDB (LMDB/heed, compiled type-safe HelixQL, graph-vector thesis, graph-vector-bench) against RuVector's redb/Cypher/hybrid stack and proposes 7 prioritized, opt-in improvements: optional schema layer with load-time validation, first-class typed graph-vector binding and a unified search-then-traverse operator, in-query embed(), unified ANN+BM25+graph RRF hybrid, a reproducible benchmark harness, schema-driven typed SDK codegen, and an object-storage tier research spike. https://claude.ai/code/session_01BrEtcS3KZykinsv9RoBGrF * feat(ruvector-graph): native schema layer + typed search-then-traverse (ADR-252 P1/P2/P4) Implements the HelixDB-inspired improvements natively in ruvector-graph: - schema.rs: opt-in GraphSchema (N::/E::/V:: equivalents) with load-time validation (self-consistency, node required/typed props + strict mode, edge from/to label constraints, vector dimension checks), higher-is-better distance metrics (cosine/dot/euclidean), and reciprocal_rank_fusion (P4). - typed_graph.rs: TypedGraph wrapper validating mutations pre-storage, plus a fused typed search_then_traverse operator (HelixQL SearchV<T>(q,k)::In/Out<E>) with optimized bounded-heap top-k selection (O(n log k)). Pure-Rust, no new deps, WASM-safe. 13 new tests, 148/148 lib tests green, clippy clean. Schemaless mode remains the default (opt-in coexistence). https://claude.ai/code/session_01BrEtcS3KZykinsv9RoBGrF * perf(ruvector-graph): optimize search_then_traverse + add criterion bench (ADR-252) Hot-path optimizations for the typed search-then-traverse operator: - GraphDB::with_node / node_ids_by_label: zero-copy borrow scoring, eliminating per-candidate Node + embedding clones (get_nodes_by_label cloned everything). - Fused single-pass cosine (q.c and c.c in one read of the candidate) + hoisted query norm out of the per-candidate loop. - Bounded top-k min-heap (O(n log k)); clone id only for heap winners. - Rayon parallel scan over DashMap for >=4096 candidates (per-thread heaps, bounded merge); serial path below threshold. Adds benches/typed_graph_bench.rs (criterion). Measured vs first cut (128-dim, k=10): 10k 7.2ms->3.08ms (2.34x), 50k 74.3ms->28.5ms (2.61x), 1k 539us->432us. New parallel-vs-reference correctness test. 149/149 lib tests green, clippy clean. https://claude.ai/code/session_01BrEtcS3KZykinsv9RoBGrF * feat(ruvector-graph): HNSW push-down for search_then_traverse (ADR-252 P2) Adds an opt-in ANN path to the typed search-then-traverse operator, removing the O(n) full-label scan for indexed vector types: - TypedGraph::build_vector_index(vector_type) builds a per-vector-type HybridIndex (HNSW under hnsw_rs, exact FlatIndex otherwise), holding only the bound label's nodes so searches stay label-scoped. Kept current incrementally via create_node -> index_node. - search_then_traverse routes through the index when present: ~O(log n) approximate search, over-fetch (max(4k, k+32)), then exact rescore with the schema metric so ANN results carry identical higher-is-better score semantics to the brute-force path. Brute force remains the default. - Parallel brute-force path refactored to capture &GraphDB (not &self) so it stays Send+Sync independent of the index's thread-safety bounds. Bench (50k nodes, 128-dim, k=10): brute-force parallel scan 27.6ms -> HNSW push-down 1.05ms (~26x; ~70x vs first cut). 151/151 lib tests green (3 new HNSW tests), clippy clean. https://claude.ai/code/session_01BrEtcS3KZykinsv9RoBGrF * feat(ruvector-graph): inline embed() + tri-modal BM25/ANN/graph hybrid (ADR-252 P3/P4) P3 - inline embedding (HelixQL Embed()): - embed.rs: Embedder trait + dependency-free deterministic HashEmbedder (feature-hashing, explicit opt-in, never a silent fallback per ADR-194). - TypedGraph::with_embedder / embed / create_node_from_text (embed-at-insert, dimension-validated) / search_text (embed-at-query). P4 - tri-modal hybrid query: - bm25.rs: self-contained Okapi-BM25 inverted index. - TypedGraph::build_text_index + hybrid_search_text fusing ANN vector + BM25 keyword + graph traversal via reciprocal rank fusion in one typed call. - Refactored search_then_traverse into shared rank_seeds/expand helpers. Bench: hash_embed_256 717ns; tri_modal_hybrid over 10k docs (embed+HNSW+BM25+ RRF+traverse) 1.63ms end-to-end. 164/164 lib tests green (+13), clippy clean. https://claude.ai/code/session_01BrEtcS3KZykinsv9RoBGrF * feat(ruvector-graph): schema-driven typed SDK codegen (ADR-252 P6) codegen.rs generates typed client stubs from a GraphSchema: - generate_typescript: interfaces with typed/optional properties (@indexed hints), edge from->to constraints, and a VectorTypes manifest + VectorTypeName. - generate_python: TypedDict classes + VECTOR_TYPES manifest. - generate_rust: serde-ready structs. Deterministic (schema elements sorted) for check-in/diff. Adds *_schemas_sorted accessors to GraphSchema. Closes HelixDB's schema->typed-SDK DX advantage. 168/168 lib tests green (+4), clippy clean. https://claude.ai/code/session_01BrEtcS3KZykinsv9RoBGrF * docs(adr): renumber ADR-252 -> ADR-253 (252 taken by FastGRNN training pipeline) ADR-252 was already merged to main as the tiny-dancer FastGRNN training pipeline. Renumber this HelixDB comparison to ADR-253 to resolve the collision. Co-Authored-By: claude-flow <ruv@ruv.net> --------- Co-authored-by: Claude <noreply@anthropic.com> Co-authored-by: ruv <ruvnet@users.noreply.github.com> |
||
|---|---|---|
| .. | ||
| adr | ||
| analysis | ||
| api | ||
| architecture | ||
| benchmarks | ||
| cloud-architecture | ||
| cnn | ||
| code-reviews | ||
| dag | ||
| development | ||
| examples | ||
| gnn | ||
| guides | ||
| hailo | ||
| 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