ruvector/examples/ruvLLM/docs/index.md

RuvLLM Documentation

Overview

This directory contains documentation for the RuvLLM self-learning LLM architecture.

Quick Links

• Main README - Getting started, API reference, benchmarks
• SPARC Documentation - Design methodology documentation

SPARC Methodology

The project was designed using the SPARC methodology:

Phase	Document	Description
1	Specification	Requirements and acceptance criteria
2	Pseudocode	Algorithm design and data flows
3	Architecture	System design and component interactions
4	Refinement	TDD implementation and iterative improvement
5	Completion	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

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

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

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

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

Config::builder()
    .router_hidden_dim(128)  // Hidden state size (higher = more capacity)

Learning Configuration

Config::builder()
    .learning_enabled(true)  // Enable self-learning

Further Reading

• LFM2 Paper - Liquid Foundation Models
• FastGRNN Paper - Fast RNN architecture
• HNSW Paper - Approximate nearest neighbor search
• EWC Paper - Continual learning