mirror of
https://github.com/ruvnet/RuView
synced 2026-07-31 18:51:42 +00:00
rUv
f49c722764
The Rust port lived two directories deep (rust-port/wifi-densepose-rs/) without any sibling under rust-port/ that warranted the extra level. Move the whole workspace up to v2/ to match v1/ (Python) at the same depth and shorten every cd / build command across the repo. git mv preserves history for all tracked files. 60 files updated for path references (CI workflows, ADRs, docs, scripts, READMEs, internal .claude-flow state). Two manual fixes for relative-cd paths in CLAUDE.md and ADR-043 that became wrong after the depth change (cd ../.. → cd ..). Validated: - cargo check --workspace --no-default-features → clean (after target/ nuke; the gitignored target/ was carried by the OS rename and had hard-coded old paths in build scripts) - cargo test --workspace --no-default-features → 1,539 passed, 0 failed, 8 ignored (same totals as pre-rename) - ESP32-S3 on COM7 → still streaming live CSI (cb #40300, RSSI -64 dBm) After-merge follow-up: contributors should `rm -rf v2/target` once and let cargo regenerate from the new path.
94 lines
3.8 KiB
Markdown
94 lines
3.8 KiB
Markdown
# ruv-neural-decoder
|
|
|
|
Cognitive state classification and BCI decoding from neural topology embeddings.
|
|
|
|
## Overview
|
|
|
|
`ruv-neural-decoder` classifies cognitive states from brain graph embeddings and
|
|
topology metrics. It provides multiple decoding strategies -- KNN classification
|
|
from labeled exemplars, threshold-based rule systems, temporal transition detection,
|
|
and clinical biomarker scoring -- plus an ensemble pipeline that combines all
|
|
strategies for robust real-time brain-computer interface (BCI) output.
|
|
|
|
## Features
|
|
|
|
- **KNN decoder** (`knn_decoder`): K-nearest neighbor classification using stored
|
|
labeled embeddings from `ruv-neural-memory`; supports configurable k and distance
|
|
metrics
|
|
- **Threshold decoder** (`threshold_decoder`): Rule-based classification from
|
|
topology metric ranges (mincut value, modularity, efficiency, Fiedler value)
|
|
with configurable `TopologyThreshold` bounds per cognitive state
|
|
- **Transition decoder** (`transition_decoder`): Detects cognitive state transitions
|
|
from temporal topology dynamics; outputs `StateTransition` events matching
|
|
known `TransitionPattern` templates
|
|
- **Clinical scorer** (`clinical`): `ClinicalScorer` for biomarker detection via
|
|
deviation from healthy baseline distributions; flags abnormal topology patterns
|
|
- **Ensemble pipeline** (`pipeline`): `DecoderPipeline` combining all decoder
|
|
strategies with confidence-weighted voting; produces `DecoderOutput` with
|
|
classified state, confidence score, and contributing decoder votes
|
|
|
|
## Usage
|
|
|
|
```rust
|
|
use ruv_neural_decoder::{
|
|
KnnDecoder, ThresholdDecoder, TopologyThreshold,
|
|
TransitionDecoder, ClinicalScorer, DecoderPipeline, DecoderOutput,
|
|
};
|
|
use ruv_neural_core::topology::{CognitiveState, TopologyMetrics};
|
|
|
|
// Threshold-based decoding from topology metrics
|
|
let mut decoder = ThresholdDecoder::new();
|
|
decoder.add_threshold(TopologyThreshold {
|
|
state: CognitiveState::Focused,
|
|
min_modularity: 0.3,
|
|
max_modularity: 0.5,
|
|
min_efficiency: 0.6,
|
|
..Default::default()
|
|
});
|
|
let state = decoder.decode(&metrics);
|
|
|
|
// KNN-based decoding from embeddings
|
|
let mut knn = KnnDecoder::new(5); // k=5
|
|
knn.add_exemplar(embedding, CognitiveState::Rest);
|
|
let predicted = knn.classify(&query_embedding);
|
|
|
|
// Transition detection from temporal sequences
|
|
let mut transition_decoder = TransitionDecoder::new();
|
|
if let Some(transition) = transition_decoder.check(¤t_metrics) {
|
|
println!("Transition: {:?} -> {:?}", transition.from, transition.to);
|
|
}
|
|
|
|
// Full ensemble pipeline
|
|
let mut pipeline = DecoderPipeline::new();
|
|
let output: DecoderOutput = pipeline.decode(&metrics, &embedding);
|
|
println!("State: {:?}, confidence: {:.2}", output.state, output.confidence);
|
|
```
|
|
|
|
## API Reference
|
|
|
|
| Module | Key Types |
|
|
|----------------------|------------------------------------------------------------|
|
|
| `knn_decoder` | `KnnDecoder` |
|
|
| `threshold_decoder` | `ThresholdDecoder`, `TopologyThreshold` |
|
|
| `transition_decoder` | `TransitionDecoder`, `StateTransition`, `TransitionPattern`|
|
|
| `clinical` | `ClinicalScorer` |
|
|
| `pipeline` | `DecoderPipeline`, `DecoderOutput` |
|
|
|
|
## Feature Flags
|
|
|
|
| Feature | Default | Description |
|
|
|---------|---------|----------------------------------|
|
|
| `std` | Yes | Standard library support |
|
|
| `wasm` | No | WASM-compatible decoding |
|
|
|
|
## Integration
|
|
|
|
Depends on `ruv-neural-core` for `CognitiveState`, `TopologyMetrics`, and
|
|
`NeuralEmbedding` types. Consumes embeddings from `ruv-neural-embed` and
|
|
topology results from `ruv-neural-mincut`. The KNN decoder can query stored
|
|
exemplars from `ruv-neural-memory`.
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0
|