d803bfe2b1
git-subtree-dir: vendor/ruvector git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900
139 lines
5.8 KiB
Markdown
139 lines
5.8 KiB
Markdown
# RuvLLM Documentation
|
|
|
|
## Overview
|
|
|
|
This directory contains documentation for the RuvLLM self-learning LLM architecture.
|
|
|
|
## Quick Links
|
|
|
|
- [Main README](../README.md) - Getting started, API reference, benchmarks
|
|
- [SPARC Documentation](./sparc/) - Design methodology documentation
|
|
|
|
## SPARC Methodology
|
|
|
|
The project was designed using the SPARC methodology:
|
|
|
|
| Phase | Document | Description |
|
|
|-------|----------|-------------|
|
|
| 1 | [Specification](./sparc/01-specification.md) | Requirements and acceptance criteria |
|
|
| 2 | [Pseudocode](./sparc/02-pseudocode.md) | Algorithm design and data flows |
|
|
| 3 | [Architecture](./sparc/03-architecture.md) | System design and component interactions |
|
|
| 4 | [Refinement](./sparc/04-refinement.md) | TDD implementation and iterative improvement |
|
|
| 5 | [Completion](./sparc/05-completion.md) | Integration, testing, and deployment |
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ RuvLLM System │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ Embedding │ │ Memory │ │ Router │ │
|
|
│ │ Service │ │ (HNSW) │ │ (FastGRNN) │ │
|
|
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
|
|
│ │ │ │ │
|
|
│ └────────────────┼────────────────┘ │
|
|
│ │ │
|
|
│ ┌──────┴──────┐ │
|
|
│ │ Orchestrator │ │
|
|
│ └──────┬──────┘ │
|
|
│ │ │
|
|
│ ┌─────────────┐ ┌──────┴──────┐ ┌─────────────┐ │
|
|
│ │ Attention │ │ Inference │ │ Learning │ │
|
|
│ │ Engine │ │ Pool │ │ Service │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Module Documentation
|
|
|
|
### Core Modules
|
|
|
|
| Module | File | Description |
|
|
|--------|------|-------------|
|
|
| `orchestrator` | `src/orchestrator.rs` | Main coordinator, request processing pipeline |
|
|
| `memory` | `src/memory.rs` | HNSW-based semantic memory with graph expansion |
|
|
| `router` | `src/router.rs` | FastGRNN routing with EWC learning |
|
|
| `attention` | `src/attention.rs` | Multi-head graph attention with edge features |
|
|
| `embedding` | `src/embedding.rs` | Tokenization, embedding, and caching |
|
|
| `inference` | `src/inference.rs` | LFM2 model pool management |
|
|
| `learning` | `src/learning.rs` | Self-learning feedback loops |
|
|
| `compression` | `src/compression.rs` | Memory compression and clustering |
|
|
|
|
### Supporting Modules
|
|
|
|
| Module | File | Description |
|
|
|--------|------|-------------|
|
|
| `config` | `src/config.rs` | Configuration system with builder pattern |
|
|
| `error` | `src/error.rs` | Error types and result aliases |
|
|
| `types` | `src/types.rs` | Core domain types and structs |
|
|
|
|
## API Examples
|
|
|
|
### Basic Query
|
|
|
|
```rust
|
|
use ruvllm::{Config, RuvLLM};
|
|
|
|
let config = Config::builder().build()?;
|
|
let llm = RuvLLM::new(config).await?;
|
|
let response = llm.query("What is Rust?").await?;
|
|
```
|
|
|
|
### Session Management
|
|
|
|
```rust
|
|
let session = llm.new_session();
|
|
let r1 = llm.query_session(&session, "Tell me about vectors").await?;
|
|
let r2 = llm.query_session(&session, "How are they used in ML?").await?;
|
|
```
|
|
|
|
### Feedback Loop
|
|
|
|
```rust
|
|
use ruvllm::Feedback;
|
|
|
|
llm.feedback(Feedback {
|
|
request_id: response.request_id,
|
|
rating: Some(5),
|
|
correction: None,
|
|
task_success: Some(true),
|
|
}).await?;
|
|
```
|
|
|
|
## Performance Tuning
|
|
|
|
### Memory Configuration
|
|
|
|
```rust
|
|
Config::builder()
|
|
.hnsw_params(
|
|
32, // M: connections per node (higher = better recall, more memory)
|
|
200, // ef_construction: build quality (higher = slower build, better index)
|
|
64, // ef_search: search quality (higher = slower search, better recall)
|
|
)
|
|
```
|
|
|
|
### Router Configuration
|
|
|
|
```rust
|
|
Config::builder()
|
|
.router_hidden_dim(128) // Hidden state size (higher = more capacity)
|
|
```
|
|
|
|
### Learning Configuration
|
|
|
|
```rust
|
|
Config::builder()
|
|
.learning_enabled(true) // Enable self-learning
|
|
```
|
|
|
|
## Further Reading
|
|
|
|
- [LFM2 Paper](https://arxiv.org/abs/2511.23404v1) - Liquid Foundation Models
|
|
- [FastGRNN Paper](https://arxiv.org/abs/1901.02358) - Fast RNN architecture
|
|
- [HNSW Paper](https://arxiv.org/abs/1603.09320) - Approximate nearest neighbor search
|
|
- [EWC Paper](https://arxiv.org/abs/1612.00796) - Continual learning
|