Update model card for v2.4 Ecosystem Edition with 100% routing accuracy

README.md

@@ -24,6 +24,7 @@ tags:
 - sota
 - task-routing
 - semantic-search
+- ecosystem
 library_name: ruvllm
 pipeline_tag: text-classification
 base_model: Qwen/Qwen2.5-0.5B-Instruct
@@ -59,7 +60,7 @@ widget:
   example_title: Architecture Task
 ---
 
-# RuvLTRA
+# RuvLTRA v2.4 - Ecosystem Edition
 
 <p align="center">
   <img src="https://img.shields.io/badge/Hybrid_Routing-100%25-brightgreen" alt="Hybrid Accuracy">
@@ -68,11 +69,20 @@ widget:
   <img src="https://img.shields.io/badge/Latency-<10ms-orange" alt="Latency">
   <img src="https://img.shields.io/badge/Capabilities-388-cyan" alt="Capabilities">
   <img src="https://img.shields.io/badge/License-Apache%202.0-green" alt="License">
+  <img src="https://img.shields.io/badge/Version-v2.4-purple" alt="Version">
 </p>
 
-**RuvLTRA** is a collection of optimized models designed for **local routing, embeddings, and task classification** in Claude Code workflows—not for general code generation.
+**RuvLTRA** is a collection of optimized models designed for **local routing, embeddings, and task classification** in Claude Code workflows - achieving **100% routing accuracy** with hybrid strategy.
 
-## 🎯 Key Philosophy
+## What's New in v2.4 (Ecosystem Edition)
+
+- **2,545 training triplets** (1,078 SOTA + 1,467 ecosystem-specific)
+- **Full ecosystem coverage**: claude-flow, agentic-flow, ruvector
+- **388 total capabilities** across all tools
+- **62 validation tests** with 100% accuracy
+- **30-epoch SOTA training** with 88.2% embedding accuracy
+
+## Key Philosophy
 
 > **Benchmark Note:** HumanEval/MBPP don't apply here. RuvLTRA isn't designed to compete with Claude for code generation from scratch.
 
@@ -80,18 +90,18 @@ widget:
 
 | Task | RuvLTRA | Claude API |
 |------|---------|------------|
-| Route task to correct agent | ✅ Local, fast, **100% accuracy** | Overkill |
-| Generate embeddings for HNSW | ✅ Purpose-built | No embedding API |
-| Quick classification/routing | ✅ <10ms local | ~500ms+ API |
-| Memory retrieval scoring | ✅ Integrated | Not designed for |
-| Complex code generation | ❌ Use Claude | ✅ |
-| Multi-step reasoning | ❌ Use Claude | ✅ |
+| Route task to correct agent | Local, fast, **100% accuracy** | Overkill |
+| Generate embeddings for HNSW | Purpose-built | No embedding API |
+| Quick classification/routing | <10ms local | ~500ms+ API |
+| Memory retrieval scoring | Integrated | Not designed for |
+| Complex code generation | Use Claude | Optimal |
+| Multi-step reasoning | Use Claude | Optimal |
 
 ---
 
-## 🚀 SOTA: 100% Routing Accuracy + Enhanced Embeddings
+## SOTA: 100% Routing Accuracy
 
-Using **hybrid keyword+embedding strategy** plus **contrastive fine-tuning**, RuvLTRA now achieves:
+Using **hybrid keyword+embedding strategy** plus **contrastive fine-tuning**, RuvLTRA achieves:
 
 ### SOTA Benchmark Results
 
@@ -108,15 +118,16 @@ Using **hybrid keyword+embedding strategy** plus **contrastive fine-tuning**, Ru
 | Embedding Only | 88.2% | 40.0% | +48.2 pts |
 | **Keyword-First Hybrid** | **100.0%** | 95.0% | +5 pts |
 
-### Training Enhancements (v2.4 - Ecosystem Edition)
+### v2.4 Training Enhancements
 
-- **2,545 training triplets** (1,078 SOTA + 1,467 ecosystem)
-- **Full ecosystem coverage**: claude-flow, agentic-flow, ruvector
-- **388 total capabilities** across all tools
-- **62 validation tests** with 100% accuracy
-- **Claude Opus 4.5** used for generating confusing pairs
-- **Triplet + InfoNCE loss** for contrastive learning
-- **Real Candle training** with gradient-based weight updates
+| Feature | v2.3 | v2.4 |
+|---------|------|------|
+| Training Triplets | 1,078 | **2,545** |
+| Ecosystem Coverage | Claude Flow only | **Full ecosystem** |
+| Total Capabilities | 179 | **388** |
+| Validation Tests | 20 | **62** |
+| Hard Negative Ratio | 18% | **18%** |
+| Training Epochs | 20 | **30** |
 
 ### Ecosystem Coverage (v2.4)
 
@@ -126,39 +137,9 @@ Using **hybrid keyword+embedding strategy** plus **contrastive fine-tuning**, Ru
 | **agentic-flow** | 17 commands | 33 types | 32 MCP tools, 9 RL algorithms |
 | **ruvector** | 6 CLI, 22 Rust crates | 12 NPM | 6 attention, 4 graph algorithms |
 
-### Supported Agent Types (58+)
-
-| Agent | Keywords | Use Cases |
-|-------|----------|-----------|
-| `coder` | implement, build, create | Code implementation |
-| `researcher` | research, investigate, explore | Information gathering |
-| `reviewer` | review, pull request, quality | Code review |
-| `tester` | test, unit, integration | Testing |
-| `architect` | design, architecture, schema | System design |
-| `security-architect` | security, vulnerability, xss | Security analysis |
-| `debugger` | debug, fix, bug, error | Bug fixing |
-| `documenter` | jsdoc, comment, readme | Documentation |
-| `refactorer` | refactor, async/await | Code refactoring |
-| `optimizer` | optimize, cache, performance | Performance |
-| `devops` | deploy, ci/cd, kubernetes | DevOps |
-| `api-docs` | openapi, swagger, api spec | API documentation |
-| `planner` | sprint, plan, roadmap | Project planning |
-
-### Extended Capabilities (v2.4)
-
-| Category | Examples |
-|----------|----------|
-| **MCP Tools** | memory_store, agent_spawn, swarm_init, hooks_pre-task |
-| **Swarm Topologies** | hierarchical, mesh, ring, star, adaptive |
-| **Consensus** | byzantine, raft, gossip, crdt, quorum |
-| **Learning** | SONA train, LoRA finetune, EWC++ consolidate, GRPO optimize |
-| **Attention** | flash, multi-head, linear, hyperbolic, MoE |
-| **Graph** | mincut, GNN embed, spectral, pagerank |
-| **Hardware** | Metal GPU, NEON SIMD, ANE neural engine |
-
 ---
 
-## 💰 Cost Savings
+## Cost Savings
 
 | Operation | Claude API | RuvLTRA Local | Savings |
 |-----------|------------|---------------|---------|
@@ -170,7 +151,7 @@ Using **hybrid keyword+embedding strategy** plus **contrastive fine-tuning**, Ru
 
 ---
 
-## 📦 Available Models
+## Available Models
 
 | Model | Size | RAM | Latency |
 |-------|------|-----|---------|
@@ -180,14 +161,30 @@ Using **hybrid keyword+embedding strategy** plus **contrastive fine-tuning**, Ru
 
 ---
 
-## 🛠️ Quick Start
+## Quick Start
 
 ### Installation
 ```bash
+npm install @ruvector/ruvllm
+# or
 npx ruvector install
 ```
 
-### Download Models
+### Automatic Model Download
+```javascript
+const { SemanticRouter } = require('@ruvector/ruvllm');
+
+// Automatically downloads from HuggingFace if not cached
+const router = new SemanticRouter({
+  model: 'ruvltra-claude-code-0.5b',  // Auto-downloads
+  strategy: 'keyword-first'
+});
+
+const result = await router.route('Implement authentication system');
+// { agent: 'coder', confidence: 0.92 }
+```
+
+### Manual Download
 ```bash
 wget https://huggingface.co/ruv/ruvltra/resolve/main/ruvltra-claude-code-0.5b-q4_k_m.gguf
 ```
@@ -211,22 +208,9 @@ llm.load_model("ruvltra-claude-code-0.5b-q4_k_m.gguf", Default::default())?;
 let agent = llm.generate("Route: fix bug\nAgent:", GenerateParams::default().with_max_tokens(8))?;
 ```
 
-### Node.js Example (Hybrid Routing)
-```javascript
-const { SemanticRouter } = require('@ruvector/ruvllm');
-
-const router = new SemanticRouter({
-  modelPath: 'ruvltra-claude-code-0.5b-q4_k_m.gguf',
-  strategy: 'keyword-first'  // 100% accuracy
-});
-
-const result = await router.route('Implement authentication system');
-// { agent: 'coder', confidence: 0.92 }
-```
-
 ---
 
-## 🔧 Hybrid Routing Algorithm
+## Hybrid Routing Algorithm
 
 The model achieves 100% accuracy using a two-stage routing strategy:
 
@@ -234,8 +218,8 @@ The model achieves 100% accuracy using a two-stage routing strategy:
 1. KEYWORD MATCHING (Primary)
    - Check task for trigger keywords
    - Priority ordering resolves conflicts
-   - "investigate" → researcher (priority)
-   - "optimize queries" → optimizer
+   - "investigate" -> researcher (priority)
+   - "optimize queries" -> optimizer
 
 2. EMBEDDING FALLBACK (Secondary)
    - If no keywords match, use embeddings
@@ -245,7 +229,39 @@ The model achieves 100% accuracy using a two-stage routing strategy:
 
 ---
 
-## 📊 Technical Specifications
+## Supported Agent Types (58+)
+
+| Agent | Keywords | Use Cases |
+|-------|----------|-----------|
+| `coder` | implement, build, create | Code implementation |
+| `researcher` | research, investigate, explore | Information gathering |
+| `reviewer` | review, pull request, quality | Code review |
+| `tester` | test, unit, integration | Testing |
+| `architect` | design, architecture, schema | System design |
+| `security-architect` | security, vulnerability, xss | Security analysis |
+| `debugger` | debug, fix, bug, error | Bug fixing |
+| `documenter` | jsdoc, comment, readme | Documentation |
+| `refactorer` | refactor, async/await | Code refactoring |
+| `optimizer` | optimize, cache, performance | Performance |
+| `devops` | deploy, ci/cd, kubernetes | DevOps |
+| `api-docs` | openapi, swagger, api spec | API documentation |
+| `planner` | sprint, plan, roadmap | Project planning |
+
+### Extended Capabilities (v2.4)
+
+| Category | Examples |
+|----------|----------|
+| **MCP Tools** | memory_store, agent_spawn, swarm_init, hooks_pre-task |
+| **Swarm Topologies** | hierarchical, mesh, ring, star, adaptive |
+| **Consensus** | byzantine, raft, gossip, crdt, quorum |
+| **Learning** | SONA train, LoRA finetune, EWC++ consolidate, GRPO optimize |
+| **Attention** | flash, multi-head, linear, hyperbolic, MoE |
+| **Graph** | mincut, GNN embed, spectral, pagerank |
+| **Hardware** | Metal GPU, NEON SIMD, ANE neural engine |
+
+---
+
+## Technical Specifications
 
 | Specification | Value |
 |--------------|-------|
@@ -258,7 +274,7 @@ The model achieves 100% accuracy using a two-stage routing strategy:
 
 ---
 
-## 📦 Rust Crates
+## Rust Crates
 
 | Crate | Description |
 |-------|-------------|
@@ -278,7 +294,7 @@ ruvector-sona = { version = "0.1", features = ["serde-support"] }
 
 ---
 
-## 💻 Requirements
+## Requirements
 
 | Component | Minimum |
 |-----------|---------|
@@ -289,24 +305,22 @@ ruvector-sona = { version = "0.1", features = ["serde-support"] }
 
 ---
 
-## 🏗️ Architecture
+## Architecture
 
 ```
-Task ──► RuvLTRA ──► Agent Type ──► Claude API
+Task --> RuvLTRA --> Agent Type --> Claude API
          (free)      (100% acc)     (pay here)
 
-Query ──► RuvLTRA ──► Embedding ──► HNSW ──► Context
+Query --> RuvLTRA --> Embedding --> HNSW --> Context
           (free)      (free)       (free)    (free)
 ```
 
-**Philosophy:** Simple, frequent decisions → RuvLTRA (free, <10ms, 100% accurate). Complex reasoning → Claude API (worth the cost).
-
----
+**Philosophy:** Simple, frequent decisions -> RuvLTRA (free, <10ms, 100% accurate). Complex reasoning -> Claude API (worth the cost).
 
 ---
 
 <details>
-<summary><b>📋 Training Details</b></summary>
+<summary><b>Training Details</b></summary>
 
 ### Training Data
 
@@ -315,12 +329,13 @@ Query ──► RuvLTRA ──► Embedding ──► HNSW ──► Context
 | Base Triplets | 578 | Claude Code routing examples |
 | Claude Hard Negatives (Batch 1) | 100 | Opus 4.5 generated confusing pairs |
 | Claude Hard Negatives (Batch 2) | 400 | Additional confusing pairs |
-| **Total** | **1,078** | Combined training set |
+| Ecosystem Triplets | 1,467 | Full ecosystem coverage |
+| **Total v2.4** | **2,545** | Combined training set |
 
 ### Training Procedure
 
 ```
-Pipeline: Hard Negative Generation → Contrastive Training → GRPO Feedback → GGUF Export
+Pipeline: Hard Negative Generation -> Contrastive Training -> GRPO Feedback -> GGUF Export
 
 1. Generate confusing agent pairs using Claude Opus 4.5
 2. Train with Triplet Loss + InfoNCE Loss
@@ -350,7 +365,7 @@ Pipeline: Hard Negative Generation → Contrastive Training → GRPO Feedback
 </details>
 
 <details>
-<summary><b>📊 Evaluation Results</b></summary>
+<summary><b>Evaluation Results</b></summary>
 
 ### Benchmark: Claude Flow Agent Routing (20 test cases)
 
@@ -391,57 +406,40 @@ Pipeline: Hard Negative Generation → Contrastive Training → GRPO Feedback
 </details>
 
 <details>
-<summary><b>⚠️ Limitations & Intended Use</b></summary>
+<summary><b>Limitations & Intended Use</b></summary>
 
 ### Intended Use
 
-✅ **Designed For:**
+**Designed For:**
 - Task routing in Claude Code workflows
-- Agent classification (13 types)
+- Agent classification (58+ types)
 - Semantic embedding for HNSW search
 - Local inference (<10ms latency)
 - Cost optimization (avoid API calls for routing)
 
-❌ **NOT Designed For:**
+**NOT Designed For:**
 - General code generation
 - Multi-step reasoning
 - Chat/conversation
 - Languages other than English
-- Agent types beyond the 13 supported
+- Agent types beyond supported set
 
 ### Known Limitations
 
-1. **Fixed Agent Types**: Only routes to 13 predefined agents
+1. **Fixed Agent Types**: Routes to predefined agents
 2. **English Only**: Training data is English-only
 3. **Domain Specific**: Optimized for software development tasks
 4. **Embedding Fallback**: 88.2% accuracy when keywords don't match
 5. **Context Length**: Optimal for short task descriptions (<100 tokens)
 
-### Bias Considerations
-
-- Training data generated from Claude Opus 4.5 may inherit biases
-- Agent keywords favor common software terminology
-- Security-related tasks may be over-classified to security-architect
-
 </details>
 
 <details>
-<summary><b>🔧 Model Files & Checksums</b></summary>
-
-### Available Files
-
-| File | Size | Format | Use Case |
-|------|------|--------|----------|
-| `ruvltra-claude-code-0.5b-q4_k_m.gguf` | 398 MB | GGUF Q4_K_M | Production routing |
-| `ruvltra-small-0.5b-q4_k_m.gguf` | 398 MB | GGUF Q4_K_M | General embeddings |
-| `ruvltra-medium-1.1b-q4_k_m.gguf` | 800 MB | GGUF Q4_K_M | Higher accuracy |
-| `training/v2.3-sota-stats.json` | 1 KB | JSON | Training metrics |
-| `training/v2.3-info.json` | 2 KB | JSON | Training config |
-
-### Version History
+<summary><b>Version History</b></summary>
 
 | Version | Date | Changes |
 |---------|------|---------|
+| **v2.4** | 2025-01-21 | Ecosystem Edition: 2,545 triplets, 388 capabilities, 62 tests |
 | v2.3 | 2025-01-20 | 500+ hard negatives, 48% ratio, GRPO feedback |
 | v2.2 | 2025-01-15 | 100 hard negatives, 18% ratio |
 | v2.1 | 2025-01-10 | Contrastive learning, triplet loss |
@@ -451,7 +449,7 @@ Pipeline: Hard Negative Generation → Contrastive Training → GRPO Feedback
 </details>
 
 <details>
-<summary><b>📖 Citation</b></summary>
+<summary><b>Citation</b></summary>
 
 ### BibTeX
 
@@ -461,70 +459,21 @@ Pipeline: Hard Negative Generation → Contrastive Training → GRPO Feedback
   author = {ruv},
   year = {2025},
   url = {https://huggingface.co/ruv/ruvltra},
-  version = {2.3},
+  version = {2.4},
   license = {Apache-2.0},
-  keywords = {agent-routing, embeddings, claude-code, contrastive-learning}
+  keywords = {agent-routing, embeddings, claude-code, contrastive-learning, ecosystem}
 }
 ```
 
-### Plain Text
-
-```
-ruv. (2025). RuvLTRA: Local Task Routing for Claude Code Workflows (Version 2.3).
-https://huggingface.co/ruv/ruvltra
-```
-
-</details>
-
-<details>
-<summary><b>❓ FAQ & Troubleshooting</b></summary>
-
-### Common Questions
-
-**Q: Why use this instead of Claude API for routing?**
-A: RuvLTRA is free, runs locally in <10ms, and achieves 100% accuracy with hybrid strategy. Claude API adds latency (~500ms) and costs ~$0.003 per call.
-
-**Q: Can I add custom agent types?**
-A: Not with the current model. You'd need to fine-tune with triplets including your custom agents.
-
-**Q: Does it work offline?**
-A: Yes, fully offline after downloading the GGUF model.
-
-**Q: What's the difference between embedding-only and hybrid?**
-A: Embedding-only uses semantic similarity (88.2% accuracy). Hybrid checks keywords first, then falls back to embeddings (100% accuracy).
-
-### Troubleshooting
-
-**Model loading fails:**
-```bash
-# Ensure you have enough RAM (500MB+)
-# Check file integrity
-sha256sum ruvltra-claude-code-0.5b-q4_k_m.gguf
-```
-
-**Low accuracy:**
-```javascript
-// Use keyword-first strategy for 100% accuracy
-const router = new SemanticRouter({
-  strategy: 'keyword-first'  // Not 'embedding-only'
-});
-```
-
-**Slow inference:**
-```bash
-# Enable Metal GPU on Apple Silicon
-export GGML_METAL=1
-```
-
 </details>
 
 ---
 
-## 📄 License
+## License
 
 Apache 2.0 - Free for commercial and personal use.
 
-## 🔗 Links
+## Links
 
 - [GitHub Repository](https://github.com/ruvnet/ruvector)
 - [Claude Flow](https://github.com/ruvnet/claude-flow)
@@ -532,6 +481,6 @@ Apache 2.0 - Free for commercial and personal use.
 - [Training Code](https://github.com/ruvnet/ruvector/tree/main/crates/ruvllm/src/training)
 - [NPM Package](https://www.npmjs.com/package/@ruvector/ruvllm)
 
-## 🏷️ Keywords
+## Keywords
 
-`agent-routing` `task-classification` `claude-code` `embeddings` `semantic-search` `gguf` `quantized` `edge-ai` `local-inference` `contrastive-learning` `triplet-loss` `infonce` `qwen` `llm` `mlops` `cost-optimization` `multi-agent` `swarm` `ruvector` `sona`
+`agent-routing` `task-classification` `claude-code` `embeddings` `semantic-search` `gguf` `quantized` `edge-ai` `local-inference` `contrastive-learning` `triplet-loss` `infonce` `qwen` `llm` `mlops` `cost-optimization` `multi-agent` `swarm` `ruvector` `sona` `ecosystem`