[options] # Deploy a template
-```
-
-### Template Categories
-
-| Category | Templates | Use Case |
-|----------|-----------|----------|
-| ๐ง **Practical** | `code-reviewer`, `doc-generator`, `test-generator` | Daily development tasks |
-| โก **Intermediate** | `feature-swarm`, `refactor-squad`, `ci-cd-pipeline` | Multi-agent coordination |
-| ๐ง **Advanced** | `self-learning-bot`, `research-swarm`, `performance-optimizer` | Neural patterns, learning |
-| ๐ **Exotic** | `hive-mind`, `byzantine-validator`, `adversarial-tester`, `multi-repo-coordinator` | Collective intelligence |
-
-### Quick Deploy Examples
-
-```bash
-# Code review with security scanning
-npx ruvbot deploy code-reviewer --repo ./my-project
-
-# Feature development swarm (4 agents)
-npx ruvbot deploy feature-swarm --feature "Add user auth"
-
-# Self-learning assistant with memory
-npx ruvbot deploy self-learning-bot --domain "code-assistance"
-
-# Hive-mind collective (15 agents)
-npx ruvbot deploy hive-mind --objective "Build complete app"
-
-# Byzantine fault-tolerant validation
-npx ruvbot deploy byzantine-validator --quorum 4
-```
-
-## ๐ค RuvBot Deployment
-
-**ALWAYS use the Cloud Run deployment, NOT local Docker:**
-
-| Resource | URL/Value |
-|----------|-----------|
-| **Cloud Run URL** | https://ruvbot-875130704813.us-central1.run.app |
-| **npm Package** | `ruvbot@0.1.1` |
-| **Default Model** | `google/gemini-2.5-pro-preview-05-06` |
-| **Region** | `us-central1` |
-
-### API Endpoints
-```bash
-# Health & Status
-curl https://ruvbot-875130704813.us-central1.run.app/health
-curl https://ruvbot-875130704813.us-central1.run.app/ready
-curl https://ruvbot-875130704813.us-central1.run.app/api/status
-curl https://ruvbot-875130704813.us-central1.run.app/api/models
-
-# Create session
-curl -X POST https://ruvbot-875130704813.us-central1.run.app/api/sessions \
- -H "Content-Type: application/json" \
- -d '{"agentId": "default-agent"}'
-
-# Chat (replace SESSION_ID)
-curl -X POST https://ruvbot-875130704813.us-central1.run.app/api/sessions/SESSION_ID/chat \
- -H "Content-Type: application/json" \
- -d '{"message": "Hello"}'
-```
-
-### Update Deployment
-```bash
-# Update env vars
-gcloud run services update ruvbot --region us-central1 \
- --set-env-vars "DEFAULT_MODEL=google/gemini-2.5-pro-preview-05-06,OPENROUTER_API_KEY=..."
-
-# Redeploy from source
-gcloud run deploy ruvbot --source npm/packages/ruvbot --region us-central1
-```
-
-### Supported Models (via OpenRouter)
-- `google/gemini-2.5-pro-preview-05-06` (default)
-- `google/gemini-2.0-flash-001`
-- `anthropic/claude-3.5-sonnet`
-- `openai/gpt-4o`
-- `qwen/qwq-32b` (reasoning)
-- `deepseek/deepseek-r1` (reasoning)
-
-## ๐ง Operational Guidance (Verified 2026-02-08)
-
-### Required Local Dependencies
-
-The auto-memory bridge requires `@claude-flow/memory` installed as a **local** dependency.
-Without it, SessionStart/SessionEnd hooks silently skip with "Memory package not available".
+## Quick Setup
```bash
-# Verify: should show "Package: Available", not "Not available"
-node .claude/helpers/auto-memory-hook.mjs status
-
-# Fix if missing:
-npm install @claude-flow/memory@latest
-```
-
-### Package Path Differences
-
-When installing packages, the `.claude/` directory location varies by install method:
-
-| Install Method | Settings path |
-|----------------|---------------|
-| `npm install claude-flow@latest` | `node_modules/claude-flow/.claude/settings.json` |
-| `npm install @claude-flow/cli@latest` | `node_modules/@claude-flow/cli/.claude/settings.json` |
-| `npx @claude-flow/cli@latest init upgrade --settings` | `.claude/settings.json` (project root, preferred) |
-
-Always use `init upgrade --settings` to copy/merge settings into the project's `.claude/` directory.
-
-### Upgrade Procedure
-
-```bash
-# 1. Upgrade packages
-npm install @claude-flow/memory@latest
-
-# 2. Merge new settings (safe, preserves existing)
-npx @claude-flow/cli@latest init upgrade --settings
-
-# 3. Verify
-npx @claude-flow/cli@latest doctor
-node .claude/helpers/auto-memory-hook.mjs status
-```
-
-### Disk Space Management
-
-Rust `target/` directories and npm/cargo caches are the primary disk consumers.
-All are fully rebuildable. Clean when disk exceeds 85%:
-
-```bash
-# Check usage
-df -h /
-
-# Clean Rust build caches (safe, rebuilds on next cargo build)
-rm -rf examples/*/target target/debug target/release target/wasm32-*
-
-# Clean package caches
-npm cache clean --force
-rm -rf ~/.cargo/registry/cache
-
-# Verify
-npx @claude-flow/cli@latest doctor
+claude mcp add claude-flow -- npx -y @claude-flow/cli@latest
+npx @claude-flow/cli@latest daemon start
+npx @claude-flow/cli@latest doctor --fix
```
-**Common offenders in this repo:**
-- `examples/*/target/` โ 20G+ (Rust builds in example projects)
-- `target/debug/` โ 18G+ (main project debug builds)
-- `~/.cargo/registry/cache` โ 1-2G
-- `~/.npm/_cacache` โ ~1G
-
-### Health Check Quick Reference
-
-```bash
-# Full system check (should show 9+ passed, 0 failures)
-npx @claude-flow/cli@latest doctor
-
-# Memory system (should show all enabled)
-node .claude/helpers/auto-memory-hook.mjs status
-
-# Daemon workers (should show RUNNING)
-npx @claude-flow/cli@latest daemon status
-
-# Memory round-trip test
-npx @claude-flow/cli@latest memory store --key "ping" --value "pong" --namespace test
-npx @claude-flow/cli@latest memory search --query "pong" --namespace test
-```
+## Claude Code vs CLI Tools
-### Verified Working Configuration (v3.1.0-alpha.16)
-
-| Component | Status | Details |
-|-----------|--------|---------|
-| Memory backend | sql.js + HNSW | 384-dim vectors, semantic search |
-| Auto-memory bridge | Active | Import on SessionStart, sync on SessionEnd |
-| LearningBridge | Enabled | Pattern training on edits |
-| MemoryGraph | Enabled | PageRank, community detection |
-| AgentScopes | Enabled | Agent memory isolation |
-| Agent Teams | Active | `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` |
-| Teammate auto-assign | Active | TeammateIdle hook wired |
-| Pattern training | Active | TaskCompleted hook wired |
-| Daemon workers | 5 active | map, audit, optimize, consolidate, testgaps |
-| Neural + autoTrain | Enabled | Coordination, optimization, prediction patterns |
+- Claude Code's Task tool handles ALL execution: agents, file ops, code generation, git
+- CLI tools handle coordination via Bash: swarm init, memory, hooks, routing
+- NEVER use CLI tools as a substitute for Task tool agents
## Support
- Documentation: https://github.com/ruvnet/claude-flow
- Issues: https://github.com/ruvnet/claude-flow/issues
-
----
-
-Remember: **Claude Flow CLI coordinates, Claude Code Task tool creates!**
-
-# important-instruction-reminders
-Do what has been asked; nothing more, nothing less.
-NEVER create files unless they're absolutely necessary for achieving your goal.
-ALWAYS prefer editing an existing file to creating a new one.
-NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.
-Never save working files, text/mds and tests to the root folder.
-
-## ๐จ SWARM EXECUTION RULES (CRITICAL)
-1. **SPAWN IN BACKGROUND**: Use `run_in_background: true` for all agent Task calls
-2. **SPAWN ALL AT ONCE**: Put ALL agent Task calls in ONE message for parallel execution
-3. **TELL USER**: After spawning, list what each agent is doing (use emojis for clarity)
-4. **STOP AND WAIT**: After spawning, STOP - do NOT add more tool calls or check status
-5. **NO POLLING**: Never poll TaskOutput or check swarm status - trust agents to return
-6. **SYNTHESIZE**: When agent results arrive, review ALL results before proceeding
-7. **NO CONFIRMATION**: Don't ask "should I check?" - just wait for results
-
-Example spawn message:
-```
-"I've launched 4 agents in background:
-- ๐ Researcher: [task]
-- ๐ป Coder: [task]
-- ๐งช Tester: [task]
-- ๐ Reviewer: [task]
-Working in parallel - I'll synthesize when they complete."
-```
diff --git a/Cargo.lock b/Cargo.lock
index 5976259f7..67d142c1c 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -8134,6 +8134,18 @@ dependencies = [
"wasm-bindgen-test",
]
+[[package]]
+name = "ruvector-dna-bench"
+version = "0.1.0"
+dependencies = [
+ "criterion 0.5.1",
+ "rand 0.8.5",
+ "ruvector-attention 0.1.31",
+ "ruvector-core 2.0.2",
+ "ruvector-delta-core",
+ "ruvector-mincut 2.0.2",
+]
+
[[package]]
name = "ruvector-economy-wasm"
version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index ee075c919..ce9bf21dd 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -77,6 +77,7 @@ members = [
"crates/ruqu-algorithms",
"crates/ruqu-wasm",
"crates/ruqu-exotic",
+ "crates/ruvector-dna-bench",
]
resolver = "2"
@@ -152,18 +153,29 @@ once_cell = "1.20"
opt-level = 3
lto = "fat"
codegen-units = 1
-strip = true
+strip = "symbols"
panic = "abort"
[profile.bench]
+opt-level = 3
+lto = "thin"
+codegen-units = 1
+debug = true
+
+[profile.release-with-debug]
inherits = "release"
debug = true
+strip = false
[profile.dev]
opt-level = 0
debug = true
+[profile.dev.package."*"]
+opt-level = 2
+
[profile.test]
+opt-level = 1
# Patch hnsw_rs to use rand 0.8 instead of 0.9 for WASM compatibility
# This resolves the getrandom version conflict (0.2 vs 0.3)
diff --git a/README.md b/README.md
index ec63fc425..b62b8f01c 100644
--- a/README.md
+++ b/README.md
@@ -1,4697 +1,771 @@
-# RuVector
+# RuVector DNA Analyzer
-[](https://crates.io/crates/ruvector-core)
-[](https://www.npmjs.com/package/ruvector)
-[](https://www.npmjs.com/package/ruvector)
-[](https://www.npmjs.com/package/ruvector)
-[](https://huggingface.co/ruv/ruvltra)
-[](https://ruv.io)
-[](https://opensource.org/licenses/MIT)
-
-**The vector database that gets smarter the more you use it.**
-
-```bash
-npx ruvector
-```
-
-Most vector databases are staticโthey store embeddings and search them. That's it. RuVector is different: it learns from every query, runs LLMs locally, scales horizontally, and costs nothing to operate.
-
-| | Pinecone/Weaviate | RuVector |
-|---|---|---|
-| **Search improves over time** | โ | โ
GNN layers learn from usage |
-| **Run LLMs locally** | โ | โ
ruvllm + RuvLTRA models ($0) |
-| **Graph queries (Cypher)** | โ | โ
`MATCH (a)-[:SIMILAR]->(b)` |
-| **Self-learning AI hooks** | โ | โ
Q-learning, HNSW memory |
-| **Real-time graph updates** | โ Rebuild index | โ
Dynamic min-cut (no rebuild) |
-| **Horizontal scaling** | ๐ฐ Paid | โ
Raft consensus, free |
-| **Works offline** | โ | โ
Browser, edge, embedded |
-
-**One package. Everything included:** vector search, graph queries, GNN learning, distributed clustering, local LLMs, 39 attention mechanisms, and WASM support.
-
-
-๐ See Full Capabilities (30+ features)
-
-**Core Vector Database**
-| # | Capability | What It Does |
-|---|------------|--------------|
-| 1 | **Store vectors** | Embeddings from OpenAI, Cohere, local ONNX with HNSW indexing |
-| 2 | **Query with Cypher** | Graph queries like Neo4j (`MATCH (a)-[:SIMILAR]->(b)`) |
-| 3 | **The index learns** | GNN layers make search results improve over time |
-| 4 | **Hyperbolic HNSW** | Hierarchical data in hyperbolic space for better tree structures |
-| 5 | **Compress automatically** | 2-32x memory reduction with adaptive tiered compression |
-
-**Distributed Systems**
-| # | Capability | What It Does |
-|---|------------|--------------|
-| 6 | **Raft consensus** | Leader election, log replication, fault-tolerant coordination |
-| 7 | **Multi-master replication** | Vector clocks, conflict resolution, geo-distributed sync |
-| 8 | **Burst scaling** | 10-50x capacity scaling for traffic spikes |
-| 9 | **Auto-sharding** | Automatic data partitioning across nodes |
-
-**AI & Machine Learning**
-| # | Capability | What It Does |
-|---|------------|--------------|
-| 10 | **Run LLMs locally** | ruvllm with GGUF, Metal/CUDA/ANE acceleration |
-| 11 | **RuvLTRA models** | Pre-trained GGUF for routing & embeddings (<10ms) โ [HuggingFace](https://huggingface.co/ruv/ruvltra) |
-| 12 | **SONA learning** | Self-Optimizing Neural Architecture with LoRA, EWC++ |
-| 13 | **39 attention mechanisms** | Flash, linear, graph, hyperbolic, mincut-gated (50% compute) |
-| 14 | **Spiking neural networks** | Event-driven neuromorphic computing |
-| 15 | **Mincut-gated transformer** | Dynamic attention via graph min-cut optimization |
-| 16 | **Route AI requests** | Semantic routing + FastGRNN for LLM optimization |
-
-**Specialized Processing**
-| # | Capability | What It Does |
-|---|------------|--------------|
-| 17 | **SciPix OCR** | LaTeX/MathML extraction from scientific documents |
-| 18 | **DAG workflows** | Self-learning directed acyclic graph execution |
-| 19 | **Cognitum Gate** | Cognitive AI gateway with TileZero acceleration |
-| 20 | **FPGA transformer** | Hardware-accelerated transformer inference |
-| 21 | **Quantum coherence** | ruQu for quantum error correction via dynamic min-cut |
-
-**Platform & Integration**
-| # | Capability | What It Does |
-|---|------------|--------------|
-| 22 | **Run anywhere** | Node.js, browser (WASM), edge (rvLite), HTTP server, Rust |
-| 23 | **Drop into Postgres** | pgvector-compatible extension with SIMD acceleration |
-| 24 | **MCP integration** | Model Context Protocol server for AI assistant tools |
-| 25 | **Cloud deployment** | One-click deploy to Cloud Run, Kubernetes |
-
-**Self-Learning & Adaptation**
-| # | Capability | What It Does |
-|---|------------|--------------|
-| 26 | **Self-learning hooks** | Q-learning, neural patterns, HNSW memory |
-| 27 | **ReasoningBank** | Trajectory learning with verdict judgment |
-| 28 | **Economy system** | Tokenomics, CRDT-based distributed state |
-| 29 | **Nervous system** | Event-driven reactive architecture |
-| 30 | **Agentic synthesis** | Multi-agent workflow composition |
-
-
-
-*Think of it as: **Pinecone + Neo4j + PyTorch + llama.cpp + postgres + etcd** โ in one Rust package.*
-
----
-
-### Ecosystem: AI Agent Orchestration
-
-RuVector powers two major AI orchestration platforms:
-
-| Platform | Purpose | Install |
-|----------|---------|---------|
-| [**Claude-Flow**](https://github.com/ruvnet/claude-flow) | Enterprise multi-agent orchestration for Claude Code | `npx @claude-flow/cli@latest` |
-| [**Agentic-Flow**](https://github.com/ruvnet/agentic-flow) | Standalone AI agent framework (any LLM provider) | `npx agentic-flow@latest` |
-
-
-Claude-Flow v3 โ Turn Claude Code into a collaborative AI team
-
-**54+ specialized agents** working together on complex software engineering tasks:
-
-```bash
-# Install
-npx @claude-flow/cli@latest init --wizard
-
-# Spawn a swarm
-npx @claude-flow/cli@latest swarm init --topology hierarchical --max-agents 8
-```
-
-**Key Features:**
-- **SONA Learning**: Sub-50ms adaptive routing, learns optimal patterns over time
-- **Queen-led Swarms**: Byzantine fault-tolerant consensus with 5 protocols (Raft, Gossip, CRDT)
-- **HNSW Memory**: 150x-12,500x faster pattern retrieval via RuVector
-- **175+ MCP Tools**: Native Model Context Protocol integration
-- **Cost Optimization**: 3-tier routing extends Claude Code quota by 2.5x
-- **Security**: AIDefence threat detection (<10ms), prompt injection blocking
-
-
-
-
-Agentic-Flow v2 โ Production AI agents for any cloud
-
-**66 self-learning agents** with Claude Agent SDK, deployable to any cloud:
-
-```bash
-# Install
-npx agentic-flow@latest
-
-# Or with npm
-npm install agentic-flow
-```
-
-**Key Features:**
-- **SONA Architecture**: <1ms adaptive learning, +55% quality improvement
-- **Flash Attention**: 2.49x JS speedup, 7.47x with NAPI bindings
-- **213 MCP Tools**: Swarm management, memory, GitHub integration
-- **Agent Booster**: 352x faster code editing for simple transforms
-- **Multi-Provider**: Claude, GPT, Gemini, Cohere, local models with failover
-- **Graph Reasoning**: GNN query refinement with +12.4% recall improvement
-
-
-
----
-
-## How the GNN Works
-
-Traditional vector search:
-```
-Query โ HNSW Index โ Top K Results
-```
-
-RuVector with GNN:
-```
-Query โ HNSW Index โ GNN Layer โ Enhanced Results
- โ โ
- โโโโโ learns from โโโโโโ
-```
-
-The GNN layer:
-1. Takes your query and its nearest neighbors
-2. Applies multi-head attention to weigh which neighbors matter
-3. Updates representations based on graph structure
-4. Returns better-ranked results
-
-Over time, frequently-accessed paths get reinforced, making common queries faster and more accurate.
-
-
-## Quick Start
-
-### One-Line Install
-
-```bash
-# Interactive installer - lists all packages
-npx ruvector install
-
-# Or install directly
-npm install ruvector
-npx ruvector
-
-# Self-learning hooks for Claude Code
-npx @ruvector/cli hooks init
-npx @ruvector/cli hooks install
-
-# LLM runtime (SONA learning, HNSW memory)
-npm install @ruvector/ruvllm
-```
-
-### Node.js / Browser
-
-```bash
-# Install
-npm install ruvector
-
-# Or try instantly
-npx ruvector
-```
-
-
-
-๐ Comparison with Other Vector Databases
-
-| Feature | RuVector | Pinecone | Qdrant | Milvus | ChromaDB |
-|---------|----------|----------|--------|--------|----------|
-| **Latency (p50)** | **61ยตs** | ~2ms | ~1ms | ~5ms | ~50ms |
-| **Memory (1M vec)** | 200MB* | 2GB | 1.5GB | 1GB | 3GB |
-| **Graph Queries** | โ
Cypher | โ | โ | โ | โ |
-| **SPARQL/RDF** | โ
W3C 1.1 | โ | โ | โ | โ |
-| **Hyperedges** | โ
| โ | โ | โ | โ |
-| **Dynamic Min-Cut** | โ
n^0.12 | โ | โ | โ | โ |
-| **Self-Learning (GNN)** | โ
| โ | โ | โ | โ |
-| **Runtime Adaptation (SONA)** | โ
LoRA+EWC++ | โ | โ | โ | โ |
-| **AI Agent Routing** | โ
Tiny Dancer | โ | โ | โ | โ |
-| **Attention Mechanisms** | โ
40 types | โ | โ | โ | โ |
-| **Coherence Gate** | โ
Prime-Radiant | โ | โ | โ | โ |
-| **Hyperbolic Embeddings** | โ
Poincarรฉ+Lorentz | โ | โ | โ | โ |
-| **Local Embeddings** | โ
8+ models | โ | โ | โ | โ |
-| **PostgreSQL Extension** | โ
77+ functions | โ | โ | โ | โ |
-| **SIMD Optimization** | โ
AVX-512/NEON | Partial | โ
| โ
| โ |
-| **Metadata Filtering** | โ
| โ
| โ
| โ
| โ
|
-| **Sparse Vectors** | โ
BM25/TF-IDF | โ
| โ
| โ
| โ |
-| **Raft Consensus** | โ
| โ | โ
| โ | โ |
-| **Multi-Master Replication** | โ
| โ | โ | โ
| โ |
-| **Auto-Sharding** | โ
| โ
| โ
| โ
| โ |
-| **Auto-Compression** | โ
2-32x | โ | โ | โ
| โ |
-| **Snapshots/Backups** | โ
| โ
| โ
| โ
| โ |
-| **Browser/WASM** | โ
WebGPU | โ | โ | โ | โ |
-| **Standalone Edge DB** | โ
rvLite | โ | โ | โ | โ |
-| **LLM Runtime** | โ
ruvllm | โ | โ | โ | โ |
-| **Pre-trained Models** | โ
RuvLTRA (HF) | โ | โ | โ | โ |
-| **MCP Server** | โ
mcp-gate | โ | โ | โ | โ |
-| **Self-Learning Hooks** | โ
Q-learning+Neural+HNSW | โ | โ | โ | โ |
-| **Quantum Coherence** | โ
ruQu | โ | โ | โ | โ |
-| **MinCut-Gated Attention** | โ
50% compute | โ | โ | โ | โ |
-| **FPGA Acceleration** | โ
| โ | โ | โ | โ |
-| **Local ONNX Embeddings** | โ
8+ models | โ | โ | โ | โ |
-| **Differentiable** | โ
| โ | โ | โ | โ |
-| **Multi-Tenancy** | โ
Collections | โ
| โ
| โ
| โ
|
-| **DAG Workflows** | โ
Self-learning | โ | โ | โ | โ |
-| **ReasoningBank** | โ
Trajectory learning | โ | โ | โ | โ |
-| **Economy System** | โ
CRDT tokenomics | โ | โ | โ | โ |
-| **Nervous System** | โ
Event-driven | โ | โ | โ | โ |
-| **Cognitum Gate** | โ
TileZero | โ | โ | โ | โ |
-| **SciPix OCR** | โ
LaTeX/MathML | โ | โ | โ | โ |
-| **Spiking Neural Nets** | โ
Neuromorphic | โ | โ | โ | โ |
-| **Node.js Native** | โ
napi-rs | โ | โ | โ | โ
|
-| **Burst Scaling** | โ
10-50x | โ
| โ | โ
| โ |
-| **Streaming API** | โ
| โ
| โ
| โ
| โ |
-| **Open Source** | โ
MIT | โ | โ
| โ
| โ
|
-
-*With PQ8 compression. Benchmarks on Apple M2 / Intel i7.
-
-
-
-
-โก Core Features & Capabilities
-
-### Core Capabilities
-
-| Feature | What It Does | Why It Matters |
-|---------|--------------|----------------|
-| **Vector Search** | HNSW index, <0.5ms latency, SIMD acceleration | Fast enough for real-time apps |
-| **Cypher Queries** | `MATCH`, `WHERE`, `CREATE`, `RETURN` | Familiar Neo4j syntax |
-| **GNN Layers** | Neural network on index topology | Search improves with usage |
-| **Hyperedges** | Connect 3+ nodes at once | Model complex relationships |
-| **Metadata Filtering** | Filter vectors by properties | Combine semantic + structured search |
-| **Collections** | Namespace isolation, multi-tenancy | Organize vectors by project/user |
-| **Hyperbolic HNSW** | Poincarรฉ ball indexing for hierarchies | Better tree/taxonomy embeddings |
-| **Sparse Vectors** | BM25/TF-IDF hybrid search | Combine keyword + semantic |
-
-### LLM Runtime
-
-| Feature | What It Does | Why It Matters |
-|---------|--------------|----------------|
-| **ruvllm** | Local LLM inference with GGUF models | Run AI without cloud APIs |
-| **Metal/CUDA/ANE** | Hardware acceleration on Mac/NVIDIA/Apple | 10-50x faster inference |
-| **ruvllm-wasm** | Browser LLM with WebGPU acceleration | Client-side AI, zero latency |
-| **RuvLTRA Models** | Pre-trained GGUF for routing & embeddings | <10ms inference โ [HuggingFace](https://huggingface.co/ruv/ruvltra) |
-| **Streaming Tokens** | Real-time token generation | Responsive chat UX |
-| **Quantization** | Q4, Q5, Q8 model support | Run 7B models in 4GB RAM |
-
-```bash
-npm install @ruvector/ruvllm # Node.js
-cargo add ruvllm # Rust
-```
-
-### Platform & Edge
-
-| Feature | What It Does | Why It Matters |
-|---------|--------------|----------------|
-| **rvLite** | Standalone 2MB edge database | IoT, mobile, embedded |
-| **PostgreSQL Extension** | 77+ SQL functions, pgvector replacement | Drop-in upgrade for existing DBs |
-| **MCP Server** | Model Context Protocol integration | AI assistant tool calling |
-| **WASM/Browser** | Full client-side vector search | Offline-first apps |
-| **Node.js Bindings** | Native napi-rs, zero-copy | No serialization overhead |
-| **HTTP/gRPC Server** | REST API with streaming | Easy microservice integration |
-
-```bash
-docker pull ruvnet/ruvector-postgres # PostgreSQL
-npm install rvlite # Edge DB
-npx ruvector mcp start # MCP Server
-```
-
-### Distributed Systems
-
-| Feature | What It Does | Why It Matters |
-|---------|--------------|----------------|
-| **Raft Consensus** | Leader election, log replication | Strong consistency for metadata |
-| **Auto-Sharding** | Consistent hashing, shard migration | Scale to billions of vectors |
-| **Multi-Master Replication** | Write to any node, conflict resolution | High availability, no SPOF |
-| **Snapshots** | Point-in-time backups, incremental | Disaster recovery |
-| **Cluster Metrics** | Prometheus-compatible monitoring | Observability at scale |
-| **Burst Scaling** | 10-50x capacity for traffic spikes | Handle viral moments |
-
-```bash
-cargo add ruvector-raft ruvector-cluster ruvector-replication
-```
-
-### AI & ML
-
-| Feature | What It Does | Why It Matters |
-|---------|--------------|----------------|
-| **Tensor Compression** | f32โf16โPQ8โPQ4โBinary | 2-32x memory reduction |
-| **Differentiable Search** | Soft attention k-NN | End-to-end trainable |
-| **Semantic Router** | Route queries to optimal endpoints | Multi-model AI orchestration |
-| **Hybrid Routing** | Keyword-first + embedding fallback | **90% accuracy** for agent routing |
-| **Tiny Dancer** | FastGRNN neural inference | Optimize LLM inference costs |
-| **Adaptive Routing** | Learn optimal routing strategies | Minimize latency, maximize accuracy |
-| **SONA** | Two-tier LoRA + EWC++ + ReasoningBank | Runtime learning without retraining |
-| **Local Embeddings** | 8+ ONNX models built-in | No external API needed |
-
-### Specialized Processing
-
-| Feature | What It Does | Why It Matters |
-|---------|--------------|----------------|
-| **SciPix OCR** | LaTeX/MathML from scientific docs | Index research papers |
-| **DAG Workflows** | Self-learning directed acyclic graphs | Complex pipeline orchestration |
-| **Cognitum Gate** | Cognitive AI gateway + TileZero | Unified AI model routing |
-| **FPGA Transformer** | Hardware-accelerated inference | Ultra-low latency serving |
-| **ruQu Quantum** | Quantum error correction via min-cut | Future-proof algorithms |
-| **Mincut-Gated Transformer** | Dynamic attention via graph optimization | **50% compute reduction** |
-| **Sparse Inference** | Efficient sparse matrix operations | 10x faster for sparse data |
-
-### Self-Learning & Adaptation
-
-| Feature | What It Does | Why It Matters |
-|---------|--------------|----------------|
-| **Self-Learning Hooks** | Q-learning + neural patterns + HNSW | System improves automatically |
-| **ReasoningBank** | Trajectory learning with verdict judgment | Learn from successes/failures |
-| **Economy System** | Tokenomics, CRDT-based distributed state | Incentivize agent behavior |
-| **Nervous System** | Event-driven reactive architecture | Real-time adaptation |
-| **Agentic Synthesis** | Multi-agent workflow composition | Emergent problem solving |
-| **EWC++** | Elastic weight consolidation | Prevent catastrophic forgetting |
-
-```bash
-npx @ruvector/cli hooks init # Install self-learning hooks
-npx @ruvector/cli hooks install # Configure for Claude Code
-```
-
-### Attention Mechanisms (`@ruvector/attention`)
-
-| Feature | What It Does | Why It Matters |
-|---------|--------------|----------------|
-| **40 Mechanisms** | Dot-product, multi-head, flash, linear, sparse, cross-attention, CGT sheaf | Cover all transformer and GNN use cases |
-| **Graph Attention** | RoPE, edge-featured, local-global, neighborhood | Purpose-built for graph neural networks |
-| **Hyperbolic Attention** | Poincarรฉ ball operations, curved-space math | Better embeddings for hierarchical data |
-| **SIMD Optimized** | Native Rust with AVX2/NEON acceleration | 2-10x faster than pure JS |
-| **Streaming & Caching** | Chunk-based processing, KV-cache | Constant memory, 10x faster inference |
-
-> **Documentation**: [Attention Module Docs](./crates/ruvector-attention/README.md)
-
-#### Core Attention Mechanisms
-
-Standard attention layers for sequence modeling and transformers.
-
-| Mechanism | Complexity | Memory | Best For |
-|-----------|------------|--------|----------|
-| **DotProductAttention** | O(nยฒ) | O(nยฒ) | Basic attention for small-medium sequences |
-| **MultiHeadAttention** | O(nยฒยทh) | O(nยฒยทh) | BERT, GPT-style transformers |
-| **FlashAttention** | O(nยฒ) | O(n) | Long sequences with limited GPU memory |
-| **LinearAttention** | O(nยทd) | O(nยทd) | 8K+ token sequences, real-time streaming |
-| **HyperbolicAttention** | O(nยฒ) | O(nยฒ) | Tree-like data: taxonomies, org charts |
-| **MoEAttention** | O(nยทk) | O(nยทk) | Large models with sparse expert routing |
-
-#### Graph Attention Mechanisms
-
-Attention layers designed for graph-structured data and GNNs.
-
-| Mechanism | Complexity | Best For |
-|-----------|------------|----------|
-| **GraphRoPeAttention** | O(nยฒ) | Position-aware graph transformers |
-| **EdgeFeaturedAttention** | O(nยฒยทe) | Molecules, knowledge graphs with edge data |
-| **DualSpaceAttention** | O(nยฒ) | Hybrid flat + hierarchical embeddings |
-| **LocalGlobalAttention** | O(nยทk + n) | 100K+ node graphs, scalable GNNs |
-
-#### Specialized Mechanisms
-
-Task-specific attention variants for efficiency and multi-modal learning.
-
-| Mechanism | Type | Best For |
-|-----------|------|----------|
-| **SparseAttention** | Efficiency | Long docs, low-memory inference |
-| **CrossAttention** | Multi-modal | Image-text, encoder-decoder models |
-| **NeighborhoodAttention** | Graph | Local message passing in GNNs |
-| **HierarchicalAttention** | Structure | Multi-level docs (section โ paragraph) |
-| **CGTSheafAttention** | Coherence | Consistency-gated graph transformers |
-
-#### Hyperbolic Math Functions
-
-Operations for Poincarรฉ ball embeddingsโcurved space that naturally represents hierarchies.
-
-| Function | Description | Use Case |
-|----------|-------------|----------|
-| `expMap(v, c)` | Map to hyperbolic space | Initialize embeddings |
-| `logMap(p, c)` | Map to flat space | Compute gradients |
-| `mobiusAddition(x, y, c)` | Add vectors in curved space | Aggregate features |
-| `poincareDistance(x, y, c)` | Measure hyperbolic distance | Compute similarity |
-| `projectToPoincareBall(p, c)` | Ensure valid coordinates | Prevent numerical errors |
-
-#### Async & Batch Operations
-
-Utilities for high-throughput inference and training optimization.
-
-| Operation | Description | Performance |
-|-----------|-------------|-------------|
-| `asyncBatchCompute()` | Process batches in parallel | 3-5x faster |
-| `streamingAttention()` | Process in chunks | Fixed memory usage |
-| `HardNegativeMiner` | Find hard training examples | Better contrastive learning |
-| `AttentionCache` | Cache key-value pairs | 10x faster inference |
-
-```bash
-# Install attention module
-npm install @ruvector/attention
-
-# CLI commands
-npx ruvector attention list # List all 39 mechanisms
-npx ruvector attention info flash # Details on FlashAttention
-npx ruvector attention benchmark # Performance comparison
-npx ruvector attention compute -t dot -d 128 # Run attention computation
-npx ruvector attention hyperbolic -a distance -v "[0.1,0.2]" -b "[0.3,0.4]"
-```
-
-### Coherence Gate (`prime-radiant`)
-
-| Feature | What It Does | Why It Matters |
-|---------|--------------|----------------|
-| **Sheaf Laplacian** | Measures consistency via E(S) = ฮฃ wโ ยท โฯแตค(xแตค) - ฯแตฅ(xแตฅ)โยฒ | Mathematical proof of coherence |
-| **Compute Ladder** | Reflex (<1ms) โ Retrieval (~10ms) โ Heavy (~100ms) โ Human | Route by confidence level |
-| **LLM Hallucination Gate** | Block incoherent responses with witnesses | Refuse generation when math says contradiction |
-| **GPU/SIMD Acceleration** | wgpu + AVX-512/NEON + vec4 WGSL kernels | 4-16x speedup on coherence checks |
-| **Governance Audit** | Blake3 hash chain, cryptographic witnesses | Every decision is provable |
-
-#### Coherence vs Confidence
-
-| Traditional AI | Prime-Radiant |
-|----------------|---------------|
-| "I'm 85% confident" | "Zero contradictions found" |
-| Can be confidently wrong | Knows when it doesn't know |
-| Guesses about the future | Proves consistency right now |
-| Trust the model | Trust the math |
-
-#### Compute Ladder Routing
-
-| Energy | Lane | Latency | Action |
-|--------|------|---------|--------|
-| < 0.1 | Reflex | < 1ms | Immediate approval |
-| 0.1-0.4 | Retrieval | ~10ms | Fetch more evidence |
-| 0.4-0.7 | Heavy | ~100ms | Deep analysis |
-| > 0.7 | Human | async | Escalate to review |
-
-```bash
-# Install coherence engine
-cargo add prime-radiant
-
-# With GPU acceleration
-cargo add prime-radiant --features gpu,simd
-```
-
-
-
-
-๐ Deployment Options
-
-| Feature | What It Does | Why It Matters |
-|---------|--------------|----------------|
-| **HTTP/gRPC Server** | REST API, streaming support | Easy integration |
-| **WASM/Browser** | Full client-side support | Run AI search offline |
-| **Node.js Bindings** | Native napi-rs bindings | No serialization overhead |
-| **FFI Bindings** | C-compatible interface | Use from Python, Go, etc. |
-| **CLI Tools** | Benchmarking, testing, management | DevOps-friendly |
-
-
-
-
-๐ Performance Benchmarks
-
-**Measured results** from [`/bench_results/`](./bench_results/):
-
-| Configuration | QPS | p50 Latency | p99 Latency | Recall |
-|---------------|-----|-------------|-------------|--------|
-| **ruvector (optimized)** | 1,216 | 0.78ms | 0.78ms | 100% |
-| **Multi-threaded (16)** | 3,597 | 2.86ms | 8.47ms | 100% |
-| **ef_search=50** | 674 | 1.35ms | 1.35ms | 100% |
-| Python baseline | 77 | 11.88ms | 11.88ms | 100% |
-| Brute force | 12 | 77.76ms | 77.76ms | 100% |
-
-*Dataset: 384D, 10K-50K vectors. See full results in [latency_benchmark.md](./bench_results/latency_benchmark.md).*
-
-| Operation | Dimensions | Time | Throughput |
-|-----------|------------|------|------------|
-| **HNSW Search (k=10)** | 384 | 61ยตs | 16,400 QPS |
-| **HNSW Search (k=100)** | 384 | 164ยตs | 6,100 QPS |
-| **Cosine Distance** | 1536 | 143ns | 7M ops/sec |
-| **Dot Product** | 384 | 33ns | 30M ops/sec |
-| **Batch Distance (1000)** | 384 | 237ยตs | 4.2M/sec |
-
-### Global Cloud Performance (500M Streams)
-
-Production-validated metrics at hyperscale:
-
-| Metric | Value | Details |
-|--------|-------|---------|
-| **Concurrent Streams** | 500M baseline | Burst capacity to 25B (50x) |
-| **Global Latency (p50)** | <10ms | Multi-region + CDN edge caching |
-| **Global Latency (p99)** | <50ms | Cross-continental with failover |
-| **Availability SLA** | 99.99% | 15 regions, automatic failover |
-| **Cost per Stream/Month** | $0.0035 | 60% optimized ($1.74M total at 500M) |
-| **Regions** | 15 global | Americas, EMEA, APAC coverage |
-| **Throughput per Region** | 100K+ QPS | Adaptive batching enabled |
-| **Memory Efficiency** | 2-32x compression | Tiered hot/warm/cold storage |
-| **Index Build Time** | 1M vectors/min | Parallel HNSW construction |
-| **Replication Lag** | <100ms | Multi-master async replication |
-
-
-
-
-๐๏ธ Adaptive Compression Tiers
-
-**The architecture adapts to your data.** Hot paths get full precision and maximum compute. Cold paths compress automatically and throttle resources. Recent data stays crystal clear; historical data optimizes itself in the background.
-
-Think of it like your computer's memory hierarchyโfrequently accessed data lives in fast cache, while older files move to slower, denser storage. RuVector does this automatically for your vectors:
-
-| Access Frequency | Format | Compression | What Happens |
-|-----------------|--------|-------------|--------------|
-| **Hot** (>80%) | f32 | 1x | Full precision, instant retrieval |
-| **Warm** (40-80%) | f16 | 2x | Slight compression, imperceptible latency |
-| **Cool** (10-40%) | PQ8 | 8x | Smart quantization, ~1ms overhead |
-| **Cold** (1-10%) | PQ4 | 16x | Heavy compression, still fast search |
-| **Archive** (<1%) | Binary | 32x | Maximum density, batch retrieval |
-
-**No configuration needed.** RuVector tracks access patterns and automatically promotes/demotes vectors between tiers. Your hot data stays fast; your cold data shrinks.
-
-
-
-
-๐ก Use Cases
-
-### AI & LLM Applications
-
-| Use Case | Features Used | Example |
-|----------|---------------|---------|
-| **RAG Pipelines** | Vector search, Local embeddings, ruvllm | [examples/ruvLLM](./examples/ruvLLM) |
-| **AI Agent Routing** | Tiny Dancer, Semantic router, SONA | [Claude-Flow](https://github.com/ruvnet/claude-flow) |
-| **Multi-Agent Orchestration** | GNN, HNSW memory, Consensus | [Agentic-Flow](https://github.com/ruvnet/agentic-flow) |
-| **Self-Learning Chatbots** | ReasoningBank, EWC++, Neural patterns | [examples/meta-cognition](./examples/meta-cognition-spiking-neural-network) |
-
-```javascript
-// RAG with local LLM (zero cloud costs)
-import { RuVector } from 'ruvector';
-import { RuvLLM } from '@ruvector/ruvllm';
-
-const db = new RuVector({ dimensions: 384 });
-const llm = new RuvLLM({ model: 'ruvltra-small-0.5b-q4_k_m.gguf' });
-
-// Search learns from usage via GNN layers
-const context = await db.search(questionEmbedding, { k: 5 });
-const response = await llm.generate(`Context: ${context}\n\nQ: ${question}`);
-```
-
-### Search & Discovery
-
-| Use Case | Features Used | Example |
-|----------|---------------|---------|
-| **Semantic Search** | HNSW, Metadata filtering, SIMD | Core feature |
-| **Hybrid Search** | BM25 + embeddings, Sparse vectors | [docs/api](./docs/api/) |
-| **Image Similarity** | CLIP embeddings, Hyperbolic HNSW | [examples/wasm-react](./examples/wasm-react) |
-| **Code Search** | Local ONNX embeddings, Graph queries | [examples/nodejs](./examples/nodejs) |
-
-```javascript
-// Hybrid search: keyword + semantic
-const results = await db.search(query, {
- k: 10,
- filter: { category: 'electronics', price: { $lt: 500 } },
- hybridAlpha: 0.7, // 70% semantic, 30% keyword
- rerank: true // GNN-enhanced reranking
-});
-```
-
-### Recommendations & Personalization
-
-| Use Case | Features Used | Example |
-|----------|---------------|---------|
-| **Product Recommendations** | Graph queries, Cypher, GNN | [examples/graph](./examples/graph) |
-| **Content Personalization** | User embeddings, Collaborative filtering | Real-time adaptation |
-| **Similar Items** | Cosine similarity, Hyperbolic space | Hierarchical taxonomies |
-
-```cypher
-// Neo4j-style recommendations with learning
-MATCH (user:User {id: $userId})-[:VIEWED]->(item:Product)
-MATCH (item)-[:SIMILAR_TO]->(rec:Product)
-WHERE NOT (user)-[:PURCHASED]->(rec)
-RETURN rec ORDER BY rec.gnn_score DESC LIMIT 10
-```
-
-### Knowledge Management
-
-| Use Case | Features Used | Example |
-|----------|---------------|---------|
-| **Knowledge Graphs** | Hypergraph, Cypher, SPARQL | [docs/api/CYPHER_REFERENCE.md](./docs/api/CYPHER_REFERENCE.md) |
-| **Document Q&A** | Chunking, Embeddings, RAG | [examples/refrag-pipeline](./examples/refrag-pipeline) |
-| **Scientific Papers** | SciPix OCR, LaTeX extraction | [examples/scipix](./examples/scipix) |
-| **Research Discovery** | Citation graphs, Concept linking | Hyperedge relationships |
-
-```cypher
-// Multi-hop knowledge graph traversal
-MATCH (paper:Paper)-[:CITES*1..3]->(cited:Paper)
-WHERE paper.topic = 'machine learning'
-MATCH (cited)-[:AUTHORED_BY]->(author:Researcher)
-RETURN author, count(cited) as influence
-ORDER BY influence DESC LIMIT 20
-```
-
-### Real-Time & Edge Computing
-
-| Use Case | Features Used | Example |
-|----------|---------------|---------|
-| **Browser AI** | WASM, WebGPU, ruvllm-wasm | [examples/wasm-vanilla](./examples/wasm-vanilla) |
-| **IoT Sensors** | rvLite, Edge DB, no_std | [examples/edge](./examples/edge) |
-| **Mobile Apps** | 2MB footprint, Offline-first | [examples/edge-net](./examples/edge-net) |
-| **Streaming Data** | Real-time indexing, Dynamic min-cut | [examples/neural-trader](./examples/neural-trader) |
-
-```javascript
-// Browser-based AI (no server required)
-import init, { RuvLLMWasm } from '@ruvector/ruvllm-wasm';
-
-await init();
-const llm = await RuvLLMWasm.new(true); // WebGPU enabled
-await llm.load_model_from_url('https://cdn.example.com/model.gguf');
-
-// Runs entirely in browser
-const response = await llm.generate('Explain quantum computing', {
- max_tokens: 200,
- temperature: 0.7
-});
-```
-
-### Scientific & Research
-
-| Use Case | Features Used | Example |
-|----------|---------------|---------|
-| **Neural Network Analysis** | Spiking NN, Meta-cognition | [examples/meta-cognition](./examples/meta-cognition-spiking-neural-network) |
-| **Algorithmic Trading** | Neural Trader, Time-series | [examples/neural-trader](./examples/neural-trader) |
-| **Quantum Computing** | ruQu, Min-cut coherence | [crates/ruQu](./crates/ruQu) |
-| **Brain Connectivity** | Dynamic min-cut, Network analysis | [examples/mincut](./examples/mincut) |
-
-```rust
-// Neuromorphic computing with spiking networks
-use ruvector_nervous_system::{SpikingNetwork, LIFNeuron};
-
-let mut network = SpikingNetwork::new();
-network.add_layer(LIFNeuron::new(128)); // 128 spiking neurons
-network.enable_stdp(); // Spike-timing plasticity
-
-// 10-50x more energy efficient than traditional ANNs
-let output = network.forward(&input_spikes);
-```
-
-### Neuromorphic Computing (micro-hnsw v2.3)
-
-Novel neuromorphic discoveries for brain-inspired vector search in **11.8KB WASM**.
-
-| Discovery | Description | Benefit |
-|-----------|-------------|---------|
-| **Spike-Timing Vector Encoding** | Convert vectors to temporal spike patterns | Temporal similarity matching |
-| **Homeostatic Plasticity** | Self-stabilizing network activity | Prevents runaway activation |
-| **Oscillatory Resonance** | Gamma-frequency (40Hz) search amplification | Improved recall via resonance |
-| **Winner-Take-All Circuits** | Competitive neural selection with lateral inhibition | Sparse, efficient representations |
-| **Dendritic Computation** | Non-linear local processing in dendrites | Complex pattern detection |
-| **STDP Learning** | Spike-Timing Dependent Plasticity | Unsupervised Hebbian learning |
-
-```rust
-// micro-hnsw: Neuromorphic HNSW in 11.8KB WASM
-use micro_hnsw_wasm::{MicroHnsw, LIFNeuron, SpikeTrain};
-
-// 256 cores ร 32 vectors = 8K total capacity
-let mut hnsw = MicroHnsw::new(16, Metric::Cosine); // 16-dim vectors
-
-// Spike-timing vector encoding
-let spike_train = SpikeTrain::encode(&embedding, 8); // 8-bit temporal resolution
-
-// LIF neuron with STDP learning
-let neuron = LIFNeuron::new(0.8); // threshold = 0.8
-neuron.enable_stdp(0.01, 0.012); // A+ = 0.01, A- = 0.012
-neuron.enable_homeostasis(0.1); // Target rate: 0.1 spikes/ms
-
-// Winner-take-all search with lateral inhibition
-let results = hnsw.search_wta(&query, 10, 0.8); // WTA inhibition = 0.8
-```
-
-### Distributed & Enterprise
-
-| Use Case | Features Used | Example |
-|----------|---------------|---------|
-| **Multi-Region Deployment** | Raft consensus, Replication | [docs/cloud-architecture](./docs/cloud-architecture/) |
-| **High Availability** | Auto-sharding, Failover | 99.99% SLA capable |
-| **PostgreSQL Integration** | 230+ SQL functions, pgvector replacement | [crates/ruvector-postgres](./crates/ruvector-postgres) |
-| **Burst Traffic** | 10-50x scaling, Load balancing | [examples/google-cloud](./examples/google-cloud) |
-
-```sql
--- PostgreSQL with RuVector extension
-CREATE EXTENSION ruvector;
-
--- Create vector column with GNN-enhanced index
-CREATE TABLE documents (
- id SERIAL PRIMARY KEY,
- content TEXT,
- embedding VECTOR(384)
-);
-
-CREATE INDEX ON documents USING hnsw_gnn (embedding);
-
--- Self-improving search
-SELECT * FROM documents
-ORDER BY embedding <-> query_vector
-LIMIT 10;
-```
-
-### AI Safety & Coherence (Cognitum Gate)
-
-A **256-tile WASM fabric** for real-time AI agent safety decisions with cryptographic verification.
-
-| Component | Description | Memory |
-|-----------|-------------|--------|
-| **Worker Tiles (255)** | Local graph shards, evidence accumulation, witness fragments | 64KB each |
-| **TileZero Arbiter** | Supergraph merging, global decisions, permit tokens | Central |
-| **Gate Decisions** | Permit / Defer / Deny with confidence scores | <1ms |
-| **Witness Receipts** | Hash-chained cryptographic audit trail | Immutable |
-
-| Feature | Description |
-|---------|-------------|
-| **Anytime-Valid Testing** | Sequential hypothesis testing with e-values |
-| **Min-Cut Aggregation** | Global coherence via distributed min-cut |
-| **Signed Permits** | Cryptographic tokens for approved actions |
-| **Evidence Filters** | Three-filter decision system (structural, evidence, combined) |
-
-```rust
-// Cognitum Gate: AI agent safety in microseconds
-use cognitum_gate_tilezero::{GateDecision, ActionContext, PermitToken};
-
-let gate = CoherenceGate::new_256_tiles();
-
-// Evaluate action safety
-let context = ActionContext {
- action_id: "deploy-model-v2".into(),
- action_type: "config_change".into(),
- agent_id: "coder-agent-01".into(),
- ..Default::default()
-};
-
-let decision = gate.evaluate(&context).await?;
-
-match decision {
- GateDecision::Permit(token) => {
- // Cryptographically signed permit token
- assert!(token.verify(&gate.public_key()));
- execute_action(token);
- }
- GateDecision::Defer(reason) => {
- // Needs more evidence - retry later
- log::info!("Deferred: {}", reason);
- }
- GateDecision::Deny(evidence) => {
- // Action blocked with witness receipt
- log::warn!("Denied: {:?}", evidence);
- }
-}
-```
-
-```javascript
-// Browser: Real-time safety checks via WASM
-import { CognitumGate } from '@cognitum/gate';
-
-const gate = await CognitumGate.init();
-
-// Check action in <1ms
-const result = await gate.evaluate({
- action: 'modify_user_data',
- agent: 'assistant-v3',
- context: { user_id: '12345' }
-});
-
-if (result.permitted) {
- const receipt = result.witnessReceipt; // Hash-chained audit log
- console.log('Permit token:', result.token);
-}
-```
-
-### Dynamic Embedding Fine-Tuning
-
-| Use Case | Features Used | Example |
-|----------|---------------|---------|
-| **Real-Time Adaptation** | MicroLoRA (<1ms), Per-request learning | [docs/ruvllm/FINE_TUNING.md](./docs/ruvllm/FINE_TUNING.md) |
-| **Contrastive Training** | Triplet loss, Hard negatives, InfoNCE | [npm/packages/ruvllm](./npm/packages/ruvllm) |
-| **Task-Specific Adapters** | 5 pre-defined adapters (Coder, Researcher, Security, Architect, Reviewer) | [docs/training](./docs/training/) |
-| **Catastrophic Forgetting Prevention** | EWC++ (Elastic Weight Consolidation) | [crates/sona](./crates/sona) |
-| **Browser Fine-Tuning** | MicroLoRA WASM, <50KB adapters | [crates/ruvllm-wasm](./crates/ruvllm-wasm) |
-
-**Three-Tier Adaptation System:**
-
-| Tier | Technique | Latency | Use Case |
-|------|-----------|---------|----------|
-| **Instant** | MicroLoRA (rank 1-2) | <1ms | Per-request adaptation |
-| **Background** | Adapter Merge + EWC++ | ~100ms | Pattern consolidation |
-| **Deep** | Full Training Pipeline | Minutes | Periodic optimization |
-
-```javascript
-// Real-time embedding fine-tuning with contrastive learning
-import { ContrastiveTrainer, tripletLoss } from '@ruvector/ruvllm';
-
-const trainer = new ContrastiveTrainer({
- epochs: 10,
- batchSize: 16,
- margin: 0.5, // Triplet loss margin
- hardNegativeRatio: 0.7 // 70% hard negatives for better learning
-});
-
-// Train with triplets: anchor (task) โ positive (correct agent) โ negative (wrong agent)
-trainer.addTriplet(taskEmb, correctAgentEmb, wrongAgentEmb, isHardNegative);
-const results = trainer.train();
-trainer.exportTrainingData('./fine-tuned-model');
-```
-
-```rust
-// Rust: MicroLoRA for per-request adaptation
-use ruvllm::lora::{MicroLoRA, MicroLoraConfig, AdaptFeedback};
-
-let lora = MicroLoRA::new(MicroLoraConfig::for_hidden_dim(4096));
-
-// During inference: apply LoRA delta
-let output = model.forward(&input)?;
-let delta = lora.forward(&input, &TargetModule::QProj);
-let enhanced = output.iter().zip(delta.iter()).map(|(o, d)| o + d).collect();
-
-// After response: adapt based on quality feedback
-lora.adapt(&input, AdaptFeedback::from_quality(0.85))?;
-lora.apply_updates(0.01); // Learning rate
-```
-
-```javascript
-// Browser: Real-time fine-tuning with MicroLoRA WASM
-import init, { MicroLoraWasm, MicroLoraConfigWasm } from 'ruvllm-wasm';
-
-await init();
-const config = new MicroLoraConfigWasm();
-config.rank = 2; // Tiny rank for browser (<50KB)
-config.alpha = 4.0;
-config.inFeatures = 768;
-
-const lora = new MicroLoraWasm(config);
-const delta = lora.forward(hiddenStates); // <1ms latency
-
-// Persist to localStorage/IndexedDB
-const json = lora.toJson();
-localStorage.setItem('user-adapter', json);
-```
-
-### Agentic Workflows
-
-| Use Case | Features Used | Example |
-|----------|---------------|---------|
-| **Version Control for AI** | Agentic Jujutsu, Branching | [examples/agentic-jujutsu](./examples/agentic-jujutsu) |
-| **Data Pipelines** | DAG workflows, Self-learning | [crates/ruvector-dag](./crates/ruvector-dag) |
-| **Web Scraping** | Apify integration, Embeddings | [examples/apify](./examples/apify) |
-| **Synthetic Data** | Agentic synthesis, Generation | [Agentic-Flow](https://github.com/ruvnet/agentic-flow) |
-
-```javascript
-// Self-learning DAG workflow
-import { QueryDag, AttentionSelector } from '@ruvector/dag';
-
-const dag = new QueryDag();
-dag.addNode({ type: 'fetch', source: 'api' });
-dag.addNode({ type: 'embed', model: 'local-onnx' });
-dag.addNode({ type: 'index', engine: 'hnsw' });
-
-// DAG learns optimal execution paths over time
-dag.enableSonaLearning();
-await dag.execute();
-```
-
-
-
-## Installation
-
-| Platform | Command |
-|----------|---------|
-| **npm** | `npm install ruvector` |
-| **npm (SONA)** | `npm install @ruvector/sona` |
-| **Browser/WASM** | `npm install ruvector-wasm` |
-| **Rust** | `cargo add ruvector-core ruvector-graph ruvector-gnn` |
-| **Rust (SONA)** | `cargo add ruvector-sona` |
-| **Rust (LLM)** | `cargo add ruvllm` |
-
----
-
-## Package Reference
-
-
-๐ Documentation
-
-#### Getting Started
-
-| Topic | Link |
-|-------|------|
-| Getting Started | [docs/guides/GETTING_STARTED.md](./docs/guides/GETTING_STARTED.md) |
-| API Reference | [docs/api/](./docs/api/) |
-| Cypher Reference | [docs/api/CYPHER_REFERENCE.md](./docs/api/CYPHER_REFERENCE.md) |
-| Performance Tuning | [docs/optimization/PERFORMANCE_TUNING_GUIDE.md](./docs/optimization/PERFORMANCE_TUNING_GUIDE.md) |
-
-#### Core Components
-
-| Topic | Link |
-|-------|------|
-| GNN Architecture | [docs/gnn/](./docs/gnn/) |
-| HNSW Indexing | [docs/hnsw/](./docs/hnsw/) |
-| DAG System | [docs/dag/](./docs/dag/) |
-| Nervous System | [docs/nervous-system/](./docs/nervous-system/) |
-| Sparse Inference | [docs/sparse-inference/](./docs/sparse-inference/) |
-
-#### Bindings & Integration
-
-| Topic | Link |
-|-------|------|
-| Node.js API | [crates/ruvector-gnn-node/README.md](./crates/ruvector-gnn-node/README.md) |
-| WASM API | [crates/ruvector-gnn-wasm/README.md](./crates/ruvector-gnn-wasm/README.md) |
-| PostgreSQL | [docs/postgres/](./docs/postgres/) |
-| Self-Learning Hooks | [docs/hooks/](./docs/hooks/) |
-| Integration Guides | [docs/integration/](./docs/integration/) |
-
-#### LLM & AI
-
-| Topic | Link |
-|-------|------|
-| RuvLLM | [docs/ruvllm/](./docs/ruvllm/) |
-| Training Guides | [docs/training/](./docs/training/) |
-
-#### Operations
-
-| Topic | Link |
-|-------|------|
-| Architecture | [docs/architecture/](./docs/architecture/) |
-| Cloud Deployment | [docs/cloud-architecture/](./docs/cloud-architecture/) |
-| Security | [docs/security/](./docs/security/) |
-| Benchmarks | [docs/benchmarks/](./docs/benchmarks/) |
-| Testing | [docs/testing/](./docs/testing/) |
-
-#### Research
-
-| Topic | Link |
-|-------|------|
-| Research Papers | [docs/research/](./docs/research/) |
-| GNN V2 Features | [docs/research/gnn-v2/](./docs/research/gnn-v2/) |
-| Min-Cut Algorithms | [docs/research/mincut/](./docs/research/mincut/) |
-| SPARQL Support | [docs/research/sparql/](./docs/research/sparql/) |
-| Latent Space | [docs/research/latent-space/](./docs/research/latent-space/) |
-
-### Architecture Decision Records (ADRs)
-
-| ADR | Status | Description |
-|-----|--------|-------------|
-| [ADR-001](./docs/adr/ADR-001-ruvector-core-architecture.md) | Accepted | Core architecture design |
-| [ADR-002](./docs/adr/ADR-002-ruvllm-integration.md) | Accepted | RuvLLM integration |
-| [ADR-003](./docs/adr/ADR-003-simd-optimization-strategy.md) | Accepted | SIMD optimization strategy |
-| [ADR-004](./docs/adr/ADR-004-kv-cache-management.md) | Accepted | KV cache management |
-| [ADR-005](./docs/adr/ADR-005-wasm-runtime-integration.md) | Accepted | WASM runtime integration |
-| [ADR-006](./docs/adr/ADR-006-memory-management.md) | Accepted | Memory management |
-| [ADR-007](./docs/adr/ADR-007-security-review-technical-debt.md) | Accepted | Security review |
-| [ADR-008](./docs/adr/ADR-008-mistral-rs-integration.md) | **New** | Mistral-rs backend integration |
-| [ADR-009](./docs/adr/ADR-009-structured-output.md) | **New** | Structured output (SOTA) |
-| [ADR-010](./docs/adr/ADR-010-function-calling.md) | **New** | Function calling (SOTA) |
-| [ADR-011](./docs/adr/ADR-011-prefix-caching.md) | **New** | Prefix caching (SOTA) |
-| [ADR-012](./docs/adr/ADR-012-security-remediation.md) | **New** | Security remediation |
-| [ADR-013](./docs/adr/ADR-013-huggingface-publishing.md) | **New** | HuggingFace publishing |
-
-
-
-
-
-๐ฆ npm Packages (45+ Packages)
-
-#### Core Packages
-
-| Package | Description | Version | Downloads |
-|---------|-------------|---------|-----------|
-| [ruvector](https://www.npmjs.com/package/ruvector) | All-in-one CLI & package | [](https://www.npmjs.com/package/ruvector) | [](https://www.npmjs.com/package/ruvector) |
-| [@ruvector/core](https://www.npmjs.com/package/@ruvector/core) | Core vector database with HNSW | [](https://www.npmjs.com/package/@ruvector/core) | [](https://www.npmjs.com/package/@ruvector/core) |
-| [@ruvector/node](https://www.npmjs.com/package/@ruvector/node) | Unified Node.js bindings | [](https://www.npmjs.com/package/@ruvector/node) | [](https://www.npmjs.com/package/@ruvector/node) |
-| [ruvector-extensions](https://www.npmjs.com/package/ruvector-extensions) | Advanced features: embeddings, UI | [](https://www.npmjs.com/package/ruvector-extensions) | [](https://www.npmjs.com/package/ruvector-extensions) |
-
-#### Graph & GNN
-
-| Package | Description | Version | Downloads |
-|---------|-------------|---------|-----------|
-| [@ruvector/gnn](https://www.npmjs.com/package/@ruvector/gnn) | Graph Neural Network layers | [](https://www.npmjs.com/package/@ruvector/gnn) | [](https://www.npmjs.com/package/@ruvector/gnn) |
-| [@ruvector/graph-node](https://www.npmjs.com/package/@ruvector/graph-node) | Hypergraph with Cypher queries | [](https://www.npmjs.com/package/@ruvector/graph-node) | [](https://www.npmjs.com/package/@ruvector/graph-node) |
-| [@ruvector/graph-wasm](https://www.npmjs.com/package/@ruvector/graph-wasm) | Browser graph queries | [](https://www.npmjs.com/package/@ruvector/graph-wasm) | [](https://www.npmjs.com/package/@ruvector/graph-wasm) |
-| [@ruvector/graph-data-generator](https://www.npmjs.com/package/@ruvector/graph-data-generator) | AI-powered synthetic graph data | [](https://www.npmjs.com/package/@ruvector/graph-data-generator) | [](https://www.npmjs.com/package/@ruvector/graph-data-generator) |
-
-#### AI Routing & Attention
-
-| Package | Description | Version | Downloads |
-|---------|-------------|---------|-----------|
-| [@ruvector/tiny-dancer](https://www.npmjs.com/package/@ruvector/tiny-dancer) | FastGRNN neural routing | [](https://www.npmjs.com/package/@ruvector/tiny-dancer) | [](https://www.npmjs.com/package/@ruvector/tiny-dancer) |
-| [@ruvector/router](https://www.npmjs.com/package/@ruvector/router) | Semantic router + HNSW | [](https://www.npmjs.com/package/@ruvector/router) | [](https://www.npmjs.com/package/@ruvector/router) |
-| [@ruvector/attention](https://www.npmjs.com/package/@ruvector/attention) | 39 attention mechanisms | [](https://www.npmjs.com/package/@ruvector/attention) | [](https://www.npmjs.com/package/@ruvector/attention) |
-
-#### Learning & Neural
-
-| Package | Description | Version | Downloads |
-|---------|-------------|---------|-----------|
-| [@ruvector/sona](https://www.npmjs.com/package/@ruvector/sona) | Self-Optimizing Neural Architecture | [](https://www.npmjs.com/package/@ruvector/sona) | [](https://www.npmjs.com/package/@ruvector/sona) |
-| [@ruvector/spiking-neural](https://www.npmjs.com/package/@ruvector/spiking-neural) | Spiking neural networks (SNN) | [](https://www.npmjs.com/package/@ruvector/spiking-neural) | [](https://www.npmjs.com/package/@ruvector/spiking-neural) |
-
-#### LLM Runtime
-
-| Package | Description | Version | Downloads |
-|---------|-------------|---------|-----------|
-| [@ruvector/ruvllm](https://www.npmjs.com/package/@ruvector/ruvllm) | LLM orchestration + SONA | [](https://www.npmjs.com/package/@ruvector/ruvllm) | [](https://www.npmjs.com/package/@ruvector/ruvllm) |
-| [@ruvector/ruvllm-cli](https://www.npmjs.com/package/@ruvector/ruvllm-cli) | LLM CLI: inference, benchmarks | [](https://www.npmjs.com/package/@ruvector/ruvllm-cli) | [](https://www.npmjs.com/package/@ruvector/ruvllm-cli) |
-| [@ruvector/ruvllm-wasm](https://www.npmjs.com/package/@ruvector/ruvllm-wasm) | Browser LLM inference | [](https://www.npmjs.com/package/@ruvector/ruvllm-wasm) | [](https://www.npmjs.com/package/@ruvector/ruvllm-wasm) |
-
-#### Distributed Systems
-
-| Package | Description | Version | Downloads |
-|---------|-------------|---------|-----------|
-| [@ruvector/cluster](https://www.npmjs.com/package/@ruvector/cluster) | Distributed clustering | [](https://www.npmjs.com/package/@ruvector/cluster) | [](https://www.npmjs.com/package/@ruvector/cluster) |
-| [@ruvector/server](https://www.npmjs.com/package/@ruvector/server) | HTTP/gRPC server | [](https://www.npmjs.com/package/@ruvector/server) | [](https://www.npmjs.com/package/@ruvector/server) |
-| [@ruvector/raft](https://www.npmjs.com/package/@ruvector/raft) | Raft consensus | [](https://www.npmjs.com/package/@ruvector/raft) | [](https://www.npmjs.com/package/@ruvector/raft) |
-| [@ruvector/replication](https://www.npmjs.com/package/@ruvector/replication) | Multi-master replication | [](https://www.npmjs.com/package/@ruvector/replication) | [](https://www.npmjs.com/package/@ruvector/replication) |
-| [@ruvector/burst-scaling](https://www.npmjs.com/package/@ruvector/burst-scaling) | 10-50x burst scaling | [](https://www.npmjs.com/package/@ruvector/burst-scaling) | [](https://www.npmjs.com/package/@ruvector/burst-scaling) |
-
-#### Edge & Standalone
-
-| Package | Description | Version | Downloads |
-|---------|-------------|---------|-----------|
-| [rvlite](https://www.npmjs.com/package/rvlite) | SQLite-style edge DB | [](https://www.npmjs.com/package/rvlite) | [](https://www.npmjs.com/package/rvlite) |
-| [@ruvector/rudag](https://www.npmjs.com/package/@ruvector/rudag) | Self-learning DAG | [](https://www.npmjs.com/package/@ruvector/rudag) | [](https://www.npmjs.com/package/@ruvector/rudag) |
-
-#### Agentic & Synthetic Data
-
-| Package | Description | Version | Downloads |
-|---------|-------------|---------|-----------|
-| [@ruvector/agentic-synth](https://www.npmjs.com/package/@ruvector/agentic-synth) | AI synthetic data generator | [](https://www.npmjs.com/package/@ruvector/agentic-synth) | [](https://www.npmjs.com/package/@ruvector/agentic-synth) |
-| [@ruvector/agentic-integration](https://www.npmjs.com/package/@ruvector/agentic-integration) | Distributed agent coordination | [](https://www.npmjs.com/package/@ruvector/agentic-integration) | [](https://www.npmjs.com/package/@ruvector/agentic-integration) |
-| [@cognitum/gate](https://www.npmjs.com/package/@cognitum/gate) | AI coherence gate | [](https://www.npmjs.com/package/@cognitum/gate) | [](https://www.npmjs.com/package/@cognitum/gate) |
-
-#### CLI Tools
-
-| Package | Description | Version | Downloads |
-|---------|-------------|---------|-----------|
-| [@ruvector/cli](https://www.npmjs.com/package/@ruvector/cli) | CLI + self-learning hooks | [](https://www.npmjs.com/package/@ruvector/cli) | [](https://www.npmjs.com/package/@ruvector/cli) |
-| [@ruvector/postgres-cli](https://www.npmjs.com/package/@ruvector/postgres-cli) | PostgreSQL extension CLI | [](https://www.npmjs.com/package/@ruvector/postgres-cli) | [](https://www.npmjs.com/package/@ruvector/postgres-cli) |
-| [@ruvector/scipix](https://www.npmjs.com/package/@ruvector/scipix) | Scientific OCR client | [](https://www.npmjs.com/package/@ruvector/scipix) | [](https://www.npmjs.com/package/@ruvector/scipix) |
-
-#### WASM Packages
-
-| Package | Description | Version | Downloads |
-|---------|-------------|---------|-----------|
-| [@ruvector/wasm](https://www.npmjs.com/package/@ruvector/wasm) | Unified WASM meta-package | [](https://www.npmjs.com/package/@ruvector/wasm) | [](https://www.npmjs.com/package/@ruvector/wasm) |
-| [@ruvector/wasm-unified](https://www.npmjs.com/package/@ruvector/wasm-unified) | Unified TypeScript API | [](https://www.npmjs.com/package/@ruvector/wasm-unified) | [](https://www.npmjs.com/package/@ruvector/wasm-unified) |
-| [@ruvector/gnn-wasm](https://www.npmjs.com/package/@ruvector/gnn-wasm) | GNN WASM bindings | [](https://www.npmjs.com/package/@ruvector/gnn-wasm) | [](https://www.npmjs.com/package/@ruvector/gnn-wasm) |
-| [@ruvector/attention-wasm](https://www.npmjs.com/package/@ruvector/attention-wasm) | Attention WASM bindings | [](https://www.npmjs.com/package/@ruvector/attention-wasm) | [](https://www.npmjs.com/package/@ruvector/attention-wasm) |
-| [@ruvector/attention-unified-wasm](https://www.npmjs.com/package/@ruvector/attention-unified-wasm) | All 39 attention mechanisms | [](https://www.npmjs.com/package/@ruvector/attention-unified-wasm) | [](https://www.npmjs.com/package/@ruvector/attention-unified-wasm) |
-| [@ruvector/tiny-dancer-wasm](https://www.npmjs.com/package/@ruvector/tiny-dancer-wasm) | AI routing WASM | [](https://www.npmjs.com/package/@ruvector/tiny-dancer-wasm) | [](https://www.npmjs.com/package/@ruvector/tiny-dancer-wasm) |
-| [@ruvector/router-wasm](https://www.npmjs.com/package/@ruvector/router-wasm) | Semantic router WASM | [](https://www.npmjs.com/package/@ruvector/router-wasm) | [](https://www.npmjs.com/package/@ruvector/router-wasm) |
-| [@ruvector/learning-wasm](https://www.npmjs.com/package/@ruvector/learning-wasm) | Learning module WASM | [](https://www.npmjs.com/package/@ruvector/learning-wasm) | [](https://www.npmjs.com/package/@ruvector/learning-wasm) |
-| [@ruvector/economy-wasm](https://www.npmjs.com/package/@ruvector/economy-wasm) | Tokenomics WASM | [](https://www.npmjs.com/package/@ruvector/economy-wasm) | [](https://www.npmjs.com/package/@ruvector/economy-wasm) |
-| [@ruvector/exotic-wasm](https://www.npmjs.com/package/@ruvector/exotic-wasm) | Exotic features WASM | [](https://www.npmjs.com/package/@ruvector/exotic-wasm) | [](https://www.npmjs.com/package/@ruvector/exotic-wasm) |
-| [@ruvector/nervous-system-wasm](https://www.npmjs.com/package/@ruvector/nervous-system-wasm) | Nervous system WASM | [](https://www.npmjs.com/package/@ruvector/nervous-system-wasm) | [](https://www.npmjs.com/package/@ruvector/nervous-system-wasm) |
-| [ruvector-attention-wasm](https://www.npmjs.com/package/ruvector-attention-wasm) | WASM attention (Flash, MoE, Hyperbolic, CGT Sheaf) | [](https://www.npmjs.com/package/ruvector-attention-wasm) | [](https://www.npmjs.com/package/ruvector-attention-wasm) |
-
-
-
-
-๐ฆ Rust Crates (63 Packages)
-
-All crates are published to [crates.io](https://crates.io) under the `ruvector-*` namespace.
-
-### Core Crates
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-core](./crates/ruvector-core) | Vector database engine with HNSW indexing | [](https://crates.io/crates/ruvector-core) |
-| [ruvector-collections](./crates/ruvector-collections) | Collection and namespace management | [](https://crates.io/crates/ruvector-collections) |
-| [ruvector-filter](./crates/ruvector-filter) | Vector filtering and metadata queries | [](https://crates.io/crates/ruvector-filter) |
-| [ruvector-metrics](./crates/ruvector-metrics) | Performance metrics and monitoring | [](https://crates.io/crates/ruvector-metrics) |
-| [ruvector-snapshot](./crates/ruvector-snapshot) | Snapshot and persistence management | [](https://crates.io/crates/ruvector-snapshot) |
-| [ruvector-node](./crates/ruvector-node) | Node.js bindings via NAPI-RS | [](https://crates.io/crates/ruvector-node) |
-| [ruvector-wasm](./crates/ruvector-wasm) | WASM bindings for browser/edge | [](https://crates.io/crates/ruvector-wasm) |
-| [ruvector-cli](./crates/ruvector-cli) | CLI and MCP server | [](https://crates.io/crates/ruvector-cli) |
-| [ruvector-bench](./crates/ruvector-bench) | Benchmarking suite | [](https://crates.io/crates/ruvector-bench) |
-
-### Graph & GNN
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-graph](./crates/ruvector-graph) | Hypergraph database with Neo4j-style Cypher | [](https://crates.io/crates/ruvector-graph) |
-| [ruvector-graph-node](./crates/ruvector-graph-node) | Node.js bindings for graph operations | [](https://crates.io/crates/ruvector-graph-node) |
-| [ruvector-graph-wasm](./crates/ruvector-graph-wasm) | WASM bindings for browser graph queries | [](https://crates.io/crates/ruvector-graph-wasm) |
-| [ruvector-gnn](./crates/ruvector-gnn) | Graph Neural Network layers and training | [](https://crates.io/crates/ruvector-gnn) |
-| [ruvector-gnn-node](./crates/ruvector-gnn-node) | Node.js bindings for GNN inference | [](https://crates.io/crates/ruvector-gnn-node) |
-| [ruvector-gnn-wasm](./crates/ruvector-gnn-wasm) | WASM bindings for browser GNN | [](https://crates.io/crates/ruvector-gnn-wasm) |
-
-### Attention Mechanisms
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-attention](./crates/ruvector-attention) | 39 attention mechanisms (Flash, Hyperbolic, MoE, Graph) | [](https://crates.io/crates/ruvector-attention) |
-| [ruvector-attention-node](./crates/ruvector-attention-node) | Node.js bindings for attention mechanisms | [](https://crates.io/crates/ruvector-attention-node) |
-| [ruvector-attention-wasm](./crates/ruvector-attention-wasm) | WASM bindings for browser attention | [](https://crates.io/crates/ruvector-attention-wasm) |
-| [ruvector-attention-cli](./crates/ruvector-attention-cli) | CLI for attention testing and benchmarking | [](https://crates.io/crates/ruvector-attention-cli) |
-
-### LLM Runtime (ruvllm)
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvllm](./crates/ruvllm) | LLM serving runtime with SONA, paged attention, KV cache, BitNet | [](https://crates.io/crates/ruvllm) |
-| [ruvllm-cli](./crates/ruvllm-cli) | CLI for model inference and benchmarking | [](https://crates.io/crates/ruvllm-cli) |
-| [ruvllm-wasm](./crates/ruvllm-wasm) | WASM bindings for browser LLM inference | [](https://crates.io/crates/ruvllm-wasm) |
-
-**Features:** Candle backend, Metal/CUDA acceleration, Apple Neural Engine, GGUF support, SONA learning, **BitNet 1.58-bit quantization** (TL1 kernels, AVX2/WASM).
-
-```bash
-cargo add ruvllm --features inference-metal # Mac with Metal
-cargo add ruvllm --features inference-cuda # NVIDIA GPU
-```
-
-**RuvLTRA Models** โ Pre-trained GGUF models optimized for Claude Code workflows:
-
-| Model | Size | Use Case | Link |
-|-------|------|----------|------|
-| ruvltra-claude-code-0.5b-q4_k_m | 398 MB | Agent routing | [HuggingFace](https://huggingface.co/ruv/ruvltra) |
-| ruvltra-small-0.5b-q4_k_m | 398 MB | Embeddings | [HuggingFace](https://huggingface.co/ruv/ruvltra) |
-| ruvltra-medium-1.1b-q4_k_m | 800 MB | Classification | [HuggingFace](https://huggingface.co/ruv/ruvltra) |
-
-```bash
-# Download and use
-wget https://huggingface.co/ruv/ruvltra/resolve/main/ruvltra-small-0.5b-q4_k_m.gguf
-```
-
-
-### Distributed Systems
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-cluster](./crates/ruvector-cluster) | Cluster management and coordination | [](https://crates.io/crates/ruvector-cluster) |
-| [ruvector-raft](./crates/ruvector-raft) | Raft consensus implementation | [](https://crates.io/crates/ruvector-raft) |
-| [ruvector-replication](./crates/ruvector-replication) | Data replication and synchronization | [](https://crates.io/crates/ruvector-replication) |
-| [ruvector-server](./crates/ruvector-server) | REST/gRPC API server | [](https://crates.io/crates/ruvector-server) |
-
-### AI Agent Routing (Tiny Dancer)
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-tiny-dancer-core](./crates/ruvector-tiny-dancer-core) | FastGRNN neural inference for AI routing | [](https://crates.io/crates/ruvector-tiny-dancer-core) |
-| [ruvector-tiny-dancer-node](./crates/ruvector-tiny-dancer-node) | Node.js bindings for AI routing | [](https://crates.io/crates/ruvector-tiny-dancer-node) |
-| [ruvector-tiny-dancer-wasm](./crates/ruvector-tiny-dancer-wasm) | WASM bindings for browser AI routing | [](https://crates.io/crates/ruvector-tiny-dancer-wasm) |
-
-### Router (Semantic Routing)
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-router-core](./crates/ruvector-router-core) | Core semantic routing engine | [](https://crates.io/crates/ruvector-router-core) |
-| [ruvector-router-cli](./crates/ruvector-router-cli) | CLI for router testing and benchmarking | [](https://crates.io/crates/ruvector-router-cli) |
-| [ruvector-router-ffi](./crates/ruvector-router-ffi) | FFI bindings for other languages | [](https://crates.io/crates/ruvector-router-ffi) |
-| [ruvector-router-wasm](./crates/ruvector-router-wasm) | WASM bindings for browser routing | [](https://crates.io/crates/ruvector-router-wasm) |
-
-**Hybrid Routing** achieves **90% accuracy** for agent routing using keyword-first strategy with embedding fallback. See [Issue #122](https://github.com/ruvnet/ruvector/issues/122) for benchmarks and the [training tutorials](#-ruvllm-training--fine-tuning-tutorials) for fine-tuning guides.
-
-### Dynamic Min-Cut (December 2025 Breakthrough)
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-mincut](./crates/ruvector-mincut) | Subpolynomial fully-dynamic min-cut ([arXiv:2512.13105](https://arxiv.org/abs/2512.13105)) | [](https://crates.io/crates/ruvector-mincut) |
-| [ruvector-mincut-node](./crates/ruvector-mincut-node) | Node.js bindings for min-cut | [](https://crates.io/crates/ruvector-mincut-node) |
-| [ruvector-mincut-wasm](./crates/ruvector-mincut-wasm) | WASM bindings for browser min-cut | [](https://crates.io/crates/ruvector-mincut-wasm) |
-
-**First deterministic exact fully-dynamic min-cut** with verified **n^0.12 subpolynomial** update scaling:
-
-- **Brain connectivity** โ Detect Alzheimer's markers by tracking neural pathway changes in milliseconds
-- **Network resilience** โ Predict outages before they happen, route around failures instantly
-- **AI agent coordination** โ Find communication bottlenecks in multi-agent systems
-- **Neural network pruning** โ Identify which connections can be removed without losing accuracy
-- **448+ tests**, 256-core parallel optimization, 8KB per core (compile-time verified)
-
-```rust
-use ruvector_mincut::{DynamicMinCut, Graph};
-
-let mut graph = Graph::new();
-graph.add_edge(0, 1, 10.0);
-graph.add_edge(1, 2, 5.0);
-
-let mincut = DynamicMinCut::new(&graph);
-let (value, cut_edges) = mincut.compute();
-// Updates in subpolynomial time as edges change
-```
-
-### Quantum Coherence (ruQu)
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruqu](./crates/ruQu) | Classical nervous system for quantum machines - coherence via min-cut | [](https://crates.io/crates/ruqu) |
-| [cognitum-gate-kernel](./crates/cognitum-gate-kernel) | Anytime-valid coherence gate kernel | [](https://crates.io/crates/cognitum-gate-kernel) |
-| [cognitum-gate-tilezero](./crates/cognitum-gate-tilezero) | TileZero arbiter for coherence decisions | [](https://crates.io/crates/cognitum-gate-tilezero) |
-| [mcp-gate](./crates/mcp-gate) | MCP server for coherence gate integration | [](https://crates.io/crates/mcp-gate) |
-| [prime-radiant](./crates/prime-radiant) | Universal coherence engine - sheaf Laplacian AI safety & hallucination detection | [](https://crates.io/crates/prime-radiant) |
-
-**ruQu Features:** Real-time quantum coherence assessment, MWPM decoder integration, mincut-gated attention (50% FLOPs reduction).
-
-```rust
-use ruqu::{CoherenceGate, SyndromeFilter};
-
-let gate = CoherenceGate::new();
-let syndrome = gate.assess_coherence(&quantum_state)?;
-```
-
-### Advanced Math & Inference
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-math](./crates/ruvector-math) | Core math utilities, SIMD operations | [](https://crates.io/crates/ruvector-math) |
-| [ruvector-math-wasm](./crates/ruvector-math-wasm) | WASM bindings for math operations | [](https://crates.io/crates/ruvector-math-wasm) |
-| [ruvector-sparse-inference](./crates/ruvector-sparse-inference) | Sparse tensor inference engine | [](https://crates.io/crates/ruvector-sparse-inference) |
-| [ruvector-sparse-inference-wasm](./crates/ruvector-sparse-inference-wasm) | WASM bindings for sparse inference | [](https://crates.io/crates/ruvector-sparse-inference-wasm) |
-| [ruvector-hyperbolic-hnsw](./crates/ruvector-hyperbolic-hnsw) | HNSW in hyperbolic space (Poincarรฉ/Lorentz) | [](https://crates.io/crates/ruvector-hyperbolic-hnsw) |
-| [ruvector-hyperbolic-hnsw-wasm](./crates/ruvector-hyperbolic-hnsw-wasm) | WASM bindings for hyperbolic HNSW | [](https://crates.io/crates/ruvector-hyperbolic-hnsw-wasm) |
-
-### FPGA & Hardware Acceleration
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-fpga-transformer](./crates/ruvector-fpga-transformer) | FPGA-optimized transformer inference | [](https://crates.io/crates/ruvector-fpga-transformer) |
-| [ruvector-fpga-transformer-wasm](./crates/ruvector-fpga-transformer-wasm) | WASM simulation of FPGA transformer | [](https://crates.io/crates/ruvector-fpga-transformer-wasm) |
-| [ruvector-mincut-gated-transformer](./crates/ruvector-mincut-gated-transformer) | MinCut-gated attention for 50% compute reduction | [](https://crates.io/crates/ruvector-mincut-gated-transformer) |
-| [ruvector-mincut-gated-transformer-wasm](./crates/ruvector-mincut-gated-transformer-wasm) | WASM bindings for mincut-gated transformer | [](https://crates.io/crates/ruvector-mincut-gated-transformer-wasm) |
-
-### Neuromorphic & Bio-Inspired Learning
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-nervous-system](./crates/ruvector-nervous-system) | Spiking neural networks with BTSP learning & EWC plasticity | [](https://crates.io/crates/ruvector-nervous-system) |
-| [ruvector-nervous-system-wasm](./crates/ruvector-nervous-system-wasm) | WASM bindings for neuromorphic learning | [](https://crates.io/crates/ruvector-nervous-system-wasm) |
-| [ruvector-learning-wasm](./crates/ruvector-learning-wasm) | MicroLoRA adaptation (<100ยตs latency) | [](https://crates.io/crates/ruvector-learning-wasm) |
-| [ruvector-economy-wasm](./crates/ruvector-economy-wasm) | CRDT-based autonomous credit economy | [](https://crates.io/crates/ruvector-economy-wasm) |
-| [ruvector-exotic-wasm](./crates/ruvector-exotic-wasm) | Exotic AI primitives (strange loops, time crystals) | [](https://crates.io/crates/ruvector-exotic-wasm) |
-| [ruvector-attention-unified-wasm](./crates/ruvector-attention-unified-wasm) | Unified 18+ attention mechanisms (Neural, DAG, Mamba SSM) | [](https://crates.io/crates/ruvector-attention-unified-wasm) |
-| [micro-hnsw-wasm](./crates/micro-hnsw-wasm) | Neuromorphic HNSW with spiking neurons (11.8KB WASM) | [](https://crates.io/crates/micro-hnsw-wasm) |
-
-**Bio-inspired features:**
-- **Spiking Neural Networks (SNNs)** โ 10-50x energy efficiency vs traditional ANNs
-- **BTSP Learning** โ Behavioral Time-Scale Synaptic Plasticity for rapid adaptation
-- **MicroLoRA** โ Sub-microsecond fine-tuning for per-operator learning
-- **Mamba SSM** โ State Space Model attention for linear-time sequences
-
-### Self-Learning (SONA)
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [sona](./crates/sona) | Self-Optimizing Neural Architecture - LoRA, EWC++, ReasoningBank | [](https://crates.io/crates/ruvector-sona) |
-
-**SONA Features:** Two-tier LoRA adaptation, Elastic Weight Consolidation (EWC++), ReasoningBank for trajectory learning, runtime-adaptive learning for LLM routers.
-
-### Standalone Edge Database (rvLite)
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [rvlite](./crates/rvlite) | Standalone 2MB edge database with SQL, SPARQL, Cypher | [](https://crates.io/crates/rvlite) |
-
-**rvLite Features:** Powered by RuVector WASM, supports SQL/SPARQL/Cypher queries, ideal for IoT, mobile, and embedded systems.
-
-### PostgreSQL Extension
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-postgres](./crates/ruvector-postgres) | pgvector replacement with 230+ SQL functions, SIMD, Flash Attention | [](https://crates.io/crates/ruvector-postgres) |
-
-**PostgreSQL Features:** Drop-in pgvector replacement, GNN layers, hybrid search, multi-tenancy, self-healing, self-learning capabilities.
-
-```bash
-docker pull ruvnet/ruvector-postgres # Docker image
-cargo add ruvector-postgres # Rust crate
-```
-
-### Self-Learning Query DAG (ruvector-dag)
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-dag](./crates/ruvector-dag) | Neural self-learning DAG for automatic query optimization | [](https://crates.io/crates/ruvector-dag) |
-| [ruvector-dag-wasm](./crates/ruvector-dag-wasm) | WASM bindings for browser DAG optimization (58KB gzipped) | [](https://crates.io/crates/ruvector-dag-wasm) |
-
-**Make your queries faster automatically.** RuVector DAG learns from every query execution and continuously optimizes performanceโno manual tuning required.
-
-- **7 Attention Mechanisms**: Automatically selects the best strategy (Topological, Causal Cone, Critical Path, MinCut Gated, etc.)
-- **SONA Learning**: Self-Optimizing Neural Architecture adapts in <100ฮผs per query
-- **MinCut Control**: Rising "tension" triggers automatic strategy switching and predictive healing
-- **50-80% Latency Reduction**: Queries improve over time without code changes
-
-```rust
-use ruvector_dag::{QueryDag, OperatorNode};
-use ruvector_dag::attention::{AttentionSelector, SelectionPolicy};
-
-let mut dag = QueryDag::new();
-let scan = dag.add_node(OperatorNode::hnsw_scan(0, "vectors_idx", 64));
-let filter = dag.add_node(OperatorNode::filter(1, "score > 0.5"));
-dag.add_edge(scan, filter).unwrap();
-
-// System learns which attention mechanism works best
-let selector = AttentionSelector::new();
-let scores = selector.select_and_apply(SelectionPolicy::Adaptive, &dag)?;
-```
-
-See [ruvector-dag README](./crates/ruvector-dag/README.md) for full documentation.
-
-### Temporal Tensor Store
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-temporal-tensor](./crates/ruvector-temporal-tensor) | Time-series tensor storage with tiered quantization | [](https://crates.io/crates/ruvector-temporal-tensor) |
-| [ruvector-temporal-tensor-wasm](./crates/ruvector-temporal-tensor-wasm) | WASM bindings for browser temporal tensors | [](https://crates.io/crates/ruvector-temporal-tensor-wasm) |
-
-**High-performance temporal embedding storage** optimized for AI agent memory systems:
-
-| Feature | Description |
-|---------|-------------|
-| **Block-Based Storage** | 4KB aligned blocks with SIMD-optimized I/O ([ADR-018](./docs/adr/temporal-tensor-store/ADR-018-block-based-storage-engine.md)) |
-| **Tiered Quantization** | F32 โ F16 โ INT8 โ INT4 with <1% accuracy loss ([ADR-019](./docs/adr/temporal-tensor-store/ADR-019-tiered-quantization-formats.md)) |
-| **Temporal Scoring** | Access frequency + recency decay for automatic tier migration ([ADR-020](./docs/adr/temporal-tensor-store/ADR-020-temporal-scoring-tier-migration.md)) |
-| **Delta Compression** | 60-80% storage reduction via temporal differencing ([ADR-021](./docs/adr/temporal-tensor-store/ADR-021-delta-compression-reconstruction.md)) |
-| **Cross-Platform WASM** | Unified API for browser, Node.js, and edge ([ADR-022](./docs/adr/temporal-tensor-store/ADR-022-wasm-api-cross-platform.md)) |
-| **AgentDB Integration** | Native coherence scoring and memory persistence |
-
-**Performance Targets:** >100K writes/sec, <1ms p99 read latency, 4-32x compression ([ADR-023](./docs/adr/temporal-tensor-store/ADR-023-benchmarking-acceptance-criteria.md))
-
-See [Domain-Driven Design](./docs/architecture/temporal-tensor-store-ddd.md) for architecture details.
-
-### CRV Signal Line Protocol
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-crv](./crates/ruvector-crv) | 6-stage CRV signal line methodology for vector search | [](https://crates.io/crates/ruvector-crv) |
-
-**Maps CRV stages to ruvector subsystems:**
-- Stage I (Ideograms) โ Poincarรฉ ball hyperbolic embeddings
-- Stage II (Sensory) โ Multi-head attention vectors
-- Stage III (Dimensional) โ GNN graph topology
-- Stage IV (Emotional) โ SNN temporal encoding
-- Stage V (Interrogation) โ Differentiable search
-- Stage VI (3D Model) โ MinCut partitioning
-
-### Quantum Simulation Engine (ruQu)
-
-[](https://www.npmjs.com/package/@ruvector/ruqu-wasm)
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruqu-core](./crates/ruqu-core) | State-vector simulator with SIMD, noise models | [](https://crates.io/crates/ruqu-core) |
-| [ruqu-algorithms](./crates/ruqu-algorithms) | VQE, Grover's search, QAOA MaxCut, Surface Code QEC | [](https://crates.io/crates/ruqu-algorithms) |
-| [ruqu-exotic](./crates/ruqu-exotic) | Quantum-classical hybrids: decay, interference, syndrome | [](https://crates.io/crates/ruqu-exotic) |
-| [ruqu-wasm](./crates/ruqu-wasm) | WebAssembly bindings (npm: `@ruvector/ruqu-wasm`) | [](https://crates.io/crates/ruqu-wasm) |
-
-```bash
-npm install @ruvector/ruqu-wasm # Browser/Node.js
-cargo add ruqu-core # Rust
-```
-
-**Pure Rust quantum simulation** with 25-qubit WASM support:
-
-| Feature | Description |
-|---------|-------------|
-| **State-Vector Simulator** | Complex128 amplitudes, SIMD acceleration ([QE-001](./docs/adr/quantum-engine/ADR-QE-001-quantum-engine-core-architecture.md)) |
-| **VQE Algorithm** | Variational Quantum Eigensolver for chemistry ([QE-005](./docs/adr/quantum-engine/ADR-QE-005-vqe-algorithm-support.md)) |
-| **Grover's Search** | Quadratic speedup for unstructured search ([QE-006](./docs/adr/quantum-engine/ADR-QE-006-grover-search-implementation.md)) |
-| **QAOA MaxCut** | Quantum approximate optimization ([QE-007](./docs/adr/quantum-engine/ADR-QE-007-qaoa-maxcut-implementation.md)) |
-| **Surface Code QEC** | Topological error correction ([QE-008](./docs/adr/quantum-engine/ADR-QE-008-surface-code-error-correction.md)) |
-| **MinCut Coherence** | Quantum-classical integration via dynamic min-cut ([QE-012](./docs/adr/quantum-engine/ADR-QE-012-mincut-coherence-integration.md)) |
-
-```rust
-use ruqu_core::{QuantumState, Gate, Circuit};
-
-let mut circuit = Circuit::new(3);
-circuit.add_gate(Gate::H, 0); // Hadamard
-circuit.add_gate(Gate::CNOT, 0, 1); // Entangle
-circuit.add_gate(Gate::CNOT, 1, 2); // GHZ state
-
-let state = circuit.execute()?;
-let result = state.measure_all(); // Collapse to |000โฉ or |111โฉ
-```
-
-See [Quantum Engine ADRs](./docs/adr/quantum-engine/) for full documentation.
-
-### Distributed Systems (Raft & Replication)
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-raft](./crates/ruvector-raft) | Raft consensus with leader election & log replication | [](https://crates.io/crates/ruvector-raft) |
-| [ruvector-replication](./crates/ruvector-replication) | Multi-master replication with vector clocks | [](https://crates.io/crates/ruvector-replication) |
-| [ruvector-cluster](./crates/ruvector-cluster) | Cluster coordination and sharding | [](https://crates.io/crates/ruvector-cluster) |
-
-**Build distributed vector databases** with strong consistency guarantees:
-
-- **Raft Consensus** โ Leader election, log replication, automatic failover
-- **Vector Clocks** โ Causal ordering for conflict detection
-- **Conflict Resolution** โ Last-Write-Wins, custom merge functions, CRDT support
-- **Change Data Capture** โ Stream changes to replicas in real-time
-- **Automatic Failover** โ Promote replicas on primary failure
-
-```typescript
-import { RaftNode, ReplicaSet, VectorClock } from '@ruvector/raft';
-import { ReplicationManager, ConflictStrategy } from '@ruvector/replication';
-
-// Raft consensus cluster
-const node = new RaftNode({
- nodeId: 'node-1',
- peers: ['node-2', 'node-3'],
- electionTimeout: [150, 300],
-});
-
-await node.start();
-const entry = await node.propose({ op: 'insert', vector: embedding });
-
-// Multi-master replication
-const replicaSet = new ReplicaSet();
-replicaSet.addReplica('primary', 'localhost:5001', 'primary');
-replicaSet.addReplica('replica-1', 'localhost:5002', 'replica');
-
-const manager = new ReplicationManager(replicaSet, {
- conflictStrategy: ConflictStrategy.LastWriteWins,
- syncMode: 'async',
-});
-
-await manager.write('vectors', { id: 'v1', data: embedding });
-```
-
-See [npm/packages/raft/README.md](./npm/packages/raft/README.md) and [npm/packages/replication/README.md](./npm/packages/replication/README.md) for full documentation.
-
-### Standalone Vector Database (rvLite)
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [rvlite](./crates/rvlite) | SQLite-style vector database for browsers & edge | [](https://crates.io/crates/rvlite) |
-
-**Runs anywhere JavaScript runs** โ browsers, Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge:
-
-- **SQL + SPARQL + Cypher** unified query interface
-- **Zero dependencies** โ thin orchestration over existing WASM crates
-- **Self-learning** via SONA ReasoningBank integration
-
-```typescript
-import { RvLite } from '@rvlite/wasm';
-
-const db = await RvLite.create();
-await db.sql(`CREATE TABLE docs (id SERIAL, embedding VECTOR(384))`);
-await db.sparql(`SELECT ?s WHERE { ?s rdf:type ex:Document }`);
-await db.cypher(`MATCH (d:Doc)-[:SIMILAR]->(r) RETURN r`);
-```
-
-### Self-Optimizing Neural Architecture (SONA)
-
-| Crate | Description | crates.io | npm |
-|-------|-------------|-----------|-----|
-| [ruvector-sona](./crates/sona) | Runtime-adaptive learning with LoRA, EWC++, and ReasoningBank | [](https://crates.io/crates/ruvector-sona) | [](https://www.npmjs.com/package/@ruvector/sona) |
-
-**SONA** enables AI systems to continuously improve from user feedback without expensive retraining:
-
-- **Two-tier LoRA**: MicroLoRA (rank 1-2) for instant adaptation, BaseLoRA (rank 4-16) for long-term learning
-- **EWC++**: Elastic Weight Consolidation prevents catastrophic forgetting
-- **ReasoningBank**: K-means++ clustering stores and retrieves successful reasoning patterns
-- **Lock-free Trajectories**: ~50ns overhead per step with crossbeam ArrayQueue
-- **Sub-millisecond Learning**: <0.8ms per trajectory processing
-
-```bash
-# Rust
-cargo add ruvector-sona
-
-# Node.js
-npm install @ruvector/sona
-```
-
-```rust
-use ruvector_sona::{SonaEngine, SonaConfig};
-
-let engine = SonaEngine::new(SonaConfig::default());
-let traj_id = engine.start_trajectory(query_embedding);
-engine.record_step(traj_id, node_id, 0.85, 150);
-engine.end_trajectory(traj_id, 0.90);
-engine.learn_from_feedback(LearningSignal::positive(50.0, 0.95));
-```
-
-```javascript
-// Node.js
-const { SonaEngine } = require('@ruvector/sona');
-
-const engine = new SonaEngine(256); // 256 hidden dimensions
-const trajId = engine.beginTrajectory([0.1, 0.2, ...]);
-engine.addTrajectoryStep(trajId, activations, attention, 0.9);
-engine.endTrajectory(trajId, 0.95);
-```
-
-
-
----
-
-## Platform Features
-
-
-๐ Self-Learning DAG (Query Optimization)
-
-[](https://crates.io/crates/ruvector-dag)
-[](https://www.npmjs.com/package/@ruvector/rudag)
-
-**Make your queries faster automatically.** RuVector DAG learns from every query execution and continuously optimizes performanceโno manual tuning required.
-
-### What is RuVector DAG?
-
-A **self-learning query optimization system**โlike a "nervous system" for your database queries that:
-
-1. **Watches** how queries execute and identifies bottlenecks
-2. **Learns** which optimization strategies work best for different query patterns
-3. **Adapts** in real-time, switching strategies when conditions change
-4. **Heals** itself by detecting anomalies and fixing problems before they impact users
-
-Unlike traditional query optimizers that use static rules, RuVector DAG learns from actual execution patterns and gets smarter over time.
-
-### Key Benefits
-
-| Benefit | What It Does | Result |
-|---------|--------------|--------|
-| **Automatic Improvement** | Queries get faster without code changes | **50-80% latency reduction** after learning |
-| **Zero-Downtime Adaptation** | Adapts to pattern changes automatically | No manual index rebuilds |
-| **Predictive Prevention** | Detects rising "tension" early | Intervenes *before* slowdowns |
-| **Works Everywhere** | PostgreSQL, Browser (58KB WASM), Embedded | Universal deployment |
-
-### Use Cases
-
-| Use Case | Why RuVector DAG Helps |
-|----------|------------------------|
-| **Vector Search Applications** | Optimize similarity searches that traditional databases struggle with |
-| **High-Traffic APIs** | Automatically adapt to changing query patterns throughout the day |
-| **Real-Time Analytics** | Learn which aggregation paths are fastest for your specific data |
-| **Edge/Embedded Systems** | 58KB WASM build runs in browsers and IoT devices |
-| **Multi-Tenant Platforms** | Learn per-tenant query patterns without manual tuning |
-
-### How It Works
-
-```
-Query comes in โ DAG analyzes execution plan โ Best attention mechanism selected
- โ
-Query executes โ Results returned โ Learning system records what worked
- โ
- Next similar query benefits from learned optimizations
-```
-
-The system maintains a **MinCut tension** score that acts as a health indicator. When tension rises, the system automatically switches to more aggressive optimization strategies and triggers predictive healing.
-
-### 7 DAG Attention Mechanisms
-
-| Mechanism | When to Use | Trigger |
-|-----------|-------------|---------|
-| **Topological** | Default baseline | Low variance |
-| **Causal Cone** | Downstream impact analysis | Write-heavy patterns |
-| **Critical Path** | Latency-bound queries | p99 > 2x p50 |
-| **MinCut Gated** | Bottleneck-aware weighting | Cut tension rising |
-| **Hierarchical Lorentz** | Deep hierarchical queries | Depth > 10 |
-| **Parallel Branch** | Wide parallel execution | Branch count > 3 |
-| **Temporal BTSP** | Time-series workloads | Temporal patterns |
-
-### Quick Start
-
-**Rust:**
-```rust
-use ruvector_dag::{QueryDag, OperatorNode, OperatorType};
-use ruvector_dag::attention::{TopologicalAttention, DagAttention};
-
-// Build a query DAG
-let mut dag = QueryDag::new();
-let scan = dag.add_node(OperatorNode::hnsw_scan(0, "vectors_idx", 64));
-let filter = dag.add_node(OperatorNode::filter(1, "score > 0.5"));
-let result = dag.add_node(OperatorNode::new(2, OperatorType::Result));
-
-dag.add_edge(scan, filter).unwrap();
-dag.add_edge(filter, result).unwrap();
-
-// Compute attention scores
-let attention = TopologicalAttention::new(Default::default());
-let scores = attention.forward(&dag).unwrap();
-```
-
-**Node.js:**
-```javascript
-import { QueryDag, TopologicalAttention } from '@ruvector/rudag';
-
-// Build DAG
-const dag = new QueryDag();
-const scan = dag.addNode({ type: 'hnsw_scan', table: 'vectors', k: 64 });
-const filter = dag.addNode({ type: 'filter', condition: 'score > 0.5' });
-dag.addEdge(scan, filter);
-
-// Apply attention
-const attention = new TopologicalAttention();
-const scores = attention.forward(dag);
-console.log('Attention scores:', scores);
-```
-
-**Browser (WASM - 58KB):**
-```html
-
-```
-
-### SONA Learning Integration
-
-SONA (Self-Optimizing Neural Architecture) runs post-query in background, never blocking execution:
-
-```rust
-use ruvector_dag::sona::{DagSonaEngine, SonaConfig};
-
-let config = SonaConfig {
- embedding_dim: 256,
- lora_rank: 2, // Rank-2 for <100ฮผs updates
- ewc_lambda: 5000.0, // Catastrophic forgetting prevention
- trajectory_capacity: 10_000,
-};
-let mut sona = DagSonaEngine::new(config);
-
-// Pre-query: Get enhanced embedding (fast path)
-let enhanced = sona.pre_query(&dag);
-
-// Execute query...
-let execution_time = execute_query(&dag);
-
-// Post-query: Record trajectory (async, background)
-sona.post_query(&dag, execution_time, baseline_time, "topological");
-```
-
-### Self-Healing
-
-Reactive (Z-score anomaly detection) + Predictive (rising MinCut tension triggers early intervention):
-
-```rust
-use ruvector_dag::healing::{HealingOrchestrator, AnomalyConfig, PredictiveConfig};
-
-let mut orchestrator = HealingOrchestrator::new();
-
-// Reactive: Z-score anomaly detection
-orchestrator.add_detector("query_latency", AnomalyConfig {
- z_threshold: 3.0,
- window_size: 100,
- min_samples: 10,
-});
-
-// Predictive: Rising cut tension triggers early intervention
-orchestrator.enable_predictive(PredictiveConfig {
- tension_threshold: 0.6, // Intervene before 0.7 crisis
- variance_threshold: 1.5, // Rising variance = trouble coming
- lookahead_window: 50, // Predict 50 queries ahead
-});
-```
-
-### Query Convergence Example
-
-A slow query converges over several runs:
-
-```text
-[run 1] query: SELECT * FROM vectors WHERE embedding <-> $1 < 0.5
- attention: topological (default)
- mincut_tension: 0.23
- latency: 847ms (improvement: 0.4%)
-
-[run 4] mincut_tension: 0.71 > 0.7 (THRESHOLD)
- --> switching attention: topological -> mincut_gated
- latency: 412ms (improvement: 51.5%)
-
-[run 10] attention: mincut_gated
- mincut_tension: 0.22 (stable)
- latency: 156ms (improvement: 81.6%)
-```
-
-### Performance Targets
-
-| Component | Target | Notes |
-|-----------|--------|-------|
-| Attention (100 nodes) | <100ฮผs | All 7 mechanisms |
-| MicroLoRA adaptation | <100ฮผs | Rank-2, per-operator |
-| Pattern search (10K) | <2ms | K-means++ indexing |
-| MinCut update | O(n^0.12) | Subpolynomial amortized |
-| Anomaly detection | <50ฮผs | Z-score, streaming |
-| WASM size | 58KB | Gzipped, browser-ready |
-
-### Installation
-
-```bash
-# Rust
-cargo add ruvector-dag
-
-# Node.js
-npm install @ruvector/rudag
-
-# WASM (browser)
-npm install @ruvector/rudag-wasm
-```
-
-> **Full Documentation**: [ruvector-dag README](./crates/ruvector-dag/README.md)
-
-
-
-
-๐ฆ rvLite - Standalone Edge Database
-
-[](https://crates.io/crates/rvlite)
-[](https://www.npmjs.com/package/@ruvector/rvlite)
-[](https://www.npmjs.com/package/@ruvector/rvlite)
-
-**A complete vector database that runs anywhere JavaScript runs** โ browsers, Node.js, Deno, Bun, Cloudflare Workers, Vercel Edge Functions.
-
-### What is rvLite?
-
-rvLite is a **lightweight, standalone vector database** that runs entirely in WebAssembly. It provides SQL, SPARQL, and Cypher query interfaces, along with graph neural networks and self-learning capabilitiesโall in under 3MB.
-
-### Key Features
-
-| Feature | What It Does | Why It Matters |
-|---------|--------------|----------------|
-| **SQL Interface** | Familiar `SELECT`, `INSERT`, `WHERE` | No learning curve |
-| **SPARQL Support** | W3C-compliant RDF queries | Knowledge graphs in browser |
-| **Cypher Queries** | Neo4j-style graph queries | Graph traversals anywhere |
-| **GNN Embeddings** | Graph neural network layers | Self-learning search |
-| **ReasoningBank** | Trajectory learning | Gets smarter over time |
-| **SIMD Optimized** | Vector operations accelerated | Native-like performance |
-
-### Runs Everywhere
-
-| Platform | Status | Use Case |
-|----------|--------|----------|
-| **Browsers** | โ
| Offline-first apps |
-| **Node.js** | โ
| Server-side |
-| **Deno** | โ
| Edge functions |
-| **Bun** | โ
| Fast runtime |
-| **Cloudflare Workers** | โ
| Edge computing |
-| **Vercel Edge** | โ
| Serverless |
-
-### Architecture
-
-```
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ RvLite (Orchestration) โ
-โ โโ SQL executor โ
-โ โโ SPARQL executor โ
-โ โโ Cypher executor โ
-โ โโ Unified WASM API โ
-โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- โ depends on (100% reuse)
- โผ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ Existing WASM Crates โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
-โ โข ruvector-core (vectors, SIMD) โ
-โ โข ruvector-graph-wasm (Cypher) โ
-โ โข ruvector-gnn-wasm (GNN layers) โ
-โ โข sona (ReasoningBank learning) โ
-โ โข micro-hnsw-wasm (ultra-fast HNSW) โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-```
-
-### Quick Start
-
-```typescript
-import { RvLite } from '@ruvector/rvlite';
-
-// Create database
-const db = await RvLite.create();
-
-// SQL with vector search
-await db.sql(`
- CREATE TABLE docs (
- id SERIAL PRIMARY KEY,
- content TEXT,
- embedding VECTOR(384)
- )
-`);
-
-await db.sql(`
- SELECT id, content, embedding <=> $1 AS distance
- FROM docs
- ORDER BY distance
- LIMIT 10
-`, [queryVector]);
-
-// Cypher graph queries
-await db.cypher(`
- CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})
-`);
-
-// SPARQL RDF queries
-await db.sparql(`
- SELECT ?name WHERE {
- ?person foaf:name ?name .
- }
-`);
-
-// GNN embeddings
-const embeddings = await db.gnn.computeEmbeddings('social_network', [
- db.gnn.createLayer('gcn', { inputDim: 128, outputDim: 64 })
-]);
-
-// Self-learning with ReasoningBank
-await db.learning.recordTrajectory({ state: [0.1], action: 2, reward: 1.0 });
-await db.learning.train({ algorithm: 'q-learning', iterations: 1000 });
-```
-
-### Size Budget
-
-| Component | Size | Purpose |
-|-----------|------|---------|
-| ruvector-core | ~500KB | Vectors, SIMD |
-| SQL parser | ~200KB | Query parsing |
-| SPARQL executor | ~300KB | RDF queries |
-| Cypher (graph-wasm) | ~600KB | Graph queries |
-| GNN layers | ~300KB | Neural networks |
-| ReasoningBank (sona) | ~300KB | Self-learning |
-| **Total** | **~2.3MB** | Gzipped |
-
-### Installation
-
-```bash
-# npm
-npm install @ruvector/rvlite
-
-# Rust
-cargo add rvlite
-
-# Build WASM
-wasm-pack build --target web --release
-```
-
-> **Full Documentation**: [rvlite README](./crates/rvlite/README.md)
-
-
-
-
-๐ Edge-Net - Collective AI Computing Network
-
-[](https://www.npmjs.com/package/@ruvector/edge-net)
-
-**Share, Contribute, Compute Together** โ A distributed computing platform that enables collective resource sharing for AI workloads.
-
-### What is Edge-Net?
-
-Edge-Net creates a **collective computing network** where participants share idle browser resources to power distributed AI workloads:
-
-```
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ EDGE-NET: COLLECTIVE AI COMPUTING NETWORK โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
-โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โ
-โ โ Your โ โ Collective โ โ AI Tasks โ โ
-โ โ Browser โโโโโโโโบโ Network โโโโโโโโบโ Completed โ โ
-โ โ (Idle CPU) โ P2P โ (1000s) โ โ for You โ โ
-โ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโ โ
-โ โ โ โ โ
-โ Contribute โโโโโโโบ Earn rUv Units โโโโโโโบ Use for AI Workloads โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-```
-
-### How It Works
-
-| Step | What Happens | Result |
-|------|--------------|--------|
-| 1. **Contribute** | Share unused CPU cycles when browsing | Help the network |
-| 2. **Earn** | Accumulate rUv (Resource Utility Vouchers) | Build credits |
-| 3. **Use** | Spend rUv to run AI tasks | Access collective power |
-| 4. **Network Grows** | More participants = more power | Everyone benefits |
-
-### Why Collective AI Computing?
-
-| Traditional AI | Collective Edge-Net |
-|----------------|---------------------|
-| Expensive GPU servers | Free idle browser CPUs |
-| Centralized data centers | Distributed global network |
-| Pay-per-use pricing | Contribution-based access |
-| Single point of failure | Resilient P2P mesh |
-| Limited by your hardware | Scale with the collective |
-
-### AI Intelligence Stack
-
-```
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-โ AI INTELLIGENCE STACK โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
-โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
-โ โ MicroLoRA Adapter Pool (from ruvLLM) โ โ
-โ โ โข LRU-managed pool (16 slots) โข <50ยตs rank-1 forward โ โ
-โ โ โข 4-bit/8-bit quantization โข 2,236+ ops/sec โ โ
-โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
-โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
-โ โ SONA - Self-Optimizing Neural Architecture โ โ
-โ โ โข Instant Loop: Per-request MicroLoRA adaptation โ โ
-โ โ โข Background Loop: Hourly K-means consolidation โ โ
-โ โ โข Deep Loop: Weekly EWC++ (prevents catastrophic forgetting) โ โ
-โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
-โ โโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โ
-โ โ HNSW Vector Index โ โ Federated Learning โ โ ReasoningBank โ โ
-โ โ โข 150x faster โ โ โข Byzantine tolerantโ โ โข Pattern learn โ โ
-โ โ โข O(log N) search โ โ โข Diff privacy โ โ โข 87x energy โ โ
-โ โโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ โ
-โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
-```
-
-### Core AI Tasks
-
-| Task Type | Use Case | Performance |
-|-----------|----------|-------------|
-| **Vector Search** | Find similar items | 150x speedup via HNSW |
-| **Embeddings** | Text understanding | Semantic vectors |
-| **Semantic Match** | Intent detection | Classify meaning |
-| **LoRA Inference** | Task adaptation | <100ยตs forward |
-| **Pattern Learning** | Self-optimization | ReasoningBank trajectories |
-
-### Pi-Key Identity System
-
-Ultra-compact cryptographic identity using mathematical constants:
-
-| Key Type | Size | Purpose |
-|----------|------|---------|
-| **ฯ (Pi-Key)** | 40 bytes | Permanent identity |
-| **e (Session)** | 34 bytes | Encrypted sessions |
-| **ฯ (Genesis)** | 21 bytes | Network origin markers |
-
-### Self-Optimizing Features
-
-| Feature | Mechanism | Benefit |
-|---------|-----------|---------|
-| **Task Routing** | Multi-head attention | Work goes to best nodes |
-| **Topology Optimization** | Self-organizing mesh | Network adapts to load |
-| **Q-Learning Security** | Reinforcement learning | Learns to defend threats |
-| **Economic Balance** | rUv token system | Self-sustaining economy |
-
-### Quick Start
-
-**Add to Your Website:**
-```html
-
-```
-
-**Use the Collective's AI Power:**
-```javascript
-// Submit an AI task to the collective
-const result = await node.submitTask('vector_search', {
- query: embeddings,
- k: 10,
- index: 'shared-knowledge-base'
-}, 5); // Spend up to 5 rUv
-
-console.log('Similar items:', result);
-```
-
-**Monitor Your Contribution:**
-```javascript
-const stats = node.getStats();
-console.log(`
- rUv Earned: ${stats.ruv_earned}
- rUv Spent: ${stats.ruv_spent}
- Tasks Completed: ${stats.tasks_completed}
- Reputation: ${(stats.reputation * 100).toFixed(1)}%
-`);
-```
-
-### Key Features
-
-| Feature | Benefit |
-|---------|---------|
-| **Idle CPU Utilization** | Use resources that would otherwise be wasted |
-| **Browser-Based** | No installation, runs in any modern browser |
-| **Adjustable Contribution** | Control how much you share (10-50% CPU) |
-| **Battery Aware** | Automatically reduces on battery power |
-| **Fair Distribution** | Work routed based on capability matching |
-| **Privacy-First** | Pi-Key cryptographic identity |
-| **Federated Learning** | Learn collectively without sharing data |
-| **Byzantine Tolerance** | Resilient to malicious nodes |
-
-### Installation
-
-```bash
-# npm
-npm install @ruvector/edge-net
-
-# Or include directly
-
-```
-
-> **Full Documentation**: [edge-net README](./examples/edge-net/README.md)
-
-
-
----
-
-## AI & Machine Learning
-
-
-๐ฒ Agentic-Synth - AI Synthetic Data Generation
-
-[](https://www.npmjs.com/package/@ruvector/agentic-synth)
-[](https://www.npmjs.com/package/@ruvector/agentic-synth)
-
-**AI-Powered Synthetic Data Generation at Scale** โ Generate unlimited, high-quality synthetic data for training AI models, testing systems, and building robust agentic applications.
-
-### Why Agentic-Synth?
-
-| Problem | Solution |
-|---------|----------|
-| Real data is **expensive** to collect | Generate **unlimited** synthetic data |
-| **Privacy-sensitive** with compliance risks | **Fully synthetic**, no PII concerns |
-| **Slow** to generate at scale | **10-100x faster** than manual creation |
-| **Insufficient** for edge cases | **Customizable** schemas for any scenario |
-| **Hard to reproduce** across environments | **Reproducible** with seed values |
-
-### Key Features
-
-| Feature | Description |
-|---------|-------------|
-| **Multi-Model Support** | Gemini, OpenRouter, GPT, Claude, and 50+ models via DSPy.ts |
-| **Context Caching** | 95%+ performance improvement with intelligent LRU cache |
-| **Smart Model Routing** | Automatic load balancing, failover, and cost optimization |
-| **DSPy.ts Integration** | Self-learning optimization with 20-25% quality improvement |
-| **Streaming** | AsyncGenerator for real-time data flow |
-| **Memory Efficient** | <50MB for datasets up to 10K records |
-
-### Data Generation Types
-
-| Type | Use Cases |
-|------|-----------|
-| **Time-Series** | Financial data, IoT sensors, metrics |
-| **Events** | Logs, user actions, system events |
-| **Structured** | JSON, CSV, databases, APIs |
-| **Embeddings** | Vector data for RAG systems |
-
-### Quick Start
-
-```bash
-# Install
-npm install @ruvector/agentic-synth
-
-# Or run instantly with npx
-npx @ruvector/agentic-synth generate --count 100
-
-# Interactive mode
-npx @ruvector/agentic-synth interactive
-```
-
-### Basic Usage
-
-```typescript
-import { AgenticSynth } from '@ruvector/agentic-synth';
-
-// Initialize with your preferred model
-const synth = new AgenticSynth({
- model: 'gemini-pro',
- apiKey: process.env.GEMINI_API_KEY
-});
-
-// Generate structured data
-const users = await synth.generate({
- schema: {
- name: 'string',
- email: 'email',
- age: 'number:18-65',
- role: ['admin', 'user', 'guest']
- },
- count: 1000
-});
-
-// Generate time-series data
-const stockData = await synth.timeSeries({
- fields: ['open', 'high', 'low', 'close', 'volume'],
- interval: '1h',
- count: 500,
- volatility: 0.02
-});
-
-// Stream large datasets
-for await (const batch of synth.stream({ count: 100000, batchSize: 1000 })) {
- await processData(batch);
-}
-```
-
-### Self-Learning with DSPy
-
-```typescript
-import { AgenticSynth, DSPyOptimizer } from '@ruvector/agentic-synth';
-
-// Enable self-learning optimization
-const synth = new AgenticSynth({
- model: 'gemini-pro',
- optimizer: new DSPyOptimizer({
- learningRate: 0.1,
- qualityThreshold: 0.85
- })
-});
-
-// Quality improves automatically over time
-const data = await synth.generate({
- schema: { ... },
- count: 1000,
- optimize: true // Enable learning
-});
-
-console.log(`Quality score: ${data.metrics.quality}`);
-// First run: 0.72
-// After 100 runs: 0.94 (+25% improvement)
-```
-
-### Performance
-
-| Metric | Value |
-|--------|-------|
-| **With caching** | 98.2% faster |
-| **P99 latency** | 2500ms โ 45ms |
-| **Memory** | <50MB for 10K records |
-| **Throughput** | 1000+ records/sec |
-
-### Ecosystem Integration
-
-| Package | Purpose |
-|---------|---------|
-| **RuVector** | Native vector database for RAG |
-| **DSPy.ts** | Prompt optimization |
-| **Agentic-Jujutsu** | Version-controlled generation |
-
-### Installation
-
-```bash
-# npm
-npm install @ruvector/agentic-synth
-
-# Examples package (50+ production examples)
-npm install @ruvector/agentic-synth-examples
-```
-
-> **Full Documentation**: [agentic-synth README](./npm/packages/agentic-synth/README.md)
-
-
-
-
-๐ Neural Trader - AI Trading System
-
-[](https://www.npmjs.com/package/neural-trader)
-[](https://www.npmjs.com/package/neural-trader)
-
-**Production-ready neural trading system** combining state-of-the-art ML for automated trading, sports betting, and portfolio management. Zero external ML dependencies, sub-millisecond latency.
-
-### Core AI/ML Engines
-
-| Engine | Description | Performance |
-|--------|-------------|-------------|
-| **Fractional Kelly** | Optimal position sizing with risk-adjusted bet scaling | 588,885 ops/s |
-| **LSTM-Transformer** | Deep learning price prediction (temporal + attention) | 1,468 seq/s |
-| **DRL Portfolio** | Reinforcement learning ensemble (PPO/SAC/A2C) | 17,043 steps/s |
-| **Sentiment Alpha** | Real-time sentiment analysis for alpha generation | 3,764 pipeline/s |
-
-### Why Neural Trader?
-
-| Traditional ML | Neural Trader |
-|----------------|---------------|
-| TensorFlow/PyTorch required | **Zero dependencies** |
-| 1.2MB+ bundle size | **45KB** bundle |
-| 2.1ms LSTM inference | **0.68ms** inference |
-| Complex deployment | **Works in browser & Node.js** |
-
-### Research-Backed Algorithms
-
-| Algorithm | Research Finding |
-|-----------|------------------|
-| **Kelly Criterion** | 1/5th fractional achieves 98% ROI with 85% less risk of ruin |
-| **LSTM-Transformer** | Temporal + attention fusion outperforms single architectures |
-| **DRL Ensemble** | PPO/SAC/A2C voting reduces variance vs single agent |
-| **Sentiment Alpha** | 3% annual excess returns documented in academia |
-
-### Quick Start
-
-```javascript
-import { KellyCriterion, HybridLSTMTransformer, DRLPortfolioManager } from 'neural-trader';
-
-// Kelly position sizing
-const kelly = new KellyCriterion();
-const stake = kelly.calculateStake(9000, 0.55, 2.0, 0.2); // 1/5th Kelly
-// โ $180 recommended stake (2% of bankroll)
-
-// LSTM-Transformer prediction
-const model = new HybridLSTMTransformer({
- lstm: { hiddenSize: 64, layers: 2 },
- transformer: { heads: 4, layers: 2 }
-});
-const prediction = model.predict(candles);
-// โ { signal: 'BUY', confidence: 0.73, direction: 'bullish' }
-
-// DRL portfolio allocation
-const manager = new DRLPortfolioManager({ numAssets: 10 });
-await manager.train(marketData, { episodes: 100 });
-const allocation = manager.getAction(currentState);
-// โ [0.15, 0.12, 0.08, ...] optimal weights
-```
-
-### Use Cases
-
-| Use Case | Example |
-|----------|---------|
-| **Stock Trading** | DAG-based pipeline with parallel execution |
-| **Sports Betting** | Kelly sizing with ML calibration |
-| **Crypto Trading** | DRL portfolio for 20+ assets |
-| **News Trading** | Real-time sentiment stream processing |
-| **Portfolio Rebalancing** | Reinforcement learning allocation |
-
-### Package Ecosystem (20+)
-
-| Package | Description |
-|---------|-------------|
-| `neural-trader` | Core engine with native HNSW, SIMD |
-| `@neural-trader/core` | Ultra-low latency Rust + Node.js bindings |
-| `@neural-trader/strategies` | Strategy management and backtesting |
-| `@neural-trader/execution` | Trade execution and order management |
-| `@neural-trader/mcp` | MCP server with 87+ trading tools |
-| `@neural-trader/risk` | VaR, stress testing, risk metrics |
-| `@neural-trader/portfolio` | Markowitz, Risk Parity optimization |
-| `@neural-trader/neural` | Neural network training |
-| `@neural-trader/brokers` | Alpaca, Interactive Brokers |
-| `@neural-trader/sports-betting` | Arbitrage, Kelly, odds analysis |
-
-### CLI Interface
-
-```bash
-# Real-time trading
-node cli.js run --strategy=hybrid --symbol=AAPL --capital=100000
-
-# Backtest historical performance
-node cli.js backtest --days=252 --capital=50000 --strategy=drl
-
-# Paper trading simulation
-node cli.js paper --capital=100000 --strategy=sentiment
-
-# Performance benchmarks
-node cli.js benchmark --iterations=100
-```
-
-### Exotic Examples
-
-| Example | Description |
-|---------|-------------|
-| **Multi-Agent Swarm** | Distributed trading intelligence with consensus |
-| **GNN Correlation Network** | Graph neural network correlation analysis |
-| **Attention Regime Detection** | Transformer-based market regime classification |
-| **Quantum Portfolio** | QAOA & quantum annealing optimization |
-| **Hyperbolic Embeddings** | Poincarรฉ disk market embeddings |
-| **Atomic Arbitrage** | Cross-exchange with MEV protection |
-
-### Performance
-
-| Module | Latency | Throughput | Status |
-|--------|---------|------------|--------|
-| Kelly Engine | 0.014ms | 71,295/s | โ Ready |
-| LSTM-Transformer | 0.681ms | 1,468/s | โ Ready |
-| DRL Portfolio | 0.059ms | 17,043/s | โ Ready |
-| Sentiment Alpha | 0.266ms | 3,764/s | โ Ready |
-| Full Pipeline | 4.68ms | 214/s | โ Ready |
-
-### Installation
-
-```bash
-# npm
-npm install neural-trader
-
-# Full ecosystem
-npm install @neural-trader/core @neural-trader/strategies @neural-trader/mcp
-```
-
-> **Full Documentation**: [neural-trader README](./examples/neural-trader/README.md)
-
-
-
-
-๐ฅ Agentic-Jujutsu - Quantum-Resistant Version Control
-
-[](https://www.npmjs.com/package/agentic-jujutsu)
-[](https://opensource.org/licenses/MIT)
-
-### What is Agentic-Jujutsu?
-
-Agentic-Jujutsu is a **quantum-resistant, self-learning version control system** designed for AI agents. It combines lock-free concurrent operations with ReasoningBank trajectory learning for continuous improvement.
-
-| Traditional Git | Agentic-Jujutsu |
-|----------------|-----------------|
-| Lock-based commits | Lock-free (23x faster) |
-| Manual conflict resolution | 87% automatic resolution |
-| Static operations | Self-learning from patterns |
-| No quantum protection | SHA3-512 + HQC-128 |
-| Sequential agents | Concurrent multi-agent |
-
-### Key Features
-
-| Feature | Performance | Description |
-|---------|-------------|-------------|
-| **Concurrent Commits** | 350 ops/s | 23x faster than Git (15 ops/s) |
-| **Context Switching** | <100ms | 10x faster than Git (500-1000ms) |
-| **Conflict Resolution** | 87% auto | AI-powered pattern matching |
-| **Quantum Security** | <1ms verify | SHA3-512 fingerprints, HQC-128 encryption |
-| **ReasoningBank** | Continuous | Trajectory learning with verdicts |
-
-### Quick Start
-
-```bash
-# Install
-npm install agentic-jujutsu
-
-# Basic usage
-npx agentic-jujutsu
-```
-
-```typescript
-import { JjWrapper } from 'agentic-jujutsu';
-
-const jj = new JjWrapper();
-
-// Start learning trajectory
-jj.startTrajectory('Implement feature X');
-
-// Make changes and commit
-await jj.newCommit('Add authentication module');
-jj.addToTrajectory();
-
-// Finalize with success score
-jj.finalizeTrajectory(0.9, 'Feature implemented successfully');
-
-// Get AI-powered suggestions
-const suggestions = await jj.getSuggestions();
-```
-
-### Multi-Agent Coordination
-
-```typescript
-// Concurrent commits without locks
-const agents = ['agent-1', 'agent-2', 'agent-3'];
-await Promise.all(agents.map(agent =>
- jj.newCommit(`Changes from ${agent}`)
-));
-// All commits succeed - no lock waiting!
-```
-
-> **Full Documentation**: [agentic-jujutsu README](./examples/agentic-jujutsu/README.md)
-
-
-
-
-๐ฌ SciPix - Scientific Document OCR
-
-[](https://crates.io/crates/ruvector-scipix)
-[](https://docs.rs/ruvector-scipix)
-[](https://opensource.org/licenses/MIT)
-
-### What is SciPix?
-
-SciPix is a **blazing-fast, memory-safe OCR engine** written in pure Rust, purpose-built for scientific documents, mathematical equations, and technical diagrams.
-
-| Feature | SciPix | Tesseract | Mathpix |
-|---------|--------|-----------|---------|
-| Simple Text OCR | **50ms** | 120ms | 200ms* |
-| Math Equation | **80ms** | N/A | 150ms* |
-| Batch (100 images) | **2.1s** | 8.5s | N/A |
-| Memory Usage | **45MB** | 180MB | Cloud |
-| LaTeX Output | Yes | No | Yes |
-
-*API latency, not processing time
-
-### Key Features
-
-| Feature | Description |
-|---------|-------------|
-| **ONNX Runtime** | GPU-accelerated with CUDA, TensorRT, CoreML |
-| **LaTeX Output** | Mathematical equation recognition with LaTeX, MathML, AsciiMath |
-| **SIMD Optimized** | 4x faster image preprocessing with AVX2, SSE4, NEON |
-| **REST API** | Production-ready HTTP server with rate limiting |
-| **MCP Server** | Integrate with Claude, ChatGPT via Model Context Protocol |
-| **WebAssembly** | Run OCR directly in browsers |
-
-### Quick Start
-
-```bash
-# Add to Cargo.toml
-cargo add ruvector-scipix
-
-# With features
-ruvector-scipix = { version = "0.1.16", features = ["ocr", "math", "optimize"] }
-```
-
-```rust
-use ruvector_scipix::{SciPixOcr, OcrConfig};
-
-// Initialize OCR engine
-let ocr = SciPixOcr::new(OcrConfig::default())?;
-
-// Process scientific image
-let result = ocr.process_image("equation.png")?;
-println!("LaTeX: {}", result.latex);
-println!("Confidence: {:.2}%", result.confidence * 100.0);
-```
-
-### Use Cases
-
-- **Academic Paper Digitization** - Extract text and equations from scanned research papers
-- **Math Homework Assistance** - Convert handwritten equations to LaTeX for AI tutoring
-- **Technical Documentation** - Process engineering diagrams and scientific charts
-- **AI/LLM Integration** - Feed scientific content to language models via MCP
-
-> **Full Documentation**: [scipix README](./examples/scipix/README.md)
-
-
-
-
-๐ง Meta-Cognition SNN - Spiking Neural Networks
-
-### What is Meta-Cognition SNN?
-
-A hybrid AI architecture combining **Spiking Neural Networks (SNN)**, **SIMD-optimized vector operations**, and **5 attention mechanisms** with meta-cognitive self-discovery capabilities.
-
-| Capability | Performance | Description |
-|------------|-------------|-------------|
-| **Spiking Neural Networks** | 10-50x faster | LIF neurons + STDP learning with N-API SIMD |
-| **SIMD Vector Operations** | 5-54x faster | Loop-unrolled distance/dot product calculations |
-| **5 Attention Mechanisms** | Sub-millisecond | Multi-Head, Flash, Linear, Hyperbolic, MoE |
-| **Vector Search** | 150x faster | RuVector-powered semantic search |
-| **Meta-Cognition** | Autonomous | Self-discovering emergent capabilities |
-
-### SIMD Performance
-
-| Operation | Speedup | Notes |
-|-----------|---------|-------|
-| LIF Updates | **16.7x** | Leaky integrate-and-fire neurons |
-| Synaptic Forward | **14.9x** | Forward propagation |
-| STDP Learning | **26.3x** | Spike-timing dependent plasticity |
-| Distance (128d) | **54x** | Euclidean distance calculation |
-| Full Simulation | **18.4x** | End-to-end SNN simulation |
-
-### 5 Attention Mechanisms
-
-| Mechanism | Best For | Latency |
-|-----------|----------|---------|
-| **Flash** | Long sequences | 0.023ms |
-| **MoE** | Specialized domains | 0.021ms |
-| **Multi-Head** | Complex patterns | 0.047ms |
-| **Linear** | Real-time processing | 0.075ms |
-| **Hyperbolic** | Hierarchical data | 0.222ms |
-
-### Quick Start
-
-```bash
-# Install and run demos
-cd examples/meta-cognition-spiking-neural-network
-npm install
-node demos/run-all.js
-```
-
-```javascript
-const { createFeedforwardSNN, rateEncoding } = require('./demos/snn/lib/SpikingNeuralNetwork');
-
-// Create SNN with SIMD optimization
-const snn = createFeedforwardSNN([100, 50, 10], {
- dt: 1.0,
- tau: 20.0,
- a_plus: 0.005,
- lateral_inhibition: true
-});
-
-// Train with STDP
-const input = rateEncoding(pattern, snn.dt, 100);
-snn.step(input);
-```
-
-### 6 Emergent Discoveries
-
-1. Multi-Scale Attention Hierarchy (Novelty: 5/5)
-2. Spike Synchronization Patterns
-3. Attention-Gated Spike Propagation
-4. Temporal Coherence Emergence
-5. Emergent Sparsity (80% fewer active neurons)
-6. Meta-Plasticity (faster learning on later tasks)
-
-> **Full Documentation**: [meta-cognition-snn README](./examples/meta-cognition-spiking-neural-network/README.md)
-
-
-
-
-๐ค RuvLLM - Self-Learning LLM Orchestration
-
-[](https://www.rust-lang.org/)
-[](LICENSE)
-[](#)
-
-### What is RuvLLM?
-
-RuvLLM is a **self-learning language model orchestration system** that combines frozen foundation models with adaptive memory and intelligent routing. Unlike traditional LLMs that rely solely on static parameters, RuvLLM continuously improves from every interaction.
-
-> *"The intelligence is not in one model anymore. It is in the loop."*
-
-### SONA: 3-Tier Temporal Learning
-
-| Loop | Frequency | Latency | Description |
-|------|-----------|---------|-------------|
-| **A: Instant** | Per-request | <100ฮผs | MicroLoRA adaptation (rank 1-2) |
-| **B: Background** | Hourly | ~1.3ms | K-means++ clustering, base LoRA (rank 4-16) |
-| **C: Deep** | Weekly | N/A | EWC++ consolidation, concept hierarchies |
-
-### Core Components
-
-| Component | Description |
-|-----------|-------------|
-| **LFM2 Cortex** | Frozen reasoning engine (135M-2.6B params) |
-| **Ruvector Memory** | Adaptive synaptic mesh with HNSW indexing |
-| **FastGRNN Router** | Intelligent model selection circuit |
-| **Graph Attention** | 8-head attention with edge features |
-| **SONA Engine** | LoRA + EWC++ + ReasoningBank |
-
-### Performance (CPU-Only)
-
-| Metric | Value |
-|--------|-------|
-| **Initialization** | 3.71ms |
-| **Average Query** | 0.09ms |
-| **Session Query** | 0.04ms |
-| **Throughput** | ~38,000 q/s |
-| **Memory** | ~50MB |
-
-### Quick Start
-
-```rust
-use ruvllm::{RuvLLMOrchestrator, OrchestratorConfig};
-
-// Initialize orchestrator
-let config = OrchestratorConfig::default();
-let orchestrator = RuvLLMOrchestrator::new(config)?;
-
-// Query with automatic learning
-let response = orchestrator.query("Explain quantum entanglement").await?;
-println!("{}", response.text);
-
-// Response improves over time as SONA learns patterns
-```
-
-### Federated Learning
-
-```rust
-// Ephemeral agents collect trajectories
-let agent = EphemeralAgent::new("task-specific-agent");
-agent.process_task(&task).await?;
-let export = agent.export();
-
-// Central coordinator aggregates learning
-coordinator.accept_export(export)?;
-coordinator.consolidate(); // Share patterns with new agents
-```
-
-### Dynamic Embedding Fine-Tuning
-
-RuvLLM's adaptive learning system enables real-time model improvement without retraining.
-
-| Feature | Description | Latency |
-|---------|-------------|---------|
-| **MicroLoRA** | Per-request adaptation (rank 1-2), <50KB adapters | <1ms |
-| **Contrastive Training** | Triplet loss with hard negatives for embedding optimization | Batch |
-| **Task-Specific Adapters** | Pre-tuned for Coder, Researcher, Security, Architect, Reviewer | Hot-swap |
-| **EWC++ Consolidation** | Prevents catastrophic forgetting during continuous learning | Background |
-| **Adapter Merging** | Average, Weighted, SLERP, TIES, DARE strategies | On-demand |
-
-```javascript
-// Contrastive fine-tuning for agent routing
-import { ContrastiveTrainer } from '@ruvector/ruvllm';
-
-const trainer = new ContrastiveTrainer({
- margin: 0.5,
- hardNegativeRatio: 0.7
-});
-
-// Learn: task โ correct agent, not wrong agent
-trainer.addTriplet(taskEmb, correctAgentEmb, wrongAgentEmb, true);
-const model = trainer.train();
-```
-
-```rust
-// Task-specific adapter hot-swapping
-use ruvllm::lora::RuvLtraAdapters;
-
-let adapters = RuvLtraAdapters::new();
-let coder = adapters.create_lora("coder", 768)?; // Rank 16, code patterns
-let security = adapters.create_lora("security", 768)?; // Rank 16, vulnerability detection
-
-// Hot-swap at runtime without model reload
-orchestrator.set_adapter(coder);
-let code_response = orchestrator.query("Implement binary search").await?;
-
-orchestrator.set_adapter(security);
-let audit_response = orchestrator.query("Audit this code for vulnerabilities").await?;
-```
-
-### Advanced Features
-
-- **SIMD Inference**: AVX2/AVX512/SSE4.1 optimization
-- **Q4 Quantization**: 4-bit weights for memory efficiency
-- **HuggingFace Export**: Export LoRA weights and preference pairs
-- **Multi-Model Routing**: SmolLM, Qwen2, TinyLlama selection
-- **WASM Support**: Run SONA in browsers and edge devices
-- **Browser Fine-Tuning**: MicroLoRA WASM with localStorage persistence
-
-> **Full Documentation**: [ruvLLM README](./examples/ruvLLM/README.md) | [Fine-Tuning Guide](./docs/ruvllm/FINE_TUNING.md) | [Task Adapters](./docs/training/task_specific_lora_adapters.md)
-
-
-
-
-๐๏ธ REFRAG - Compress-Sense-Expand RAG
-
-### What is REFRAG?
-
-REFRAG implements the **Compress-Sense-Expand architecture** from [arXiv:2509.01092](https://arxiv.org/abs/2509.01092), achieving **~30x RAG latency reduction** by storing pre-computed representation tensors instead of raw text.
-
-### Architecture
-
-```
-โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโ
-โ COMPRESS โโโโโถโ SENSE โโโโโถโ EXPAND โ
-โ Layer โ โ Layer โ โ Layer โ
-โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโ
-
-Binary tensor Policy network Dimension projection
-storage with decides COMPRESS (768 โ 4096 dims)
-zero-copy access vs EXPAND
-```
-
-### Compression Strategies
-
-| Strategy | Compression | Use Case |
-|----------|-------------|----------|
-| `None` | 1x | Maximum precision |
-| `Float16` | 2x | Good balance |
-| `Int8` | 4x | Memory constrained |
-| `Binary` | 32x | Extreme compression |
-
-### Policy Networks
-
-| Policy | Latency | Description |
-|--------|---------|-------------|
-| `ThresholdPolicy` | ~2ฮผs | Cosine similarity threshold |
-| `LinearPolicy` | ~5ฮผs | Single layer classifier |
-| `MLPPolicy` | ~15ฮผs | Two-layer neural network |
-
-### Quick Start
-
-```bash
-# Run demo
-cargo run --bin refrag-demo
-
-# Run benchmarks
-cargo run --bin refrag-benchmark --release
-```
-
-```rust
-use refrag_pipeline_example::{RefragStore, RefragEntry};
-
-// Create REFRAG-enabled store
-let store = RefragStore::new(384, 768)?;
-
-// Insert with representation tensor
-let entry = RefragEntry::new("doc_1", search_vector, "The quick brown fox...")
- .with_tensor(tensor_bytes, "llama3-8b");
-store.insert(entry)?;
-
-// Hybrid search (policy-based COMPRESS/EXPAND)
-let results = store.search_hybrid(&query, 10, Some(0.85))?;
-
-for result in results {
- match result.response_type {
- RefragResponseType::Compress => {
- // Tensor directly injectable into LLM context
- println!("Tensor: {} dims", result.tensor_dims.unwrap());
- }
- RefragResponseType::Expand => {
- // Original text when full context needed
- println!("Text: {}", result.content.unwrap());
- }
- }
-}
-```
-
-### Target LLM Dimensions
-
-| Source | Target | LLM |
-|--------|--------|-----|
-| 768 | 4096 | LLaMA-3 8B |
-| 768 | 8192 | LLaMA-3 70B |
-| 1536 | 8192 | GPT-4 |
-
-> **Full Documentation**: [refrag-pipeline README](./examples/refrag-pipeline/README.md)
-
-
-
-
-๐ฆ 7sense - Bioacoustic Intelligence Platform
-
-[](https://www.rust-lang.org)
-[]()
-[]()
-
-### What is 7sense?
-
-7sense transforms **bird calls into navigable geometric space** using cutting-edge AI and vector search. It converts audio recordings of bird songs into rich, searchable embeddings using Perch 2.0 neural networks and ultra-fast HNSW indexing.
-
-| Traditional Monitoring | 7sense |
-|----------------------|--------|
-| Expert human listeners | Instant AI species ID |
-| Basic spectrogram analysis | Neural embeddings (1536-dim) |
-| Limited scale | Millions of recordings |
-| Manual pattern finding | Automated discovery |
-
-### Performance Targets
-
-| Metric | Target | Status |
-|--------|--------|--------|
-| HNSW Search Speedup | 150x vs brute force | Achieved |
-| Query Latency (p99) | < 50ms | Achieved |
-| Recall@10 | >= 0.95 | Achieved |
-| Embedding Throughput | > 100 segments/sec | Achieved |
-| Memory per 1M vectors | < 6 GB | Achieved |
-
-### 9 Rust Crates
-
-| Crate | Description |
-|-------|-------------|
-| `sevensense-core` | Species taxonomy, temporal types |
-| `sevensense-audio` | WAV/MP3/FLAC, Mel spectrograms |
-| `sevensense-embedding` | Perch 2.0 ONNX, 1536-dim vectors |
-| `sevensense-vector` | HNSW with 150x speedup |
-| `sevensense-learning` | GNN training, EWC regularization |
-| `sevensense-analysis` | HDBSCAN clustering, Markov models |
-| `sevensense-interpretation` | Evidence packs, species narratives |
-| `sevensense-api` | GraphQL, REST, WebSocket streaming |
-| `sevensense-benches` | Criterion.rs performance suites |
-
-### Quick Start
-
-```bash
-# Build and run
-cd examples/vibecast-7sense
-cargo build --release
-cargo run -p sevensense-api --release
-```
-
-```rust
-use sevensense_audio::AudioProcessor;
-use sevensense_embedding::EmbeddingPipeline;
-use sevensense_vector::HnswIndex;
-
-// Load and process audio
-let processor = AudioProcessor::new(Default::default());
-let segments = processor.process_file("recording.wav").await?;
-
-// Generate Perch 2.0 embeddings
-let pipeline = EmbeddingPipeline::new(Default::default()).await?;
-let embeddings = pipeline.embed_segments(&segments).await?;
-
-// Search for similar calls (150x faster)
-let index = HnswIndex::new(Default::default());
-index.add_batch(&embeddings)?;
-let neighbors = index.search(&embeddings[0], 10)?;
-
-println!("Found {} similar bird calls", neighbors.len());
-```
-
-### Use Cases
-
-- **Species Identification** - Instant predictions with confidence scores
-- **Pattern Discovery** - Find similar calls across millions of recordings
-- **Behavioral Insights** - Detect singing patterns, dialects, anomalies
-- **Conservation Monitoring** - Track biodiversity at scale
-
-> **Full Documentation**: [7sense README](./examples/vibecast-7sense/README.md)
-
-
-
-
-๐งฌ EXO-AI - Advanced Cognitive Substrate
-
-[](https://crates.io/crates/exo-core)
-[](https://docs.rs/exo-core)
-[](LICENSE)
-
-### What is EXO-AI?
-
-EXO-AI 2025 is a comprehensive **cognitive substrate** implementing cutting-edge theories from neuroscience, physics, and consciousness research. It provides 9 interconnected Rust crates totaling ~15,800+ lines of research-grade code.
-
-> Traditional AI systems process information. EXO-AI aims to understand it.
-
-### SIMD-Accelerated Performance
-
-| Operation | Speedup | Notes |
-|-----------|---------|-------|
-| Distance (128d) | **54x** | AVX2/NEON optimized |
-| Cosine Similarity | **2.73x** | Batch operations |
-| Pattern Matching | **8-54x** | Loop-unrolled |
-| Meta-Simulation | **13+ quadrillion/s** | From ultra-low-latency-sim |
-
-### 9 Rust Crates
-
-| Crate | Description |
-|-------|-------------|
-| `exo-core` | IIT consciousness (ฮฆ) measurement & Landauer thermodynamics |
-| `exo-temporal` | Temporal memory with causal tracking & consolidation |
-| `exo-hypergraph` | Topological analysis with persistent homology |
-| `exo-manifold` | SIREN networks + SIMD-accelerated retrieval |
-| `exo-exotic` | 10 cutting-edge cognitive experiments |
-| `exo-federation` | Post-quantum federated cognitive mesh |
-| `exo-backend-classical` | SIMD-accelerated compute backend |
-| `exo-wasm` | Browser & edge WASM deployment |
-| `exo-node` | Node.js bindings via NAPI-RS |
-
-### Key Theories Implemented
-
-| Theory | Implementation |
-|--------|---------------|
-| **IIT (Integrated Information Theory)** | Consciousness level (ฮฆ) measurement |
-| **Landauer's Principle** | Computational thermodynamics |
-| **Free Energy Principle** | Friston's predictive processing |
-| **Strange Loops** | Hofstadter's self-referential patterns |
-| **Morphogenesis** | Pattern formation emergence |
-
-### Quick Start
-
-```toml
-[dependencies]
-exo-core = "0.1"
-exo-temporal = "0.1"
-exo-exotic = "0.1"
-exo-manifold = "0.1" # SIMD acceleration!
-```
-
-```rust
-use exo_core::consciousness::{ConsciousnessSubstrate, IITConfig};
-use exo_core::thermodynamics::CognitiveThermometer;
-
-// Measure integrated information (ฮฆ)
-let substrate = ConsciousnessSubstrate::new(IITConfig::default());
-substrate.add_pattern(pattern);
-let phi = substrate.compute_phi();
-println!("Consciousness level (ฮฆ): {:.4}", phi);
-
-// Track computational thermodynamics
-let thermo = CognitiveThermometer::new(300.0); // Kelvin
-let cost = thermo.landauer_cost_bits(1024);
-println!("Landauer cost: {:.2e} J", cost);
-```
-
-### SIMD Pattern Retrieval
-
-```rust
-use exo_manifold::{ManifoldEngine, cosine_similarity_simd, batch_distances};
-
-// 54x faster similarity search
-let query = vec![0.5; 768];
-let results = engine.retrieve(&query, 10)?;
-
-// Batch distance computation
-let distances = batch_distances(&query, &database); // 8-54x speedup
-```
-
-> **Full Documentation**: [exo-ai README](./examples/exo-ai-2025/README.md)
-
-
-
----
-
-## Database Extensions
-
-
-๐ PostgreSQL Extension
-
-[](https://crates.io/crates/ruvector-postgres)
-[](https://www.npmjs.com/package/@ruvector/postgres-cli)
-[](https://hub.docker.com/r/ruvnet/ruvector-postgres)
-[](https://hub.docker.com/r/ruvnet/ruvector-postgres)
-
-**The most advanced PostgreSQL vector extension** โ a drop-in pgvector replacement with 230+ SQL functions, hardware-accelerated SIMD operations, and built-in AI capabilities. Transform your existing PostgreSQL database into a full-featured vector search engine with GNN layers, attention mechanisms, and self-learning capabilities.
-
-```bash
-# Quick Install from Docker Hub
-docker run -d --name ruvector \
- -e POSTGRES_PASSWORD=secret \
- -p 5432:5432 \
- ruvnet/ruvector-postgres:latest
-
-# Connect and use
-psql -h localhost -U ruvector -d ruvector_test
-
-# Create extension
-CREATE EXTENSION ruvector;
-```
-
-**Why RuVector Postgres?**
-- **Zero Migration** โ Works with existing pgvector code, just swap the extension
-- **10x More Functions** โ 230+ SQL functions vs pgvector's ~20
-- **2x Faster** โ AVX-512/AVX2/NEON SIMD acceleration
-- **AI-Native** โ GNN layers, 39 attention mechanisms, local embeddings
-- **Self-Learning** โ Improves search quality over time with ReasoningBank
-
-| Feature | pgvector | RuVector Postgres |
-|---------|----------|-------------------|
-| SQL Functions | ~20 | **230+** |
-| SIMD Acceleration | Basic | AVX-512/AVX2/NEON (~2x faster) |
-| Index Types | HNSW, IVFFlat | HNSW, IVFFlat + Hyperbolic |
-| Attention Mechanisms | โ | 39 types (Flash, Linear, Graph) |
-| GNN Layers | โ | GCN, GraphSAGE, GAT, GIN |
-| Sparse Vectors | โ | BM25, TF-IDF, SPLADE |
-| Self-Learning | โ | ReasoningBank, trajectory learning |
-| Local Embeddings | โ | 6 fastembed models built-in |
-| Multi-Tenancy | โ | Built-in namespace isolation |
-| Quantization | โ | Scalar, Product, Binary (4-32x compression) |
-
-
-๐ณ Docker Hub (Recommended)
-
-**Pull from Docker Hub:** [hub.docker.com/r/ruvnet/ruvector-postgres](https://hub.docker.com/r/ruvnet/ruvector-postgres)
-
-```bash
-# Quick start
-docker run -d --name ruvector \
- -e POSTGRES_PASSWORD=secret \
- -p 5432:5432 \
- ruvnet/ruvector-postgres:latest
-
-# Connect
-psql -h localhost -U ruvector -d ruvector_test
-
-# Create extension
-CREATE EXTENSION ruvector;
-```
-
-**Environment Variables:**
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `POSTGRES_USER` | `ruvector` | Database user |
-| `POSTGRES_PASSWORD` | `ruvector` | Database password |
-| `POSTGRES_DB` | `ruvector_test` | Default database |
-
-**Docker Compose:**
-```yaml
-version: '3.8'
-services:
- ruvector-postgres:
- image: ruvnet/ruvector-postgres:latest
- environment:
- POSTGRES_PASSWORD: secret
- POSTGRES_DB: ruvector_test
- ports:
- - "5432:5432"
- volumes:
- - pgdata:/var/lib/postgresql/data
-
-volumes:
- pgdata:
-```
-
-**Available Tags:**
-- `ruvnet/ruvector-postgres:latest` - PostgreSQL + RuVector 2.0
-- `ruvnet/ruvector-postgres:2.0.0` - Specific version
-
-
-
-
-๐ฆ npm CLI
-
-```bash
-# Install globally
-npm install -g @ruvector/postgres-cli
-
-# Or use npx
-npx @ruvector/postgres-cli --help
-
-# Commands available as 'ruvector-pg' or 'rvpg'
-ruvector-pg --version
-rvpg --help
-```
-
-**CLI Commands:**
-```bash
-# Install extension to existing PostgreSQL
-ruvector-pg install
-
-# Create vector table with HNSW index
-ruvector-pg vector create table embeddings --dim 1536 --index hnsw
-
-# Import vectors from file
-ruvector-pg vector import embeddings data.json
-
-# Search vectors
-ruvector-pg vector search embeddings --query "0.1,0.2,..." --limit 10
-
-# Benchmark performance
-ruvector-pg bench --iterations 1000
-
-# Check extension status
-ruvector-pg status
-```
-
-**Programmatic Usage:**
-```typescript
-import { RuvectorPG } from '@ruvector/postgres-cli';
-
-const client = new RuvectorPG({
- host: 'localhost',
- port: 5432,
- database: 'vectors',
- user: 'postgres',
- password: 'secret'
-});
-
-// Create table with HNSW index
-await client.createTable('embeddings', {
- dimensions: 1536,
- indexType: 'hnsw',
- distanceMetric: 'cosine'
-});
-
-// Insert vectors
-await client.insert('embeddings', {
- id: '1',
- vector: [0.1, 0.2, ...],
- metadata: { source: 'openai' }
-});
-
-// Search
-const results = await client.search('embeddings', queryVector, { limit: 10 });
-```
-
-
-
-
-๐ฆ Rust Crate
-
-```bash
-# Install pgrx (PostgreSQL extension framework)
-cargo install cargo-pgrx --version "0.12.9" --locked
-cargo pgrx init
-
-# Build and install extension
-cd crates/ruvector-postgres
-cargo pgrx install --release
-
-# Or install specific PostgreSQL version
-cargo pgrx install --release --pg-config /usr/lib/postgresql/17/bin/pg_config
-```
-
-**Cargo.toml:**
-```toml
-[dependencies]
-ruvector-postgres = "2.0"
-
-# Optional features
-[features]
-default = ["pg17"]
-pg16 = ["ruvector-postgres/pg16"]
-pg15 = ["ruvector-postgres/pg15"]
-
-# AI features (opt-in)
-ai-complete = ["ruvector-postgres/ai-complete"] # All AI features
-learning = ["ruvector-postgres/learning"] # Self-learning
-attention = ["ruvector-postgres/attention"] # 39 attention mechanisms
-gnn = ["ruvector-postgres/gnn"] # Graph neural networks
-hyperbolic = ["ruvector-postgres/hyperbolic"] # Hyperbolic embeddings
-embeddings = ["ruvector-postgres/embeddings"] # Local embedding generation
-```
-
-**Build with all features:**
-```bash
-cargo pgrx install --release --features "ai-complete,embeddings"
-```
-
-
-
-
-๐ SQL Examples
-
-```sql
--- Enable extension
-CREATE EXTENSION ruvector;
-
--- Create table with vector column
-CREATE TABLE documents (
- id SERIAL PRIMARY KEY,
- content TEXT,
- embedding VECTOR(1536)
-);
-
--- Create HNSW index
-CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)
- WITH (m = 16, ef_construction = 200);
-
--- Insert vectors
-INSERT INTO documents (content, embedding)
-VALUES ('Hello world', '[0.1, 0.2, ...]'::vector);
-
--- Semantic search (cosine similarity)
-SELECT id, content, embedding <=> '[0.1, 0.2, ...]'::vector AS distance
-FROM documents
-ORDER BY distance
-LIMIT 10;
-
--- Hybrid search (vector + full-text)
-SELECT id, content
-FROM documents
-WHERE to_tsvector(content) @@ to_tsquery('machine & learning')
-ORDER BY embedding <=> query_embedding
-LIMIT 10;
-
--- GNN-enhanced search (with learning)
-SELECT * FROM ruvector_gnn_search(
- 'documents',
- '[0.1, 0.2, ...]'::vector,
- 10, -- limit
- 'gcn' -- gnn_type: gcn, graphsage, gat, gin
-);
-
--- Generate embeddings locally (no API needed)
-SELECT ruvector_embed('all-MiniLM-L6-v2', 'Your text here');
-
--- Flash attention
-SELECT ruvector_flash_attention(query, key, value);
-```
-
-
-
-See [ruvector-postgres README](./crates/ruvector-postgres/README.md) for full SQL API reference (230+ functions).
-
-
-
----
-
-## Developer Tools
-
-
-๐ ๏ธ Tools & Utilities
-
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-bench](./crates/ruvector-bench) | Benchmarking suite for vector operations | [](https://crates.io/crates/ruvector-bench) |
-| [ruvector-metrics](./crates/ruvector-metrics) | Observability, metrics, and monitoring | [](https://crates.io/crates/ruvector-metrics) |
-| [ruvector-filter](./crates/ruvector-filter) | Metadata filtering and query predicates | [](https://crates.io/crates/ruvector-filter) |
-| [ruvector-collections](./crates/ruvector-collections) | Multi-tenant collection management | [](https://crates.io/crates/ruvector-collections) |
-| [ruvector-snapshot](./crates/ruvector-snapshot) | Point-in-time snapshots and backups | [](https://crates.io/crates/ruvector-snapshot) |
-| [micro-hnsw-wasm](./crates/micro-hnsw-wasm) | Lightweight HNSW implementation for WASM | [](https://crates.io/crates/micro-hnsw-wasm) |
-
-### Embedded & IoT
-
-| Crate | Description | Target |
-|-------|-------------|--------|
-| [ruvector-esp32](./examples/edge) | ESP32/ESP-IDF vector search | ESP32, ESP32-S3 |
-| [rvlite](./crates/rvlite) | SQLite-style edge DB (no_std compatible) | ARM, RISC-V, WASM |
-| [micro-hnsw-wasm](./crates/micro-hnsw-wasm) | <50KB HNSW for constrained devices | WASM, embedded |
-
-```rust
-// ESP32 example (no_std)
-#![no_std]
-use rvlite::RvLite;
-
-let db = RvLite::new(128); // 128-dim vectors
-db.insert(0, &embedding);
-let results = db.search(&query, 5);
-```
-
-
-
----
-
-## Browser & Edge (WASM)
-
-
-๐ WASM Packages (Browser & Edge)
-
-Specialized WebAssembly modules for browser and edge deployment. These packages bring advanced AI and distributed computing primitives to JavaScript/TypeScript with near-native performance.
-
-### Quick Install (All Browser WASM)
-
-```bash
-# Core vector search
-npm install ruvector-wasm @ruvector/rvlite
-
-# AI & Neural
-npm install @ruvector/gnn-wasm @ruvector/attention-wasm @ruvector/sona-wasm
-
-# Graph & Algorithms
-npm install @ruvector/graph-wasm @ruvector/mincut-wasm @ruvector/hyperbolic-hnsw-wasm
-
-# Exotic AI
-npm install @ruvector/economy-wasm @ruvector/exotic-wasm @ruvector/nervous-system-wasm
-
-# LLM (browser inference)
-npm install @ruvector/ruvllm-wasm
-```
-
-| Category | Packages | Total Size |
-|----------|----------|------------|
-| **Core** | ruvector-wasm, rvlite | ~200KB |
-| **AI/Neural** | gnn, attention, sona | ~300KB |
-| **Graph** | graph, mincut, hyperbolic-hnsw | ~250KB |
-| **Exotic** | economy, exotic, nervous-system | ~350KB |
-| **LLM** | ruvllm-wasm | ~500KB |
-
-### Installation
-
-```bash
-# Install individual packages
-npm install @ruvector/learning-wasm
-npm install @ruvector/economy-wasm
-npm install @ruvector/exotic-wasm
-npm install @ruvector/nervous-system-wasm
-npm install @ruvector/attention-unified-wasm
-
-# Or build from source
-cd crates/ruvector-learning-wasm
-wasm-pack build --target web
-```
-
-### ruvector-learning-wasm
-
-**MicroLoRA, BTSP, and HDC for self-learning AI systems.**
-
-Ultra-fast Low-Rank Adaptation (LoRA) optimized for WASM execution with <100us adaptation latency. Designed for real-time per-operator learning in query optimization and AI agent systems.
-
-| Feature | Performance | Description |
-|---------|-------------|-------------|
-| **MicroLoRA** | <100us latency | Rank-2 LoRA matrices for instant weight adaptation |
-| **Per-Operator Scoping** | Zero-allocation hot paths | Separate adapters for different operator types |
-| **Trajectory Tracking** | Lock-free buffers | Record learning trajectories for replay |
-
-**Architecture:**
-
-```
-Input Embedding (256-dim)
- |
- v
- +---------+
- | A: d x 2 | Down projection
- +---------+
- |
- v
- +---------+
- | B: 2 x d | Up projection
- +---------+
- |
- v
-Delta W = alpha * (A @ B)
- |
- v
-Output = Input + Delta W
-```
-
-**JavaScript/TypeScript Example:**
-
-```typescript
-import init, { WasmMicroLoRA } from '@ruvector/learning-wasm';
-
-await init();
-
-// Create MicroLoRA engine (256-dim, alpha=0.1, lr=0.01)
-const lora = new WasmMicroLoRA(256, 0.1, 0.01);
-
-// Forward pass with adaptation
-const input = new Float32Array(256).fill(0.5);
-const output = lora.forward_array(input);
-
-// Adapt based on gradient signal
-const gradient = new Float32Array(256).fill(0.1);
-lora.adapt_array(gradient);
-
-// Adapt with reward signal for RL
-lora.adapt_with_reward(0.8); // 80% improvement
-
-console.log(`Adaptations: ${lora.adapt_count()}`);
-console.log(`Delta norm: ${lora.delta_norm()}`);
-```
-
-### ruvector-economy-wasm
-
-**CRDT-based autonomous credit economy for distributed compute networks.**
+**The world's first coherence-gated genomic analysis engine.**
-P2P-safe concurrent transactions using Conflict-free Replicated Data Types (CRDTs). Features a 10x-to-1x early adopter contribution curve and stake/slash mechanisms for participation incentives.
-
-| Feature | Description |
-|---------|-------------|
-| **CRDT Ledger** | G-Counter (earned) + PN-Counter (spent) for P2P consistency |
-| **Contribution Curve** | 10x early adopter multiplier decaying to 1x baseline |
-| **Stake/Slash** | Participation requirements with slashing for bad actors |
-| **Reputation Scoring** | Multi-factor: accuracy * uptime * stake_weight |
-| **Merkle Verification** | SHA-256 state root for quick ledger verification |
+[](https://www.rust-lang.org/)
+[](https://opensource.org/licenses/MIT)
+[](https://github.com/ruvnet/ruvector/actions)
+[](https://crates.io/crates/ruvector-core)
+[](https://ruv.io)
-**Architecture:**
+---
-```
-+------------------------+
-| CreditLedger | <-- CRDT-based P2P-safe ledger
-| +------------------+ |
-| | G-Counter: Earned| | <-- Monotonically increasing
-| | PN-Counter: Spent| | <-- Can handle disputes/refunds
-| | Stake: Locked | | <-- Participation requirement
-| | State Root | | <-- Merkle root for verification
-| +------------------+ |
-+------------------------+
- |
- v
-+------------------------+
-| ContributionCurve | <-- Exponential decay: 10x -> 1x
-+------------------------+
- |
- v
-+------------------------+
-| ReputationScore | <-- accuracy * uptime * stake_weight
-+------------------------+
-```
+## What Is RuVector DNA Analyzer?
-**JavaScript/TypeScript Example:**
+RuVector DNA Analyzer is a unified genomic analysis engine that takes raw sequencing data -- whether from Illumina short reads, PacBio long reads, or Oxford Nanopore electrical signals -- and produces variant calls, gene annotations, protein structure predictions, CRISPR safety assessments, and clinical pharmacogenomic reports within a single, streaming pipeline. Unlike traditional bioinformatics workflows that chain together dozens of disconnected tools, RuVector treats every stage of analysis as part of one coherent computation.
-```typescript
-import init, {
- CreditLedger,
- ReputationScore,
- contribution_multiplier
-} from '@ruvector/economy-wasm';
+**The problem it solves:** Modern genomics is fragmented. Researchers must stitch together separate tools for alignment (BWA-MEM2), variant calling (GATK, DeepVariant), annotation (VEP), structure prediction (AlphaFold), and dozens more -- each with different formats, assumptions, and failure modes. Errors in one stage silently propagate to the next. No tool can tell you whether its output is structurally consistent with the rest of your analysis.
-await init();
+**What makes it different:** RuVector introduces *coherence gating* -- a mathematical framework based on minimum graph cuts and spectral analysis that certifies when results across the pipeline are mutually consistent, and refuses to emit results when they are not. Every output carries a cryptographic witness certificate. The engine streams data through the pipeline without holding entire genomes in memory, accelerates compute-heavy stages on FPGAs, and deploys everywhere from browser-based WASM to clinical-grade server clusters.
-// Create a new ledger for a node
-const ledger = new CreditLedger("node-123");
+---
-// Earn credits (with early adopter multiplier)
-ledger.creditWithMultiplier(100, "task:abc");
-console.log(`Balance: ${ledger.balance()}`);
-console.log(`Multiplier: ${ledger.currentMultiplier()}x`);
+## Features
+
+### RuVector vs Existing Tools
+
+| Feature | RuVector | BWA-MEM2 | GATK | DeepVariant | minimap2 |
+|---------|----------|----------|------|-------------|----------|
+| Unified pipeline (align to report) | Yes | Alignment only | Variant calling only | Variant calling only | Alignment only |
+| Streaming analysis | Yes | No | No | No | Partial |
+| Graph genome support | Yes | No | No | No | No |
+| Coherence gating with witnesses | Yes | No | No | No | No |
+| FPGA acceleration | Yes | No | No | No | No |
+| Self-optimizing (SONA/EWC++) | Yes | No | No | No | No |
+| Browser deployment (WASM) | Yes | No | No | No | No |
+| Context window | 100 Kbp+ | N/A | N/A | N/A | N/A |
+| Protein structure prediction | Yes | No | No | No | No |
+| CRISPR off-target analysis | Yes | No | No | No | No |
+| Pharmacogenomics | Yes | No | No | No | No |
+| Pathogen surveillance | Yes | No | No | No | No |
-// Stake for participation
-ledger.stake(50);
-console.log(`Staked: ${ledger.stakedAmount()}`);
+### Performance Targets
-// Check multiplier for network compute hours
-const mult = contribution_multiplier(50000.0); // 50K hours
-console.log(`Network multiplier: ${mult}x`); // ~8.5x
+| Metric | RuVector Target | Current Best-in-Class |
+|--------|----------------|----------------------|
+| Throughput | >10 Tbp/hour | ~1 Tbp/hour (DRAGEN v4.3) |
+| SNV F1 score | >99.99% | 99.97% (DeepVariant v1.6) |
+| Indel F1 score | >99.99% | 99.7% (DeepVariant v1.6) |
+| SV F1 score | >98% | ~95% (Sniffles2 + cuteSV) |
+| Variant call latency | <100 us | ~10 ms (GATK per-site) |
+| K-mer similarity search (p50) | <61 us | ~500 us (sourmash) |
+| CRISPR off-target search | <100 ms/guide | ~30 s (Cas-OFFinder) |
+| Memory (streaming genome) | <2 GB | >8 GB (GATK) |
+| Basecalling accuracy | >Q30 (99.9%) | Q25 (Dorado v0.8 SUP) |
-// Track reputation
-const rep = new ReputationScore(0.95, 0.98, 1000);
-console.log(`Composite score: ${rep.composite_score()}`);
+---
-// P2P merge with another ledger (CRDT operation)
-const otherEarned = new Uint8Array([/* serialized earned counter */]);
-const otherSpent = new Uint8Array([/* serialized spent counter */]);
-const mergedCount = ledger.merge(otherEarned, otherSpent);
+## Architecture Overview
+
+The system is organized into **10 bounded contexts**, each a distinct domain with explicit contracts and anti-corruption layers:
+
+```
++===========================================================================+
+| RUVECTOR DNA ANALYZER SYSTEM |
++===========================================================================+
+| |
+| +-------------------+ +---------------------+ +-----------------+|
+| | 1. Sequence | | 2. Alignment & | | 3. Variant ||
+| | Ingestion |---->| Mapping |---->| Calling ||
+| | | | | | ||
+| | ruvector-nervous | | ruvector-core | | ruvector-mincut ||
+| | -system, sona | | ruvector-graph | | cognitum-gate ||
+| +-------------------+ +---------------------+ +--------+--------+|
+| | | | |
+| v v v |
+| +-------------------+ +---------------------+ +-----------------+|
+| | 4. Graph Genome | | 5. Annotation & |<----| 6. Epigenomics ||
+| | |<----| Interpretation | | ||
+| | ruvector-graph | | | | ruvector-gnn ||
+| | ruvector-mincut | | ruvector-core (HNSW) | | ruvector-core ||
+| +-------------------+ +---------------------+ +-----------------+|
+| | |
+| v |
+| +-------------------+ +---------------------+ +-----------------+|
+| | 7. Pharmaco- |<----| 8. Population | | 9. Pathogen ||
+| | genomics | | Genomics | | Surveillance ||
+| | | | | | ||
+| | sona, ruvector- | | ruvector-hyperbolic | | ruvector-delta ||
+| | graph | | -hnsw, ruvector-core | | -consensus ||
+| +-------------------+ +---------------------+ +-----------------+|
+| |
+| +-------------------+ |
+| | 10. CRISPR | Pipeline Orchestration: ruvector-dag |
+| | Engineering | Hardware Accel: ruvector-fpga-transformer |
+| | | State Mgmt: ruvector-delta-core |
+| | ruvector-attention| Compression: ruvector-temporal-tensor |
+| | ruvector-mincut | Quantum: ruQu |
+| +-------------------+ |
+| |
++===========================================================================+
+```
+
+### Data Flow
+
+```
+Raw Signal (FAST5/POD5/FASTQ/BAM)
+ |
+ v
+[Sequence Ingestion] -- dendritic basecalling, QC, adapter trimming
+ |
+ v
+[Alignment & Mapping] -- graph-aware seed-and-extend, HNSW k-mer index
+ |
+ v
+[Variant Calling] -- min-cut coherence gating, witness certificates
+ |
+ +---> [Graph Genome] -- pan-genome construction, Gomory-Hu trees
+ +---> [Annotation] -- ClinVar, ACMG classification, consequence prediction
+ | |
+ | +---> [Epigenomics] -- methylation, chromatin, Hi-C
+ | +---> [Pharmacogenomics] -- star alleles, drug response, dosing
+ | +---> [Population Genomics] -- ancestry, relatedness, GWAS
+ |
+ +---> [Pathogen Surveillance] -- metagenomics, AMR, outbreak detection
+ +---> [CRISPR Engineering] -- guide design, off-target, edit scoring
+ |
+ v
+Coherence-Certified Output (VCF + witness chain)
```
-### ruvector-exotic-wasm
-
-**Exotic AI mechanisms for emergent behavior in distributed systems.**
-
-Novel coordination primitives inspired by decentralized governance, developmental biology, and quantum physics.
-
-| Mechanism | Inspiration | Use Case |
-|-----------|-------------|----------|
-| **Neural Autonomous Organization (NAO)** | DAOs + oscillatory sync | Decentralized AI agent governance |
-| **Morphogenetic Network** | Developmental biology | Emergent network topology |
-| **Time Crystal Coordinator** | Quantum time crystals | Robust distributed coordination |
-
-**NAO Features:**
-- Stake-weighted quadratic voting
-- Oscillatory synchronization for coherence
-- Quorum-based consensus (configurable threshold)
-
-**Morphogenetic Network Features:**
-- Cellular differentiation through morphogen gradients
-- Emergent network topology via growth/pruning
-- Synaptic pruning for optimization
-
-**Time Crystal Features:**
-- Period-doubled oscillations for stable coordination
-- Floquet engineering for noise resilience
-- Phase-locked agent synchronization
-
-**JavaScript/TypeScript Example:**
-
-```typescript
-import init, {
- WasmNAO,
- WasmMorphogeneticNetwork,
- WasmTimeCrystal,
- ExoticEcosystem
-} from '@ruvector/exotic-wasm';
-
-await init();
-
-// Neural Autonomous Organization
-const nao = new WasmNAO(0.7); // 70% quorum
-nao.addMember("agent_1", 100); // 100 stake
-nao.addMember("agent_2", 50);
-
-const propId = nao.propose("Upgrade memory backend");
-nao.vote(propId, "agent_1", 0.9); // 90% approval weight
-nao.vote(propId, "agent_2", 0.6);
-
-if (nao.execute(propId)) {
- console.log("Proposal executed!");
-}
-
-// Morphogenetic Network
-const net = new WasmMorphogeneticNetwork(100, 100); // 100x100 grid
-net.seedSignaling(50, 50); // Seed signaling cell at center
-
-for (let i = 0; i < 1000; i++) {
- net.grow(0.1); // 10% growth rate
-}
-net.differentiate();
-net.prune(0.1); // 10% pruning threshold
-
-// Time Crystal Coordinator
-const crystal = new WasmTimeCrystal(10, 100); // 10 oscillators, 100ms period
-crystal.crystallize();
-
-for (let i = 0; i < 200; i++) {
- const pattern = crystal.tick();
- // Use pattern for coordination decisions
-}
-
-console.log(`Synchronization: ${crystal.orderParameter()}`);
+---
-// Combined Ecosystem (all three working together)
-const eco = new ExoticEcosystem(5, 50, 8); // 5 agents, 50x50 grid, 8 oscillators
-eco.crystallize();
+## Quick Start
-for (let i = 0; i < 100; i++) {
- eco.step();
-}
+### Installation
-console.log(eco.summaryJson());
-```
+```bash
+# From source
+git clone https://github.com/ruvnet/ruvector.git
+cd ruvector
+cargo build --release
-### ruvector-nervous-system-wasm
-
-**Bio-inspired neural system components for browser execution.**
-
-| Component | Performance | Description |
-|-----------|-------------|-------------|
-| **BTSP** | Immediate | Behavioral Timescale Synaptic Plasticity for one-shot learning |
-| **HDC** | <50ns bind, <100ns similarity | Hyperdimensional Computing with 10,000-bit vectors |
-| **WTA** | <1us | Winner-Take-All for instant decisions |
-| **K-WTA** | <10us | K-Winner-Take-All for sparse distributed coding |
-| **Global Workspace** | <10us | 4-7 item attention bottleneck (Miller's Law) |
-
-**Hyperdimensional Computing:**
-- 10,000-bit binary hypervectors
-- 10^40 representational capacity
-- XOR binding (associative, commutative, self-inverse)
-- Hamming distance similarity with SIMD optimization
-
-**Biological References:**
-- BTSP: Bittner et al. 2017 - Hippocampal place fields
-- HDC: Kanerva 1988, Plate 2003 - Hyperdimensional computing
-- WTA: Cortical microcircuits - Lateral inhibition
-- Global Workspace: Baars 1988, Dehaene 2014 - Consciousness
-
-**JavaScript/TypeScript Example:**
-
-```typescript
-import init, {
- BTSPLayer,
- Hypervector,
- HdcMemory,
- WTALayer,
- KWTALayer,
- GlobalWorkspace,
- WorkspaceItem,
-} from '@ruvector/nervous-system-wasm';
-
-await init();
-
-// One-shot learning with BTSP
-const btsp = new BTSPLayer(100, 2000.0); // 100 dim, 2000ms tau
-const pattern = new Float32Array(100).fill(0.1);
-btsp.one_shot_associate(pattern, 1.0); // Immediate association
-const output = btsp.forward(pattern);
-
-// Hyperdimensional Computing
-const apple = Hypervector.random();
-const orange = Hypervector.random();
-const fruit = apple.bind(orange); // XOR binding
-
-const similarity = apple.similarity(orange); // ~0.0 (orthogonal)
-console.log(`Similarity: ${similarity}`); // Random vectors are orthogonal
-
-// HDC Memory
-const memory = new HdcMemory();
-memory.store("apple", apple);
-memory.store("orange", orange);
-
-const results = memory.retrieve(apple, 0.9); // threshold 0.9
-const topK = memory.top_k(fruit, 3); // top-3 similar
-
-// Instant decisions with WTA
-const wta = new WTALayer(1000, 0.5, 0.8); // 1000 neurons, threshold, inhibition
-const activations = new Float32Array(1000);
-// ... fill activations ...
-const winner = wta.compete(activations);
-
-// Sparse coding with K-WTA
-const kwta = new KWTALayer(1000, 50); // 1000 neurons, k=50 winners
-const winners = kwta.select(activations);
-
-// Attention bottleneck with Global Workspace
-const workspace = new GlobalWorkspace(7); // Miller's Law: 7 +/- 2
-const item = new WorkspaceItem(
- new Float32Array([1, 2, 3]), // content
- 0.9, // salience
- 1, // source
- Date.now() // timestamp
-);
-workspace.broadcast(item);
+# Or install the CLI directly
+cargo install ruvector-cli
```
-### ruvector-attention-unified-wasm
-
-**Unified API for 18+ attention mechanisms across Neural, DAG, Graph, and SSM domains.**
-
-A single WASM interface that routes to the appropriate attention implementation based on your data structure and requirements.
-
-| Category | Mechanisms | Best For |
-|----------|------------|----------|
-| **Neural** | Scaled Dot-Product, Multi-Head, Hyperbolic, Linear, Flash, Local-Global, MoE | Transformers, sequences |
-| **DAG** | Topological, Causal Cone, Critical Path, MinCut-Gated, Hierarchical Lorentz, Parallel Branch, Temporal BTSP | Query DAGs, workflows |
-| **Graph** | GAT, GCN, GraphSAGE | GNNs, knowledge graphs |
-| **SSM** | Mamba | Long sequences, streaming |
+### Run Your First Analysis
-**Mechanism Selection:**
+```bash
+# Basic variant calling
+ruvector analyze \
+ --input sample.fastq \
+ --reference hg38.fa \
+ --output results.vcf
-```
-+------------------+ +-------------------+
-| Your Data | --> | UnifiedAttention | --> Optimal Mechanism
-+------------------+ +-------------------+
- |
- +----------------------+----------------------+
- | | |
- +----v----+ +-----v-----+ +-----v----+
- | Neural | | DAG | | Graph |
- +---------+ +-----------+ +----------+
- | dot_prod| | topological| | gat |
- | multi_hd| | causal_cone| | gcn |
- | flash | | mincut_gtd | | graphsage|
- +---------+ +-----------+ +----------+
-```
+# Stream a nanopore run in real time
+ruvector stream \
+ --input /data/nanopore/run001/ \
+ --reference hg38.fa \
+ --output streaming_results.vcf \
+ --mode streaming
-**JavaScript/TypeScript Example:**
-
-```typescript
-import init, {
- UnifiedAttention,
- availableMechanisms,
- getStats,
- softmax,
- temperatureSoftmax,
- cosineSimilarity,
- // Neural attention
- ScaledDotProductAttention,
- MultiHeadAttention,
- // DAG attention
- TopologicalAttention,
- MinCutGatedAttention,
- // Graph attention
- GraphAttention,
- // SSM
- MambaSSM,
-} from '@ruvector/attention-unified-wasm';
-
-await init();
-
-// List all available mechanisms
-console.log(availableMechanisms());
-// { neural: [...], dag: [...], graph: [...], ssm: [...] }
-
-console.log(getStats());
-// { total_mechanisms: 18, neural_count: 7, dag_count: 7, ... }
-
-// Unified selector - routes to appropriate implementation
-const attention = new UnifiedAttention("multi_head");
-console.log(`Category: ${attention.category}`); // "neural"
-console.log(`Supports sequences: ${attention.supportsSequences()}`); // true
-console.log(`Supports graphs: ${attention.supportsGraphs()}`); // false
-
-// For DAG structures
-const dagAttention = new UnifiedAttention("topological");
-console.log(`Category: ${dagAttention.category}`); // "dag"
-console.log(`Supports graphs: ${dagAttention.supportsGraphs()}`); // true
-
-// Hyperbolic attention for hierarchical data
-const hypAttention = new UnifiedAttention("hierarchical_lorentz");
-console.log(`Supports hyperbolic: ${hypAttention.supportsHyperbolic()}`); // true
-
-// Utility functions
-const logits = [1.0, 2.0, 3.0, 4.0];
-const probs = softmax(logits);
-console.log(`Probabilities sum to: ${probs.reduce((a, b) => a + b)}`); // 1.0
-
-// Temperature-scaled softmax (lower = more peaked)
-const sharperProbs = temperatureSoftmax(logits, 0.5);
-
-// Cosine similarity
-const vecA = [1.0, 0.0, 0.0];
-const vecB = [1.0, 0.0, 0.0];
-console.log(`Similarity: ${cosineSimilarity(vecA, vecB)}`); // 1.0
+# CRISPR guide evaluation
+ruvector crispr \
+ --guides guides.tsv \
+ --reference hg38.fa \
+ --output offtarget_report.json
```
-### WASM Package Summary
-
-| Package | Size Target | Key Features |
-|---------|-------------|--------------|
-| `@ruvector/learning-wasm` | <50KB | MicroLoRA (<100us), trajectory tracking |
-| `@ruvector/economy-wasm` | <100KB | CRDT ledger, 10x->1x curve, stake/slash |
-| `@ruvector/exotic-wasm` | <150KB | NAO, Morphogenetic, Time Crystal |
-| `@ruvector/nervous-system-wasm` | <100KB | BTSP, HDC (10K-bit), WTA, Global Workspace |
-| `@ruvector/attention-unified-wasm` | <200KB | 18+ attention mechanisms, unified API |
+### Build & Test
-**Common Patterns:**
+```bash
+# Build the entire workspace
+cargo build --release
-```typescript
-// All packages follow the same initialization pattern
-import init, { /* exports */ } from '@ruvector/-wasm';
-await init();
+# Run all tests
+cargo test --workspace
-// Version check
-import { version } from '@ruvector/-wasm';
-console.log(`Version: ${version()}`);
+# Run benchmarks
+cargo bench -p ruvector-bench
-// Feature discovery
-import { available_mechanisms } from '@ruvector/-wasm';
-console.log(available_mechanisms());
+# Lint
+cargo clippy --workspace -- -D warnings
```
-
-
---
-## Self-Learning Systems
-
-๐ง Self-Learning Intelligence Hooks
-
-**Make your AI assistant smarter over time.**
-
-When you use Claude Code (or any AI coding assistant), it starts fresh every session. It doesn't remember which approaches worked, which files you typically edit together, or what errors you've seen before.
-
-**RuVector Hooks fixes this.** It's a lightweight intelligence layer that:
-
-1. **Remembers what works** โ Tracks which agent types succeed for different tasks
-2. **Learns from mistakes** โ Records error patterns and suggests fixes you've used before
-3. **Predicts your workflow** โ Knows that after editing `api.rs`, you usually edit `api_test.rs`
-4. **Coordinates teams** โ Manages multi-agent swarms for complex tasks
-
-Think of it as giving your AI assistant a memory and intuition about your codebase.
-
-#### How It Works
-
-```
-โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
-โ Claude Code โโโโโโถโ RuVector Hooks โโโโโโถโ Intelligence โ
-โ (PreToolUse) โ โ (pre-edit) โ โ Layer โ
-โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
- โ
- โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- โผ
-โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
-โ Q-Learning โ โ Vector Memory โ โ Swarm Graph โ
-โ ฮฑ=0.1 ฮณ=0.95 โ โ 64-dim embed โ โ Coordination โ
-โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
-```
-
-The hooks integrate with Claude Code's event system:
-- **PreToolUse** โ Provides guidance before edits (agent routing, related files)
-- **PostToolUse** โ Records outcomes for learning (success/failure, patterns)
-- **SessionStart/Stop** โ Manages session state and metrics export
-
-#### Technical Specifications
-
-| Component | Implementation | Details |
-|-----------|----------------|---------|
-| **Q-Learning** | Temporal Difference | ฮฑ=0.1, ฮณ=0.95, ฮต=0.1 (ฮต-greedy exploration) |
-| **Embeddings** | Hash-based vectors | 64 dimensions, normalized, cosine similarity |
-| **LRU Cache** | `lru` crate | 1000 entries, ~10x faster Q-value lookups |
-| **Compression** | `flate2` gzip | 70-83% storage reduction, fast compression |
-| **Storage** | JSON / PostgreSQL | Auto-fallback, 5000 memory entry limit |
-| **Cross-platform** | Rust + TypeScript | Windows (USERPROFILE), Unix (HOME) |
-
-#### Performance
+Advanced Configuration
-| Metric | Value |
-|--------|-------|
-| Q-value lookup (cached) | <1ยตs |
-| Q-value lookup (uncached) | ~50ยตs |
-| Memory search (1000 entries) | <5ms |
-| Storage compression ratio | 70-83% |
-| Session start overhead | <10ms |
+### FPGA Setup
-| Crate/Package | Description | Status |
-|---------------|-------------|--------|
-| [ruvector-cli hooks](./crates/ruvector-cli) | Rust CLI with 34 hooks commands | [](https://crates.io/crates/ruvector-cli) |
-| [@ruvector/cli hooks](./npm/packages/cli) | npm CLI with 29 hooks commands | [](https://www.npmjs.com/package/@ruvector/cli) |
+RuVector supports FPGA acceleration via the `ruvector-fpga-transformer` crate for basecalling, alignment scoring, and protein structure refinement.
-#### Quick Start
-
-```bash
-# Rust CLI
-cargo install ruvector-cli
-ruvector hooks init
-ruvector hooks install
-
-# npm CLI
-npx @ruvector/cli hooks init
-npx @ruvector/cli hooks install
-```
-
-#### Core Capabilities
-
-| Feature | Description | Technical Details |
-|---------|-------------|-------------------|
-| **Q-Learning Routing** | Routes tasks to best agent with learned confidence scores | TD learning with ฮฑ=0.1, ฮณ=0.95, ฮต-greedy exploration |
-| **Semantic Memory** | Vector-based memory with embeddings for context retrieval | 64-dim hash embeddings, cosine similarity, top-k search |
-| **Error Learning** | Records error patterns and suggests fixes | Pattern matching for E0308, E0433, TS2322, etc. |
-| **File Sequences** | Predicts next files to edit based on historical patterns | Markov chain transitions, frequency-weighted suggestions |
-| **Swarm Coordination** | Registers agents, tracks coordination edges, optimizes | Graph-based topology, weighted edges, task assignment |
-| **LRU Cache** | 1000-entry cache for faster Q-value lookups | ~10x speedup, automatic eviction, RefCell for interior mutability |
-| **Gzip Compression** | Storage savings with automatic compression | flate2 fast mode, 70-83% reduction, transparent load/save |
-| **Batch Saves** | Dirty flag tracking to reduce disk I/O | Only writes when data changes, force_save() override |
-| **Shell Completions** | Tab completion for all commands | bash, zsh, fish, PowerShell support |
-
-#### Supported Error Codes
-
-The intelligence layer has built-in knowledge for common error patterns:
-
-| Language | Error Codes | Auto-Suggested Fixes |
-|----------|-------------|---------------------|
-| **Rust** | E0308, E0433, E0425, E0277, E0382 | Type mismatches, missing imports, borrow checker |
-| **TypeScript** | TS2322, TS2339, TS2345, TS7006 | Type assignments, property access, argument types |
-| **Python** | ImportError, AttributeError, TypeError | Module imports, attribute access, type errors |
-| **Go** | undefined, cannot use, not enough arguments | Variable scope, type conversion, function calls |
-
-#### Commands Reference
-
-```bash
-# Setup
-ruvector hooks init [--force] [--postgres] # Initialize hooks (--postgres for DB schema)
-ruvector hooks install # Install into Claude settings
-
-# Core
-ruvector hooks stats # Show intelligence statistics
-ruvector hooks session-start [--resume] # Start/resume a session
-ruvector hooks session-end # End session with metrics
-
-# Memory
-ruvector hooks remember -t edit "content" # Store in semantic memory
-ruvector hooks recall "query" -k 5 # Search memory semantically
-
-# Learning
-ruvector hooks learn --reward 0.8 # Record trajectory
-ruvector hooks suggest --actions "a,b,c" # Get action suggestion
-ruvector hooks route "implement caching" --file src/cache.rs # Route to agent
-
-# Claude Code Hooks
-ruvector hooks pre-edit # Pre-edit intelligence hook
-ruvector hooks post-edit --success # Post-edit learning hook
-ruvector hooks pre-command # Pre-command hook
-ruvector hooks post-command --success # Post-command hook
-ruvector hooks suggest-context # UserPromptSubmit context injection
-ruvector hooks track-notification # Track notification patterns
-ruvector hooks pre-compact [--auto] # Pre-compact hook (auto/manual)
-
-# Claude Code v2.0.55+ Features
-ruvector hooks lsp-diagnostic --file --severity error # LSP diagnostics
-ruvector hooks suggest-ultrathink "complex task" # Recommend extended reasoning
-ruvector hooks async-agent --action spawn --agent-id # Async sub-agents
-
-# Intelligence
-ruvector hooks record-error # Record error pattern
-ruvector hooks suggest-fix E0308 # Get fix for error code
-ruvector hooks suggest-next -n 3 # Predict next files
-ruvector hooks should-test # Check if tests needed
-
-# Swarm
-ruvector hooks swarm-register # Register agent
-ruvector hooks swarm-coordinate # Record coordination
-ruvector hooks swarm-optimize "task1,task2" # Optimize distribution
-ruvector hooks swarm-recommend "rust" # Recommend agent for task
-ruvector hooks swarm-heal # Handle agent failure
-ruvector hooks swarm-stats # Show swarm statistics
-
-# Optimization (Rust only)
-ruvector hooks compress # Compress storage (70-83% savings)
-ruvector hooks cache-stats # Show LRU cache statistics
-ruvector hooks completions bash # Generate shell completions
-```
-
-#### Tutorial: Claude Code Integration
-
-**1. Initialize and install hooks:**
-
-```bash
-ruvector hooks init
-ruvector hooks install --settings-dir .claude
+```toml
+# ruvector.toml
+[fpga]
+backend = "pcie" # Options: pcie, daemon, native_sim, wasm_sim
+device = "xilinx_u250" # Xilinx Alveo U250/U280 or Intel Stratix 10
+quantization = "int4" # INT4/INT8 for maximum throughput
+verify_signatures = true # Ed25519 artifact verification
```
-This creates `.claude/settings.json` with hook configurations:
-
-```json
-{
- "hooks": {
- "PreToolUse": [
- { "matcher": "Edit|Write|MultiEdit", "hooks": ["ruvector hooks pre-edit \"$TOOL_INPUT_FILE_PATH\""] },
- { "matcher": "Bash", "hooks": ["ruvector hooks pre-command \"$TOOL_INPUT_COMMAND\""] }
- ],
- "PostToolUse": [
- { "matcher": "Edit|Write|MultiEdit", "hooks": ["ruvector hooks post-edit ... --success"] },
- { "matcher": "Bash", "hooks": ["ruvector hooks post-command ... --success"] }
- ],
- "SessionStart": ["ruvector hooks session-start"],
- "Stop": ["ruvector hooks session-end --export-metrics"],
- "PreCompact": ["ruvector hooks pre-compact"]
- }
-}
-```
+Supported FPGA platforms:
+- Xilinx Alveo U250/U280 (Vitis 2024.2+)
+- Intel Stratix 10 (Quartus Prime Pro)
-**All 7 Claude Code hooks covered:**
-| Hook | When It Fires | What RuVector Does |
-|------|---------------|-------------------|
-| `PreToolUse` | Before file edit, command, or Task | Suggests agent, shows related files, validates agent assignments |
-| `PostToolUse` | After file edit or command | Records outcome, updates Q-values, injects context |
-| `SessionStart` | When session begins/resumes | Loads intelligence, shows stats (startup vs resume) |
-| `Stop` | When session ends | Saves state, exports metrics |
-| `PreCompact` | Before context compaction | Preserves critical memories (auto vs manual) |
-| `UserPromptSubmit` | Before processing user prompt | Injects learned patterns as context |
-| `Notification` | On system notifications | Tracks notification patterns |
+### SIMD Tuning
-**Advanced Features:**
-- **Stdin JSON Parsing**: Hooks receive full JSON via stdin (session_id, tool_input, tool_response)
-- **Context Injection**: PostToolUse returns `additionalContext` to inject into Claude's context
-- **Timeout Optimization**: All hooks have optimized timeouts (1-5 seconds vs 60s default)
+The engine auto-dispatches to the best available SIMD instruction set:
+- **x86_64**: AVX-512, AVX2, SSE4.1
+- **ARM64**: NEON, SVE
+- **RISC-V**: Vector extensions
+- **WASM**: SIMD128
-**2. Use routing for intelligent agent selection:**
+No manual configuration is required. Override with:
```bash
-# Route a task to the best agent
-$ ruvector hooks route "implement vector search" --file src/lib.rs
-{
- "recommended": "rust-developer",
- "confidence": 0.85,
- "reasoning": "learned from 47 similar edits"
-}
+RUVECTOR_SIMD=avx2 ruvector analyze --input sample.fastq ...
```
-**3. Learn from outcomes:**
-
-```bash
-# Record successful outcome
-ruvector hooks learn "edit-rs-lib" "rust-developer" --reward 1.0
-
-# Record failed outcome
-ruvector hooks learn "edit-rs-lib" "typescript-dev" --reward -0.5
-```
+### Memory Configuration
-**4. Get error fix suggestions:**
+For streaming analysis of a 30x human genome:
-```bash
-$ ruvector hooks suggest-fix E0308
-{
- "code": "E0308",
- "type": "type_mismatch",
- "fixes": [
- "Check return type matches function signature",
- "Use .into() or .as_ref() for type conversion",
- "Verify generic type parameters"
- ]
-}
+```toml
+[memory]
+streaming_budget = "2GB" # Peak RAM limit
+temporal_compression = true # Enable ruvector-temporal-tensor
+quantization_bits = 4 # INT4 for intermediate embeddings
+delta_window_size = "10MB" # Delta propagation window
```
-#### Tutorial: Swarm Coordination
-
-**1. Register agents:**
+For population-scale pan-genome indexing (10,000 individuals):
-```bash
-ruvector hooks swarm-register agent-1 rust-developer --capabilities "rust,async,testing"
-ruvector hooks swarm-register agent-2 typescript-dev --capabilities "ts,react,node"
-ruvector hooks swarm-register agent-3 reviewer --capabilities "review,security,performance"
+```toml
+[memory]
+pan_genome_budget = "64GB"
+scalar_quantization = true
+tangent_space_compression = true # Hyperbolic HNSW optimization
```
-**2. Record coordination patterns:**
+
-```bash
-# Agent-1 hands off to Agent-3 for review
-ruvector hooks swarm-coordinate agent-1 agent-3 --weight 0.9
-```
+
+Architecture Deep Dive
-**3. Optimize task distribution:**
+### Domain-Driven Design
-```bash
-$ ruvector hooks swarm-optimize "implement-api,write-tests,code-review"
-{
- "assignments": {
- "implement-api": "agent-1",
- "write-tests": "agent-1",
- "code-review": "agent-3"
- }
-}
-```
+Each of the 10 bounded contexts follows strict DDD principles:
-**4. Handle failures with self-healing:**
+| Bounded Context | Aggregate Root | Key Domain Events |
+|----------------|----------------|-------------------|
+| Sequence Ingestion | `SequencingRun` | `ReadBasecalled`, `QCPassed`, `AdapterTrimmed` |
+| Alignment & Mapping | `AlignmentSession` | `ReadAligned`, `MappingQualityAssessed` |
+| Variant Calling | `VariantCallSet` | `VariantCalled`, `CoherenceGateDecided` |
+| Graph Genome | `PanGenomeGraph` | `StructuralVariantDetected`, `GraphUpdated` |
+| Annotation | `AnnotatedVariant` | `ConsequencePredicted`, `ClinicalClassified` |
+| Epigenomics | `EpigenomeProfile` | `MethylationQuantified`, `DMRIdentified` |
+| Pharmacogenomics | `PharmacogeneReport` | `StarAlleleCalled`, `DrugResponsePredicted` |
+| Population Genomics | `CohortAnalysis` | `AncestryInferred`, `KinshipComputed` |
+| Pathogen Surveillance | `SurveillanceStream` | `PathogenClassified`, `OutbreakAlerted` |
+| CRISPR Engineering | `GuideLibrary` | `OffTargetEvaluated`, `GuideApproved` |
-```bash
-# Mark agent as failed and redistribute
-ruvector hooks swarm-heal agent-2
-```
+### Event Sourcing & CQRS
-#### PostgreSQL Storage (Optional)
+All state changes are captured as immutable domain events. The `ruvector-delta-core` crate provides:
+- **Delta encoding** for incremental state propagation
+- **Conflict resolution** for distributed deployments
+- **Surgical deletion** for GDPR Right to Erasure compliance
-For production deployments, use PostgreSQL instead of JSON files:
+### Coherence Gating
-```bash
-# Set connection URL
-export RUVECTOR_POSTGRES_URL="postgres://user:pass@localhost/ruvector"
+The coherence engine uses three tiers of mathematical verification:
-# Initialize PostgreSQL schema (automatic)
-ruvector hooks init --postgres
+1. **Tier 1 -- Deterministic Min-Cut (El-Hayek et al., 2025):** n^{o(1)} amortized update time for variant call quality decisions. Empirically scales as n^{0.12}.
-# Or apply schema manually
-psql $RUVECTOR_POSTGRES_URL -f crates/ruvector-cli/sql/hooks_schema.sql
+2. **Tier 2 -- Spectral Sparsification (Khanna et al., 2025):** O~(n) linear sketches for hypergraph spectral sparsification. Powers CRISPR off-target coherence gating.
-# Build CLI with postgres feature
-cargo build -p ruvector-cli --features postgres
-```
+3. **Tier 3 -- Gomory-Hu Trees (Abboud et al., 2025):** Deterministic m^{1+o(1)} construction for all-pairs min-cuts. Identifies structural variant breakpoints and recombination hotspots.
-The PostgreSQL backend provides:
-- Vector embeddings with native `ruvector` type
-- Q-learning functions (`ruvector_hooks_update_q`, `ruvector_hooks_best_action`)
-- Swarm coordination tables with foreign key relationships
-- Automatic memory cleanup (keeps last 5000 entries)
+Every gate decision is one of:
+- **PERMIT** -- output is structurally consistent; witness certificate issued
+- **DEFER** -- insufficient evidence; escalate to higher-sensitivity analysis
+- **DENY** -- contradictory evidence; output suppressed
----
-
-## Additional Modules
-
-๐ฌ Scientific OCR (SciPix)
-
-| Package | Description | Install |
-|---------|-------------|---------|
-| [ruvector-scipix](./examples/scipix) | Rust OCR engine for scientific documents | `cargo add ruvector-scipix` |
-| [@ruvector/scipix](https://www.npmjs.com/package/@ruvector/scipix) | TypeScript client for SciPix API | `npm install @ruvector/scipix` |
-
-**SciPix** extracts text and mathematical equations from images, converting them to LaTeX, MathML, or plain text.
+API Reference
-**Features:**
-- **Multi-format output** โ LaTeX, MathML, AsciiMath, plain text, structured JSON
-- **Batch processing** โ Process multiple images with parallel execution
-- **Content detection** โ Equations, tables, diagrams, mixed content
-- **Confidence scoring** โ Per-region confidence levels (high/medium/low)
-- **PDF support** โ Extract from multi-page PDFs with page selection
+### Core Types
-```typescript
-import { SciPixClient, OutputFormat } from '@ruvector/scipix';
-
-const client = new SciPixClient({
- baseUrl: 'http://localhost:8080',
- apiKey: 'your-api-key',
-});
-
-// OCR an image file
-const result = await client.ocrFile('./equation.png', {
- formats: [OutputFormat.LaTeX, OutputFormat.MathML],
- detectEquations: true,
+```rust
+use ruvector_core::{VectorStore, HnswIndex, SearchResult};
+use ruvector_mincut::{CoherenceGate, GateDecision, WitnessCertificate};
+use ruvector_graph::{PanGenomeGraph, GenomeNode, StructuralVariant};
+use ruvector_dag::{Pipeline, PipelineStep, ExecutionPlan};
+use cognitum_gate_kernel::{TileZero, GateKernel, EvidenceAccumulator};
+
+// Vector search for k-mer similarity
+let index = HnswIndex::builder()
+ .dimensions(384)
+ .ef_construction(200)
+ .max_connections(16)
+ .build()?;
+
+index.insert(kmer_vector, metadata)?;
+let results: Vec = index.search(&query_vector, k=10)?;
+
+// Coherence-gated variant calling
+let gate = CoherenceGate::new(GateConfig {
+ permit_threshold: 0.1, // 10% of read depth
+ defer_threshold: 0.02, // 2% of read depth
});
-console.log('LaTeX:', result.latex);
-console.log('Confidence:', result.confidence);
+match gate.evaluate(&variant_graph)? {
+ GateDecision::Permit(witness) => emit_variant(variant, witness),
+ GateDecision::Defer(reason) => escalate(variant, reason),
+ GateDecision::Deny(reason) => suppress(variant, reason),
+}
+```
-// Quick LaTeX extraction
-const latex = await client.extractLatex('./math.png');
+### Pipeline Construction
-// Batch processing
-const batchResult = await client.batchOcr({
- images: [
- { source: 'base64...', id: 'eq1' },
- { source: 'base64...', id: 'eq2' },
- ],
- defaultOptions: { formats: [OutputFormat.LaTeX] },
-});
-```
+```rust
+use ruvector_dag::{Pipeline, Step};
-```bash
-# Rust CLI usage
-scipix-cli ocr --input equation.png --format latex
-scipix-cli serve --port 3000
+let pipeline = Pipeline::builder()
+ .step(Step::basecall("nanopore_signal"))
+ .step(Step::align("graph_reference"))
+ .step(Step::call_variants("coherence_gated"))
+ .step(Step::annotate("clinvar_2025"))
+ .step(Step::predict_structure("missense_variants"))
+ .parallel(vec![
+ Step::pharmacogenomics("pgx_report"),
+ Step::pathogen_surveillance("amr_detection"),
+ Step::crispr_evaluation("guide_library"),
+ ])
+ .build()?;
-# MCP server for Claude/AI assistants
-scipix-cli mcp
-claude mcp add scipix -- scipix-cli mcp
+pipeline.execute_streaming(input_stream).await?;
```
-See [npm/packages/scipix/README.md](./npm/packages/scipix/README.md) for full documentation.
-
-๐ ONNX Embeddings
+Benchmark Results
-| Example | Description | Path |
-|---------|-------------|------|
-| [ruvector-onnx-embeddings](./examples/onnx-embeddings) | Production-ready ONNX embedding generation in pure Rust | `examples/onnx-embeddings` |
+### Latency Targets
-**ONNX Embeddings** provides native embedding generation using ONNX Runtime โ no Python required. Supports 8+ pretrained models (all-MiniLM, BGE, E5, GTE), multiple pooling strategies, GPU acceleration (CUDA, TensorRT, CoreML, WebGPU), and direct RuVector index integration for RAG pipelines.
+| Operation | Target | SOTA Baseline | Speedup |
+|-----------|--------|---------------|---------|
+| Single variant call decision | <100 us | ~10 ms (GATK) | 100x |
+| Gene annotation lookup | <1 ms | ~5 ms (VEP) | 5x |
+| K-mer similarity search | <61 us | ~500 us (sourmash) | 8x |
+| Protein structure (<150 res) | <10 s | ~120 s (AlphaFold2) | 12x |
+| CRISPR off-target (per guide) | <100 ms | ~30 s (Cas-OFFinder) | 300x |
+| Coherence gate decision | <50 us | N/A (no prior art) | -- |
-```rust
-use ruvector_onnx_embeddings::{Embedder, PretrainedModel};
+### Throughput Targets
-#[tokio::main]
-async fn main() -> anyhow::Result<()> {
- // Create embedder with default model (all-MiniLM-L6-v2)
- let mut embedder = Embedder::default_model().await?;
+| Workload | Target | SOTA Baseline | Improvement |
+|----------|--------|---------------|-------------|
+| Sequencing data ingestion | >10 Tbp/hr | ~1 Tbp/hr (DRAGEN) | 10x |
+| Variant calls per second | >500 K/s | ~50 K/s (DeepVariant GPU) | 10x |
+| Metagenomic classification | >40 M reads/s | ~4 M reads/s (Kraken2) | 10x |
+| Population-scale queries | >10,000/s | ~100/s (KING) | 100x |
- // Generate embedding (384 dimensions)
- let embedding = embedder.embed_one("Hello, world!")?;
+### Accuracy Targets
- // Compute semantic similarity
- let sim = embedder.similarity(
- "I love programming in Rust",
- "Rust is my favorite language"
- )?;
- println!("Similarity: {:.4}", sim); // ~0.85
+| Metric | Target | SOTA Baseline |
+|--------|--------|---------------|
+| SNV F1 (GIAB high-confidence) | 99.9999% | 99.97% (DeepVariant v1.6) |
+| Indel F1 (GIAB Tier 1) | 99.99% | 99.7% (DeepVariant v1.6) |
+| SV F1 (GIAB SV Tier 1) | >98% | ~95% (Sniffles2 + cuteSV) |
+| Basecalling Q-score | >Q30 | Q25 (Dorado v0.8) |
+| Protein structure RMSD | <1.0 A | 1.5 A (AlphaFold3) |
- Ok(())
-}
-```
+### Validation Datasets
-**Supported Models:**
-| Model | Dimension | Speed | Best For |
-|-------|-----------|-------|----------|
-| `AllMiniLmL6V2` | 384 | Fast | General purpose (default) |
-| `BgeSmallEnV15` | 384 | Fast | Search & retrieval |
-| `AllMpnetBaseV2` | 768 | Accurate | Production RAG |
+| Dataset | Purpose |
+|---------|---------|
+| GIAB HG001-HG007 | SNV/indel/SV accuracy |
+| GIAB Tier 1 SV v0.6 | Structural variant accuracy |
+| CMRG v1.0 | Challenging medically relevant genes |
+| CAMI2 | Metagenomic classification |
+| CASP16 targets | Protein structure prediction |
+| SKEMPI v2.0 | Binding affinity prediction |
+| PCAWG | Mutation signatures and driver genes |
+| GeT-RM | Pharmacogene star-allele accuracy |
+| GUIDE-seq | CRISPR off-target validation |
+| 1000 Genomes + HGDP | Population genetics |
-๐ง Bindings & Tools
-
-**Native bindings and tools** for integrating RuVector into any environment โ Node.js, browsers, CLI, or as an HTTP/gRPC server.
+Security and Privacy
-| Crate | Description | crates.io |
-|-------|-------------|-----------|
-| [ruvector-node](./crates/ruvector-node) | Native Node.js bindings via napi-rs | [](https://crates.io/crates/ruvector-node) |
-| [ruvector-wasm](./crates/ruvector-wasm) | WASM bindings for browsers & edge | [](https://crates.io/crates/ruvector-wasm) |
-| [ruvllm-wasm](./crates/ruvllm-wasm) | Browser LLM inference with WebGPU | [](https://crates.io/crates/ruvllm-wasm) |
-| [ruvector-cli](./crates/ruvector-cli) | Command-line interface | [](https://crates.io/crates/ruvector-cli) |
-| [ruvector-server](./crates/ruvector-server) | HTTP/gRPC server | [](https://crates.io/crates/ruvector-server) |
+RuVector DNA Analyzer implements defense-in-depth for genomic data protection:
-**Node.js (Native Performance)**
-```bash
-npm install @ruvector/node
-```
-```javascript
-const { RuVector } = require('@ruvector/node');
-const db = new RuVector({ dimensions: 1536 });
-db.insert('doc1', embedding, { title: 'Hello' });
-const results = db.search(queryEmbedding, 10);
-```
+### Differential Privacy
-**Browser (WASM)**
-```bash
-npm install @ruvector/wasm
-```
-```javascript
-import { RuVectorWasm } from '@ruvector/wasm';
-const db = await RuVectorWasm.create({ dimensions: 384 });
-await db.insert('doc1', embedding);
-const results = await db.search(query, 5);
-```
+All population-level frequency queries satisfy (epsilon, delta)-differential privacy. The Gaussian mechanism with calibrated noise ensures individual genomes cannot be re-identified from aggregate query results.
-**CLI**
-```bash
-cargo install ruvector-cli
-ruvector init mydb --dim 1536
-ruvector insert mydb --file embeddings.json
-ruvector search mydb --query "[0.1, 0.2, ...]" --limit 10
-```
+- Default: epsilon = 1.0, delta = 1e-5
+- Genomic-specific calibration for allele frequency, genotype frequency, and haplotype queries
+- Renyi Differential Privacy (RDP) accountant for cumulative privacy budget tracking
-**HTTP Server**
-```bash
-cargo install ruvector-server
-ruvector-server --port 8080 --data ./vectors
+### Homomorphic Encryption
-# REST API
-curl -X POST http://localhost:8080/search \
- -H "Content-Type: application/json" \
- -d '{"vector": [0.1, 0.2, ...], "limit": 10}'
-```
+Selective CKKS homomorphic encryption with three-tier classification:
+- **Tier 1 (Public):** Reference allele data, aggregate statistics -- no encryption
+- **Tier 2 (Protected):** Individual genotypes, clinical annotations -- AES-256 at rest
+- **Tier 3 (Encrypted Compute):** Rare variants, pharmacogenomic data -- full CKKS homomorphic encryption for computation on ciphertext
-
+### Zero-Knowledge Proofs
----
+Genomic attestation without data exposure:
+- Prove carrier status for a condition without revealing full genotype
+- Verify ancestry composition within ranges without exact breakdown
+- Pharmacogenomic compatibility checks without disclosing specific alleles
-## Examples & Tutorials
+### Regulatory Compliance
-
-๐ Production Examples
-
-28 production-ready examples demonstrating RuVector integration patterns.
-
-| Example | Description | Type |
-|---------|-------------|------|
-| [agentic-jujutsu](./examples/agentic-jujutsu) | Quantum-resistant version control for AI agents (23x faster than Git) | Rust |
-| [mincut](./examples/mincut) | 6 self-organizing network demos: strange loops, time crystals, causal discovery | Rust |
-| [subpolynomial-time](./examples/subpolynomial-time) | n^0.12 subpolynomial algorithm demos | Rust |
-| [exo-ai-2025](./examples/exo-ai-2025) | Cognitive substrate with 9 neural-symbolic crates + 11 research experiments | Rust/TS |
-| [neural-trader](./examples/neural-trader) | AI trading with DRL + sentiment analysis + SONA learning | Rust |
-| [ultra-low-latency-sim](./examples/ultra-low-latency-sim) | 13+ quadrillion meta-simulations/sec with SIMD | Rust |
-| [meta-cognition-spiking-neural-network](./examples/meta-cognition-spiking-neural-network) | Spiking neural network with meta-cognitive learning (10-50x speedup) | npm |
-| [spiking-network](./examples/spiking-network) | Biologically-inspired spiking neural networks | Rust |
-| [ruvLLM](./examples/ruvLLM) | LLM integration patterns for RAG and AI agents | Rust |
-| [onnx-embeddings](./examples/onnx-embeddings) | Production ONNX embedding generation without Python | Rust |
-| [onnx-embeddings-wasm](./examples/onnx-embeddings-wasm) | WASM ONNX embeddings for browsers | WASM |
-| [refrag-pipeline](./examples/refrag-pipeline) | RAG pipeline with vector search and document processing | Rust |
-| [scipix](./examples/scipix) | Scientific OCR: equations โ LaTeX/MathML with ONNX inference | Rust |
-| [graph](./examples/graph) | Graph database examples with Cypher queries | Rust |
-| [edge](./examples/edge) | 364KB WASM edge deployment | Rust |
-| [edge-full](./examples/edge-full) | Full-featured edge vector DB | Rust |
-| [edge-net](./examples/edge-net) | Networked edge deployment with zero-cost swarms | Rust |
-| [vibecast-7sense](./examples/vibecast-7sense) | 7-sense perception AI application | TypeScript |
-| [apify](./examples/apify) | 13 Apify actors: trading, memory engine, synth data, market research | npm |
-| [google-cloud](./examples/google-cloud) | GCP templates for Cloud Run, GKE, Vertex AI | Terraform |
-| [wasm-react](./examples/wasm-react) | React integration with WASM vector operations | WASM |
-| [wasm-vanilla](./examples/wasm-vanilla) | Vanilla JS WASM example for browser vector search | WASM |
-| [wasm](./examples/wasm) | Core WASM examples and bindings | WASM |
-| [nodejs](./examples/nodejs) | Node.js integration examples | Node.js |
-| [rust](./examples/rust) | Core Rust usage examples | Rust |
+| Standard | Implementation |
+|----------|---------------|
+| FDA 21 CFR Part 11 | Complete audit trail via coherence witness chain |
+| HIPAA | AES-256 at rest, TLS 1.3 in transit, zero-copy processing |
+| ISO 15189 | Deterministic algorithms, Ed25519-signed model artifacts |
+| GDPR Right to Erasure | Delta-based surgical deletion without full index rebuild |
-๐ Tutorials
+Deployment Options
-### Tutorial 1: Vector Search in 60 Seconds
+### Native (Server/Workstation)
-```javascript
-import { VectorDB } from 'ruvector';
-
-// Create DB with 384-dimensional vectors
-const db = new VectorDB(384);
-
-// Add vectors
-db.insert('doc1', [0.1, 0.2, ...]); // 384 floats
-db.insert('doc2', [0.3, 0.1, ...]);
-
-// Search (returns top 5 nearest neighbors)
-const results = db.search(queryVector, 5);
-// -> [{ id: 'doc1', score: 0.95 }, { id: 'doc2', score: 0.87 }]
-```
-
-### Tutorial 2: Graph Queries with Cypher
+Full-featured deployment with SIMD auto-dispatch:
-```javascript
-import { GraphDB } from 'ruvector';
-
-const graph = new GraphDB();
-
-// Create nodes and relationships
-graph.query(`
- CREATE (a:Person {name: 'Alice', embedding: $emb1})
- CREATE (b:Person {name: 'Bob', embedding: $emb2})
- CREATE (a)-[:KNOWS {since: 2020}]->(b)
-`, { emb1: aliceVector, emb2: bobVector });
-
-// Hybrid query: graph traversal + vector similarity
-const results = graph.query(`
- MATCH (p:Person)-[:KNOWS*1..3]->(friend)
- WHERE vector.similarity(friend.embedding, $query) > 0.8
- RETURN friend.name, vector.similarity(friend.embedding, $query) as score
- ORDER BY score DESC
-`, { query: queryVector });
+```bash
+cargo build --release
+./target/release/ruvector-cli analyze --input data.fastq --reference ref.fa
```
-### Tutorial 3: Self-Learning with SONA
-
-```rust
-use ruvector_sona::{SonaEngine, SonaConfig};
-
-// Initialize SONA with LoRA adapters
-let sona = SonaEngine::with_config(SonaConfig {
- hidden_dim: 256,
- lora_rank: 8,
- ewc_lambda: 0.4, // Elastic Weight Consolidation
- ..Default::default()
-});
+Supported architectures: x86_64 (AVX-512/AVX2), ARM64 (NEON/SVE), RISC-V (vector extensions).
-// Record successful action
-let mut trajectory = sona.begin_trajectory(query_embedding);
-trajectory.add_step(result_embedding, vec![], 1.0); // reward=1.0
-sona.end_trajectory(trajectory, true); // success=true
+### WASM (Browser)
-// SONA learns and improves future predictions
-sona.force_learn();
+Client-side variant viewing and lightweight analysis:
-// Later: get improved predictions
-let prediction = sona.predict(&new_query_embedding);
+```bash
+cd crates/ruvector-wasm && npm run build
+# Deploy the WASM bundle (<10 MB) to any web server
```
-### Tutorial 4: Dynamic Min-Cut (n^0.12 Updates)
-
-```rust
-use ruvector_mincut::{DynamicMinCut, Graph};
-
-// Build graph
-let mut graph = Graph::new(100); // 100 nodes
-graph.add_edge(0, 1, 10.0);
-graph.add_edge(1, 2, 5.0);
-graph.add_edge(0, 2, 15.0);
-
-// Compute initial min-cut
-let mut mincut = DynamicMinCut::new(&graph);
-let (value, cut_edges) = mincut.compute();
-println!("Min-cut value: {}", value); // -> 15.0
-
-// Dynamic update - subpolynomial time O(n^0.12)!
-graph.update_edge(1, 2, 20.0);
-let (new_value, _) = mincut.recompute(); // Much faster than recomputing from scratch
-```
+Supported browsers: Chrome, Firefox, Safari with WebAssembly SIMD.
-### Tutorial 5: 39 Attention Mechanisms
+### Edge Devices
-```rust
-use ruvector_attention::{
- Attention, FlashAttention, LinearAttention,
- HyperbolicAttention, GraphAttention, MinCutGatedAttention
-};
+Minimal footprint with `rvlite` and `micro-hnsw-wasm`:
-// FlashAttention - O(n) memory, fastest for long sequences
-let flash = FlashAttention::new(512, 8); // dim=512, heads=8
-let output = flash.forward(&query, &key, &value);
+```bash
+cargo build --release -p rvlite --target wasm32-wasi
+```
-// LinearAttention - O(n) time complexity
-let linear = LinearAttention::new(512, 8);
+### FPGA Acceleration
-// HyperbolicAttention - for hierarchical data (Poincarรฉ ball)
-let hyper = HyperbolicAttention::new(512, 8, Curvature(-1.0));
+For maximum throughput on basecalling, alignment, and structure prediction:
-// GraphAttention - respects graph structure
-let gat = GraphAttention::new(512, 8, &adjacency_matrix);
+```bash
+# Build with FPGA support
+cargo build --release -p ruvector-fpga-transformer --features pcie
-// MinCutGatedAttention - 50% compute reduction via sparsity
-let mincut_gated = MinCutGatedAttention::new(512, 8, sparsity: 0.5);
-let sparse_output = mincut_gated.forward(&query, &key, &value);
+# Configure the FPGA backend
+ruvector fpga init --device xilinx_u250 --bitstream path/to/bitstream.xclbin
```
-### Tutorial 6: Spiking Neural Networks
+### GPU Acceleration
-```javascript
-import { SpikingNetwork, HDCEncoder } from '@ruvector/spiking-neural';
+For attention-heavy workloads (protein structure, population PCA):
-// High-Dimensional Computing encoder (10K-bit vectors)
-const encoder = new HDCEncoder(10000);
-const encoded = encoder.encode("hello world");
+```bash
+cargo build --release --features cuda # CUDA 12+
+cargo build --release --features rocm # ROCm 6+
+```
-// Spiking network with BTSP learning
-const network = new SpikingNetwork({
- layers: [784, 256, 10],
- learning: 'btsp', // Behavioral Time-Scale Plasticity
- threshold: 1.0
-});
+### PostgreSQL Extension
-// Train with spike timing
-network.train(spikes, labels, { epochs: 10 });
+Clinical deployment in hospital information systems:
-// Inference
-const output = network.forward(inputSpikes);
+```sql
+CREATE EXTENSION ruvector;
+SELECT * FROM ruvector_search(query_vector, k => 10)
+WHERE annotation @> '{"clinical_significance": "pathogenic"}';
```
-### Tutorial 7: Claude Code Hooks Integration
+### Node.js Bindings
```bash
-# 1. Initialize hooks
-npx @ruvector/cli hooks init
-
-# 2. Install into Claude settings
-npx @ruvector/cli hooks install
-
-# 3. Hooks now capture:
-# - File edits (pre/post)
-# - Commands (pre/post)
-# - Sessions (start/end)
-# - Errors and fixes
-
-# 4. Query learned patterns
-npx @ruvector/cli hooks recall "authentication error"
-# -> Returns similar past solutions
-
-# 5. Get AI routing suggestions
-npx @ruvector/cli hooks route "implement caching"
-# -> Suggests: rust-developer (confidence: 0.89)
+cd crates/ruvector-node && npm run build
```
-### Tutorial 8: Edge Deployment with rvLite
-
```javascript
-import { RvLite } from '@ruvector/rvlite';
-
-// Create persistent edge database (IndexedDB in browser)
-const db = await RvLite.create({
- path: 'my-vectors.db',
- dimensions: 384
-});
-
-// Works offline - all computation local
-await db.insert('doc1', embedding1, { title: 'Hello' });
-await db.insert('doc2', embedding2, { title: 'World' });
-
-// Semantic search with metadata filtering
-const results = await db.search(queryEmbedding, {
- limit: 10,
- filter: { title: { $contains: 'Hello' } }
-});
-
-// Sync when online
-await db.sync('https://api.example.com/vectors');
+const { VectorStore } = require('ruvector');
+const store = new VectorStore({ dimensions: 384 });
+await store.insert(vector, { gene: 'BRCA1', variant: 'p.Arg1699Trp' });
+const results = await store.search(queryVector, { k: 10 });
```
-๐ WASM & Utility Packages
-
-| Package | Description | Version | Downloads |
-|---------|-------------|---------|-----------|
-| [@ruvector/wasm](https://www.npmjs.com/package/@ruvector/wasm) | WASM core vector DB | [](https://www.npmjs.com/package/@ruvector/wasm) | [](https://www.npmjs.com/package/@ruvector/wasm) |
-| [@ruvector/gnn-wasm](https://www.npmjs.com/package/@ruvector/gnn-wasm) | WASM GNN layers | [](https://www.npmjs.com/package/@ruvector/gnn-wasm) | [](https://www.npmjs.com/package/@ruvector/gnn-wasm) |
-| [@ruvector/graph-wasm](https://www.npmjs.com/package/@ruvector/graph-wasm) | WASM graph DB | [](https://www.npmjs.com/package/@ruvector/graph-wasm) | [](https://www.npmjs.com/package/@ruvector/graph-wasm) |
-| [@ruvector/attention-wasm](https://www.npmjs.com/package/@ruvector/attention-wasm) | WASM attention | [](https://www.npmjs.com/package/@ruvector/attention-wasm) | [](https://www.npmjs.com/package/@ruvector/attention-wasm) |
-| [@ruvector/tiny-dancer-wasm](https://www.npmjs.com/package/@ruvector/tiny-dancer-wasm) | WASM AI routing | [](https://www.npmjs.com/package/@ruvector/tiny-dancer-wasm) | [](https://www.npmjs.com/package/@ruvector/tiny-dancer-wasm) |
-| [@ruvector/router-wasm](https://www.npmjs.com/package/@ruvector/router-wasm) | WASM semantic router | [](https://www.npmjs.com/package/@ruvector/router-wasm) | [](https://www.npmjs.com/package/@ruvector/router-wasm) |
-| [@ruvector/postgres-cli](https://www.npmjs.com/package/@ruvector/postgres-cli) | Postgres extension CLI | [](https://www.npmjs.com/package/@ruvector/postgres-cli) | [](https://www.npmjs.com/package/@ruvector/postgres-cli) |
-| [@ruvector/agentic-synth](https://www.npmjs.com/package/@ruvector/agentic-synth) | Synthetic data generator | [](https://www.npmjs.com/package/@ruvector/agentic-synth) | [](https://www.npmjs.com/package/@ruvector/agentic-synth) |
-| [@ruvector/graph-data-generator](https://www.npmjs.com/package/@ruvector/graph-data-generator) | Graph data generation | [](https://www.npmjs.com/package/@ruvector/graph-data-generator) | [](https://www.npmjs.com/package/@ruvector/graph-data-generator) |
-| [@ruvector/agentic-integration](https://www.npmjs.com/package/@ruvector/agentic-integration) | Agentic workflows | [](https://www.npmjs.com/package/@ruvector/agentic-integration) | [](https://www.npmjs.com/package/@ruvector/agentic-integration) |
-| [rvlite](https://www.npmjs.com/package/rvlite) | SQLite-style edge DB (SQL/SPARQL/Cypher) | [](https://www.npmjs.com/package/rvlite) | [](https://www.npmjs.com/package/rvlite) |
-
-
-**Platform-specific native bindings** (auto-detected):
-- `@ruvector/node-linux-x64-gnu`, `@ruvector/node-linux-arm64-gnu`, `@ruvector/node-darwin-x64`, `@ruvector/node-darwin-arm64`, `@ruvector/node-win32-x64-msvc`
-- `@ruvector/gnn-linux-x64-gnu`, `@ruvector/gnn-linux-arm64-gnu`, `@ruvector/gnn-darwin-x64`, `@ruvector/gnn-darwin-arm64`, `@ruvector/gnn-win32-x64-msvc`
-- `@ruvector/tiny-dancer-linux-x64-gnu`, `@ruvector/tiny-dancer-linux-arm64-gnu`, `@ruvector/tiny-dancer-darwin-x64`, `@ruvector/tiny-dancer-darwin-arm64`, `@ruvector/tiny-dancer-win32-x64-msvc`
-- `@ruvector/router-linux-x64-gnu`, `@ruvector/router-linux-arm64-gnu`, `@ruvector/router-darwin-x64`, `@ruvector/router-darwin-arm64`, `@ruvector/router-win32-x64-msvc`
-- `@ruvector/attention-linux-x64-gnu`, `@ruvector/attention-linux-arm64-gnu`, `@ruvector/attention-darwin-x64`, `@ruvector/attention-darwin-arm64`, `@ruvector/attention-win32-x64-msvc`
-- `@ruvector/ruvllm-linux-x64-gnu`, `@ruvector/ruvllm-linux-arm64-gnu`, `@ruvector/ruvllm-darwin-x64`, `@ruvector/ruvllm-darwin-arm64`, `@ruvector/ruvllm-win32-x64-msvc`
-
-See [GitHub Issue #20](https://github.com/ruvnet/ruvector/issues/20) for multi-platform npm package roadmap.
-
-```bash
-# Install all-in-one package
-npm install ruvector
+Contributing
-# Or install individual packages
-npm install @ruvector/core @ruvector/gnn @ruvector/graph-node
+### Getting Started
-# List all available packages
-npx ruvector install
+```bash
+git clone https://github.com/ruvnet/ruvector.git
+cd ruvector
+cargo build
+cargo test --workspace
```
+### Code Style
-```javascript
-const ruvector = require('ruvector');
+- Follow the Rust API Guidelines: https://rust-lang.github.io/api-guidelines/
+- All public APIs must have typed interfaces
+- Keep files under 500 lines
+- Use `thiserror` for error types, `anyhow` for application errors
+- Run `cargo clippy --workspace -- -D warnings` before submitting
-// Vector search
-const db = new ruvector.VectorDB(128);
-db.insert('doc1', embedding1);
-const results = db.search(queryEmbedding, 10);
+### Testing Requirements
-// Graph queries (Cypher)
-db.execute("CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})");
-db.execute("MATCH (p:Person)-[:KNOWS]->(friend) RETURN friend.name");
+- All new code must include unit tests
+- Use property-based testing (`proptest`) for algorithmic correctness
+- Use `mockall` for dependency isolation (London School TDD)
+- Integration tests go in `/tests`
+- Run the full suite: `cargo test --workspace`
-// GNN-enhanced search
-const layer = new ruvector.GNNLayer(128, 256, 4);
-const enhanced = layer.forward(query, neighbors, weights);
+### Architecture Principles
-// Compression (2-32x memory savings)
-const compressed = ruvector.compress(embedding, 0.3);
+- Domain-Driven Design with explicit bounded contexts
+- Event sourcing for all state changes
+- Input validation at system boundaries
+- No hardcoded secrets or credentials
-// Tiny Dancer: AI agent routing
-const router = new ruvector.Router();
-const decision = router.route(candidates, { optimize: 'cost' });
-```
+### Pull Request Process
+
+1. Create a feature branch from `main`
+2. Ensure all tests pass and clippy is clean
+3. Add or update tests for new functionality
+4. Update relevant ADR documents if changing architecture
+5. Submit PR with a clear description of changes
-๐ฆ Rust Usage Examples
+Theoretical Foundations
-```bash
-cargo add ruvector-graph ruvector-gnn
-```
+### Information Theory
-```rust
-use ruvector_graph::{GraphDB, NodeBuilder};
-use ruvector_gnn::{RuvectorLayer, differentiable_search};
+RuVector's coherence gating is grounded in information-theoretic principles:
-let db = GraphDB::new();
+- **Min-cut/max-flow duality** quantifies the evidence bottleneck for variant calls. The minimum cut between reference and alternate allele partitions measures the weakest link in the evidence chain.
+- **Spectral gap analysis** measures graph connectivity. A large spectral gap between on-target and off-target CRISPR sites indicates high guide selectivity.
+- **Sheaf cohomology** (via the sheaf Laplacian) detects local-to-global inconsistencies across the analysis pipeline.
-let doc = NodeBuilder::new("doc1")
- .label("Document")
- .property("embedding", vec![0.1, 0.2, 0.3])
- .build();
-db.create_node(doc)?;
+### Key Papers
-// GNN layer
-let layer = RuvectorLayer::new(128, 256, 4, 0.1);
-let enhanced = layer.forward(&query, &neighbors, &weights);
-```
+1. **El-Hayek, Henzinger, Li (2025)** -- "Deterministic and Exact Fully Dynamic Minimum Cut of Superpolylogarithmic Size in Subpolynomial Time." Provides n^{o(1)} amortized update time for min-cut maintenance, enabling real-time variant call gating.
-```rust
-use ruvector_raft::{RaftNode, RaftNodeConfig};
-use ruvector_cluster::{ClusterManager, ConsistentHashRing};
-use ruvector_replication::{SyncManager, SyncMode};
-
-// Configure a 5-node Raft cluster
-let config = RaftNodeConfig {
- node_id: "node-1".into(),
- cluster_members: vec!["node-1", "node-2", "node-3", "node-4", "node-5"]
- .into_iter().map(Into::into).collect(),
- election_timeout_min: 150, // ms
- election_timeout_max: 300, // ms
- heartbeat_interval: 50, // ms
-};
-let raft = RaftNode::new(config);
-
-// Auto-sharding with consistent hashing (150 virtual nodes per real node)
-let ring = ConsistentHashRing::new(64, 3); // 64 shards, replication factor 3
-let shard = ring.get_shard("my-vector-key");
-
-// Multi-master replication with conflict resolution
-let sync = SyncManager::new(SyncMode::SemiSync { min_replicas: 2 });
-```
+2. **Khanna, Krauthgamer, Li, Quanrud (2025)** -- "Linear Sketches for Hypergraph Cuts." Near-optimal O~(n) sketches for hypergraph spectral sparsification with polylog(n) dynamic updates. Powers CRISPR off-target analysis.
-
+3. **Abboud, Choudhary, Gawrychowski, Li (2025)** -- "Deterministic Almost-Linear-Time Gomory-Hu Trees for All-Pairs Mincuts." Enables pan-genome structural analysis in m^{1+o(1)} time.
+### Topological Data Analysis
-
-๐ RuvLLM Training & RLM Fine-Tuning Tutorials
+- Persistent homology for detecting topological features in genome graphs
+- Betti numbers track connected components, loops, and voids in pan-genome structure
+- Mapper algorithm for dimensionality reduction of population-scale genotype data
-#### Hybrid Routing (90% Accuracy)
+### Spectral Methods
-RuvLTRA achieves **90% routing accuracy** using a keyword-first strategy with embedding fallback:
+- Graph Laplacian eigenvectors for population stratification (PCA on genetic distance matrices)
+- Spectral clustering for outbreak detection in pathogen surveillance
+- Cheeger inequality bounds relate spectral gap to graph conductance for coherence certification
-```javascript
-// Optimal routing: Keywords first, embeddings as tiebreaker
-function routeTask(task, taskEmbedding, agentEmbeddings) {
- const keywordScores = getKeywordScores(task);
- const maxKw = Math.max(...Object.values(keywordScores));
+### Hyperbolic Geometry
- if (maxKw > 0) {
- const candidates = Object.entries(keywordScores)
- .filter(([_, score]) => score === maxKw)
- .map(([agent]) => agent);
+- Poincare ball embeddings for phylogenetic trees (exponential volume growth matches taxonomic branching)
+- Tangent-space pruning for efficient nearest-neighbor search in hyperbolic space
+- Per-shard curvature adaptation for different taxonomic depths
- if (candidates.length === 1) return { agent: candidates[0] };
- return pickByEmbedding(candidates, taskEmbedding, agentEmbeddings);
- }
+### Quantum-Inspired Algorithms
- return embeddingSimilarity(taskEmbedding, agentEmbeddings);
-}
-```
+The `ruQu` crate implements classically-simulated quantum algorithms:
+- **Grover search** for amplitude-amplified rare variant detection
+- **QAOA** for graph partitioning in phylogenetic tree optimization
+- **VQE** for molecular energy minimization in drug-binding prediction
+- Surface code error correction and tensor network evaluation
-Run the benchmark: `node npm/packages/ruvllm/scripts/hybrid-model-compare.js`
+
-#### Generate Training Data
+---
-```bash
-# Using CLI (recommended)
-npx @ruvector/ruvllm train stats # View dataset statistics
-npx @ruvector/ruvllm train dataset # Export training data
-npx @ruvector/ruvllm train contrastive # Run full training pipeline
-
-# With options
-npx @ruvector/ruvllm train dataset --output ./my-training
-npx @ruvector/ruvllm train contrastive --epochs 20 --batch-size 32 --lr 0.0001
-```
+## Crate Ecosystem
-**Programmatic API:**
-```javascript
-import { ContrastiveTrainer, generateTrainingDataset, getDatasetStats } from '@ruvector/ruvllm';
+RuVector consists of 70+ crates organized by domain. Each crate is independently versioned and publishable.
-const stats = getDatasetStats();
-console.log(`${stats.totalExamples} examples, ${stats.agentTypes} agent types`);
+### Core Search and Storage
-const trainer = new ContrastiveTrainer({ epochs: 10, margin: 0.5 });
-trainer.addTriplet(anchor, anchorEmb, positive, positiveEmb, negative, negativeEmb, true);
-const result = trainer.train();
-trainer.exportTrainingData('./output');
-```
+| Crate | Description |
+|-------|-------------|
+| `ruvector-core` | HNSW vector index with 61us p50 latency, SIMD-accelerated distance computation, scalar/INT4/product/binary quantization |
+| `ruvector-hyperbolic-hnsw` | Poincare ball HNSW for hierarchical data (phylogenetics, taxonomy, haplotype genealogy) |
+| `ruvector-collections` | Typed collection management for vector stores |
+| `ruvector-filter` | Pre-query and post-query filtering engine |
+| `ruvector-postgres` | PostgreSQL extension for SQL-accessible vector queries |
+| `rvlite` | Minimal embedded vector store for resource-constrained environments |
+| `micro-hnsw-wasm` | Ultra-lightweight HNSW for browser deployment (<10 MB) |
-#### Fine-Tune with LoRA
+### Graph and Cut Analysis
-```bash
-pip install transformers peft datasets accelerate
-
-python -m peft.lora_train \
- --model_name Qwen/Qwen2.5-0.5B-Instruct \
- --dataset ./data/training/routing-examples.jsonl \
- --output_dir ./ruvltra-routing-lora \
- --lora_r 8 --lora_alpha 16 \
- --num_train_epochs 3 \
- --learning_rate 2e-4
-```
+| Crate | Description |
+|-------|-------------|
+| `ruvector-graph` | Dynamic graph engine with edge insertion/deletion and connected component tracking |
+| `ruvector-mincut` | Deterministic min-cut with n^{o(1)} update time, Gomory-Hu trees, Benczur-Karger sparsification |
+| `ruvector-mincut-gated-transformer` | Min-cut-gated transformer architecture for coherence-aware neural inference |
+| `ruvector-dag` | Directed acyclic graph execution engine for pipeline orchestration |
+| `ruvector-cluster` | Sample clustering with HNSW-seeded initialization |
-#### Convert to GGUF
+### Neural Processing
-```bash
-# Merge LoRA weights
-python -c "
-from peft import PeftModel
-from transformers import AutoModelForCausalLM
-base = AutoModelForCausalLM.from_pretrained('Qwen/Qwen2.5-0.5B-Instruct')
-model = PeftModel.from_pretrained(base, './ruvltra-routing-lora')
-model.merge_and_unload().save_pretrained('./ruvltra-routing-merged')
-"
-
-# Convert and quantize
-python llama.cpp/convert_hf_to_gguf.py ./ruvltra-routing-merged --outfile ruvltra-routing-f16.gguf
-./llama.cpp/llama-quantize ruvltra-routing-f16.gguf ruvltra-routing-q4_k_m.gguf Q4_K_M
-```
+| Crate | Description |
+|-------|-------------|
+| `ruvector-attention` | 7 attention types: scaled-dot, multi-head, flash, linear, local-global, hyperbolic, MoE |
+| `ruvector-gnn` | Graph neural networks (GCN/GAT/GraphSAGE) with EWC continual learning |
+| `ruvector-sparse-inference` | Activation-sparse neural inference with 3/5/7-bit precision lanes and hot/cold neuron caching |
+| `sona` | Self-Optimizing Neural Architecture: Micro-LoRA (rank 1-2), EWC++, ReasoningBank |
+| `ruvector-nervous-system` | Bio-inspired dendritic computation, hyperdimensional encoding, cognitive routing |
+| `cognitum-gate-kernel` | 256-tile parallel coherence evaluation with deterministic tick loop and witness generation |
+| `cognitum-gate-tilezero` | Tile-level gate execution kernel |
-#### Contrastive Embedding Training
+### Hardware Acceleration
-**Using RuvLLM CLI (recommended):**
-```bash
-# Full contrastive training pipeline with triplet loss
-npx @ruvector/ruvllm train contrastive --output ./training-output
+| Crate | Description |
+|-------|-------------|
+| `ruvector-fpga-transformer` | FPGA-accelerated transformer inference (Xilinx/Intel) with zero-allocation hot path |
+| `ruvector-math` | Optimized mathematical primitives (matrix ops, distance functions, numerics) |
-# Exports: triplets.jsonl, embeddings.json, lora_config.json, train.sh
-```
+### State Management and Coordination
-**Using Python (for GPU training):**
-```python
-from sentence_transformers import SentenceTransformer, losses, InputExample
-from torch.utils.data import DataLoader
+| Crate | Description |
+|-------|-------------|
+| `ruvector-delta-core` | Delta encoding/propagation for streaming state management and incremental updates |
+| `ruvector-delta-graph` | Incremental graph edge propagation compatible with dynamic min-cut maintenance |
+| `ruvector-delta-index` | Delta-aware vector index updates |
+| `ruvector-delta-consensus` | Raft-based consensus for distributed delta propagation |
+| `ruvector-temporal-tensor` | Temporal tensor compression (4x-10.67x) with drift-aware segmentation |
+| `ruvector-raft` | Raft consensus protocol for distributed cluster coordination |
+| `ruvector-replication` | Multi-master replication with vector clocks and conflict resolution |
+| `ruvector-snapshot` | Point-in-time snapshot management |
+| `ruvector-crv` | Conflict-free replicated vectors (CRDT-based) |
+
+### Quantum-Inspired
-train_examples = [
- InputExample(texts=["implement login", "build auth component"], label=1.0),
- InputExample(texts=["implement login", "write unit tests"], label=0.0),
-]
+| Crate | Description |
+|-------|-------------|
+| `ruQu` | Quantum algorithm simulation: Grover search, QAOA, VQE |
+| `ruqu-core` | Core quantum circuit primitives and gate definitions |
+| `ruqu-algorithms` | Quantum-inspired algorithm implementations |
+| `ruqu-exotic` | Experimental quantum-inspired methods |
-model = SentenceTransformer("Qwen/Qwen2.5-0.5B-Instruct")
-train_loss = losses.CosineSimilarityLoss(model)
-model.fit([(DataLoader(train_examples, batch_size=16), train_loss)], epochs=5)
-```
+### LLM Integration
-**Resources:** [Issue #122](https://github.com/ruvnet/ruvector/issues/122) | [LoRA Paper](https://arxiv.org/abs/2106.09685) | [Sentence Transformers](https://www.sbert.net/docs/training/overview.html)
+| Crate | Description |
+|-------|-------------|
+| `ruvllm` | Local LLM inference engine with GGUF model support |
+| `ruvllm-cli` | Command-line interface for local LLM operations |
+| `prime-radiant` | Neural architecture search and model optimization |
-#### Rust Training Module
+### Routing and Serving
-For production-scale dataset generation, use the Rust training module ([full docs](./crates/ruvllm/src/training/README.md)):
+| Crate | Description |
+|-------|-------------|
+| `ruvector-router-core` | Request routing engine with load balancing |
+| `ruvector-router-cli` | CLI for router management |
+| `ruvector-router-ffi` | Foreign function interface for router integration |
+| `ruvector-server` | HTTP/gRPC server for vector operations |
+| `ruvector-cli` | Primary command-line interface and MCP server |
+| `mcp-gate` | Model Context Protocol gateway |
-```rust
-use ruvllm::training::{DatasetGenerator, DatasetConfig};
-
-let config = DatasetConfig {
- examples_per_category: 100,
- enable_augmentation: true,
- seed: 42,
- ..Default::default()
-};
-
-let dataset = DatasetGenerator::new(config).generate();
-let (train, val, test) = dataset.split(0.7, 0.15, 0.15, 42);
-dataset.export_jsonl("training.jsonl")?;
-```
+### Metrics and Benchmarking
-**Features:**
-- **5 agent categories**: Coder, Researcher, Security, Architecture, Reviewer (20% each)
-- **Model routing**: Haiku (simple) โ Sonnet (moderate) โ Opus (complex/security)
-- **Data augmentation**: Paraphrasing, complexity variations, domain transfer
-- **8 technical domains**: Web, Systems, DataScience, Mobile, DevOps, Security, Database, API
-- **Quality scores**: 0.80-0.96 based on template quality and category
-- **Performance**: ~10,000 examples/second, ~50 MB/s JSONL export
+| Crate | Description |
+|-------|-------------|
+| `ruvector-metrics` | Observability: latency histograms, throughput counters, resource gauges |
+| `ruvector-bench` | Comprehensive benchmark suite with Criterion |
-```bash
-cargo run --example generate_claude_dataset --release
-# Outputs: train.jsonl, val.jsonl, test.jsonl, stats.json
-```
+### WASM and Node.js Bindings
-
+| Crate | Description |
+|-------|-------------|
+| `ruvector-wasm` | Core WASM bindings for browser deployment |
+| `ruvector-node` | Node.js native bindings via NAPI |
+| `ruvector-graph-wasm` | Graph engine WASM bindings |
+| `ruvector-graph-node` | Graph engine Node.js bindings |
+| `ruvector-gnn-wasm` | GNN WASM bindings |
+| `ruvector-gnn-node` | GNN Node.js bindings |
+| `ruvector-attention-wasm` | Attention mechanism WASM bindings |
+| `ruvector-attention-node` | Attention mechanism Node.js bindings |
+| `ruvector-attention-unified-wasm` | Unified attention WASM bundle |
+| `ruvector-mincut-wasm` | Min-cut WASM bindings |
+| `ruvector-mincut-node` | Min-cut Node.js bindings |
+| `ruvector-mincut-gated-transformer-wasm` | Gated transformer WASM bindings |
+| `ruvector-dag-wasm` | DAG engine WASM bindings |
+| `ruvector-delta-wasm` | Delta state WASM bindings |
+| `ruvector-fpga-transformer-wasm` | FPGA transformer simulation in WASM |
+| `ruvector-sparse-inference-wasm` | Sparse inference WASM bindings |
+| `ruvector-math-wasm` | Math primitives WASM bindings |
+| `ruvector-nervous-system-wasm` | Nervous system WASM bindings |
+| `ruvector-economy-wasm` | Economy simulation WASM bindings |
+| `ruvector-learning-wasm` | Learning subsystem WASM bindings |
+| `ruvector-exotic-wasm` | Experimental features WASM bindings |
+| `ruvector-router-wasm` | Router WASM bindings |
+| `ruvector-temporal-tensor-wasm` | Temporal tensor WASM bindings |
+| `ruvector-tiny-dancer-core` | Lightweight inference core |
+| `ruvector-tiny-dancer-wasm` | Lightweight inference WASM |
+| `ruvector-tiny-dancer-node` | Lightweight inference Node.js |
+| `ruvllm-wasm` | LLM inference WASM bindings |
+| `ruqu-wasm` | Quantum simulation WASM bindings |
+| `ruvector-hyperbolic-hnsw-wasm` | Hyperbolic HNSW WASM bindings |
---
-## Project
-
-
-๐ Project Structure
-
-```
-crates/
-โโโ ruvector-core/ # Vector DB engine (HNSW, storage)
-โโโ ruvector-graph/ # Graph DB + Cypher parser + Hyperedges
-โโโ ruvector-gnn/ # GNN layers, compression, training
-โโโ ruvector-tiny-dancer-core/ # AI agent routing (FastGRNN)
-โโโ ruvector-*-wasm/ # WebAssembly bindings
-โโโ ruvector-*-node/ # Node.js bindings (napi-rs)
-```
+## License
-
+This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
-## Contributing
+Copyright (c) 2024-2026 RuVector Team
-We welcome contributions! See [CONTRIBUTING.md](./docs/development/CONTRIBUTING.md).
+---
-```bash
-# Run tests
-cargo test --workspace
+## Citation
-# Run benchmarks
-cargo bench --workspace
+If you use RuVector DNA Analyzer in your research, please cite:
-# Build WASM
-cargo build -p ruvector-gnn-wasm --target wasm32-unknown-unknown
+```bibtex
+@software{ruvector_dna_analyzer,
+ title = {RuVector DNA Analyzer: A Coherence-Gated Genomic Analysis Engine},
+ author = {{RuVector Team}},
+ year = {2026},
+ url = {https://github.com/ruvnet/ruvector},
+ version = {2.0.2},
+ license = {MIT},
+ note = {Unified streaming pipeline with min-cut coherence gating,
+ FPGA acceleration, and graph-genome support}
+}
```
-## License
-
-MIT License โ free for commercial and personal use.
-
---
-
-
-**Built by [rUv](https://ruv.io)** โข [GitHub](https://github.com/ruvnet/ruvector) โข [npm](https://npmjs.com/package/ruvector) โข [Docs](./docs/)
-
-*Vector search that gets smarter over time.*
-
-
+
+ RuVector DNA Analyzer -- Unifying sequence, graph, and deep learning into one coherent substrate.
+
+ GitHub |
+ Website |
+ Issues
+
diff --git a/benches/bench_attention_genomic.rs b/benches/bench_attention_genomic.rs
new file mode 100644
index 000000000..374c7002a
--- /dev/null
+++ b/benches/bench_attention_genomic.rs
@@ -0,0 +1,294 @@
+//! Attention Mechanism Benchmarks for Genomic Sequences
+//!
+//! Benchmarks attention operations with parameters realistic for genomic
+//! sequence analysis (long sequences, varying model dimensions).
+//!
+//! Run: cargo bench -p ruvector-dna-bench --bench bench_attention_genomic
+
+use criterion::{
+ criterion_group, criterion_main, BenchmarkId, Criterion, Throughput,
+};
+
+use ruvector_attention::attention::ScaledDotProductAttention;
+use ruvector_attention::sparse::FlashAttention;
+use ruvector_attention::traits::Attention;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/// Deterministic pseudo-random vector generator.
+fn gen_vector(dim: usize, seed: u64) -> Vec {
+ let mut state = seed
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ (0..dim)
+ .map(|_| {
+ state = state
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ let bits = ((state >> 33) ^ state) as u32;
+ (bits as f32 / u32::MAX as f32) * 2.0 - 1.0
+ })
+ .collect()
+}
+
+fn gen_vectors(count: usize, dim: usize, base_seed: u64) -> Vec> {
+ (0..count)
+ .map(|i| gen_vector(dim, base_seed.wrapping_add(i as u64)))
+ .collect()
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Flash Attention Forward Pass (varying sequence lengths)
+// ---------------------------------------------------------------------------
+
+fn bench_flash_attention_forward(c: &mut Criterion) {
+ let mut group = c.benchmark_group("attention_genomic/flash_forward");
+ group.sample_size(10);
+
+ let dim = 64; // Head dimension
+ let block_size = 64;
+
+ // Genomic sequence lengths: 1K, 4K, 16K tokens
+ // (64K is very large for single-query attention, included only as a
+ // stress test if the machine has enough memory.)
+ for &seq_len in &[1_024usize, 4_096, 16_384] {
+ let flash = FlashAttention::new(dim, block_size);
+
+ let query = gen_vector(dim, 42);
+ let keys = gen_vectors(seq_len, dim, 100);
+ let values = gen_vectors(seq_len, dim, 200);
+
+ let keys_refs: Vec<&[f32]> = keys.iter().map(|k| k.as_slice()).collect();
+ let values_refs: Vec<&[f32]> = values.iter().map(|v| v.as_slice()).collect();
+
+ group.throughput(Throughput::Elements(seq_len as u64));
+ group.bench_with_input(
+ BenchmarkId::new("seq_len", seq_len),
+ &(query.as_slice(), keys_refs.as_slice(), values_refs.as_slice()),
+ |b, (q, k, v)| {
+ b.iter(|| flash.compute(q, k, v).expect("flash forward"));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Standard Attention Forward Pass (for comparison)
+// ---------------------------------------------------------------------------
+
+fn bench_standard_attention_forward(c: &mut Criterion) {
+ let mut group = c.benchmark_group("attention_genomic/standard_forward");
+ group.sample_size(10);
+
+ let dim = 64;
+
+ // Standard attention is O(n^2) so keep lengths modest
+ for &seq_len in &[256usize, 1_024, 4_096] {
+ let attention = ScaledDotProductAttention::new(dim);
+
+ let query = gen_vector(dim, 42);
+ let keys = gen_vectors(seq_len, dim, 100);
+ let values = gen_vectors(seq_len, dim, 200);
+
+ let keys_refs: Vec<&[f32]> = keys.iter().map(|k| k.as_slice()).collect();
+ let values_refs: Vec<&[f32]> = values.iter().map(|v| v.as_slice()).collect();
+
+ group.throughput(Throughput::Elements(seq_len as u64));
+ group.bench_with_input(
+ BenchmarkId::new("seq_len", seq_len),
+ &(query.as_slice(), keys_refs.as_slice(), values_refs.as_slice()),
+ |b, (q, k, v)| {
+ b.iter(|| attention.compute(q, k, v).expect("standard forward"));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Flash vs Standard Throughput Comparison
+//
+// Fixed sequence length, measure tokens/second for both.
+// ---------------------------------------------------------------------------
+
+fn bench_throughput_comparison(c: &mut Criterion) {
+ let mut group = c.benchmark_group("attention_genomic/throughput_comparison");
+
+ let dim = 64;
+ let seq_len = 4_096;
+
+ let query = gen_vector(dim, 42);
+ let keys = gen_vectors(seq_len, dim, 100);
+ let values = gen_vectors(seq_len, dim, 200);
+ let keys_refs: Vec<&[f32]> = keys.iter().map(|k| k.as_slice()).collect();
+ let values_refs: Vec<&[f32]> = values.iter().map(|v| v.as_slice()).collect();
+
+ group.throughput(Throughput::Elements(seq_len as u64));
+
+ group.bench_function("flash_attention", |b| {
+ let flash = FlashAttention::new(dim, 64);
+ b.iter(|| flash.compute(&query, &keys_refs, &values_refs).expect("flash"));
+ });
+
+ group.bench_function("standard_attention", |b| {
+ let standard = ScaledDotProductAttention::new(dim);
+ b.iter(|| standard.compute(&query, &keys_refs, &values_refs).expect("standard"));
+ });
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Memory Usage Comparison (Flash vs Naive)
+//
+// We approximate memory usage by measuring the peak allocation size
+// difference. In practice, flash attention uses O(block_size) intermediate
+// memory vs O(n^2) for standard attention. We benchmark the wall-clock
+// cost of the memory-efficient path.
+// ---------------------------------------------------------------------------
+
+fn bench_memory_comparison(c: &mut Criterion) {
+ let mut group = c.benchmark_group("attention_genomic/memory_comparison");
+ group.sample_size(10);
+
+ let dim = 64;
+
+ for &seq_len in &[1_024usize, 4_096, 16_384] {
+ let query = gen_vector(dim, 42);
+ let keys = gen_vectors(seq_len, dim, 100);
+ let values = gen_vectors(seq_len, dim, 200);
+ let keys_refs: Vec<&[f32]> = keys.iter().map(|k| k.as_slice()).collect();
+ let values_refs: Vec<&[f32]> = values.iter().map(|v| v.as_slice()).collect();
+
+ // Flash attention: O(block_size) intermediate memory
+ group.bench_with_input(
+ BenchmarkId::new("flash_block64", seq_len),
+ &(query.as_slice(), keys_refs.as_slice(), values_refs.as_slice()),
+ |b, (q, k, v)| {
+ let flash = FlashAttention::new(dim, 64);
+ b.iter(|| flash.compute(q, k, v).expect("flash"));
+ },
+ );
+
+ // Flash attention with smaller block size: even less memory
+ group.bench_with_input(
+ BenchmarkId::new("flash_block16", seq_len),
+ &(query.as_slice(), keys_refs.as_slice(), values_refs.as_slice()),
+ |b, (q, k, v)| {
+ let flash = FlashAttention::new(dim, 16);
+ b.iter(|| flash.compute(q, k, v).expect("flash"));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Varying Block Size Impact
+// ---------------------------------------------------------------------------
+
+fn bench_block_size_impact(c: &mut Criterion) {
+ let mut group = c.benchmark_group("attention_genomic/block_size_impact");
+
+ let dim = 64;
+ let seq_len = 4_096;
+
+ let query = gen_vector(dim, 42);
+ let keys = gen_vectors(seq_len, dim, 100);
+ let values = gen_vectors(seq_len, dim, 200);
+ let keys_refs: Vec<&[f32]> = keys.iter().map(|k| k.as_slice()).collect();
+ let values_refs: Vec<&[f32]> = values.iter().map(|v| v.as_slice()).collect();
+
+ for &block_size in &[8, 16, 32, 64, 128, 256] {
+ group.bench_with_input(
+ BenchmarkId::new("block_size", block_size),
+ &(query.as_slice(), keys_refs.as_slice(), values_refs.as_slice()),
+ |b, (q, k, v)| {
+ let flash = FlashAttention::new(dim, block_size);
+ b.iter(|| flash.compute(q, k, v).expect("flash"));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Causal vs Non-Causal Flash Attention
+// ---------------------------------------------------------------------------
+
+fn bench_causal_attention(c: &mut Criterion) {
+ let mut group = c.benchmark_group("attention_genomic/causal_vs_noncausal");
+
+ let dim = 64;
+ let seq_len = 4_096;
+
+ let query = gen_vector(dim, 42);
+ let keys = gen_vectors(seq_len, dim, 100);
+ let values = gen_vectors(seq_len, dim, 200);
+ let keys_refs: Vec<&[f32]> = keys.iter().map(|k| k.as_slice()).collect();
+ let values_refs: Vec<&[f32]> = values.iter().map(|v| v.as_slice()).collect();
+
+ group.throughput(Throughput::Elements(seq_len as u64));
+
+ group.bench_function("non_causal", |b| {
+ let flash = FlashAttention::new(dim, 64);
+ b.iter(|| flash.compute(&query, &keys_refs, &values_refs).expect("non-causal"));
+ });
+
+ group.bench_function("causal", |b| {
+ let flash = FlashAttention::causal(dim, 64);
+ b.iter(|| flash.compute(&query, &keys_refs, &values_refs).expect("causal"));
+ });
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Dimension Scaling
+// ---------------------------------------------------------------------------
+
+fn bench_dimension_scaling(c: &mut Criterion) {
+ let mut group = c.benchmark_group("attention_genomic/dimension_scaling");
+
+ let seq_len = 2_048;
+
+ for &dim in &[32, 64, 128, 256, 512] {
+ let flash = FlashAttention::new(dim, 64);
+
+ let query = gen_vector(dim, 42);
+ let keys = gen_vectors(seq_len, dim, 100);
+ let values = gen_vectors(seq_len, dim, 200);
+ let keys_refs: Vec<&[f32]> = keys.iter().map(|k| k.as_slice()).collect();
+ let values_refs: Vec<&[f32]> = values.iter().map(|v| v.as_slice()).collect();
+
+ group.throughput(Throughput::Elements(seq_len as u64));
+ group.bench_with_input(
+ BenchmarkId::new("dim", dim),
+ &(query, keys_refs, values_refs),
+ |b, (q, k, v)| {
+ b.iter(|| flash.compute(q, k, v).expect("flash"));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+criterion_group!(
+ benches,
+ bench_flash_attention_forward,
+ bench_standard_attention_forward,
+ bench_throughput_comparison,
+ bench_memory_comparison,
+ bench_block_size_impact,
+ bench_causal_attention,
+ bench_dimension_scaling,
+);
+criterion_main!(benches);
diff --git a/benches/bench_delta_propagation.rs b/benches/bench_delta_propagation.rs
new file mode 100644
index 000000000..9d5a3fa87
--- /dev/null
+++ b/benches/bench_delta_propagation.rs
@@ -0,0 +1,454 @@
+//! Delta Propagation Benchmarks
+//!
+//! Benchmarks delta creation, application, composition, stream operations,
+//! and checkpoint creation/restoration for genomic vector pipelines.
+//!
+//! Run: cargo bench -p ruvector-dna-bench --bench bench_delta_propagation
+
+use criterion::{
+ criterion_group, criterion_main, BenchmarkId, Criterion, Throughput,
+};
+
+use ruvector_delta_core::{
+ Delta, DeltaStream, DeltaStreamConfig, StreamCheckpoint, VectorDelta,
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/// Deterministic pseudo-random vector generator.
+fn gen_vector(dim: usize, seed: u64) -> Vec {
+ let mut state = seed
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ (0..dim)
+ .map(|_| {
+ state = state
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ let bits = ((state >> 33) ^ state) as u32;
+ (bits as f32 / u32::MAX as f32) * 2.0 - 1.0
+ })
+ .collect()
+}
+
+/// Generate a pair of vectors with a given sparsity of changes.
+/// `sparsity` is the fraction of dimensions that remain unchanged (0.0 = all change, 1.0 = none).
+fn gen_delta_pair(dim: usize, sparsity: f32, seed: u64) -> (Vec, Vec) {
+ let old = gen_vector(dim, seed);
+ let mut new = old.clone();
+ let mut state = seed.wrapping_add(999_999);
+ for i in 0..dim {
+ state = state
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ let r = (state >> 33) as f32 / (u32::MAX as f32);
+ if r > sparsity {
+ // Perturb this dimension
+ state = state
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ let perturbation = ((state >> 33) as f32 / u32::MAX as f32) * 0.2 - 0.1;
+ new[i] += perturbation;
+ }
+ }
+ (old, new)
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Delta Creation
+// ---------------------------------------------------------------------------
+
+fn bench_delta_creation(c: &mut Criterion) {
+ let mut group = c.benchmark_group("delta_propagation/creation");
+
+ let dim = 384;
+
+ // Test different sparsity levels
+ for &sparsity in &[0.0f32, 0.5, 0.9, 0.99] {
+ let (old, new) = gen_delta_pair(dim, sparsity, 42);
+
+ group.bench_with_input(
+ BenchmarkId::new("sparsity", format!("{:.0}pct", sparsity * 100.0)),
+ &(old.clone(), new.clone()),
+ |b, (old, new)| {
+ b.iter(|| VectorDelta::compute(old, new));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Delta Application
+// ---------------------------------------------------------------------------
+
+fn bench_delta_apply(c: &mut Criterion) {
+ let mut group = c.benchmark_group("delta_propagation/apply");
+
+ let dim = 384;
+
+ for &sparsity in &[0.0f32, 0.5, 0.9, 0.99] {
+ let (old, new) = gen_delta_pair(dim, sparsity, 42);
+ let delta = VectorDelta::compute(&old, &new);
+
+ group.bench_with_input(
+ BenchmarkId::new("sparsity", format!("{:.0}pct", sparsity * 100.0)),
+ &(old.clone(), delta.clone()),
+ |b, (base, delta)| {
+ b.iter(|| {
+ let mut v = base.clone();
+ delta.apply(&mut v).expect("apply");
+ v
+ });
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Delta Composition (chaining two deltas)
+// ---------------------------------------------------------------------------
+
+fn bench_delta_composition(c: &mut Criterion) {
+ let mut group = c.benchmark_group("delta_propagation/composition");
+
+ let dim = 384;
+
+ for &sparsity in &[0.0f32, 0.5, 0.9] {
+ let (v1, v2) = gen_delta_pair(dim, sparsity, 42);
+ let (_, v3) = gen_delta_pair(dim, sparsity, 123);
+
+ let delta1 = VectorDelta::compute(&v1, &v2);
+ let delta2 = VectorDelta::compute(&v2, &v3);
+
+ group.bench_with_input(
+ BenchmarkId::new("sparsity", format!("{:.0}pct", sparsity * 100.0)),
+ &(delta1.clone(), delta2.clone()),
+ |b, (d1, d2)| {
+ b.iter(|| d1.clone().compose(d2.clone()));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Delta Inverse
+// ---------------------------------------------------------------------------
+
+fn bench_delta_inverse(c: &mut Criterion) {
+ let mut group = c.benchmark_group("delta_propagation/inverse");
+
+ let dim = 384;
+
+ for &sparsity in &[0.0f32, 0.5, 0.9] {
+ let (old, new) = gen_delta_pair(dim, sparsity, 42);
+ let delta = VectorDelta::compute(&old, &new);
+
+ group.bench_with_input(
+ BenchmarkId::new("sparsity", format!("{:.0}pct", sparsity * 100.0)),
+ &delta,
+ |b, delta| {
+ b.iter(|| delta.inverse());
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Delta Byte Size
+// ---------------------------------------------------------------------------
+
+fn bench_delta_byte_size(c: &mut Criterion) {
+ let mut group = c.benchmark_group("delta_propagation/byte_size");
+
+ let dim = 384;
+
+ for &sparsity in &[0.0f32, 0.5, 0.9, 0.99] {
+ let (old, new) = gen_delta_pair(dim, sparsity, 42);
+ let delta = VectorDelta::compute(&old, &new);
+
+ group.bench_with_input(
+ BenchmarkId::new("sparsity", format!("{:.0}pct", sparsity * 100.0)),
+ &delta,
+ |b, delta| {
+ b.iter(|| delta.byte_size());
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Stream Push (pipeline ingestion)
+// ---------------------------------------------------------------------------
+
+fn bench_stream_push(c: &mut Criterion) {
+ let mut group = c.benchmark_group("delta_propagation/stream_push");
+ group.sample_size(10);
+
+ let dim = 384;
+
+ for &batch_size in &[100usize, 1_000, 10_000] {
+ // Pre-generate deltas
+ let deltas: Vec = (0..batch_size)
+ .map(|i| {
+ let (old, new) = gen_delta_pair(dim, 0.9, i as u64);
+ VectorDelta::compute(&old, &new)
+ })
+ .collect();
+
+ group.throughput(Throughput::Elements(batch_size as u64));
+ group.bench_with_input(
+ BenchmarkId::new("deltas", batch_size),
+ &deltas,
+ |b, deltas| {
+ b.iter(|| {
+ let config = DeltaStreamConfig {
+ max_deltas: batch_size + 1000,
+ checkpoint_interval: batch_size / 10,
+ max_memory_bytes: 256 * 1024 * 1024,
+ auto_compact: false,
+ };
+ let mut stream = DeltaStream::::with_config(config);
+ for delta in deltas {
+ stream.push(delta.clone());
+ }
+ stream
+ });
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Stream Replay (full reconstruction)
+// ---------------------------------------------------------------------------
+
+fn bench_stream_replay(c: &mut Criterion) {
+ let mut group = c.benchmark_group("delta_propagation/stream_replay");
+ group.sample_size(10);
+
+ let dim = 384;
+
+ for &num_deltas in &[100usize, 1_000] {
+ let config = DeltaStreamConfig {
+ max_deltas: num_deltas + 1000,
+ checkpoint_interval: num_deltas + 1,
+ max_memory_bytes: 256 * 1024 * 1024,
+ auto_compact: false,
+ };
+ let mut stream = DeltaStream::::with_config(config);
+ let initial = gen_vector(dim, 0);
+
+ for i in 0..num_deltas {
+ let (old, new) = gen_delta_pair(dim, 0.9, i as u64);
+ let delta = VectorDelta::compute(&old, &new);
+ stream.push(delta);
+ }
+
+ group.throughput(Throughput::Elements(num_deltas as u64));
+ group.bench_with_input(
+ BenchmarkId::new("deltas", num_deltas),
+ &(stream, initial.clone()),
+ |b, (stream, initial)| {
+ b.iter(|| stream.replay(initial.clone()).expect("replay"));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Checkpoint Creation
+// ---------------------------------------------------------------------------
+
+fn bench_checkpoint_creation(c: &mut Criterion) {
+ let mut group = c.benchmark_group("delta_propagation/checkpoint_create");
+
+ let dim = 384;
+
+ for &num_deltas in &[100usize, 1_000] {
+ let config = DeltaStreamConfig {
+ max_deltas: num_deltas + 1000,
+ checkpoint_interval: num_deltas + 1,
+ max_memory_bytes: 256 * 1024 * 1024,
+ auto_compact: false,
+ };
+ let mut stream = DeltaStream::::with_config(config);
+ let initial = gen_vector(dim, 0);
+
+ for i in 0..num_deltas {
+ let (old, new) = gen_delta_pair(dim, 0.9, i as u64);
+ stream.push(VectorDelta::compute(&old, &new));
+ }
+
+ // Replay to get current state
+ let current_state = stream.replay(initial.clone()).expect("replay");
+
+ group.bench_with_input(
+ BenchmarkId::new("after_deltas", num_deltas),
+ &(stream.clone(), current_state.clone()),
+ |b, (stream, state)| {
+ b.iter_batched(
+ || stream.clone(),
+ |mut s| {
+ s.create_checkpoint(state.clone());
+ s
+ },
+ criterion::BatchSize::SmallInput,
+ );
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Checkpoint Restoration (replay from checkpoint)
+// ---------------------------------------------------------------------------
+
+fn bench_checkpoint_restore(c: &mut Criterion) {
+ let mut group = c.benchmark_group("delta_propagation/checkpoint_restore");
+ group.sample_size(10);
+
+ let dim = 384;
+ let num_before_checkpoint = 500;
+ let num_after_checkpoint = 500;
+
+ let config = DeltaStreamConfig {
+ max_deltas: 2000,
+ checkpoint_interval: 2000,
+ max_memory_bytes: 256 * 1024 * 1024,
+ auto_compact: false,
+ };
+ let mut stream = DeltaStream::::with_config(config);
+ let initial = gen_vector(dim, 0);
+
+ // Push deltas before checkpoint
+ for i in 0..num_before_checkpoint {
+ let (old, new) = gen_delta_pair(dim, 0.9, i as u64);
+ stream.push(VectorDelta::compute(&old, &new));
+ }
+
+ // Create checkpoint
+ let checkpoint_state = stream.replay(initial.clone()).expect("replay");
+ stream.create_checkpoint(checkpoint_state);
+
+ // Push more deltas after checkpoint
+ for i in 0..num_after_checkpoint {
+ let (old, new) = gen_delta_pair(dim, 0.9, (i + num_before_checkpoint) as u64);
+ stream.push(VectorDelta::compute(&old, &new));
+ }
+
+ group.bench_function("restore_from_checkpoint", |b| {
+ b.iter(|| {
+ stream
+ .replay_from_checkpoint(0)
+ .expect("checkpoint exists")
+ .expect("replay ok")
+ });
+ });
+
+ group.bench_function("replay_from_scratch", |b| {
+ b.iter(|| stream.replay(initial.clone()).expect("replay"));
+ });
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Stream Compaction
+// ---------------------------------------------------------------------------
+
+fn bench_stream_compaction(c: &mut Criterion) {
+ let mut group = c.benchmark_group("delta_propagation/compaction");
+ group.sample_size(10);
+
+ let dim = 384;
+
+ for &num_deltas in &[100usize, 1_000] {
+ let config = DeltaStreamConfig {
+ max_deltas: num_deltas + 10000,
+ checkpoint_interval: num_deltas + 10000,
+ max_memory_bytes: 256 * 1024 * 1024,
+ auto_compact: false,
+ };
+
+ group.bench_with_input(
+ BenchmarkId::new("deltas", num_deltas),
+ &num_deltas,
+ |b, &num_deltas| {
+ b.iter_batched(
+ || {
+ let mut stream = DeltaStream::::with_config(config.clone());
+ for i in 0..num_deltas {
+ let (old, new) = gen_delta_pair(dim, 0.9, i as u64);
+ stream.push(VectorDelta::compute(&old, &new));
+ }
+ stream
+ },
+ |mut stream| {
+ let compacted = stream.compact().expect("compact");
+ compacted
+ },
+ criterion::BatchSize::SmallInput,
+ );
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Dimension Scaling
+// ---------------------------------------------------------------------------
+
+fn bench_dimension_scaling(c: &mut Criterion) {
+ let mut group = c.benchmark_group("delta_propagation/dimension_scaling");
+
+ for &dim in &[64usize, 128, 384, 768, 1536] {
+ let (old, new) = gen_delta_pair(dim, 0.5, 42);
+
+ group.throughput(Throughput::Elements(dim as u64));
+ group.bench_with_input(
+ BenchmarkId::new("compute_dim", dim),
+ &(old.clone(), new.clone()),
+ |b, (old, new)| {
+ b.iter(|| VectorDelta::compute(old, new));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+criterion_group!(
+ benches,
+ bench_delta_creation,
+ bench_delta_apply,
+ bench_delta_composition,
+ bench_delta_inverse,
+ bench_delta_byte_size,
+ bench_stream_push,
+ bench_stream_replay,
+ bench_checkpoint_creation,
+ bench_checkpoint_restore,
+ bench_stream_compaction,
+ bench_dimension_scaling,
+);
+criterion_main!(benches);
diff --git a/benches/bench_hnsw_genomic.rs b/benches/bench_hnsw_genomic.rs
new file mode 100644
index 000000000..89383117c
--- /dev/null
+++ b/benches/bench_hnsw_genomic.rs
@@ -0,0 +1,278 @@
+//! HNSW Index Benchmarks for Genomic Workloads
+//!
+//! Benchmarks HNSW operations with parameters realistic for k-mer embedding
+//! vectors (384-dimensional, normalized, cosine metric).
+//!
+//! Run: cargo bench -p ruvector-dna-bench --bench bench_hnsw_genomic
+
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+
+use ruvector_core::index::hnsw::HnswIndex;
+use ruvector_core::index::VectorIndex;
+use ruvector_core::types::{DistanceMetric, HnswConfig};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/// Deterministic pseudo-random vector generator (LCG-based, no external deps).
+fn gen_vector(dim: usize, seed: u64) -> Vec {
+ let mut state = seed
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ let raw: Vec = (0..dim)
+ .map(|_| {
+ state = state
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ let bits = ((state >> 33) ^ state) as u32;
+ (bits as f32 / u32::MAX as f32) * 2.0 - 1.0
+ })
+ .collect();
+ // Normalize for cosine metric
+ let norm = raw.iter().map(|x| x * x).sum::().sqrt();
+ if norm > 1e-8 {
+ raw.iter().map(|x| x / norm).collect()
+ } else {
+ raw
+ }
+}
+
+fn gen_vectors(count: usize, dim: usize, base_seed: u64) -> Vec> {
+ (0..count)
+ .map(|i| gen_vector(dim, base_seed.wrapping_add(i as u64)))
+ .collect()
+}
+
+/// Build an HNSW index with `n` vectors of dimension `dim`.
+fn build_index(n: usize, dim: usize) -> HnswIndex {
+ let config = HnswConfig {
+ m: 16,
+ ef_construction: 128,
+ ef_search: 64,
+ max_elements: n + 1024,
+ };
+ let mut index = HnswIndex::new(dim, DistanceMetric::Cosine, config)
+ .expect("Failed to create HNSW index");
+
+ let vectors = gen_vectors(n, dim, 42);
+ let entries: Vec<(String, Vec)> = vectors
+ .into_iter()
+ .enumerate()
+ .map(|(i, v)| (format!("kmer_{}", i), v))
+ .collect();
+
+ index.add_batch(entries).expect("Failed to insert batch");
+ index
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Index Construction
+// ---------------------------------------------------------------------------
+
+fn bench_index_construction(c: &mut Criterion) {
+ let mut group = c.benchmark_group("hnsw_genomic/index_construction");
+ group.sample_size(10);
+
+ let dim = 384; // Typical k-mer embedding dimension
+
+ for &n in &[10_000u64, 100_000] {
+ group.throughput(Throughput::Elements(n));
+ group.bench_with_input(BenchmarkId::new("vectors", n), &n, |b, &n| {
+ b.iter(|| {
+ let config = HnswConfig {
+ m: 16,
+ ef_construction: 128,
+ ef_search: 64,
+ max_elements: n as usize + 1024,
+ };
+ let mut index = HnswIndex::new(dim, DistanceMetric::Cosine, config)
+ .expect("create index");
+
+ let vectors = gen_vectors(n as usize, dim, 42);
+ let entries: Vec<(String, Vec)> = vectors
+ .into_iter()
+ .enumerate()
+ .map(|(i, v)| (format!("kmer_{}", i), v))
+ .collect();
+
+ index.add_batch(entries).expect("batch insert");
+ index
+ });
+ });
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Single-Query Search Latency
+// ---------------------------------------------------------------------------
+
+fn bench_single_query_search(c: &mut Criterion) {
+ let mut group = c.benchmark_group("hnsw_genomic/single_query_search");
+
+ let dim = 384;
+ let n = 10_000;
+ let index = build_index(n, dim);
+ let query = gen_vector(dim, 9999);
+
+ for &k in &[1, 10, 50, 100] {
+ group.bench_with_input(BenchmarkId::new("top_k", k), &k, |b, &k| {
+ b.iter(|| index.search(&query, k).expect("search"));
+ });
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Search with varying ef_search (quality vs speed)
+// ---------------------------------------------------------------------------
+
+fn bench_ef_search_tradeoff(c: &mut Criterion) {
+ let mut group = c.benchmark_group("hnsw_genomic/ef_search_tradeoff");
+
+ let dim = 384;
+ let n = 10_000;
+ let index = build_index(n, dim);
+ let query = gen_vector(dim, 9999);
+ let k = 10;
+
+ for &ef in &[16, 32, 64, 128, 256, 512] {
+ group.bench_with_input(BenchmarkId::new("ef_search", ef), &ef, |b, &ef| {
+ b.iter(|| index.search_with_ef(&query, k, ef).expect("search"));
+ });
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Batch Search (100 queries)
+// ---------------------------------------------------------------------------
+
+fn bench_batch_search(c: &mut Criterion) {
+ let mut group = c.benchmark_group("hnsw_genomic/batch_search");
+ group.sample_size(10);
+
+ let dim = 384;
+ let n = 10_000;
+ let index = build_index(n, dim);
+ let queries = gen_vectors(100, dim, 80_000);
+ let k = 10;
+
+ group.throughput(Throughput::Elements(100));
+ group.bench_function("100_queries_top10", |b| {
+ b.iter(|| {
+ let results: Vec<_> = queries
+ .iter()
+ .map(|q| index.search(q, k).expect("search"))
+ .collect();
+ results
+ });
+ });
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Recall@10 Measurement
+//
+// We insert known vectors, then search for them to verify recall.
+// This is a correctness-aware benchmark: it measures search quality
+// alongside latency.
+// ---------------------------------------------------------------------------
+
+fn bench_recall_at_10(c: &mut Criterion) {
+ let mut group = c.benchmark_group("hnsw_genomic/recall_at_10");
+ group.sample_size(10);
+
+ let dim = 384;
+ let n = 10_000;
+ let index = build_index(n, dim);
+ let queries = gen_vectors(100, dim, 42); // Same seed as index vectors
+
+ group.bench_function("recall_measurement", |b| {
+ b.iter(|| {
+ let mut total_recall = 0.0f64;
+ for (i, query) in queries.iter().enumerate() {
+ let results = index.search(query, 10).expect("search");
+ let expected_id = format!("kmer_{}", i);
+ let found = results.iter().any(|r| r.id == expected_id);
+ if found {
+ total_recall += 1.0;
+ }
+ }
+ total_recall / queries.len() as f64
+ });
+ });
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Memory Usage Estimation
+//
+// Measures serialized index size as a proxy for memory footprint.
+// ---------------------------------------------------------------------------
+
+fn bench_memory_estimation(c: &mut Criterion) {
+ let mut group = c.benchmark_group("hnsw_genomic/memory_estimation");
+ group.sample_size(10);
+
+ let dim = 384;
+
+ for &n in &[1_000u64, 10_000] {
+ group.bench_with_input(
+ BenchmarkId::new("serialize_index", n),
+ &n,
+ |b, &n| {
+ let index = build_index(n as usize, dim);
+ b.iter(|| {
+ let bytes = index.serialize().expect("serialize");
+ bytes.len()
+ });
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Incremental Insertion
+// ---------------------------------------------------------------------------
+
+fn bench_incremental_insert(c: &mut Criterion) {
+ let mut group = c.benchmark_group("hnsw_genomic/incremental_insert");
+
+ let dim = 384;
+ let n = 10_000;
+
+ group.bench_function("single_insert_into_10k", |b| {
+ let mut index = build_index(n, dim);
+ let mut counter = n;
+ b.iter(|| {
+ let v = gen_vector(dim, counter as u64 + 100_000);
+ index
+ .add(format!("new_{}", counter), v)
+ .expect("insert");
+ counter += 1;
+ });
+ });
+
+ group.finish();
+}
+
+criterion_group!(
+ benches,
+ bench_index_construction,
+ bench_single_query_search,
+ bench_ef_search_tradeoff,
+ bench_batch_search,
+ bench_recall_at_10,
+ bench_memory_estimation,
+ bench_incremental_insert,
+);
+criterion_main!(benches);
diff --git a/benches/bench_mincut_genome_graph.rs b/benches/bench_mincut_genome_graph.rs
new file mode 100644
index 000000000..aa36ad093
--- /dev/null
+++ b/benches/bench_mincut_genome_graph.rs
@@ -0,0 +1,319 @@
+//! Min-Cut Benchmarks for Genome-Scale Graphs
+//!
+//! Benchmarks min-cut operations on graph structures resembling genomic
+//! overlap / assembly graphs (sparse, with moderately-weighted edges).
+//!
+//! Run: cargo bench -p ruvector-dna-bench --bench bench_mincut_genome_graph
+
+use criterion::{
+ criterion_group, criterion_main, BenchmarkId, Criterion, Throughput,
+};
+
+use ruvector_mincut::{DynamicGraph, DynamicMinCut, MinCutBuilder};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/// Deterministic pseudo-random number from seed (LCG).
+fn lcg(seed: u64) -> u64 {
+ seed.wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407)
+}
+
+/// Build a genome-like graph: a backbone chain with random cross-links.
+///
+/// Mimics assembly / overlap graphs where contigs form a chain and
+/// repeats create additional edges.
+fn build_genome_graph(num_nodes: usize, extra_edges_ratio: f64) -> Vec<(u64, u64, f64)> {
+ let mut edges = Vec::new();
+ let mut seed = 42u64;
+
+ // Backbone chain
+ for i in 0..(num_nodes - 1) {
+ seed = lcg(seed);
+ let weight = 1.0 + (seed % 100) as f64 / 100.0; // [1.0, 2.0)
+ edges.push((i as u64, (i + 1) as u64, weight));
+ }
+
+ // Cross-links (simulating repeat regions)
+ let num_extra = (num_nodes as f64 * extra_edges_ratio) as usize;
+ for _ in 0..num_extra {
+ seed = lcg(seed);
+ let u = (seed % num_nodes as u64) as u64;
+ seed = lcg(seed);
+ let v = (seed % num_nodes as u64) as u64;
+ if u != v {
+ seed = lcg(seed);
+ let weight = 0.5 + (seed % 200) as f64 / 100.0;
+ edges.push((u, v, weight));
+ }
+ }
+
+ edges
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Graph Construction
+// ---------------------------------------------------------------------------
+
+fn bench_graph_construction(c: &mut Criterion) {
+ let mut group = c.benchmark_group("mincut_genome/graph_construction");
+ group.sample_size(10);
+
+ for &num_nodes in &[1_000usize, 10_000, 50_000] {
+ let edges = build_genome_graph(num_nodes, 0.5);
+
+ group.throughput(Throughput::Elements(num_nodes as u64));
+ group.bench_with_input(
+ BenchmarkId::new("nodes", num_nodes),
+ &edges,
+ |b, edges| {
+ b.iter(|| {
+ MinCutBuilder::new()
+ .exact()
+ .with_edges(edges.clone())
+ .build()
+ .expect("build graph")
+ });
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Min-Cut Value Query
+// ---------------------------------------------------------------------------
+
+fn bench_mincut_query(c: &mut Criterion) {
+ let mut group = c.benchmark_group("mincut_genome/min_cut_query");
+
+ for &num_nodes in &[1_000usize, 5_000, 10_000] {
+ let edges = build_genome_graph(num_nodes, 0.5);
+ let mincut = MinCutBuilder::new()
+ .exact()
+ .with_edges(edges)
+ .build()
+ .expect("build");
+
+ group.bench_with_input(
+ BenchmarkId::new("nodes", num_nodes),
+ &mincut,
+ |b, mc| {
+ b.iter(|| mc.min_cut_value());
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Full Min-Cut Result (with partition)
+// ---------------------------------------------------------------------------
+
+fn bench_mincut_full_result(c: &mut Criterion) {
+ let mut group = c.benchmark_group("mincut_genome/full_result");
+
+ for &num_nodes in &[1_000usize, 5_000, 10_000] {
+ let edges = build_genome_graph(num_nodes, 0.5);
+ let mincut = MinCutBuilder::new()
+ .exact()
+ .with_edges(edges)
+ .build()
+ .expect("build");
+
+ group.bench_with_input(
+ BenchmarkId::new("nodes", num_nodes),
+ &mincut,
+ |b, mc| {
+ b.iter(|| mc.min_cut());
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Incremental Edge Insertion
+// ---------------------------------------------------------------------------
+
+fn bench_incremental_insert(c: &mut Criterion) {
+ let mut group = c.benchmark_group("mincut_genome/edge_insert");
+
+ for &num_nodes in &[1_000usize, 5_000] {
+ let edges = build_genome_graph(num_nodes, 0.3);
+
+ group.bench_with_input(
+ BenchmarkId::new("nodes", num_nodes),
+ &edges,
+ |b, edges| {
+ b.iter_batched(
+ || {
+ // Setup: build initial graph
+ let mc = MinCutBuilder::new()
+ .exact()
+ .with_edges(edges.clone())
+ .build()
+ .expect("build");
+ mc
+ },
+ |mut mc| {
+ // Insert 100 new edges
+ let base = num_nodes as u64;
+ for i in 0..100u64 {
+ let u = base + i;
+ let v = i % base;
+ let _ = mc.insert_edge(u, v, 1.0);
+ }
+ },
+ criterion::BatchSize::SmallInput,
+ );
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Incremental Edge Deletion
+// ---------------------------------------------------------------------------
+
+fn bench_incremental_delete(c: &mut Criterion) {
+ let mut group = c.benchmark_group("mincut_genome/edge_delete");
+
+ for &num_nodes in &[1_000usize, 5_000] {
+ let edges = build_genome_graph(num_nodes, 0.5);
+
+ group.bench_with_input(
+ BenchmarkId::new("nodes", num_nodes),
+ &edges,
+ |b, edges| {
+ b.iter_batched(
+ || {
+ MinCutBuilder::new()
+ .exact()
+ .with_edges(edges.clone())
+ .build()
+ .expect("build")
+ },
+ |mut mc| {
+ // Delete backbone edges (which are guaranteed to exist)
+ for i in 0..50u64 {
+ let _ = mc.delete_edge(i, i + 1);
+ }
+ },
+ criterion::BatchSize::SmallInput,
+ );
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Graph Statistics (lightweight query)
+// ---------------------------------------------------------------------------
+
+fn bench_graph_stats(c: &mut Criterion) {
+ let mut group = c.benchmark_group("mincut_genome/graph_stats");
+
+ for &num_nodes in &[1_000usize, 10_000, 50_000] {
+ let edges = build_genome_graph(num_nodes, 0.5);
+ let mincut = MinCutBuilder::new()
+ .exact()
+ .with_edges(edges)
+ .build()
+ .expect("build");
+
+ group.bench_with_input(
+ BenchmarkId::new("nodes", num_nodes),
+ &mincut,
+ |b, mc| {
+ b.iter(|| {
+ let graph = mc.graph();
+ let reader = graph.read();
+ reader.stats()
+ });
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Connectivity Check
+// ---------------------------------------------------------------------------
+
+fn bench_connectivity(c: &mut Criterion) {
+ let mut group = c.benchmark_group("mincut_genome/connectivity");
+
+ for &num_nodes in &[1_000usize, 10_000] {
+ let edges = build_genome_graph(num_nodes, 0.5);
+ let mincut = MinCutBuilder::new()
+ .exact()
+ .with_edges(edges)
+ .build()
+ .expect("build");
+
+ group.bench_with_input(
+ BenchmarkId::new("nodes", num_nodes),
+ &mincut,
+ |b, mc| {
+ b.iter(|| mc.is_connected());
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ---------------------------------------------------------------------------
+// Benchmark: Approximate Min-Cut
+// ---------------------------------------------------------------------------
+
+fn bench_approximate_mincut(c: &mut Criterion) {
+ let mut group = c.benchmark_group("mincut_genome/approximate");
+ group.sample_size(10);
+
+ for &num_nodes in &[1_000usize, 10_000] {
+ let edges = build_genome_graph(num_nodes, 0.5);
+
+ for &epsilon in &[0.1, 0.2, 0.5] {
+ let mc = MinCutBuilder::new()
+ .approximate(epsilon)
+ .with_edges(edges.clone())
+ .build()
+ .expect("build");
+
+ group.bench_with_input(
+ BenchmarkId::new(format!("nodes_{}_eps", num_nodes), format!("{:.1}", epsilon)),
+ &mc,
+ |b, mc| {
+ b.iter(|| mc.min_cut());
+ },
+ );
+ }
+ }
+
+ group.finish();
+}
+
+criterion_group!(
+ benches,
+ bench_graph_construction,
+ bench_mincut_query,
+ bench_mincut_full_result,
+ bench_incremental_insert,
+ bench_incremental_delete,
+ bench_graph_stats,
+ bench_connectivity,
+ bench_approximate_mincut,
+);
+criterion_main!(benches);
diff --git a/benches/bench_quantization.rs b/benches/bench_quantization.rs
new file mode 100644
index 000000000..bd60a0860
--- /dev/null
+++ b/benches/bench_quantization.rs
@@ -0,0 +1,463 @@
+//! Quantization Benchmarks
+//!
+//! Benchmarks quantization throughput, distance computation speedups, and
+//! reconstruction accuracy for genomic embedding vectors.
+//!
+//! Run: cargo bench -p ruvector-dna-bench --bench bench_quantization
+
+use criterion::{
+ criterion_group, criterion_main, BenchmarkId, Criterion, Throughput,
+};
+
+use ruvector_core::quantization::{
+ BinaryQuantized, Int4Quantized, QuantizedVector, ScalarQuantized,
+};
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/// Deterministic pseudo-random vector generator.
+fn gen_vector(dim: usize, seed: u64) -> Vec {
+ let mut state = seed
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ (0..dim)
+ .map(|_| {
+ state = state
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ let bits = ((state >> 33) ^ state) as u32;
+ // Map to [-1.0, 1.0] -- typical range for normalized embeddings
+ (bits as f32 / u32::MAX as f32) * 2.0 - 1.0
+ })
+ .collect()
+}
+
+fn gen_vectors(count: usize, dim: usize, base_seed: u64) -> Vec> {
+ (0..count)
+ .map(|i| gen_vector(dim, base_seed.wrapping_add(i as u64)))
+ .collect()
+}
+
+/// Naive f32 Euclidean squared distance for baseline comparison.
+fn f32_distance_sq(a: &[f32], b: &[f32]) -> f32 {
+ a.iter()
+ .zip(b.iter())
+ .map(|(x, y)| {
+ let d = x - y;
+ d * d
+ })
+ .sum()
+}
+
+// ===========================================================================
+// Benchmark: f32 -> Binary Quantization Throughput
+// ===========================================================================
+
+fn bench_binary_quantize_throughput(c: &mut Criterion) {
+ let mut group = c.benchmark_group("quantization/binary_quantize");
+
+ let dim = 384;
+
+ for &batch_size in &[1usize, 100, 1_000, 10_000] {
+ let vectors = gen_vectors(batch_size, dim, 42);
+
+ group.throughput(Throughput::Elements(batch_size as u64));
+ group.bench_with_input(
+ BenchmarkId::new("vectors", batch_size),
+ &vectors,
+ |b, vectors| {
+ b.iter(|| {
+ let quantized: Vec = vectors
+ .iter()
+ .map(|v| BinaryQuantized::quantize(v))
+ .collect();
+ quantized
+ });
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ===========================================================================
+// Benchmark: f32 -> INT4 Quantization Throughput
+// ===========================================================================
+
+fn bench_int4_quantize_throughput(c: &mut Criterion) {
+ let mut group = c.benchmark_group("quantization/int4_quantize");
+
+ let dim = 384;
+
+ for &batch_size in &[1usize, 100, 1_000, 10_000] {
+ let vectors = gen_vectors(batch_size, dim, 42);
+
+ group.throughput(Throughput::Elements(batch_size as u64));
+ group.bench_with_input(
+ BenchmarkId::new("vectors", batch_size),
+ &vectors,
+ |b, vectors| {
+ b.iter(|| {
+ let quantized: Vec = vectors
+ .iter()
+ .map(|v| Int4Quantized::quantize(v))
+ .collect();
+ quantized
+ });
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ===========================================================================
+// Benchmark: f32 -> Scalar (u8) Quantization Throughput
+// ===========================================================================
+
+fn bench_scalar_quantize_throughput(c: &mut Criterion) {
+ let mut group = c.benchmark_group("quantization/scalar_quantize");
+
+ let dim = 384;
+
+ for &batch_size in &[1usize, 100, 1_000, 10_000] {
+ let vectors = gen_vectors(batch_size, dim, 42);
+
+ group.throughput(Throughput::Elements(batch_size as u64));
+ group.bench_with_input(
+ BenchmarkId::new("vectors", batch_size),
+ &vectors,
+ |b, vectors| {
+ b.iter(|| {
+ let quantized: Vec = vectors
+ .iter()
+ .map(|v| ScalarQuantized::quantize(v))
+ .collect();
+ quantized
+ });
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ===========================================================================
+// Benchmark: Distance Computation with Quantized Vectors
+// ===========================================================================
+
+fn bench_binary_distance(c: &mut Criterion) {
+ let mut group = c.benchmark_group("quantization/binary_distance");
+
+ for &dim in &[128usize, 384, 768, 1536] {
+ let v1 = gen_vector(dim, 42);
+ let v2 = gen_vector(dim, 123);
+ let q1 = BinaryQuantized::quantize(&v1);
+ let q2 = BinaryQuantized::quantize(&v2);
+
+ group.throughput(Throughput::Elements(dim as u64));
+ group.bench_with_input(
+ BenchmarkId::new("dim", dim),
+ &(q1.clone(), q2.clone()),
+ |b, (q1, q2)| {
+ b.iter(|| q1.distance(q2));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+fn bench_int4_distance(c: &mut Criterion) {
+ let mut group = c.benchmark_group("quantization/int4_distance");
+
+ for &dim in &[128usize, 384, 768, 1536] {
+ let v1 = gen_vector(dim, 42);
+ let v2 = gen_vector(dim, 123);
+ let q1 = Int4Quantized::quantize(&v1);
+ let q2 = Int4Quantized::quantize(&v2);
+
+ group.throughput(Throughput::Elements(dim as u64));
+ group.bench_with_input(
+ BenchmarkId::new("dim", dim),
+ &(q1.clone(), q2.clone()),
+ |b, (q1, q2)| {
+ b.iter(|| q1.distance(&q2));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+fn bench_scalar_distance(c: &mut Criterion) {
+ let mut group = c.benchmark_group("quantization/scalar_distance");
+
+ for &dim in &[128usize, 384, 768, 1536] {
+ let v1 = gen_vector(dim, 42);
+ let v2 = gen_vector(dim, 123);
+ let q1 = ScalarQuantized::quantize(&v1);
+ let q2 = ScalarQuantized::quantize(&v2);
+
+ group.throughput(Throughput::Elements(dim as u64));
+ group.bench_with_input(
+ BenchmarkId::new("dim", dim),
+ &(q1.clone(), q2.clone()),
+ |b, (q1, q2)| {
+ b.iter(|| q1.distance(q2));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ===========================================================================
+// Benchmark: Distance Speedup (quantized vs f32 baseline)
+// ===========================================================================
+
+fn bench_distance_speedup_comparison(c: &mut Criterion) {
+ let mut group = c.benchmark_group("quantization/distance_speedup");
+
+ let dim = 384;
+ let v1 = gen_vector(dim, 42);
+ let v2 = gen_vector(dim, 123);
+
+ // Pre-quantize
+ let scalar_q1 = ScalarQuantized::quantize(&v1);
+ let scalar_q2 = ScalarQuantized::quantize(&v2);
+ let int4_q1 = Int4Quantized::quantize(&v1);
+ let int4_q2 = Int4Quantized::quantize(&v2);
+ let binary_q1 = BinaryQuantized::quantize(&v1);
+ let binary_q2 = BinaryQuantized::quantize(&v2);
+
+ group.throughput(Throughput::Elements(dim as u64));
+
+ group.bench_function("f32_euclidean_sq", |b| {
+ b.iter(|| f32_distance_sq(&v1, &v2));
+ });
+
+ group.bench_function("scalar_u8_distance", |b| {
+ b.iter(|| scalar_q1.distance(&scalar_q2));
+ });
+
+ group.bench_function("int4_distance", |b| {
+ b.iter(|| int4_q1.distance(&int4_q2));
+ });
+
+ group.bench_function("binary_hamming", |b| {
+ b.iter(|| binary_q1.distance(&binary_q2));
+ });
+
+ group.finish();
+}
+
+// ===========================================================================
+// Benchmark: Batch Distance Computation
+// ===========================================================================
+
+fn bench_batch_distance(c: &mut Criterion) {
+ let mut group = c.benchmark_group("quantization/batch_distance");
+ group.sample_size(10);
+
+ let dim = 384;
+ let num_vectors = 10_000;
+
+ let query = gen_vector(dim, 42);
+ let vectors = gen_vectors(num_vectors, dim, 100);
+
+ // Pre-quantize all vectors
+ let binary_query = BinaryQuantized::quantize(&query);
+ let binary_db: Vec = vectors
+ .iter()
+ .map(|v| BinaryQuantized::quantize(v))
+ .collect();
+
+ let scalar_query = ScalarQuantized::quantize(&query);
+ let scalar_db: Vec = vectors
+ .iter()
+ .map(|v| ScalarQuantized::quantize(v))
+ .collect();
+
+ group.throughput(Throughput::Elements(num_vectors as u64));
+
+ group.bench_function("f32_batch_10k", |b| {
+ b.iter(|| {
+ let dists: Vec = vectors.iter().map(|v| f32_distance_sq(&query, v)).collect();
+ dists
+ });
+ });
+
+ group.bench_function("binary_batch_10k", |b| {
+ b.iter(|| {
+ let dists: Vec = binary_db
+ .iter()
+ .map(|v| binary_query.distance(v))
+ .collect();
+ dists
+ });
+ });
+
+ group.bench_function("scalar_batch_10k", |b| {
+ b.iter(|| {
+ let dists: Vec = scalar_db
+ .iter()
+ .map(|v| scalar_query.distance(v))
+ .collect();
+ dists
+ });
+ });
+
+ group.finish();
+}
+
+// ===========================================================================
+// Benchmark: Reconstruction Accuracy (quality check alongside speed)
+// ===========================================================================
+
+fn bench_reconstruction(c: &mut Criterion) {
+ let mut group = c.benchmark_group("quantization/reconstruction");
+
+ let dim = 384;
+
+ for &batch_size in &[100usize, 1_000] {
+ let vectors = gen_vectors(batch_size, dim, 42);
+
+ // Binary reconstruction
+ group.bench_with_input(
+ BenchmarkId::new("binary_reconstruct", batch_size),
+ &vectors,
+ |b, vectors| {
+ let quantized: Vec = vectors
+ .iter()
+ .map(|v| BinaryQuantized::quantize(v))
+ .collect();
+ b.iter(|| {
+ let reconstructed: Vec> =
+ quantized.iter().map(|q| q.reconstruct()).collect();
+ reconstructed
+ });
+ },
+ );
+
+ // Scalar reconstruction
+ group.bench_with_input(
+ BenchmarkId::new("scalar_reconstruct", batch_size),
+ &vectors,
+ |b, vectors| {
+ let quantized: Vec = vectors
+ .iter()
+ .map(|v| ScalarQuantized::quantize(v))
+ .collect();
+ b.iter(|| {
+ let reconstructed: Vec> =
+ quantized.iter().map(|q| q.reconstruct()).collect();
+ reconstructed
+ });
+ },
+ );
+
+ // Int4 reconstruction
+ group.bench_with_input(
+ BenchmarkId::new("int4_reconstruct", batch_size),
+ &vectors,
+ |b, vectors| {
+ let quantized: Vec = vectors
+ .iter()
+ .map(|v| Int4Quantized::quantize(v))
+ .collect();
+ b.iter(|| {
+ let reconstructed: Vec> =
+ quantized.iter().map(|q| q.reconstruct()).collect();
+ reconstructed
+ });
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ===========================================================================
+// Benchmark: Dimension Scaling (quantization cost vs vector size)
+// ===========================================================================
+
+fn bench_dimension_scaling(c: &mut Criterion) {
+ let mut group = c.benchmark_group("quantization/dimension_scaling");
+
+ for &dim in &[64usize, 128, 256, 384, 768, 1536, 3072] {
+ let v = gen_vector(dim, 42);
+
+ group.throughput(Throughput::Elements(dim as u64));
+
+ group.bench_with_input(
+ BenchmarkId::new("binary_quantize", dim),
+ &v,
+ |b, v| {
+ b.iter(|| BinaryQuantized::quantize(v));
+ },
+ );
+
+ group.bench_with_input(
+ BenchmarkId::new("int4_quantize", dim),
+ &v,
+ |b, v| {
+ b.iter(|| Int4Quantized::quantize(v));
+ },
+ );
+
+ group.bench_with_input(
+ BenchmarkId::new("scalar_quantize", dim),
+ &v,
+ |b, v| {
+ b.iter(|| ScalarQuantized::quantize(v));
+ },
+ );
+ }
+
+ group.finish();
+}
+
+// ===========================================================================
+// Benchmark: Memory Footprint (bytes per quantized vector)
+// ===========================================================================
+
+fn bench_memory_footprint(c: &mut Criterion) {
+ let mut group = c.benchmark_group("quantization/memory_footprint");
+
+ let dim = 384;
+ let v = gen_vector(dim, 42);
+
+ group.bench_function("measure_sizes", |b| {
+ b.iter(|| {
+ let f32_size = dim * std::mem::size_of::();
+ let scalar = ScalarQuantized::quantize(&v);
+ let scalar_size = scalar.data.len() + std::mem::size_of::();
+ let int4 = Int4Quantized::quantize(&v);
+ let int4_size = int4.data.len() + std::mem::size_of::();
+ let binary = BinaryQuantized::quantize(&v);
+ let binary_size = binary.bits.len() + std::mem::size_of::();
+ (f32_size, scalar_size, int4_size, binary_size)
+ });
+ });
+
+ group.finish();
+}
+
+criterion_group!(
+ benches,
+ bench_binary_quantize_throughput,
+ bench_int4_quantize_throughput,
+ bench_scalar_quantize_throughput,
+ bench_binary_distance,
+ bench_int4_distance,
+ bench_scalar_distance,
+ bench_distance_speedup_comparison,
+ bench_batch_distance,
+ bench_reconstruction,
+ bench_dimension_scaling,
+ bench_memory_footprint,
+);
+criterion_main!(benches);
diff --git a/crates/ruQu/docs/ddd/DDD-003-population-genomics-domain.md b/crates/ruQu/docs/ddd/DDD-003-population-genomics-domain.md
new file mode 100644
index 000000000..415f1b808
--- /dev/null
+++ b/crates/ruQu/docs/ddd/DDD-003-population-genomics-domain.md
@@ -0,0 +1,795 @@
+# DDD-003: Population Genomics Domain Model
+
+**Status**: Proposed
+**Date**: 2026-02-11
+**Authors**: ruv.io, RuVector Team
+**Related ADR**: ADR-001-ruqu-architecture
+**Related DDD**: DDD-001-coherence-gate-domain, DDD-002-syndrome-processing-domain
+
+---
+
+## Overview
+
+This document defines the Domain-Driven Design model for the Population Genomics bounded context -- the large-scale analytical subsystem that computes ancestry decomposition, kinship matrices, genome-wide association studies (GWAS), and natural selection signals across millions of individuals. The design exploits RuVector's HNSW indexing, distributed clustering, sparse inference, and subpolynomial dynamic min-cut to achieve order-of-magnitude speedups over current state-of-the-art tooling (PLINK 2.0, GCTA, ADMIXTURE).
+
+---
+
+## Strategic Design
+
+### Domain Vision Statement
+
+> The Population Genomics domain provides real-time, population-scale inference on genetic variation data, enabling ancestry estimation in sub-100ms, kinship computation for 1M samples in under 2.4 hours, and full-genome association scans at 10x throughput improvement over existing tools -- all powered by RuVector's vector-native architecture.
+
+### Core Domain
+
+**Population Structure Analysis** is the core domain. This is what differentiates the RuVector DNA Analyzer from traditional bioinformatics pipelines:
+
+- Not variant calling (that is upstream infrastructure)
+- Not quality control or imputation (those are supporting domains)
+- **The novel capability**: Treating every individual as a high-dimensional genotype vector, enabling vector-similarity operations (PCA, kinship, association) to run as native RuVector queries with HNSW-accelerated nearest-neighbor lookups and distributed sparse-matrix computation.
+
+### Supporting Domains
+
+| Domain | Role | Boundary |
+|--------|------|----------|
+| **Variant Ingestion** | Load VCF/BGEN/PLINK genotype data | Generic, infrastructure |
+| **Quality Control** | Filter samples and variants by missingness, HWE, MAF | Generic, pipeline |
+| **Imputation** | Fill missing genotypes from reference panels | External, existing tools |
+| **Phenotype Registry** | Store and validate phenotype/covariate data | Supporting, CRUD |
+| **Reference Panels** | 1000 Genomes, gnomAD allele frequency databases | External, read-only |
+
+### Generic Subdomains
+
+- Logging, observability, and audit trail
+- Job scheduling and compute orchestration
+- Authentication and access control (HIPAA/GDPR compliance)
+
+---
+
+## Ubiquitous Language
+
+### Core Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Individual** | A single sequenced organism with a genotype vector embedding | Aggregate root |
+| **Population** | A named group of individuals sharing demographic or geographic origin | Aggregate root |
+| **Genotype Vector** | A 384-dimensional embedding of an individual's multi-locus genotype, stored in ruvector-core | Value object |
+| **Allele Frequency** | The proportion of a given allele at a locus within a population | Value object |
+| **Fst** | Wright's fixation index measuring population differentiation (0 = identical, 1 = fixed) | Value object |
+| **Kinship Coefficient** | Probability that alleles drawn from two individuals are IBD | Value object |
+
+### Analysis Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **GWAS** | Genome-Wide Association Study: statistical scan testing each variant for phenotype association | Domain service |
+| **Manhattan Plot** | Visualization of -log10(p-values) across chromosomal positions | Value object |
+| **PCA** | Principal Component Analysis of the genotype matrix for population stratification | Domain service |
+| **Ancestry Component** | Fractional membership in a reference population (e.g., 0.42 European, 0.38 East Asian) | Value object |
+| **Selection Signal** | Evidence of natural selection acting on a genomic locus | Entity |
+| **GRM** | Genetic Relationship Matrix (n x n kinship matrix) | Value object |
+
+### Scalability Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Genotype Shard** | A partition of the genotype matrix distributed across ruvector-cluster nodes | Infrastructure |
+| **Hypergraph Sketch** | Khanna et al. sparsification of population structure as hypergraph with O-tilde(n) edges | Algorithm |
+| **Stratification Cut** | Dynamic min-cut partitioning of the population relatedness graph into subpopulations | Algorithm |
+
+---
+
+## Bounded Contexts
+
+### Context Map
+
+```
++-----------------------------------------------------------------------------+
+| POPULATION GENOMICS CONTEXT |
+| (Core Domain) |
+| +-------------+ +-------------+ +-------------+ +-------------+ |
+| | Ancestry | | Kinship | | GWAS | | Selection | |
+| | Engine | | Engine | | Engine | | Scanner | |
+| +-------------+ +-------------+ +-------------+ +-------------+ |
++-----------+--------------+--------------+--------------+--------------------+
+ | | | |
+ | Upstream | Upstream | Upstream | Downstream
+ v v v v
++-----------------+ +-----------------+ +-----------------+ +-----------------+
+| VARIANT | | PHENOTYPE | | REFERENCE | | REPORTING |
+| INGESTION | | REGISTRY | | PANELS | | CONTEXT |
+| (Supporting) | | (Supporting) | | (External) | | (Downstream) |
++-----------------+ +-----------------+ +-----------------+ +-----------------+
+```
+
+### Population Genomics Context (Core)
+
+**Responsibility**: Compute ancestry, kinship, association, and selection analyses at population scale.
+
+**Key Aggregates**:
+- Individual
+- Population
+- GWASResult
+- SelectionSignal
+
+**Anti-Corruption Layers**:
+- Variant Adapter (translates VCF/BGEN to genotype vectors)
+- Phenotype Adapter (translates clinical data to domain phenotype model)
+- Reference Panel Adapter (translates 1000G/gnomAD frequencies to domain format)
+
+### Variant Ingestion Context (Supporting)
+
+**Responsibility**: Parse, validate, and vectorize raw genotype files.
+
+**Key Aggregates**:
+- GenotypeFile
+- VariantCatalog
+- IngestionJob
+
+**Relationship**: Conformist -- conforms to Population Genomics Context's genotype vector schema.
+
+### Phenotype Registry Context (Supporting)
+
+**Responsibility**: Manage phenotype definitions, covariate data, and case/control assignments.
+
+**Key Aggregates**:
+- PhenotypeDefinition
+- CovariateSet
+- CohortAssignment
+
+**Relationship**: Customer-Supplier with Population Genomics Context.
+
+---
+
+## Aggregates
+
+### Individual (Root Aggregate)
+
+The central entity representing a genotyped organism.
+
+```
++---------------------------------------------------------------------+
+| INDIVIDUAL |
+| (Aggregate Root) |
++---------------------------------------------------------------------+
+| individual_id: IndividualId (UUID) |
+| sample_id: SampleId (external lab identifier) |
+| genotype_vector: GenotypeVector (384-dim f32, stored in HNSW) |
+| ancestry_components: Vec |
+| relatedness_edges: Vec |
+| metadata: IndividualMetadata |
+| created_at: Timestamp |
+| updated_at: Timestamp |
++---------------------------------------------------------------------+
+| +---------------------------------------------------------------+ |
+| | GenotypeVector (Value Object) | |
+| | dimensions: usize (384) | |
+| | embedding: Vec | |
+| | source_variants: usize (count of variants encoded) | |
+| | missing_rate: f32 (fraction of missing calls) | |
+| | encoding: GenotypeEncoding { Additive | Dominant | Recessive }| |
+| +---------------------------------------------------------------+ |
+| +---------------------------------------------------------------+ |
+| | AncestryComponent (Value Object) | |
+| | population_label: PopulationLabel | |
+| | proportion: f64 (0.0 .. 1.0) | |
+| | confidence_interval: (f64, f64) (lower, upper 95% CI) | |
+| +---------------------------------------------------------------+ |
+| +---------------------------------------------------------------+ |
+| | RelatednessEdge (Value Object) | |
+| | other_id: IndividualId | |
+| | kinship_coefficient: f64 | |
+| | relationship_degree: RelationshipDegree | |
+| | ibd_segments: usize | |
+| +---------------------------------------------------------------+ |
++---------------------------------------------------------------------+
+| Invariants: |
+| - genotype_vector dimensions must equal configured embedding size |
+| - ancestry_components proportions must sum to 1.0 (+/- epsilon) |
+| - kinship_coefficient in range [0.0, 0.5] |
+| - missing_rate in range [0.0, 1.0], must be below QC threshold |
++---------------------------------------------------------------------+
+```
+
+### Population (Aggregate Root)
+
+A defined group of individuals with computed summary statistics.
+
+```
++---------------------------------------------------------------------+
+| POPULATION |
+| (Aggregate Root) |
++---------------------------------------------------------------------+
+| population_id: PopulationId |
+| label: PopulationLabel |
+| description: String |
+| member_count: usize |
+| allele_frequencies: AlleleFrequencyMap |
+| fst_distances: FstMatrix |
+| demographic_history: Option |
+| centroid: GenotypeVector (mean embedding of members) |
++---------------------------------------------------------------------+
+| +---------------------------------------------------------------+ |
+| | AlleleFrequencyMap (Value Object) | |
+| | frequencies: HashMap | |
+| | variant_count: usize | |
+| | effective_sample_size: f64 | |
+| +---------------------------------------------------------------+ |
+| +---------------------------------------------------------------+ |
+| | FstMatrix (Value Object) | |
+| | populations: Vec | |
+| | values: Vec (upper-triangular packed) | |
+| | method: FstMethod { Weir | Hudson | Nei } | |
+| +---------------------------------------------------------------+ |
+| +---------------------------------------------------------------+ |
+| | DemographicHistory (Value Object) | |
+| | effective_sizes: Vec<(Generation, f64)> | |
+| | migration_rates: Vec<(PopulationId, PopulationId, f64)> | |
+| | divergence_times: Vec<(PopulationId, PopulationId, Generation)> |
+| +---------------------------------------------------------------+ |
++---------------------------------------------------------------------+
+| Invariants: |
+| - All allele frequencies in [0.0, 1.0] |
+| - Fst values in [0.0, 1.0] |
+| - FstMatrix is symmetric |
+| - member_count > 0 |
+| - centroid dimensions match configured embedding size |
++---------------------------------------------------------------------+
+```
+
+### GWASResult (Aggregate Root)
+
+The output of a genome-wide association scan.
+
+```
++---------------------------------------------------------------------+
+| GWAS RESULT |
+| (Aggregate Root) |
++---------------------------------------------------------------------+
+| gwas_id: GwasId |
+| phenotype: PhenotypeId |
+| model: AssociationModel { Linear | Logistic | Mixed } |
+| sample_count: usize |
+| variant_count: usize |
+| genomic_inflation: f64 (lambda_GC) |
+| significant_loci: Vec |
+| manhattan_plot: ManhattanPlot |
+| covariates_used: Vec |
+| pca_adjustment: usize (number of PCs used) |
+| created_at: Timestamp |
++---------------------------------------------------------------------+
+| +---------------------------------------------------------------+ |
+| | SignificantLocus (Entity) | |
+| | locus_id: LocusId | |
+| | variant_id: VariantId | |
+| | chromosome: Chromosome | |
+| | position: u64 | |
+| | p_value: f64 | |
+| | odds_ratio: Option (for binary traits) | |
+| | beta: Option (for continuous traits) | |
+| | standard_error: f64 | |
+| | effect_allele: Allele | |
+| | allele_frequency: f64 | |
+| +---------------------------------------------------------------+ |
+| +---------------------------------------------------------------+ |
+| | ManhattanPlot (Value Object) | |
+| | points: Vec | |
+| | significance_threshold: f64 (default 5e-8) | |
+| | suggestive_threshold: f64 (default 1e-5) | |
+| +---------------------------------------------------------------+ |
++---------------------------------------------------------------------+
+| Invariants: |
+| - genomic_inflation (lambda_GC) should be in [0.9, 1.1] for valid scan |
+| - p_values in (0.0, 1.0] |
+| - significant_loci sorted by p_value ascending |
+| - sample_count >= minimum for specified model |
++---------------------------------------------------------------------+
+```
+
+### SelectionSignal (Aggregate Root)
+
+Evidence of natural selection at a genomic locus.
+
+```
++---------------------------------------------------------------------+
+| SELECTION SIGNAL |
+| (Aggregate Root) |
++---------------------------------------------------------------------+
+| signal_id: SelectionSignalId |
+| locus: GenomicRegion { chromosome, start, end } |
+| selection_type: SelectionType { Positive | Balancing | Purifying } |
+| evidence_score: f64 (composite score, 0.0 - 1.0) |
+| statistics: Vec |
+| populations_affected: Vec |
+| candidate_gene: Option |
++---------------------------------------------------------------------+
+| +---------------------------------------------------------------+ |
+| | SelectionStatistic (Value Object) | |
+| | test_name: String (iHS, XP-EHH, Tajima's D, Fst-outlier) | |
+| | value: f64 | |
+| | p_value: f64 | |
+| | empirical_rank: f64 (percentile in genome-wide distribution) | |
+| +---------------------------------------------------------------+ |
++---------------------------------------------------------------------+
+| Invariants: |
+| - evidence_score in [0.0, 1.0] |
+| - At least one SelectionStatistic required |
+| - GenomicRegion.start < GenomicRegion.end |
+| - populations_affected non-empty |
++---------------------------------------------------------------------+
+```
+
+---
+
+## Value Objects
+
+### GenotypeVector
+
+384-dimensional embedding stored in ruvector-core HNSW index.
+
+```rust
+struct GenotypeVector {
+ embedding: [f32; 384],
+ source_variants: usize,
+ missing_rate: f32,
+ encoding: GenotypeEncoding,
+}
+
+impl GenotypeVector {
+ fn cosine_similarity(&self, other: &GenotypeVector) -> f32;
+ fn euclidean_distance(&self, other: &GenotypeVector) -> f32;
+ fn is_valid(&self) -> bool {
+ self.missing_rate <= MAX_MISSING_RATE
+ }
+}
+```
+
+### AlleleFrequency
+
+Frequency of a specific allele in a population.
+
+```rust
+struct AlleleFrequency {
+ variant_id: VariantId,
+ ref_allele: Allele,
+ alt_allele: Allele,
+ frequency: f64, // alt allele frequency
+ sample_count: usize, // number of non-missing samples
+ hw_p_value: f64, // Hardy-Weinberg equilibrium test
+}
+
+impl AlleleFrequency {
+ fn is_polymorphic(&self) -> bool {
+ self.frequency > 0.0 && self.frequency < 1.0
+ }
+ fn minor_allele_frequency(&self) -> f64 {
+ self.frequency.min(1.0 - self.frequency)
+ }
+}
+```
+
+### KinshipCoefficient
+
+Pairwise kinship with relationship inference.
+
+```rust
+struct KinshipCoefficient {
+ value: f64,
+ ibd0: f64, // P(0 alleles IBD)
+ ibd1: f64, // P(1 allele IBD)
+ ibd2: f64, // P(2 alleles IBD)
+}
+
+impl KinshipCoefficient {
+ fn relationship_degree(&self) -> RelationshipDegree {
+ match self.value {
+ v if v > 0.354 => RelationshipDegree::Duplicate,
+ v if v > 0.177 => RelationshipDegree::First, // parent-child, siblings
+ v if v > 0.0884 => RelationshipDegree::Second, // grandparent, uncle
+ v if v > 0.0442 => RelationshipDegree::Third,
+ _ => RelationshipDegree::Unrelated,
+ }
+ }
+}
+```
+
+### GenomicRegion
+
+A contiguous span on a chromosome.
+
+```rust
+struct GenomicRegion {
+ chromosome: Chromosome,
+ start: u64,
+ end: u64,
+}
+
+impl GenomicRegion {
+ fn length(&self) -> u64 { self.end - self.start }
+ fn overlaps(&self, other: &GenomicRegion) -> bool {
+ self.chromosome == other.chromosome
+ && self.start < other.end
+ && other.start < self.end
+ }
+}
+```
+
+---
+
+## Domain Events
+
+### Analysis Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `IndividualGenotyped` | Genotype vector computed | individual_id, vector_hash, variant_count |
+| `AncestryInferred` | Ancestry estimation complete | individual_id, components, method |
+| `KinshipComputed` | Pairwise kinship calculated | individual_pair, coefficient, relationship |
+| `GRMConstructed` | Full kinship matrix built | population_id, dimension, compute_time |
+| `PCACompleted` | Principal components extracted | population_id, n_components, variance_explained |
+
+### GWAS Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `GWASScanStarted` | Scan initiated | gwas_id, phenotype, sample_count, variant_count |
+| `GWASScanCompleted` | Full scan done | gwas_id, significant_count, lambda_gc, duration |
+| `SignificantLocusFound` | p < threshold | gwas_id, locus_id, variant_id, p_value |
+| `GenomicInflationWarning` | lambda_GC outside [0.9, 1.1] | gwas_id, lambda_gc |
+
+### Population Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `PopulationDefined` | New population created | population_id, label, member_count |
+| `AlleleFrequenciesUpdated` | Frequencies recomputed | population_id, variant_count |
+| `FstMatrixUpdated` | Differentiation recalculated | population_ids, mean_fst |
+| `PopulationStratificationDetected` | Min-cut identifies substructure | population_id, cut_value, subgroups |
+| `SelectionSignalDetected` | Selection test significant | signal_id, locus, selection_type, score |
+
+---
+
+## Domain Services
+
+### AncestryInferenceService
+
+Per-sample ancestry estimation using HNSW nearest-neighbor search.
+
+```rust
+trait AncestryInferenceService {
+ /// Infer ancestry for a single individual in <100ms
+ /// Uses ruvector-core HNSW to find k nearest reference panel individuals,
+ /// then computes soft clustering via weighted nearest-neighbor assignment.
+ async fn infer_ancestry(
+ &self,
+ individual: &Individual,
+ reference_panel: &ReferencePanel,
+ k: usize,
+ ) -> Result, AncestryError>;
+
+ /// Batch ancestry for a cohort using ruvector-cluster distributed search
+ async fn infer_batch(
+ &self,
+ individuals: &[IndividualId],
+ reference_panel: &ReferencePanel,
+ ) -> Result)>, AncestryError>;
+
+ /// Update ancestry as new reference samples arrive (incremental)
+ async fn update_references(
+ &self,
+ new_references: &[Individual],
+ ) -> Result<(), AncestryError>;
+}
+```
+
+**Performance bound**: Per-sample inference in O(log n) via HNSW where n = reference panel size. Target <100ms for panels up to 10M individuals.
+
+### KinshipComputationService
+
+Genetic relationship matrix construction using sparse-matrix operations.
+
+```rust
+trait KinshipComputationService {
+ /// Construct the GRM for n individuals
+ /// Uses ruvector-sparse-inference for sparse matrix multiply:
+ /// GRM = (1/m) * Z * Z^T where Z is standardized genotype matrix
+ ///
+ /// Complexity: O(n^2 * m / p) with p cluster nodes via ruvector-cluster
+ /// where m = variants, n = individuals
+ async fn compute_grm(
+ &self,
+ population: &PopulationId,
+ config: GrmConfig,
+ ) -> Result;
+
+ /// Sparse kinship for specific pairs only (avoid full n^2)
+ /// Uses HNSW pre-filtering: only compute kinship for pairs
+ /// within distance threshold in embedding space
+ async fn compute_sparse_kinship(
+ &self,
+ population: &PopulationId,
+ distance_threshold: f32,
+ ) -> Result;
+
+ /// Identify close relatives (kinship > threshold)
+ async fn find_relatives(
+ &self,
+ individual: &IndividualId,
+ threshold: f64,
+ ) -> Result, KinshipError>;
+}
+```
+
+**Performance bound**: 1M x 1M GRM in <2.4 hours. This exploits ruvector-sparse-inference for the Z*Z^T product with block-sparse structure (most pairs are unrelated, yielding kinship near zero). Distributed across ruvector-cluster nodes, the block-sparse multiply achieves O(n * k_eff * m / p) where k_eff is the effective number of related pairs per individual (typically O(sqrt(n)) due to population structure), yielding a 10x improvement over the naive O(n^2 * m) GCTA approach.
+
+### GWASService
+
+Genome-wide association scan using distributed computation.
+
+```rust
+trait GWASService {
+ /// Run full GWAS scan
+ /// Each variant test is independent -> embarrassingly parallel across
+ /// ruvector-cluster nodes. Uses ruvector-sparse-inference for mixed
+ /// model computations (GRAMMAR approximation with pre-computed GRM).
+ async fn run_scan(
+ &self,
+ phenotype: &PhenotypeId,
+ config: GwasConfig,
+ ) -> Result;
+
+ /// Incremental GWAS: test additional variants against existing model
+ async fn extend_scan(
+ &self,
+ gwas_id: &GwasId,
+ new_variants: &[VariantId],
+ ) -> Result, GwasError>;
+
+ /// Conditional analysis: test loci adjusting for known signals
+ async fn conditional_analysis(
+ &self,
+ gwas_id: &GwasId,
+ conditioning_variants: &[VariantId],
+ ) -> Result;
+}
+```
+
+**Performance bound**: Full scan of 10M variants x 1M samples in <1 hour. Sharding strategy: variants are partitioned across ruvector-cluster nodes (each node tests m/p variants), with the pre-computed GRM inverse broadcast once. Per-variant test cost: O(n) for score test, yielding total O(n * m / p). With p=100 nodes and SIMD-vectorized score tests, the 1-hour target requires ~28K variant-tests/second/node, well within ruvector-sparse-inference's SIMD throughput.
+
+### PopulationStratificationService
+
+Dynamic population structure detection using min-cut.
+
+```rust
+trait PopulationStratificationService {
+ /// Run PCA on the genotype matrix
+ /// Uses randomized SVD via ruvector-sparse-inference:
+ /// Complexity O(n * m * k) for top-k components where k << min(n, m)
+ async fn compute_pca(
+ &self,
+ population: &PopulationId,
+ n_components: usize,
+ ) -> Result;
+
+ /// Detect population substructure using dynamic min-cut
+ /// Models the relatedness graph as a weighted graph where edge weights
+ /// are kinship coefficients. Uses ruvector-mincut subpolynomial algorithm
+ /// for real-time stratification as new samples arrive.
+ ///
+ /// Complexity: O(n^{o(1)}) amortized per sample insertion
+ /// (arXiv:2512.13105, El-Hayek/Henzinger/Li SODA 2025)
+ async fn detect_substructure(
+ &self,
+ population: &PopulationId,
+ ) -> Result, StratificationError>;
+
+ /// Update stratification incrementally as new samples arrive
+ /// Uses hypergraph sparsification (Khanna et al.) to maintain
+ /// an O-tilde(n) sketch of the population structure hypergraph
+ async fn update_incremental(
+ &self,
+ population: &PopulationId,
+ new_individuals: &[IndividualId],
+ ) -> Result;
+}
+```
+
+**Performance bound**: PCA of first 20 components for 1M samples in <30 minutes via randomized SVD with O(n * m * k) complexity. Dynamic stratification via subpolynomial min-cut yields O(n^{o(1)}) = 2^{O(log^{1-c} n)} amortized update time per new sample, per arXiv:2512.13105. The hypergraph sketch (Khanna et al.) reduces the population structure from O(n^2) pairwise edges to O-tilde(n) hyperedges while preserving all cuts within (1 +/- epsilon).
+
+---
+
+## Repositories
+
+### IndividualRepository
+
+```rust
+trait IndividualRepository {
+ /// Store individual with genotype vector indexed in HNSW
+ async fn store(&self, individual: Individual) -> Result<(), StoreError>;
+
+ /// Find by ID
+ async fn find_by_id(&self, id: &IndividualId) -> Option;
+
+ /// Find nearest neighbors in genotype space (ancestry similarity)
+ /// Delegates to ruvector-core HNSW search
+ async fn find_nearest(
+ &self,
+ query: &GenotypeVector,
+ k: usize,
+ ) -> Result, SearchError>;
+
+ /// Find all individuals in a population
+ async fn find_by_population(&self, pop: &PopulationId) -> Vec;
+
+ /// Count total individuals
+ async fn count(&self) -> usize;
+
+ /// Batch insert (for initial data loading)
+ async fn store_batch(
+ &self,
+ individuals: Vec,
+ ) -> Result;
+}
+```
+
+### PopulationRepository
+
+```rust
+trait PopulationRepository {
+ async fn store(&self, population: Population) -> Result<(), StoreError>;
+ async fn find_by_id(&self, id: &PopulationId) -> Option;
+ async fn find_by_label(&self, label: &PopulationLabel) -> Option;
+ async fn list_all(&self) -> Vec;
+ async fn update_frequencies(
+ &self,
+ id: &PopulationId,
+ frequencies: AlleleFrequencyMap,
+ ) -> Result<(), StoreError>;
+}
+```
+
+### GWASResultRepository
+
+```rust
+trait GWASResultRepository {
+ async fn store(&self, result: GWASResult) -> Result<(), StoreError>;
+ async fn find_by_id(&self, id: &GwasId) -> Option;
+ async fn find_by_phenotype(&self, phenotype: &PhenotypeId) -> Vec;
+ async fn find_significant_loci(
+ &self,
+ gwas_id: &GwasId,
+ p_threshold: f64,
+ ) -> Vec;
+}
+```
+
+### SelectionSignalRepository
+
+```rust
+trait SelectionSignalRepository {
+ async fn store(&self, signal: SelectionSignal) -> Result<(), StoreError>;
+ async fn find_by_region(&self, region: &GenomicRegion) -> Vec;
+ async fn find_by_type(&self, stype: SelectionType) -> Vec;
+ async fn find_top_signals(&self, n: usize) -> Vec;
+}
+```
+
+---
+
+## RuVector Integration Architecture
+
+### Crate Mapping
+
+| Domain Operation | RuVector Crate | Mechanism |
+|-----------------|----------------|-----------|
+| Genotype vector storage + HNSW search | `ruvector-core` | 384-dim HNSW index, O(log n) ANN |
+| Distributed GRM/GWAS computation | `ruvector-cluster` | Shard genotype matrix across nodes |
+| Sparse GRM multiply (Z*Z^T) | `ruvector-sparse-inference` | Block-sparse SIMD matrix ops |
+| Population structure hypergraph | `ruvector-core::advanced::hypergraph` | Hyperedge representation |
+| Dynamic stratification min-cut | `ruvector-mincut::subpolynomial` | O(n^{o(1)}) amortized updates |
+| Randomized SVD for PCA | `ruvector-sparse-inference` | Low-rank approximation |
+| Selection scan parallelism | `ruvector-cluster` | Variant-parallel distributed scan |
+
+### Performance Targets with Complexity Bounds
+
+| Operation | Target | Complexity | Bound Source |
+|-----------|--------|------------|--------------|
+| Ancestry inference (per sample) | <100ms | O(log n) HNSW search | ruvector-core benchmarks |
+| GRM construction (1M x 1M) | <2.4 hours | O(n * k_eff * m / p) sparse | ruvector-sparse-inference |
+| PCA (20 components, 1M samples) | <30 minutes | O(n * m * k) randomized SVD | Halko et al. 2011 |
+| GWAS (10M variants x 1M samples) | <1 hour | O(n * m / p) distributed | ruvector-cluster |
+| Stratification update (per sample) | O(n^{o(1)}) | 2^{O(log^{1-c} n)} amortized | arXiv:2512.13105 |
+| Hypergraph sketch maintenance | O-tilde(n) space | Sparsification preserving cuts | Khanna et al. |
+
+---
+
+## Invariants and Business Rules
+
+### Individual Invariants
+
+1. **Vector Dimensionality**: Genotype vector must be exactly 384 dimensions
+2. **Ancestry Sum-to-One**: Ancestry component proportions must sum to 1.0 within floating-point tolerance (|sum - 1.0| < 1e-6)
+3. **QC Thresholds**: Missing rate must be below configured maximum (default 0.05)
+4. **Unique Sample ID**: sample_id must be unique across the system
+
+### GWAS Invariants
+
+1. **Minimum Sample Size**: GWAS requires minimum n=100 for linear, n=50 cases + 50 controls for logistic
+2. **Inflation Control**: Lambda_GC must be logged and flagged if outside [0.9, 1.1]
+3. **Multiple Testing**: Genome-wide significance requires p < 5e-8 (Bonferroni for ~1M independent tests)
+4. **Covariate Completeness**: All covariates must be non-missing for included samples
+
+### Population Invariants
+
+1. **Non-Empty**: Populations must have at least one member
+2. **Fst Symmetry**: Fst matrix must be symmetric with zero diagonal
+3. **Frequency Range**: All allele frequencies must be in [0.0, 1.0]
+
+---
+
+## Anti-Corruption Layers
+
+### Variant Ingestion ACL
+
+Translates VCF/BGEN/PLINK binary formats to domain genotype vectors.
+
+```rust
+impl VariantIngestionAcl {
+ /// Convert raw genotype calls to 384-dim embedding
+ /// Uses additive encoding (0/1/2) -> PCA projection -> HNSW-compatible vector
+ fn vectorize(&self, genotypes: &RawGenotypes) -> Result {
+ let additive = self.encode_additive(genotypes);
+ let standardized = self.standardize(additive);
+ let embedding = self.project_to_embedding(standardized);
+ Ok(GenotypeVector {
+ embedding,
+ source_variants: genotypes.variant_count(),
+ missing_rate: genotypes.missing_fraction(),
+ encoding: GenotypeEncoding::Additive,
+ })
+ }
+}
+```
+
+### Reference Panel ACL
+
+Translates external reference databases to domain model.
+
+```rust
+impl ReferencePanelAcl {
+ fn translate(&self, panel: ExternalPanel) -> ReferencePanel {
+ ReferencePanel {
+ individuals: panel.samples.iter()
+ .map(|s| self.to_domain_individual(s))
+ .collect(),
+ populations: panel.populations.iter()
+ .map(|p| self.to_domain_population(p))
+ .collect(),
+ }
+ }
+}
+```
+
+---
+
+## Context Boundaries Summary
+
+| Boundary | Upstream | Downstream | Integration Pattern |
+|----------|----------|------------|---------------------|
+| Variant -> PopGen | Variant Ingestion | Population Genomics | Published Language (GenotypeVector) |
+| PopGen -> Reporting | Population Genomics | Reporting Context | Domain Events (GWASScanCompleted) |
+| RefPanel -> PopGen | Reference Panels | Population Genomics | ACL (ReferencePanel) |
+| Phenotype -> PopGen | Phenotype Registry | Population Genomics | Customer-Supplier (PhenotypeData) |
+
+---
+
+## References
+
+- DDD-001: Coherence Gate Domain Model
+- DDD-002: Syndrome Processing Domain Model
+- arXiv:2512.13105 -- El-Hayek, Henzinger, Li. "Deterministic and Exact Fully-dynamic Minimum Cut of Superpolylogarithmic Size in Subpolynomial Time" (SODA 2025)
+- Khanna et al. -- Hypergraph sparsification with O-tilde(n) sketch preserving all cuts
+- Halko, Martinsson, Tropp. "Finding Structure with Randomness" (2011) -- randomized SVD bounds
+- Evans, Eric. "Domain-Driven Design." Addison-Wesley, 2003.
+- Vernon, Vaughn. "Implementing Domain-Driven Design." Addison-Wesley, 2013.
diff --git a/crates/ruQu/docs/ddd/DDD-004-pharmacogenomics-domain.md b/crates/ruQu/docs/ddd/DDD-004-pharmacogenomics-domain.md
new file mode 100644
index 000000000..71302852d
--- /dev/null
+++ b/crates/ruQu/docs/ddd/DDD-004-pharmacogenomics-domain.md
@@ -0,0 +1,950 @@
+# DDD-004: Pharmacogenomics Domain Model
+
+**Status**: Proposed
+**Date**: 2026-02-11
+**Authors**: ruv.io, RuVector Team
+**Related ADR**: ADR-001-ruqu-architecture
+**Related DDD**: DDD-001-coherence-gate-domain, DDD-003-population-genomics-domain
+
+---
+
+## Overview
+
+This document defines the Domain-Driven Design model for the Pharmacogenomics bounded context -- the clinical decision-support subsystem that predicts individual drug responses from genomic data, determines metabolizer phenotypes from star allele diplotypes, generates evidence-graded dosing recommendations, and assesses adverse drug reaction (ADR) risk. The design integrates RuVector's GNN for drug-gene interaction prediction, attention mechanisms for sequence-to-phenotype inference, and vector similarity search for finding patients with analogous pharmacogenomic profiles.
+
+---
+
+## Strategic Design
+
+### Domain Vision Statement
+
+> The Pharmacogenomics domain translates an individual's genetic variation at pharmacogenes into actionable clinical guidance: metabolizer status classification, dose adjustments, drug interaction warnings, and adverse reaction risk scores -- powered by RuVector's graph neural networks for interaction prediction and HNSW-based similar-patient retrieval for treatment outcome inference.
+
+### Core Domain
+
+**Pharmacogenetic Interpretation** is the core domain. This is the novel analytical capability:
+
+- Not genotyping (that is upstream infrastructure shared with Population Genomics)
+- Not drug databases (those are external reference data)
+- **The novel capability**: Predicting individualized drug response by combining star-allele diplotyping, metabolizer phenotype inference, evidence-weighted dosing recommendation generation, and GNN-powered interaction discovery -- with RuVector enabling fast similar-patient lookup to ground predictions in real-world treatment outcomes.
+
+### Supporting Domains
+
+| Domain | Role | Boundary |
+|--------|------|----------|
+| **Variant Ingestion** | Provide called genotypes at pharmacogene loci | Shared with Population Genomics |
+| **Drug Knowledge Base** | PharmGKB, CPIC, DPWG guideline data | External, read-only |
+| **Clinical Data** | Patient medication lists, lab values, outcomes | External, EHR integration |
+| **Population Genomics** | Ancestry-adjusted allele frequencies for star allele calling | Upstream bounded context |
+
+### Generic Subdomains
+
+- Audit logging (FDA 21 CFR Part 11 compliance)
+- Version control for guideline updates
+- Patient consent and data governance
+
+---
+
+## Ubiquitous Language
+
+### Core Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Star Allele** | A named haplotype at a pharmacogene (e.g., CYP2D6*4, CYP2C19*17) | Value object |
+| **Diplotype** | The pair of star alleles an individual carries at a gene (e.g., *1/*4) | Value object |
+| **Metabolizer Status** | The predicted enzyme activity phenotype: PM, IM, NM, RM, UM | Value object |
+| **Activity Score** | Numeric score assigned to a diplotype (sum of allele activities) | Value object |
+| **Drug-Gene Interaction** | A relationship between a drug and a gene where genetic variation affects response | Entity |
+| **Dosing Recommendation** | An evidence-graded adjustment to standard drug dosing based on genotype | Entity |
+| **Adverse Drug Reaction** | A harmful, unintended response to a drug linked to a genetic variant | Entity |
+
+### Classification Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **PM** | Poor Metabolizer -- little to no enzyme activity, drug may accumulate | Phenotype |
+| **IM** | Intermediate Metabolizer -- reduced activity | Phenotype |
+| **NM** | Normal Metabolizer -- typical activity (formerly "EM") | Phenotype |
+| **RM** | Rapid Metabolizer -- increased activity | Phenotype |
+| **UM** | Ultrarapid Metabolizer -- greatly increased activity, prodrug over-activation | Phenotype |
+
+### Evidence Terms
+
+| Term | Definition | Context |
+|------|------------|---------|
+| **Evidence Level** | Strength of pharmacogenomic evidence (1A, 1B, 2A, 2B, 3, 4 per PharmGKB) | Value object |
+| **CPIC Level** | Clinical Pharmacogenetics Implementation Consortium guideline strength (A, B, C) | Value object |
+| **Actionability** | Whether a drug-gene pair has sufficient evidence for clinical action | Classification |
+
+---
+
+## Bounded Contexts
+
+### Context Map
+
+```
++-----------------------------------------------------------------------------+
+| PHARMACOGENOMICS CONTEXT |
+| (Core Domain) |
+| +-------------+ +-------------+ +-------------+ +-------------+ |
+| | Star Allele | | Metabolizer | | Dosing | | ADR | |
+| | Caller | | Classifier | | Recommender| | Assessor | |
+| +-------------+ +-------------+ +-------------+ +-------------+ |
++-----------+--------------+--------------+--------------+--------------------+
+ | | | |
+ | Upstream | Upstream | External | Downstream
+ v v v v
++-----------------+ +-----------------+ +-----------------+ +-----------------+
+| VARIANT | | POPULATION | | DRUG | | CLINICAL |
+| INGESTION | | GENOMICS | | KNOWLEDGE BASE | | DECISION |
+| (Supporting) | | (Upstream BC) | | (External) | | SUPPORT |
++-----------------+ +-----------------+ +-----------------+ +-----------------+
+```
+
+### Pharmacogenomics Context (Core)
+
+**Responsibility**: Determine star allele diplotypes, classify metabolizer status, generate dosing recommendations, assess ADR risk, and predict drug-gene interactions using GNN.
+
+**Key Aggregates**:
+- PharmacogeneticProfile
+- DrugGeneInteraction
+- DosingRecommendation
+- AdverseDrugReaction
+
+**Anti-Corruption Layers**:
+- Variant Adapter (translates raw genotypes at pharmacogene loci to star allele calls)
+- Drug Knowledge Base Adapter (translates PharmGKB/CPIC/DPWG data to domain model)
+- Clinical Data Adapter (translates EHR medication and lab data to domain format)
+- Population Adapter (translates ancestry-adjusted frequencies from Population Genomics)
+
+---
+
+## Aggregates
+
+### PharmacogeneticProfile (Root Aggregate)
+
+The central aggregate containing all pharmacogenomic information for an individual.
+
+```
++---------------------------------------------------------------------+
+| PHARMACOGENETIC PROFILE |
+| (Aggregate Root) |
++---------------------------------------------------------------------+
+| profile_id: ProfileId (UUID) |
+| individual_id: IndividualId (link to Population Genomics) |
+| star_alleles: Vec |
+| metabolizer_statuses: Vec |
+| drug_interactions: Vec |
+| profile_vector: ProfileVector (384-dim, for similar-patient search) |
+| evidence_summary: EvidenceSummary |
+| created_at: Timestamp |
+| guideline_version: GuidelineVersion |
++---------------------------------------------------------------------+
+| +---------------------------------------------------------------+ |
+| | StarAlleleDiplotype (Value Object) | |
+| | gene: PharmaGene (CYP2D6, CYP2C19, CYP2C9, CYP3A5, ...) | |
+| | allele_1: StarAllele (e.g., *1) | |
+| | allele_2: StarAllele (e.g., *4) | |
+| | activity_score: f64 (sum of allele activity values) | |
+| | call_confidence: f64 (0.0 - 1.0) | |
+| | phasing_method: PhasingMethod { Statistical | Read | Family } | |
+| +---------------------------------------------------------------+ |
+| +---------------------------------------------------------------+ |
+| | MetabolizerStatus (Value Object) | |
+| | gene: PharmaGene | |
+| | phenotype: MetabolizerPhenotype { PM | IM | NM | RM | UM } | |
+| | activity_score: f64 | |
+| | classification_source: ClassificationSource { CPIC | DPWG } | |
+| +---------------------------------------------------------------+ |
+| +---------------------------------------------------------------+ |
+| | DrugInteractionAssessment (Entity) | |
+| | assessment_id: AssessmentId | |
+| | drug: DrugId | |
+| | gene: PharmaGene | |
+| | effect: DrugEffect { Efficacy | Toxicity | Dosing } | |
+| | severity: Severity { High | Moderate | Low | Informational } | |
+| | recommendation: String (clinical action) | |
+| | evidence_level: EvidenceLevel | |
+| +---------------------------------------------------------------+ |
++---------------------------------------------------------------------+
+| Invariants: |
+| - Each gene appears at most once in star_alleles |
+| - Each gene in metabolizer_statuses must have a corresponding |
+| star_allele diplotype |
+| - activity_score >= 0.0 |
+| - call_confidence in [0.0, 1.0] |
+| - guideline_version must be a valid published version |
++---------------------------------------------------------------------+
+```
+
+### DrugGeneInteraction (Aggregate Root)
+
+A curated or predicted relationship between a drug and a gene.
+
+```
++---------------------------------------------------------------------+
+| DRUG-GENE INTERACTION |
+| (Aggregate Root) |
++---------------------------------------------------------------------+
+| interaction_id: InteractionId |
+| drug: DrugId |
+| drug_name: String |
+| gene: PharmaGene |
+| alleles_affected: Vec |
+| effect: DrugEffect { Efficacy | Toxicity | Dosing } |
+| evidence_level: EvidenceLevel { Level1A | 1B | 2A | 2B | 3 | 4 } |
+| cpic_level: Option |
+| phenotype_mapping: HashMap |
+| source: InteractionSource { CPIC | DPWG | PharmGKB | Predicted } |
+| prediction_confidence: Option (for GNN-predicted interactions) |
++---------------------------------------------------------------------+
+| +---------------------------------------------------------------+ |
+| | ClinicalImpact (Value Object) | |
+| | impact_description: String | |
+| | dose_adjustment: Option | |
+| | alternative_drugs: Vec | |
+| | monitoring_required: bool | |
+| +---------------------------------------------------------------+ |
++---------------------------------------------------------------------+
+| Invariants: |
+| - evidence_level must be from valid PharmGKB hierarchy |
+| - prediction_confidence required iff source == Predicted |
+| - prediction_confidence (when present) in [0.0, 1.0] |
+| - phenotype_mapping must cover at least PM and NM phenotypes |
++---------------------------------------------------------------------+
+```
+
+### DosingRecommendation (Aggregate Root)
+
+An evidence-graded dosing adjustment for a specific drug-genotype combination.
+
+```
++---------------------------------------------------------------------+
+| DOSING RECOMMENDATION |
+| (Aggregate Root) |
++---------------------------------------------------------------------+
+| recommendation_id: RecommendationId |
+| drug: DrugId |
+| genotype_context: GenotypeContext |
+| standard_dose: Dose |
+| recommended_dose: Dose |
+| adjustment_factor: f64 (multiplier, e.g., 0.5 for half-dose) |
+| confidence: ConfidenceGrade { High | Moderate | Low } |
+| source_guideline: GuidelineReference |
+| clinical_rationale: String |
+| contraindicated: bool |
++---------------------------------------------------------------------+
+| +---------------------------------------------------------------+ |
+| | GenotypeContext (Value Object) | |
+| | gene: PharmaGene | |
+| | diplotype: StarAlleleDiplotype | |
+| | metabolizer_status: MetabolizerPhenotype | |
+| | activity_score: f64 | |
+| +---------------------------------------------------------------+ |
+| +---------------------------------------------------------------+ |
+| | Dose (Value Object) | |
+| | amount: f64 | |
+| | unit: DoseUnit { Mg | MgPerKg | MgPerM2 } | |
+| | frequency: Frequency { Daily | BID | TID | QID | Weekly } | |
+| | route: Route { Oral | IV | IM | Topical | Inhaled } | |
+| +---------------------------------------------------------------+ |
+| +---------------------------------------------------------------+ |
+| | GuidelineReference (Value Object) | |
+| | source: GuidelineSource { CPIC | DPWG | FDA | InHouse } | |
+| | guideline_id: String | |
+| | version: String | |
+| | publication_date: Date | |
+| | url: Option | |
+| +---------------------------------------------------------------+ |
++---------------------------------------------------------------------+
+| Invariants: |
+| - adjustment_factor > 0.0 (unless contraindicated, then 0.0) |
+| - If contraindicated, recommended_dose must be zero |
+| - source_guideline must reference a published, version-tracked |
+| guideline |
+| - confidence must reflect the weakest evidence in the chain |
++---------------------------------------------------------------------+
+```
+
+### AdverseDrugReaction (Aggregate Root)
+
+A genetically-mediated adverse drug reaction risk assessment.
+
+```
++---------------------------------------------------------------------+
+| ADVERSE DRUG REACTION |
+| (Aggregate Root) |
++---------------------------------------------------------------------+
+| adr_id: AdrId |
+| drug: DrugId |
+| variant: VariantId (typically HLA allele or specific SNP) |
+| gene: PharmaGene |
+| reaction_type: ReactionType { SJS | DRESS | Hepatotoxicity | |
+| QTProlongation | Myopathy | |
+| Anaphylaxis | Other(String) } |
+| severity: AdrSeverity { LifeThreatening | Severe | Moderate | Mild } |
+| frequency: AdrFrequency { value: f64, population: PopulationId } |
+| risk_allele: Allele |
+| risk_score: f64 (0.0 - 1.0, individual's risk given genotype) |
+| evidence_level: EvidenceLevel |
+| clinical_action: ClinicalAction { Avoid | Monitor | TestFirst } |
++---------------------------------------------------------------------+
+| +---------------------------------------------------------------+ |
+| | AdrFrequency (Value Object) | |
+| | value: f64 (proportion of risk-allele carriers affected) | |
+| | population: PopulationId (ancestry-specific frequency) | |
+| | total_cases: usize | |
+| | total_exposed: usize | |
+| +---------------------------------------------------------------+ |
++---------------------------------------------------------------------+
+| Invariants: |
+| - risk_score in [0.0, 1.0] |
+| - frequency.value in [0.0, 1.0] |
+| - LifeThreatening ADRs must have clinical_action == Avoid |
+| - frequency.total_exposed > 0 |
++---------------------------------------------------------------------+
+```
+
+---
+
+## Value Objects
+
+### StarAllele
+
+A named haplotype at a pharmacogene.
+
+```rust
+struct StarAllele {
+ gene: PharmaGene,
+ name: String, // e.g., "*4", "*17"
+ defining_variants: Vec,
+ function: AlleleFunction, // NoFunction, Decreased, Normal, Increased
+ activity_value: f64, // 0.0, 0.5, 1.0, 1.5, 2.0 per CPIC
+}
+
+impl StarAllele {
+ fn is_no_function(&self) -> bool {
+ matches!(self.function, AlleleFunction::NoFunction)
+ }
+ fn is_increased_function(&self) -> bool {
+ matches!(self.function, AlleleFunction::Increased)
+ }
+}
+```
+
+### ProfileVector
+
+384-dimensional embedding of a pharmacogenomic profile for similar-patient search.
+
+```rust
+struct ProfileVector {
+ embedding: [f32; 384],
+ genes_encoded: Vec,
+ encoding_version: u32,
+}
+
+impl ProfileVector {
+ /// Construct from star allele diplotypes
+ /// Encodes metabolizer status, activity scores, and interaction pattern
+ /// into a dense vector suitable for ruvector-core HNSW indexing
+ fn from_profile(profile: &PharmacogeneticProfile) -> Self;
+
+ /// Find similar pharmacogenomic profiles via HNSW nearest-neighbor
+ fn similarity(&self, other: &ProfileVector) -> f32;
+}
+```
+
+### EvidenceLevel
+
+PharmGKB evidence classification.
+
+```rust
+enum EvidenceLevel {
+ Level1A, // Variant-drug in CPIC/DPWG guideline, clinical annotation
+ Level1B, // Variant-drug in PharmGKB clinical annotation
+ Level2A, // Variant-drug in VIP with known functional significance
+ Level2B, // Variant in VIP with evidence of PGx association
+ Level3, // Annotations with limited evidence
+ Level4, // Case reports, non-significant studies
+}
+
+impl EvidenceLevel {
+ fn is_actionable(&self) -> bool {
+ matches!(self, Self::Level1A | Self::Level1B | Self::Level2A)
+ }
+ fn confidence_weight(&self) -> f64 {
+ match self {
+ Self::Level1A => 1.0,
+ Self::Level1B => 0.9,
+ Self::Level2A => 0.75,
+ Self::Level2B => 0.5,
+ Self::Level3 => 0.25,
+ Self::Level4 => 0.1,
+ }
+ }
+}
+```
+
+### DoseAdjustment
+
+Quantified dose modification.
+
+```rust
+struct DoseAdjustment {
+ direction: AdjustmentDirection { Increase | Decrease | Contraindicate | NoChange },
+ factor: f64, // e.g., 0.5 for 50% reduction
+ absolute_change: Option, // alternative: specify exact dose
+ titration_required: bool,
+ monitoring_parameters: Vec,
+}
+
+impl DoseAdjustment {
+ fn apply_to(&self, standard: &Dose) -> Dose {
+ match self.direction {
+ AdjustmentDirection::Contraindicate => Dose::zero(),
+ _ => standard.scale(self.factor),
+ }
+ }
+}
+```
+
+---
+
+## Domain Events
+
+### Profile Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `ProfileGenotyped` | Star alleles called for all pharmacogenes | profile_id, individual_id, genes_typed |
+| `MetabolizerStatusDetermined` | Phenotype classified from diplotype | profile_id, gene, phenotype, activity_score |
+| `ProfileVectorComputed` | 384-dim embedding generated | profile_id, vector_hash |
+| `SimilarPatientsFound` | HNSW search returned matches | profile_id, match_count, top_similarity |
+
+### Recommendation Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `DosingRecommendationGenerated` | Dose adjustment computed | recommendation_id, drug, gene, adjustment |
+| `ContraindicationDetected` | Drug contraindicated for genotype | drug, gene, diplotype, reason |
+| `GuidelineUpdated` | New CPIC/DPWG version loaded | source, version, affected_drugs |
+| `InteractionPredicted` | GNN predicts new drug-gene pair | interaction_id, drug, gene, confidence |
+
+### ADR Events
+
+| Event | Trigger | Payload |
+|-------|---------|---------|
+| `AdverseReactionRiskAssessed` | ADR risk computed for patient | adr_id, drug, risk_score, severity |
+| `HighRiskAlertGenerated` | Risk score exceeds critical threshold | individual_id, drug, reaction_type, score |
+| `PopulationRiskUpdated` | Frequency recalculated with new data | adr_id, population, new_frequency |
+
+---
+
+## Domain Services
+
+### StarAlleleCallerService
+
+Determine star allele diplotypes from raw genotype data.
+
+```rust
+trait StarAlleleCallerService {
+ /// Call star alleles at a pharmacogene from genotype data
+ /// Uses combinatorial matching against known haplotype definitions.
+ /// Ancestry from Population Genomics context adjusts prior probabilities
+ /// for ambiguous calls.
+ async fn call_diplotype(
+ &self,
+ individual: &IndividualId,
+ gene: PharmaGene,
+ genotypes: &PharmaGeneGenotypes,
+ ancestry: &[AncestryComponent],
+ ) -> Result;
+
+ /// Batch call for all pharmacogenes
+ async fn call_all_genes(
+ &self,
+ individual: &IndividualId,
+ ) -> Result, CallerError>;
+}
+```
+
+### MetabolizerClassificationService
+
+Classify metabolizer phenotype from diplotype and activity score.
+
+```rust
+trait MetabolizerClassificationService {
+ /// Classify metabolizer phenotype using CPIC activity score system
+ fn classify(
+ &self,
+ diplotype: &StarAlleleDiplotype,
+ classification_system: ClassificationSource,
+ ) -> MetabolizerStatus;
+
+ /// Batch classify for all genes in a profile
+ fn classify_profile(
+ &self,
+ profile: &PharmacogeneticProfile,
+ ) -> Vec;
+}
+```
+
+### DosingRecommendationService
+
+Generate evidence-graded dosing recommendations.
+
+```rust
+trait DosingRecommendationService {
+ /// Generate dosing recommendation for a drug-genotype pair
+ /// Retrieves applicable CPIC/DPWG guidelines, applies the recommendation
+ /// for the patient's metabolizer status, and grades confidence.
+ async fn recommend(
+ &self,
+ drug: DrugId,
+ profile: &PharmacogeneticProfile,
+ ) -> Result;
+
+ /// Check all current medications against profile
+ async fn screen_medication_list(
+ &self,
+ medications: &[DrugId],
+ profile: &PharmacogeneticProfile,
+ ) -> Result, RecommendationError>;
+
+ /// Find similar patients and their outcomes for prediction grounding
+ /// Uses ruvector-core HNSW search on ProfileVector
+ async fn find_similar_outcomes(
+ &self,
+ profile: &PharmacogeneticProfile,
+ drug: DrugId,
+ k: usize,
+ ) -> Result, RecommendationError>;
+}
+```
+
+### DrugGeneInteractionPredictionService
+
+Predict novel drug-gene interactions using GNN.
+
+```rust
+trait DrugGeneInteractionPredictionService {
+ /// Predict interaction using ruvector-gnn
+ /// Models the drug-gene-variant network as a heterogeneous graph.
+ /// Node features: drug structure embeddings, gene expression profiles,
+ /// variant functional annotations.
+ /// Edge prediction: GNN link prediction for (drug, gene) pairs.
+ ///
+ /// Uses ruvector-gnn::RuvectorLayer for message passing and
+ /// ruvector-gnn::differentiable_search for candidate retrieval.
+ async fn predict_interaction(
+ &self,
+ drug: DrugId,
+ gene: PharmaGene,
+ ) -> Result;
+
+ /// Batch predict all potential interactions for a new drug
+ async fn predict_all_for_drug(
+ &self,
+ drug: DrugId,
+ ) -> Result, PredictionError>;
+
+ /// Update GNN model with newly confirmed interactions
+ /// Uses ruvector-gnn::ElasticWeightConsolidation to prevent
+ /// catastrophic forgetting of previously learned patterns.
+ async fn update_model(
+ &self,
+ confirmed: &[DrugGeneInteraction],
+ ) -> Result<(), PredictionError>;
+}
+```
+
+### AdverseDrugReactionService
+
+Assess ADR risk for a patient-drug combination.
+
+```rust
+trait AdverseDrugReactionService {
+ /// Assess ADR risk for a specific drug
+ async fn assess_risk(
+ &self,
+ individual: &IndividualId,
+ drug: DrugId,
+ profile: &PharmacogeneticProfile,
+ ) -> Result, AdrError>;
+
+ /// Screen all medications for ADR risks
+ async fn screen_all(
+ &self,
+ individual: &IndividualId,
+ medications: &[DrugId],
+ profile: &PharmacogeneticProfile,
+ ) -> Result;
+
+ /// Use ruvector-attention for sequence -> ADR risk prediction
+ /// Applies multi-head attention over the patient's variant sequence
+ /// at HLA and pharmacogene loci to predict ADR susceptibility.
+ async fn predict_from_sequence(
+ &self,
+ variant_sequence: &[VariantId],
+ drug: DrugId,
+ ) -> Result;
+}
+```
+
+### SimilarPatientSearchService
+
+Find patients with analogous pharmacogenomic profiles.
+
+```rust
+trait SimilarPatientSearchService {
+ /// Find k most similar pharmacogenomic profiles
+ /// Uses ruvector-core HNSW nearest-neighbor search on ProfileVector.
+ /// Complexity: O(log n) per query where n = indexed patients.
+ async fn find_similar(
+ &self,
+ profile: &PharmacogeneticProfile,
+ k: usize,
+ ) -> Result, SearchError>;
+
+ /// Find similar patients who took a specific drug, with outcomes
+ /// Combines HNSW search with metadata filtering for drug and outcome.
+ async fn find_similar_with_outcome(
+ &self,
+ profile: &PharmacogeneticProfile,
+ drug: DrugId,
+ k: usize,
+ ) -> Result, SearchError>;
+}
+```
+
+---
+
+## Repositories
+
+### PharmacogeneticProfileRepository
+
+```rust
+trait PharmacogeneticProfileRepository {
+ /// Store profile with vector indexed in HNSW
+ async fn store(&self, profile: PharmacogeneticProfile) -> Result<(), StoreError>;
+
+ /// Find by profile ID
+ async fn find_by_id(&self, id: &ProfileId) -> Option;
+
+ /// Find by individual ID
+ async fn find_by_individual(
+ &self,
+ individual: &IndividualId,
+ ) -> Option;
+
+ /// Search by vector similarity (delegates to ruvector-core HNSW)
+ async fn search_similar(
+ &self,
+ vector: &ProfileVector,
+ k: usize,
+ ) -> Result, SearchError>;
+
+ /// Find all profiles with a specific metabolizer status
+ async fn find_by_metabolizer_status(
+ &self,
+ gene: PharmaGene,
+ phenotype: MetabolizerPhenotype,
+ ) -> Vec;
+}
+```
+
+### DrugGeneInteractionRepository
+
+```rust
+trait DrugGeneInteractionRepository {
+ async fn store(&self, interaction: DrugGeneInteraction) -> Result<(), StoreError>;
+ async fn find_by_id(&self, id: &InteractionId) -> Option;
+ async fn find_by_drug(&self, drug: &DrugId) -> Vec;
+ async fn find_by_gene(&self, gene: &PharmaGene) -> Vec;
+ async fn find_by_drug_and_gene(
+ &self,
+ drug: &DrugId,
+ gene: &PharmaGene,
+ ) -> Option;
+ async fn find_actionable(&self) -> Vec;
+ async fn find_predicted(&self, min_confidence: f64) -> Vec;
+}
+```
+
+### DosingRecommendationRepository
+
+```rust
+trait DosingRecommendationRepository {
+ async fn store(&self, rec: DosingRecommendation) -> Result<(), StoreError>;
+ async fn find_by_id(&self, id: &RecommendationId) -> Option;
+ async fn find_by_drug(&self, drug: &DrugId) -> Vec;
+ async fn find_contraindications(&self) -> Vec;
+ async fn find_by_guideline(
+ &self,
+ source: GuidelineSource,
+ version: &str,
+ ) -> Vec;
+}
+```
+
+### AdverseDrugReactionRepository
+
+```rust
+trait AdverseDrugReactionRepository {
+ async fn store(&self, adr: AdverseDrugReaction) -> Result<(), StoreError>;
+ async fn find_by_id(&self, id: &AdrId) -> Option;
+ async fn find_by_drug(&self, drug: &DrugId) -> Vec;
+ async fn find_by_variant(&self, variant: &VariantId) -> Vec;
+ async fn find_life_threatening(&self) -> Vec;
+ async fn find_by_severity(
+ &self,
+ min_severity: AdrSeverity,
+ ) -> Vec;
+}
+```
+
+---
+
+## RuVector Integration Architecture
+
+### Crate Mapping
+
+| Domain Operation | RuVector Crate | Mechanism |
+|-----------------|----------------|-----------|
+| Profile vector storage + similar-patient search | `ruvector-core` | 384-dim HNSW index, O(log n) ANN |
+| Drug-gene interaction prediction (GNN) | `ruvector-gnn` | Heterogeneous graph link prediction |
+| Catastrophic forgetting prevention | `ruvector-gnn::ewc` | Elastic Weight Consolidation |
+| Sequence -> metabolizer status prediction | `ruvector-attention` | Multi-head attention over variant sequence |
+| HLA-mediated ADR risk attention | `ruvector-attention` | Graph attention for HLA-variant interactions |
+| Similar patient outcome retrieval | `ruvector-core` | HNSW + metadata filtered search |
+| Drug interaction graph queries | `ruvector-graph` | Cypher-style traversal of drug-gene network |
+
+### GNN Architecture for Drug-Gene Prediction
+
+The drug-gene interaction graph is modeled as a heterogeneous graph with three node types and two edge types:
+
+```
+Node Types:
+ - Drug nodes: feature = molecular fingerprint embedding (384-dim)
+ - Gene nodes: feature = gene expression + pathway embedding (384-dim)
+ - Variant nodes: feature = functional annotation embedding (384-dim)
+
+Edge Types:
+ - (Drug) --[INTERACTS_WITH]--> (Gene): known or predicted interaction
+ - (Variant) --[AFFECTS]--> (Gene): variant's functional effect on gene
+
+GNN Pipeline (ruvector-gnn):
+ 1. RuvectorLayer message passing (2-3 hops)
+ 2. Edge score prediction for (Drug, Gene) pairs
+ 3. EWC regularization during incremental learning
+ 4. ReplayBuffer for experience replay on confirmed interactions
+```
+
+**Performance**: Link prediction inference in O(|V| + |E|) per query via ruvector-gnn forward pass. Model update with EWC in O(|params|) per new interaction batch.
+
+### Attention for Sequence-to-Phenotype
+
+```
+Input: Ordered variant sequence at pharmacogene locus [v1, v2, ..., vk]
+ Each variant embedded as 384-dim vector via ruvector-core
+
+Attention Pipeline (ruvector-attention):
+ 1. ScaledDotProductAttention over variant embeddings
+ 2. Multi-head attention (8 heads) captures different functional aspects
+ 3. Classification head: attention output -> MetabolizerPhenotype
+
+Use case: Complex genes like CYP2D6 with copy number variation,
+ hybrid alleles, and ambiguous star allele calls where
+ rule-based calling fails.
+```
+
+### Performance Targets
+
+| Operation | Target | Complexity | Mechanism |
+|-----------|--------|------------|-----------|
+| Star allele calling (per gene) | <10ms | O(h * v) where h=haplotypes, v=variants | Combinatorial matching |
+| Metabolizer classification | <1ms | O(1) lookup from diplotype | Activity score table |
+| Dosing recommendation | <50ms | O(g) where g = genes in profile | Guideline lookup + scoring |
+| Similar patient search | <100ms | O(log n) HNSW | ruvector-core |
+| GNN interaction prediction | <200ms | O(|V| + |E|) forward pass | ruvector-gnn |
+| ADR risk assessment (per drug) | <50ms | O(v) where v = risk variants | Variant lookup + scoring |
+| Full medication screening | <500ms | O(m * g) where m=medications | Parallel drug-gene lookup |
+| Attention-based phenotype prediction | <100ms | O(k^2 * d) where k=variants, d=384 | ruvector-attention |
+
+---
+
+## Invariants and Business Rules
+
+### Profile Invariants
+
+1. **Gene Uniqueness**: Each pharmacogene appears at most once in star_alleles
+2. **Status Consistency**: Every MetabolizerStatus must have a corresponding StarAlleleDiplotype
+3. **Activity Score Non-Negative**: All activity scores >= 0.0
+4. **Confidence Range**: Call confidence in [0.0, 1.0]
+5. **Guideline Currency**: Profile must be annotated with the guideline version used
+
+### Recommendation Invariants
+
+1. **Contraindication Override**: If contraindicated == true, recommended_dose must be zero
+2. **Evidence Chain**: Confidence grade must reflect the weakest evidence link
+3. **Guideline Traceability**: Every recommendation must link to a specific published guideline with version
+4. **Adjustment Positivity**: adjustment_factor > 0.0 unless contraindicated
+
+### ADR Invariants
+
+1. **Life-Threatening Action**: LifeThreatening severity must result in clinical_action == Avoid
+2. **Frequency Validity**: AdrFrequency.value in [0.0, 1.0], total_exposed > 0
+3. **Risk Score Range**: risk_score in [0.0, 1.0]
+4. **Population Specificity**: ADR frequencies must be tagged with ancestry population
+
+### GNN Prediction Invariants
+
+1. **Confidence Threshold**: Only interactions with prediction_confidence >= 0.7 are surfaced
+2. **No Self-Interaction**: Drug cannot have an interaction with itself
+3. **Forgetting Prevention**: EWC penalty weight must be applied during model updates
+4. **Replay Coverage**: ReplayBuffer must maintain minimum 1000 entries before allowing new training
+
+---
+
+## Anti-Corruption Layers
+
+### Drug Knowledge Base ACL
+
+Translates PharmGKB/CPIC/DPWG data to domain model.
+
+```rust
+impl DrugKnowledgeBaseAcl {
+ /// Translate CPIC guideline to domain DrugGeneInteraction
+ fn translate_cpic(&self, guideline: CpicGuideline) -> Vec {
+ guideline.recommendations.iter().map(|rec| {
+ DrugGeneInteraction {
+ interaction_id: InteractionId::new(),
+ drug: self.map_drug_id(&rec.drug),
+ gene: self.map_gene(&rec.gene),
+ alleles_affected: self.map_alleles(&rec.alleles),
+ effect: self.classify_effect(&rec),
+ evidence_level: EvidenceLevel::Level1A, // CPIC = 1A
+ cpic_level: Some(self.map_cpic_strength(&rec.strength)),
+ phenotype_mapping: self.build_phenotype_map(&rec),
+ source: InteractionSource::CPIC,
+ prediction_confidence: None,
+ }
+ }).collect()
+ }
+
+ /// Translate PharmGKB clinical annotation
+ fn translate_pharmgkb(&self, annotation: PharmgkbAnnotation) -> DrugGeneInteraction;
+}
+```
+
+### Clinical Data ACL
+
+Translates EHR medication and lab data to domain format.
+
+```rust
+impl ClinicalDataAcl {
+ /// Translate medication list from EHR format to domain DrugIds
+ fn translate_medications(&self, ehr_meds: &[EhrMedication]) -> Vec {
+ ehr_meds.iter()
+ .filter_map(|med| self.rxnorm_to_drug_id(&med.rxnorm_code))
+ .collect()
+ }
+
+ /// Translate lab values relevant to pharmacogenomics
+ fn translate_labs(&self, labs: &[EhrLab]) -> Vec {
+ labs.iter()
+ .filter(|lab| self.is_pgx_relevant(&lab.loinc_code))
+ .map(|lab| self.to_monitoring_parameter(lab))
+ .collect()
+ }
+}
+```
+
+### Population Genomics ACL
+
+Translates ancestry data for ancestry-adjusted star allele calling.
+
+```rust
+impl PopulationGenomicsAcl {
+ /// Get ancestry-adjusted allele frequencies for star allele priors
+ fn get_adjusted_frequencies(
+ &self,
+ gene: PharmaGene,
+ ancestry: &[AncestryComponent],
+ ) -> HashMap {
+ // Weight population-specific star allele frequencies
+ // by the individual's ancestry proportions
+ ancestry.iter()
+ .flat_map(|comp| {
+ let pop_freqs = self.reference_frequencies(gene, &comp.population_label);
+ pop_freqs.iter().map(move |(allele, freq)| {
+ (allele.clone(), freq * comp.proportion)
+ })
+ })
+ .fold(HashMap::new(), |mut acc, (allele, weighted_freq)| {
+ *acc.entry(allele).or_insert(0.0) += weighted_freq;
+ acc
+ })
+ }
+}
+```
+
+---
+
+## Event Flow: End-to-End Pharmacogenomic Report
+
+```
+1. [Variant Ingestion] GenotypeDataReceived
+ |
+ v
+2. [Population Genomics] IndividualGenotyped -> AncestryInferred
+ |
+ v
+3. [Pharmacogenomics] StarAlleleCallerService.call_all_genes()
+ | -> ProfileGenotyped event
+ v
+4. [Pharmacogenomics] MetabolizerClassificationService.classify_profile()
+ | -> MetabolizerStatusDetermined event (per gene)
+ v
+5. [Pharmacogenomics] ProfileVector computed, indexed in HNSW
+ | -> ProfileVectorComputed event
+ v
+6. [Pharmacogenomics] DosingRecommendationService.screen_medication_list()
+ | -> DosingRecommendationGenerated event (per drug)
+ | -> ContraindicationDetected event (if applicable)
+ v
+7. [Pharmacogenomics] AdverseDrugReactionService.screen_all()
+ | -> AdverseReactionRiskAssessed event (per drug-variant pair)
+ | -> HighRiskAlertGenerated event (if risk > threshold)
+ v
+8. [Pharmacogenomics] SimilarPatientSearchService.find_similar_with_outcome()
+ | -> SimilarPatientsFound event
+ v
+9. [Clinical Decision Support] Report assembled and delivered
+```
+
+---
+
+## Context Boundaries Summary
+
+| Boundary | Upstream | Downstream | Integration Pattern |
+|----------|----------|------------|---------------------|
+| Variant -> PGx | Variant Ingestion | Pharmacogenomics | Published Language (PharmaGeneGenotypes) |
+| PopGen -> PGx | Population Genomics | Pharmacogenomics | ACL (AncestryComponent) |
+| DrugKB -> PGx | Drug Knowledge Base | Pharmacogenomics | ACL (DrugGeneInteraction) |
+| PGx -> CDS | Pharmacogenomics | Clinical Decision Support | Domain Events (DosingRecommendationGenerated) |
+| EHR -> PGx | Clinical Data | Pharmacogenomics | ACL (medication list, labs) |
+
+---
+
+## References
+
+- DDD-001: Coherence Gate Domain Model
+- DDD-003: Population Genomics Domain Model
+- arXiv:2512.13105 -- El-Hayek, Henzinger, Li. "Deterministic and Exact Fully-dynamic Minimum Cut" (SODA 2025)
+- CPIC (Clinical Pharmacogenetics Implementation Consortium) Guidelines
+- PharmGKB Clinical Annotations and VIP Summaries
+- DPWG (Dutch Pharmacogenetics Working Group) Guidelines
+- Evans, Eric. "Domain-Driven Design." Addison-Wesley, 2003.
+- Vernon, Vaughn. "Implementing Domain-Driven Design." Addison-Wesley, 2013.
diff --git a/crates/ruvector-core/Cargo.toml b/crates/ruvector-core/Cargo.toml
index 7ca0b1003..ae9a06239 100644
--- a/crates/ruvector-core/Cargo.toml
+++ b/crates/ruvector-core/Cargo.toml
@@ -96,6 +96,11 @@ uuid-support = [] # Deprecated: uuid is now always included
real-embeddings = [] # Feature flag for embedding provider API (use ApiEmbedding for production)
api-embeddings = ["reqwest"] # API-based embeddings (not available in WASM)
+[[example]]
+name = "dna_analysis_pipeline"
+path = "../../examples/dna_analysis_pipeline.rs"
+required-features = ["hnsw", "parallel"]
+
[lib]
crate-type = ["rlib"]
bench = false
diff --git a/crates/ruvector-dna-bench/Cargo.toml b/crates/ruvector-dna-bench/Cargo.toml
new file mode 100644
index 000000000..ef53589dc
--- /dev/null
+++ b/crates/ruvector-dna-bench/Cargo.toml
@@ -0,0 +1,49 @@
+[package]
+name = "ruvector-dna-bench"
+version = "0.1.0"
+edition = "2021"
+description = "Comprehensive benchmark suite for RuVector DNA Analyzer core crates"
+publish = false
+
+[dependencies]
+# Crates under test
+ruvector-core = { path = "../ruvector-core", features = ["hnsw", "simd", "parallel"] }
+ruvector-mincut = { path = "../ruvector-mincut", default-features = true }
+ruvector-attention = { path = "../ruvector-attention", default-features = true }
+ruvector-delta-core = { path = "../ruvector-delta-core", features = ["std"] }
+
+# Benchmarking
+criterion = { version = "0.5", features = ["html_reports"] }
+rand = "0.8"
+
+[lib]
+bench = false
+
+# ---------------------------------------------------------------------------
+# Benchmark targets -- each file lives in ../../benches/ (workspace root)
+# ---------------------------------------------------------------------------
+
+[[bench]]
+name = "bench_hnsw_genomic"
+harness = false
+path = "../../benches/bench_hnsw_genomic.rs"
+
+[[bench]]
+name = "bench_mincut_genome_graph"
+harness = false
+path = "../../benches/bench_mincut_genome_graph.rs"
+
+[[bench]]
+name = "bench_attention_genomic"
+harness = false
+path = "../../benches/bench_attention_genomic.rs"
+
+[[bench]]
+name = "bench_delta_propagation"
+harness = false
+path = "../../benches/bench_delta_propagation.rs"
+
+[[bench]]
+name = "bench_quantization"
+harness = false
+path = "../../benches/bench_quantization.rs"
diff --git a/crates/ruvector-dna-bench/src/lib.rs b/crates/ruvector-dna-bench/src/lib.rs
new file mode 100644
index 000000000..f728c8892
--- /dev/null
+++ b/crates/ruvector-dna-bench/src/lib.rs
@@ -0,0 +1,43 @@
+//! RuVector DNA Analyzer Benchmark Suite
+//!
+//! Comprehensive benchmarks for core crates covering:
+//! - HNSW index operations (genomic k-mer embeddings)
+//! - Min-cut on genome-scale graphs
+//! - Attention mechanisms for genomic sequences
+//! - Delta propagation and checkpointing
+//! - Quantization throughput and accuracy
+
+/// Deterministic pseudo-random vector generator for reproducible benchmarks.
+///
+/// Uses a fast LCG-based PRNG seeded per-vector so results are consistent
+/// across runs without pulling in `rand` as a benchmark dependency.
+pub fn deterministic_vector(dim: usize, seed: u64) -> Vec {
+ let mut state = seed.wrapping_mul(6364136223846793005).wrapping_add(1442695040888963407);
+ (0..dim)
+ .map(|_| {
+ state = state
+ .wrapping_mul(6364136223846793005)
+ .wrapping_add(1442695040888963407);
+ let bits = ((state >> 33) ^ state) as u32;
+ // Map to [-1.0, 1.0]
+ (bits as f32 / u32::MAX as f32) * 2.0 - 1.0
+ })
+ .collect()
+}
+
+/// Generate a batch of deterministic vectors.
+pub fn deterministic_vectors(count: usize, dim: usize, base_seed: u64) -> Vec> {
+ (0..count)
+ .map(|i| deterministic_vector(dim, base_seed.wrapping_add(i as u64)))
+ .collect()
+}
+
+/// Normalize a vector to unit length (for cosine-based indices).
+pub fn normalize(v: &[f32]) -> Vec {
+ let norm = v.iter().map(|x| x * x).sum::().sqrt();
+ if norm > 1e-8 {
+ v.iter().map(|x| x / norm).collect()
+ } else {
+ v.to_vec()
+ }
+}
diff --git a/crates/ruvector-fpga-transformer/src/backend/wasm_sim.rs b/crates/ruvector-fpga-transformer/src/backend/wasm_sim.rs
index 187a184c8..278480051 100644
--- a/crates/ruvector-fpga-transformer/src/backend/wasm_sim.rs
+++ b/crates/ruvector-fpga-transformer/src/backend/wasm_sim.rs
@@ -81,12 +81,11 @@ impl WasmSimBackend {
};
// Determine number of layers from artifact or default
- let num_layers = artifact
- .manifest
- .backend
- .as_ref()
- .and_then(|b| if b.early_exit { Some(6) } else { None })
- .unwrap_or(4);
+ let num_layers = if artifact.manifest.backend.options.early_exit {
+ 6
+ } else {
+ 4
+ };
Ok(WasmModel {
artifact: artifact.clone(),
diff --git a/crates/ruvector-gnn-wasm/Cargo.toml b/crates/ruvector-gnn-wasm/Cargo.toml
index 9fee6561c..acf424a58 100644
--- a/crates/ruvector-gnn-wasm/Cargo.toml
+++ b/crates/ruvector-gnn-wasm/Cargo.toml
@@ -17,31 +17,23 @@ crate-type = ["cdylib", "rlib"]
[dependencies]
ruvector-gnn = { path = "../ruvector-gnn", default-features = false, features = ["wasm"] }
+serde = { workspace = true }
-# WASM
+[target.'cfg(target_arch = "wasm32")'.dependencies]
wasm-bindgen = { workspace = true }
js-sys = { workspace = true }
-getrandom = { workspace = true }
-
-# Serialization
-serde = { workspace = true }
+getrandom = { workspace = true, features = ["wasm_js"] }
+getrandom02 = { package = "getrandom", version = "0.2", features = ["js"] }
serde-wasm-bindgen = "0.6"
-
-# Utils
console_error_panic_hook = { version = "0.1", optional = true }
-[dev-dependencies]
+[target.'cfg(target_arch = "wasm32")'.dev-dependencies]
wasm-bindgen-test = "0.3"
[features]
default = []
console_error_panic_hook = ["dep:console_error_panic_hook"]
-# Ensure getrandom uses wasm_js/js feature for WASM
-[target.'cfg(target_arch = "wasm32")'.dependencies]
-getrandom = { workspace = true, features = ["wasm_js"] }
-getrandom02 = { package = "getrandom", version = "0.2", features = ["js"] }
-
[profile.release]
opt-level = "z"
lto = true
diff --git a/crates/ruvector-gnn-wasm/src/lib.rs b/crates/ruvector-gnn-wasm/src/lib.rs
index 2bf7c9dc3..d4c59068c 100644
--- a/crates/ruvector-gnn-wasm/src/lib.rs
+++ b/crates/ruvector-gnn-wasm/src/lib.rs
@@ -7,408 +7,424 @@
//! - Differentiable search with soft attention
//! - Hierarchical forward propagation
-use ruvector_gnn::{
- differentiable_search as core_differentiable_search,
- hierarchical_forward as core_hierarchical_forward, CompressedTensor, CompressionLevel,
- RuvectorLayer, TensorCompress,
-};
-use serde::{Deserialize, Serialize};
-use wasm_bindgen::prelude::*;
-
-/// Initialize panic hook for better error messages
-#[wasm_bindgen(start)]
-pub fn init() {
- #[cfg(feature = "console_error_panic_hook")]
- console_error_panic_hook::set_once();
-}
+// All WASM bindings are gated behind wasm32 target since they depend on
+// wasm-bindgen, JsValue, and serde-wasm-bindgen which are WASM-only.
+#[cfg(target_arch = "wasm32")]
+mod wasm_bindings {
+ use ruvector_gnn::{
+ differentiable_search as core_differentiable_search,
+ hierarchical_forward as core_hierarchical_forward, CompressedTensor, CompressionLevel,
+ RuvectorLayer, TensorCompress,
+ };
+ use serde::{Deserialize, Serialize};
+ use wasm_bindgen::prelude::*;
+
+ /// Initialize panic hook for better error messages
+ #[wasm_bindgen(start)]
+ pub fn init() {
+ #[cfg(feature = "console_error_panic_hook")]
+ console_error_panic_hook::set_once();
+ }
-// ============================================================================
-// Type Definitions for WASM
-// ============================================================================
-
-/// Query configuration for differentiable search
-#[derive(Debug, Clone, Serialize, Deserialize)]
-#[wasm_bindgen]
-pub struct SearchConfig {
- /// Number of top results to return
- pub k: usize,
- /// Temperature for softmax (lower = sharper, higher = smoother)
- pub temperature: f32,
-}
+ // ========================================================================
+ // Type Definitions for WASM
+ // ========================================================================
-#[wasm_bindgen]
-impl SearchConfig {
- /// Create a new search configuration
- #[wasm_bindgen(constructor)]
- pub fn new(k: usize, temperature: f32) -> Self {
- Self { k, temperature }
+ /// Query configuration for differentiable search
+ #[derive(Debug, Clone, Serialize, Deserialize)]
+ #[wasm_bindgen]
+ pub struct SearchConfig {
+ /// Number of top results to return
+ pub k: usize,
+ /// Temperature for softmax (lower = sharper, higher = smoother)
+ pub temperature: f32,
}
-}
-/// Search results with indices and weights (internal)
-#[derive(Debug, Clone, Serialize, Deserialize)]
-struct SearchResultInternal {
- /// Indices of top-k candidates
- indices: Vec,
- /// Soft weights for each result
- weights: Vec,
-}
+ #[wasm_bindgen]
+ impl SearchConfig {
+ /// Create a new search configuration
+ #[wasm_bindgen(constructor)]
+ pub fn new(k: usize, temperature: f32) -> Self {
+ Self { k, temperature }
+ }
+ }
-// ============================================================================
-// JsRuvectorLayer - GNN Layer Wrapper
-// ============================================================================
+ /// Search results with indices and weights (internal)
+ #[derive(Debug, Clone, Serialize, Deserialize)]
+ struct SearchResultInternal {
+ /// Indices of top-k candidates
+ indices: Vec,
+ /// Soft weights for each result
+ weights: Vec,
+ }
-/// Graph Neural Network layer for HNSW topology
-#[wasm_bindgen]
-pub struct JsRuvectorLayer {
- inner: RuvectorLayer,
- hidden_dim: usize,
-}
+ // ========================================================================
+ // JsRuvectorLayer - GNN Layer Wrapper
+ // ========================================================================
-#[wasm_bindgen]
-impl JsRuvectorLayer {
- /// Create a new GNN layer
- ///
- /// # Arguments
- /// * `input_dim` - Dimension of input node embeddings
- /// * `hidden_dim` - Dimension of hidden representations
- /// * `heads` - Number of attention heads
- /// * `dropout` - Dropout rate (0.0 to 1.0)
- #[wasm_bindgen(constructor)]
- pub fn new(
- input_dim: usize,
+ /// Graph Neural Network layer for HNSW topology
+ #[wasm_bindgen]
+ pub struct JsRuvectorLayer {
+ inner: RuvectorLayer,
hidden_dim: usize,
- heads: usize,
- dropout: f32,
- ) -> Result {
- if dropout < 0.0 || dropout > 1.0 {
- return Err(JsValue::from_str("Dropout must be between 0.0 and 1.0"));
- }
-
- Ok(JsRuvectorLayer {
- inner: RuvectorLayer::new(input_dim, hidden_dim, heads, dropout),
- hidden_dim,
- })
}
- /// Forward pass through the GNN layer
- ///
- /// # Arguments
- /// * `node_embedding` - Current node's embedding (Float32Array)
- /// * `neighbor_embeddings` - Embeddings of neighbor nodes (array of Float32Arrays)
- /// * `edge_weights` - Weights of edges to neighbors (Float32Array)
- ///
- /// # Returns
- /// Updated node embedding (Float32Array)
#[wasm_bindgen]
- pub fn forward(
- &self,
- node_embedding: Vec,
- neighbor_embeddings: JsValue,
- edge_weights: Vec,
- ) -> Result, JsValue> {
- // Convert neighbor embeddings from JS value
- let neighbors: Vec> = serde_wasm_bindgen::from_value(neighbor_embeddings)
- .map_err(|e| {
- JsValue::from_str(&format!("Failed to parse neighbor embeddings: {}", e))
- })?;
+ impl JsRuvectorLayer {
+ /// Create a new GNN layer
+ ///
+ /// # Arguments
+ /// * `input_dim` - Dimension of input node embeddings
+ /// * `hidden_dim` - Dimension of hidden representations
+ /// * `heads` - Number of attention heads
+ /// * `dropout` - Dropout rate (0.0 to 1.0)
+ #[wasm_bindgen(constructor)]
+ pub fn new(
+ input_dim: usize,
+ hidden_dim: usize,
+ heads: usize,
+ dropout: f32,
+ ) -> Result {
+ if dropout < 0.0 || dropout > 1.0 {
+ return Err(JsValue::from_str("Dropout must be between 0.0 and 1.0"));
+ }
- // Validate inputs
- if neighbors.len() != edge_weights.len() {
- return Err(JsValue::from_str(&format!(
- "Number of neighbors ({}) must match number of edge weights ({})",
- neighbors.len(),
- edge_weights.len()
- )));
+ Ok(JsRuvectorLayer {
+ inner: RuvectorLayer::new(input_dim, hidden_dim, heads, dropout),
+ hidden_dim,
+ })
}
- // Call core forward
- let result = self
- .inner
- .forward(&node_embedding, &neighbors, &edge_weights);
+ /// Forward pass through the GNN layer
+ ///
+ /// # Arguments
+ /// * `node_embedding` - Current node's embedding (Float32Array)
+ /// * `neighbor_embeddings` - Embeddings of neighbor nodes (array of Float32Arrays)
+ /// * `edge_weights` - Weights of edges to neighbors (Float32Array)
+ ///
+ /// # Returns
+ /// Updated node embedding (Float32Array)
+ #[wasm_bindgen]
+ pub fn forward(
+ &self,
+ node_embedding: Vec,
+ neighbor_embeddings: JsValue,
+ edge_weights: Vec,
+ ) -> Result, JsValue> {
+ let neighbors: Vec> =
+ serde_wasm_bindgen::from_value(neighbor_embeddings).map_err(|e| {
+ JsValue::from_str(&format!("Failed to parse neighbor embeddings: {}", e))
+ })?;
+
+ if neighbors.len() != edge_weights.len() {
+ return Err(JsValue::from_str(&format!(
+ "Number of neighbors ({}) must match number of edge weights ({})",
+ neighbors.len(),
+ edge_weights.len()
+ )));
+ }
+
+ let result = self
+ .inner
+ .forward(&node_embedding, &neighbors, &edge_weights);
- Ok(result)
+ Ok(result)
+ }
+
+ /// Get the output dimension of this layer
+ #[wasm_bindgen(getter, js_name = outputDim)]
+ pub fn output_dim(&self) -> usize {
+ self.hidden_dim
+ }
}
- /// Get the output dimension of this layer
- #[wasm_bindgen(getter, js_name = outputDim)]
- pub fn output_dim(&self) -> usize {
- self.hidden_dim
+ // ========================================================================
+ // JsTensorCompress - Tensor Compression Wrapper
+ // ========================================================================
+
+ /// Tensor compressor with adaptive level selection
+ #[wasm_bindgen]
+ pub struct JsTensorCompress {
+ inner: TensorCompress,
}
-}
-// ============================================================================
-// JsTensorCompress - Tensor Compression Wrapper
-// ============================================================================
+ #[wasm_bindgen]
+ impl JsTensorCompress {
+ /// Create a new tensor compressor
+ #[wasm_bindgen(constructor)]
+ pub fn new() -> Self {
+ Self {
+ inner: TensorCompress::new(),
+ }
+ }
-/// Tensor compressor with adaptive level selection
-#[wasm_bindgen]
-pub struct JsTensorCompress {
- inner: TensorCompress,
-}
+ /// Compress an embedding based on access frequency
+ ///
+ /// # Arguments
+ /// * `embedding` - The input embedding vector (Float32Array)
+ /// * `access_freq` - Access frequency in range [0.0, 1.0]
+ /// - f > 0.8: Full precision (hot data)
+ /// - f > 0.4: Half precision (warm data)
+ /// - f > 0.1: 8-bit PQ (cool data)
+ /// - f > 0.01: 4-bit PQ (cold data)
+ /// - f <= 0.01: Binary (archive)
+ ///
+ /// # Returns
+ /// Compressed tensor as JsValue
+ #[wasm_bindgen]
+ pub fn compress(
+ &self,
+ embedding: Vec,
+ access_freq: f32,
+ ) -> Result {
+ let compressed = self
+ .inner
+ .compress(&embedding, access_freq)
+ .map_err(|e| JsValue::from_str(&format!("Compression failed: {}", e)))?;
+
+ serde_wasm_bindgen::to_value(&compressed)
+ .map_err(|e| JsValue::from_str(&format!("Serialization failed: {}", e)))
+ }
-#[wasm_bindgen]
-impl JsTensorCompress {
- /// Create a new tensor compressor
- #[wasm_bindgen(constructor)]
- pub fn new() -> Self {
- Self {
- inner: TensorCompress::new(),
+ /// Compress with explicit compression level
+ ///
+ /// # Arguments
+ /// * `embedding` - The input embedding vector
+ /// * `level` - Compression level ("none", "half", "pq8", "pq4", "binary")
+ ///
+ /// # Returns
+ /// Compressed tensor as JsValue
+ #[wasm_bindgen(js_name = compressWithLevel)]
+ pub fn compress_with_level(
+ &self,
+ embedding: Vec,
+ level: &str,
+ ) -> Result {
+ let compression_level = match level {
+ "none" => CompressionLevel::None,
+ "half" => CompressionLevel::Half { scale: 1.0 },
+ "pq8" => CompressionLevel::PQ8 {
+ subvectors: 8,
+ centroids: 16,
+ },
+ "pq4" => CompressionLevel::PQ4 {
+ subvectors: 8,
+ outlier_threshold: 3.0,
+ },
+ "binary" => CompressionLevel::Binary { threshold: 0.0 },
+ _ => {
+ return Err(JsValue::from_str(&format!(
+ "Unknown compression level: {}",
+ level
+ )))
+ }
+ };
+
+ let compressed = self
+ .inner
+ .compress_with_level(&embedding, &compression_level)
+ .map_err(|e| JsValue::from_str(&format!("Compression failed: {}", e)))?;
+
+ serde_wasm_bindgen::to_value(&compressed)
+ .map_err(|e| JsValue::from_str(&format!("Serialization failed: {}", e)))
}
- }
- /// Compress an embedding based on access frequency
- ///
- /// # Arguments
- /// * `embedding` - The input embedding vector (Float32Array)
- /// * `access_freq` - Access frequency in range [0.0, 1.0]
- /// - f > 0.8: Full precision (hot data)
- /// - f > 0.4: Half precision (warm data)
- /// - f > 0.1: 8-bit PQ (cool data)
- /// - f > 0.01: 4-bit PQ (cold data)
- /// - f <= 0.01: Binary (archive)
- ///
- /// # Returns
- /// Compressed tensor as JsValue
- #[wasm_bindgen]
- pub fn compress(&self, embedding: Vec, access_freq: f32) -> Result {
- let compressed = self
- .inner
- .compress(&embedding, access_freq)
- .map_err(|e| JsValue::from_str(&format!("Compression failed: {}", e)))?;
-
- // Serialize using serde_wasm_bindgen
- serde_wasm_bindgen::to_value(&compressed)
- .map_err(|e| JsValue::from_str(&format!("Serialization failed: {}", e)))
+ /// Decompress a compressed tensor
+ ///
+ /// # Arguments
+ /// * `compressed` - Serialized compressed tensor (JsValue)
+ ///
+ /// # Returns
+ /// Decompressed embedding vector (Float32Array)
+ #[wasm_bindgen]
+ pub fn decompress(&self, compressed: JsValue) -> Result, JsValue> {
+ let compressed_tensor: CompressedTensor =
+ serde_wasm_bindgen::from_value(compressed).map_err(|e| {
+ JsValue::from_str(&format!("Deserialization failed: {}", e))
+ })?;
+
+ let decompressed = self
+ .inner
+ .decompress(&compressed_tensor)
+ .map_err(|e| JsValue::from_str(&format!("Decompression failed: {}", e)))?;
+
+ Ok(decompressed)
+ }
+
+ /// Get compression ratio estimate for a given access frequency
+ ///
+ /// # Arguments
+ /// * `access_freq` - Access frequency in range [0.0, 1.0]
+ ///
+ /// # Returns
+ /// Estimated compression ratio (original_size / compressed_size)
+ #[wasm_bindgen(js_name = getCompressionRatio)]
+ pub fn get_compression_ratio(&self, access_freq: f32) -> f32 {
+ if access_freq > 0.8 {
+ 1.0 // No compression
+ } else if access_freq > 0.4 {
+ 2.0 // Half precision
+ } else if access_freq > 0.1 {
+ 4.0 // 8-bit PQ
+ } else if access_freq > 0.01 {
+ 8.0 // 4-bit PQ
+ } else {
+ 32.0 // Binary
+ }
+ }
}
- /// Compress with explicit compression level
+ // ========================================================================
+ // Standalone Functions
+ // ========================================================================
+
+ /// Differentiable search using soft attention mechanism
///
/// # Arguments
- /// * `embedding` - The input embedding vector
- /// * `level` - Compression level ("none", "half", "pq8", "pq4", "binary")
+ /// * `query` - The query vector (Float32Array)
+ /// * `candidate_embeddings` - List of candidate embedding vectors (array of Float32Arrays)
+ /// * `config` - Search configuration (k and temperature)
///
/// # Returns
- /// Compressed tensor as JsValue
- #[wasm_bindgen(js_name = compressWithLevel)]
- pub fn compress_with_level(
- &self,
- embedding: Vec