Squashed 'vendor/ruvector/' content from commit b64c2172

git-subtree-dir: vendor/ruvector
git-subtree-split: b64c21726f2bb37286d9ee36a7869fef60cc6900

examples/ruvLLM/docs/index.md

@@ -0,0 +1,138 @@
+# 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