mirror of
https://github.com/ruvnet/RuVector.git
synced 2026-05-28 09:53:36 +00:00
844db18b4b
Reframes `examples/ruvLLM/esp32-flash` from a single-chip "tiny LLM" skeleton (which had drifted out of sync with `lib.rs` and was reported as broken in #409) into a fleet of tiny ruvLLM/ruvector agents. Each ESP32 chip runs ONE role drawn from the canonical primitive surface defined in ADR-002, ADR-074, ADR-084. Roles (one binary, one chip, one role): HnswIndexer — MicroHNSW kNN + HashEmbedder (ESP32-C3 default) RagRetriever — MicroRAG retrieval (ESP32 default) AnomalySentinel — AnomalyDetector (ESP32-S2 default) MemoryArchivist — SemanticMemory type-tagged (ESP32-C6 default) LoraAdapter — MicroLoRA rank 1-2 (ESP32-S3 SIMD) SpeculativeDrafter — SpeculativeDecoder (ESP32-S3 default) PipelineRelay — PipelineNode head/middle/tail Verified end-to-end: cargo build --no-default-features --features host-test → green; all 5 variants boot to correct default role; smoke tests confirm RagRetriever recall, MemoryArchivist recall by type, AnomalySentinel learn+check. cargo +esp build --release --target xtensa-esp32s3-espidf → green; 858 KB ELF. espflash flash --chip esp32s3 /dev/ttyACM0 … → 451 KB programmed; chip boots; Rust main entered; TinyAgent constructed with HNSW capacity 32; banner + stats reach the host on /dev/ttyACM0: === ruvllm-esp32 tiny-agent (ADR-165) === variant=esp32s3 role=SpeculativeDrafter chip_id=0 sram_kb=512 [ready] type 'help' for commands role=SpeculativeDrafter variant=esp32s3 sram_kb=512 ops=0 hnsw=0 Issues solved while wiring up the cross-compile and on-device path: - build.rs cfg(target_os) evaluated against the host, not the cargo target. Switched to env::var("CARGO_CFG_TARGET_OS") so embuild's espidf::sysenv::output() runs only when actually cross-compiling to *-espidf — required for ldproxy's --ldproxy-linker arg to propagate into the link line. - embuild now needs `features = ["espidf"]` in build-dependencies. - esp-idf-svc 0.49.1 / esp-idf-hal 0.46.2 had a *const i8 / *const u8 bindgen regression and a broken TransmitConfig field; pinned the trio to 0.51.0 / 0.45.2 / 0.36.1. - The host's RUSTFLAGS=-C link-arg=-fuse-ld=mold breaks Xtensa link (mold doesn't speak Xtensa). CI invocation in the workflow uses `env -u RUSTFLAGS` and the README documents the local override. - `.cargo/config.toml` only declared xtensa-esp32-espidf — added blocks for esp32s2, esp32s3, esp32c3, esp32c6 with linker = "ldproxy". - ESP32-S3 dev board exposes USB-Serial/JTAG, not the UART0 GPIO pins my prior main was driving. Switched the device main path to `usb_serial_jtag_write_bytes` / `_read_bytes` directly so I/O actually reaches /dev/ttyACM0. - `sdkconfig.defaults` was per-variant inconsistent (ESP32 keys on an S3 build). Split into a chip-agnostic base + per-variant `sdkconfig.defaults.<target>` files (`sdkconfig.defaults.esp32s3` is the first; CI matrix will add the others). - Bumped main task stack to 96 KB and dropped HNSW capacity to 32 so TinyAgent fits without overflowing on Xtensa stack growth. Files: ADR-165 — formal decision record (context, role catalog, per-variant assignment, embedder choice, federation bus, build/release plan, acceptance gates G1–G6, out-of-scope, roadmap). build.rs — cfg-via-env-var fix. Cargo.toml — pinned trio + binstart + native + embuild espidf. .cargo/config.toml — ldproxy linker for all 5 ESP32 variants. sdkconfig.defaults + sdkconfig.defaults.esp32s3 — split base / S3. src/main.rs — full rewrite as TinyAgent role engine; HashEmbedder per ADR-074 Tier 1; UART CLI on host-test; usb_serial_jtag CLI on esp32; WASM shim untouched. README.md — top-of-file rewrite with the ADR-165 framing, role matrix, primitive surface, and explicit "honest scope" disclaimer pointing at #409 + ADR-090 for the PSRAM big-model path. .github/workflows/ruvllm-esp32-firmware.yml — three-job CI: host-test smoke (G1–G3), matrix cross-compile via `espup install --targets $variant` + `cargo +esp build --release` + `espflash save-image --merge`, attach `ruvllm-esp32-${target}.bin` assets matching the URL pattern in `npm/web-flasher/index.html`. .gitignore — exclude target/, .embuild/, *.bin from the example dir. Closes #409 observations 1a, 1b, 3 in this commit. Observation 2 (no firmware in releases) closes when CI runs against the next ruvllm-esp32 tag. 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