Merge commit 'd803bfe2b1fe7f5e219e50ac20d6801a0a58ac75' as 'vendor/ruvector'
This commit is contained in:
ruv
233
vendor/ruvector/crates/ruvector-nervous-system/examples/README.md
vendored
Normal file
233
vendor/ruvector/crates/ruvector-nervous-system/examples/README.md
vendored
Normal file
@@ -0,0 +1,233 @@
|
||||
# Nervous System Examples
|
||||
|
||||
[](https://www.rust-lang.org/)
|
||||
[](../LICENSE)
|
||||
[]()
|
||||
|
||||
Bio-inspired nervous system architecture examples demonstrating the transition from **"How do we make machines smarter?"** to **"What kind of organism are we building?"**
|
||||
|
||||
## Overview
|
||||
|
||||
These examples show how nervous system thinking unlocks new products, markets, and research categories. The architecture enables systems that **age well** instead of breaking under complexity.
|
||||
|
||||
All tier examples are organized in the unified `tiers/` folder with prefixed names for easy navigation.
|
||||
|
||||
## Application Tiers
|
||||
|
||||
### Tier 1: Immediate Practical Applications
|
||||
*Shippable with current architecture*
|
||||
|
||||
| Example | Domain | Key Benefit |
|
||||
|---------|--------|-------------|
|
||||
| [t1_anomaly_detection](tiers/t1_anomaly_detection.rs) | Infrastructure, Finance, Security | Detection before failure, microsecond response |
|
||||
| [t1_edge_autonomy](tiers/t1_edge_autonomy.rs) | Drones, Vehicles, Robotics | Lower power, certified reflex paths |
|
||||
| [t1_medical_wearable](tiers/t1_medical_wearable.rs) | Monitoring, Assistive Devices | Adapts to the person, always-on, private |
|
||||
|
||||
### Tier 2: Near-Term Transformative Applications
|
||||
*Possible once local learning and coherence routing mature*
|
||||
|
||||
| Example | Domain | Key Benefit |
|
||||
|---------|--------|-------------|
|
||||
| [t2_self_optimizing](tiers/t2_self_optimizing.rs) | Agents Monitoring Agents | Self-stabilizing software, structural witnesses |
|
||||
| [t2_swarm_intelligence](tiers/t2_swarm_intelligence.rs) | IoT Fleets, Sensor Meshes | Scale without fragility, emergent intelligence |
|
||||
| [t2_adaptive_simulation](tiers/t2_adaptive_simulation.rs) | Digital Twins, Logistics | Always-warm simulation, costs scale with relevance |
|
||||
|
||||
### Tier 3: Exotic But Real Applications
|
||||
*Technically grounded, novel research directions*
|
||||
|
||||
| Example | Domain | Key Benefit |
|
||||
|---------|--------|-------------|
|
||||
| [t3_self_awareness](tiers/t3_self_awareness.rs) | Structural Self-Sensing | Systems say "I am becoming unstable" |
|
||||
| [t3_synthetic_nervous](tiers/t3_synthetic_nervous.rs) | Buildings, Factories, Cities | Environments respond like organisms |
|
||||
| [t3_bio_machine](tiers/t3_bio_machine.rs) | Prosthetics, Rehabilitation | Machines stop fighting biology |
|
||||
|
||||
### Tier 4: SOTA & Exotic Research Applications
|
||||
*Cutting-edge research directions pushing neuromorphic boundaries*
|
||||
|
||||
| Example | Domain | Key Benefit |
|
||||
|---------|--------|-------------|
|
||||
| [t4_neuromorphic_rag](tiers/t4_neuromorphic_rag.rs) | LLM Memory, Retrieval | Coherence-gated retrieval, 100x compute reduction |
|
||||
| [t4_agentic_self_model](tiers/t4_agentic_self_model.rs) | Agentic AI, Self-Awareness | Agent models own cognition, knows when capable |
|
||||
| [t4_collective_dreaming](tiers/t4_collective_dreaming.rs) | Swarm Consolidation | Hippocampal replay, cross-agent memory transfer |
|
||||
| [t4_compositional_hdc](tiers/t4_compositional_hdc.rs) | Zero-Shot Reasoning | HDC binding for analogy and composition |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Run a Tier 1 example
|
||||
cargo run --example t1_anomaly_detection
|
||||
|
||||
# Run a Tier 2 example
|
||||
cargo run --example t2_swarm_intelligence
|
||||
|
||||
# Run a Tier 3 example
|
||||
cargo run --example t3_self_awareness
|
||||
|
||||
# Run a Tier 4 example
|
||||
cargo run --example t4_neuromorphic_rag
|
||||
```
|
||||
|
||||
## Architecture Principles
|
||||
|
||||
Each example demonstrates the same five-layer architecture:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ COHERENCE LAYER │
|
||||
│ Global Workspace • Oscillatory Routing • Predictive Coding │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↑
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ LEARNING LAYER │
|
||||
│ BTSP One-Shot • E-prop Online • EWC Consolidation │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↑
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ MEMORY LAYER │
|
||||
│ Hopfield Networks • HDC Vectors • Pattern Separation │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↑
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ REFLEX LAYER │
|
||||
│ K-WTA Competition • Dendritic Coincidence • Safety │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↑
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ SENSING LAYER │
|
||||
│ Event Bus • Sparse Spikes • Backpressure Control │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Key Concepts Demonstrated
|
||||
|
||||
### Reflex Arcs
|
||||
Fast, deterministic responses with bounded execution:
|
||||
- Latency: <100μs
|
||||
- Certifiable: Maximum iteration counts
|
||||
- Safety: Witness logging for every decision
|
||||
|
||||
### Homeostasis
|
||||
Self-regulation instead of static thresholds:
|
||||
- Adaptive learning from normal operation
|
||||
- Graceful degradation under stress
|
||||
- Anticipatory maintenance
|
||||
|
||||
### Coherence Gating
|
||||
Synchronize only when needed:
|
||||
- Kuramoto oscillators for phase coupling
|
||||
- Communication gain based on phase coherence
|
||||
- 90-99% bandwidth reduction via prediction
|
||||
|
||||
### One-Shot Learning
|
||||
Learn immediately from single examples:
|
||||
- BTSP: Seconds-scale eligibility traces
|
||||
- No batch retraining required
|
||||
- Personalization through use
|
||||
|
||||
## Tutorial: Building a Custom Application
|
||||
|
||||
### Step 1: Define Your Sensing Layer
|
||||
|
||||
```rust
|
||||
use ruvector_nervous_system::eventbus::{DVSEvent, EventRingBuffer};
|
||||
|
||||
// Create event buffer with backpressure
|
||||
let buffer = EventRingBuffer::new(1024);
|
||||
|
||||
// Process events sparsely
|
||||
if let Some(event) = buffer.pop() {
|
||||
// Only significant changes generate events
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: Add Reflex Gates
|
||||
|
||||
```rust
|
||||
use ruvector_nervous_system::compete::WTALayer;
|
||||
|
||||
// Winner-take-all for fast decisions
|
||||
let mut wta = WTALayer::new(100, 0.5, 0.8);
|
||||
|
||||
// <1μs for 1000 neurons
|
||||
if let Some(winner) = wta.compete(&inputs) {
|
||||
trigger_immediate_response(winner);
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Implement Memory
|
||||
|
||||
```rust
|
||||
use ruvector_nervous_system::hopfield::ModernHopfield;
|
||||
use ruvector_nervous_system::hdc::Hypervector;
|
||||
|
||||
// Hopfield for associative retrieval
|
||||
let mut hopfield = ModernHopfield::new(512, 10.0);
|
||||
hopfield.store(pattern);
|
||||
|
||||
// HDC for ultra-fast similarity
|
||||
let similarity = v1.similarity(&v2); // <100ns
|
||||
```
|
||||
|
||||
### Step 4: Enable Learning
|
||||
|
||||
```rust
|
||||
use ruvector_nervous_system::plasticity::btsp::BTSPSynapse;
|
||||
|
||||
// One-shot learning
|
||||
let mut synapse = BTSPSynapse::new(0.5, 2000.0); // 2s time constant
|
||||
synapse.update(presynaptic_active, plateau_signal, dt);
|
||||
```
|
||||
|
||||
### Step 5: Add Coherence
|
||||
|
||||
```rust
|
||||
use ruvector_nervous_system::routing::{OscillatoryRouter, GlobalWorkspace};
|
||||
|
||||
// Phase-coupled routing
|
||||
let mut router = OscillatoryRouter::new(10, 40.0); // 40Hz gamma
|
||||
let gain = router.communication_gain(sender, receiver);
|
||||
|
||||
// Global workspace (4-7 items)
|
||||
let mut workspace = GlobalWorkspace::new(7);
|
||||
workspace.broadcast(representation);
|
||||
```
|
||||
|
||||
## Performance Targets
|
||||
|
||||
| Component | Latency | Throughput |
|
||||
|-----------|---------|------------|
|
||||
| Event Bus | <100ns push/pop | 10,000+ events/ms |
|
||||
| WTA | <1μs | 1M+ decisions/sec |
|
||||
| HDC Similarity | <100ns | 10M+ comparisons/sec |
|
||||
| Hopfield Retrieval | <1ms | 1000+ queries/sec |
|
||||
| BTSP Update | <100ns | 10M+ synapses/sec |
|
||||
|
||||
## From Practical to SOTA
|
||||
|
||||
The same architecture scales from:
|
||||
|
||||
1. **Practical**: Anomaly detection with microsecond response
|
||||
2. **Transformative**: Self-optimizing software systems
|
||||
3. **Exotic**: Machines that sense their own coherence
|
||||
4. **SOTA**: Neuromorphic RAG, self-modeling agents, collective dreaming
|
||||
|
||||
The difference is how much reflex, learning, and coherence you turn on.
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [Architecture Documentation](../../docs/nervous-system/architecture.md)
|
||||
- [Deployment Guide](../../docs/nervous-system/deployment.md)
|
||||
- [Test Plan](../../docs/nervous-system/test-plan.md)
|
||||
- [Main Crate Documentation](../README.md)
|
||||
|
||||
## Contributing
|
||||
|
||||
Examples welcome! Each should demonstrate:
|
||||
1. A clear use case
|
||||
2. The nervous system architecture
|
||||
3. Performance characteristics
|
||||
4. Tests and documentation
|
||||
|
||||
## License
|
||||
|
||||
MIT License - See [LICENSE](../LICENSE)
|
||||
Reference in New Issue
Block a user