feat: ADR-024 Contrastive CSI Embedding Model — all 7 phases (#52)

Full implementation of Project AETHER — Contrastive CSI Embedding Model. ## Phases Delivered 1. ProjectionHead (64→128→128) + L2 normalization 2. CsiAugmenter (5 physically-motivated augmentations) 3. InfoNCE contrastive loss + SimCLR pretraining 4. FingerprintIndex (4 index types: env, activity, temporal, person) 5. RVF SEG_EMBED (0x0C) + CLI integration 6. Cross-modal alignment (PoseEncoder + InfoNCE) 7. Deep RuVector: MicroLoRA, EWC++, drift detection, hard-negative mining, SEG_LORA ## Stats - 276 tests passing (191 lib + 51 bin + 16 rvf + 18 vitals) - 3,342 additions across 8 files - Zero unsafe/unwrap/panic/todo stubs - ~55KB INT8 model for ESP32 edge deployment Also fixes deprecated GitHub Actions (v3→v4) and adds feat/* branch CI triggers. Closes #50
2026-03-01 01:44:38 -05:00
parent 44b9c30dbc
commit 9bbe95648c
39 changed files with 5136 additions and 68 deletions
--- a/rust-port/wifi-densepose-rs/crates/README.md
+++ b/rust-port/wifi-densepose-rs/crates/README.md
@@ -0,0 +1,297 @@
+# WiFi-DensePose Rust Crates
+
+[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE)
+[![Rust 1.85+](https://img.shields.io/badge/rust-1.85%2B-orange.svg)](https://www.rust-lang.org/)
+[![Workspace](https://img.shields.io/badge/workspace-14%20crates-green.svg)](https://github.com/ruvnet/wifi-densepose)
+[![RuVector v2.0.4](https://img.shields.io/badge/ruvector-v2.0.4-purple.svg)](https://crates.io/crates/ruvector-mincut)
+[![Tests](https://img.shields.io/badge/tests-542%2B-brightgreen.svg)](#testing)
+
+**See through walls with WiFi. No cameras. No wearables. Just radio waves.**
+
+A modular Rust workspace for WiFi-based human pose estimation, vital sign monitoring, and disaster response using Channel State Information (CSI). Built on [RuVector](https://crates.io/crates/ruvector-mincut) graph algorithms and the [WiFi-DensePose](https://github.com/ruvnet/wifi-densepose) research platform by [rUv](https://github.com/ruvnet).
+
+---
+
+## Performance
+
+| Operation | Python v1 | Rust v2 | Speedup |
+|-----------|-----------|---------|---------|
+| CSI Preprocessing | ~5 ms | 5.19 us | **~1000x** |
+| Phase Sanitization | ~3 ms | 3.84 us | **~780x** |
+| Feature Extraction | ~8 ms | 9.03 us | **~890x** |
+| Motion Detection | ~1 ms | 186 ns | **~5400x** |
+| Full Pipeline | ~15 ms | 18.47 us | **~810x** |
+| Vital Signs | N/A | 86 us (11,665 fps) | -- |
+
+## Crate Overview
+
+### Core Foundation
+
+| Crate | Description | crates.io |
+|-------|-------------|-----------|
+| [`wifi-densepose-core`](wifi-densepose-core/) | Types, traits, and utilities (`CsiFrame`, `PoseEstimate`, `SignalProcessor`) | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-core.svg)](https://crates.io/crates/wifi-densepose-core) |
+| [`wifi-densepose-config`](wifi-densepose-config/) | Configuration management (env, TOML, YAML) | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-config.svg)](https://crates.io/crates/wifi-densepose-config) |
+| [`wifi-densepose-db`](wifi-densepose-db/) | Database persistence (PostgreSQL, SQLite, Redis) | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-db.svg)](https://crates.io/crates/wifi-densepose-db) |
+
+### Signal Processing & Sensing
+
+| Crate | Description | RuVector Integration | crates.io |
+|-------|-------------|---------------------|-----------|
+| [`wifi-densepose-signal`](wifi-densepose-signal/) | SOTA CSI signal processing (6 algorithms from SpotFi, FarSense, Widar 3.0) | `ruvector-mincut`, `ruvector-attn-mincut`, `ruvector-attention`, `ruvector-solver` | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-signal.svg)](https://crates.io/crates/wifi-densepose-signal) |
+| [`wifi-densepose-vitals`](wifi-densepose-vitals/) | Vital sign extraction: breathing (6-30 BPM) and heart rate (40-120 BPM) | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-vitals.svg)](https://crates.io/crates/wifi-densepose-vitals) |
+| [`wifi-densepose-wifiscan`](wifi-densepose-wifiscan/) | Multi-BSSID WiFi scanning for Windows-enhanced sensing | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-wifiscan.svg)](https://crates.io/crates/wifi-densepose-wifiscan) |
+
+### Neural Network & Training
+
+| Crate | Description | RuVector Integration | crates.io |
+|-------|-------------|---------------------|-----------|
+| [`wifi-densepose-nn`](wifi-densepose-nn/) | Multi-backend inference (ONNX, PyTorch, Candle) with DensePose head (24 body parts) | -- | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-nn.svg)](https://crates.io/crates/wifi-densepose-nn) |
+| [`wifi-densepose-train`](wifi-densepose-train/) | Training pipeline with MM-Fi dataset, 114->56 subcarrier interpolation | **All 5 crates** | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-train.svg)](https://crates.io/crates/wifi-densepose-train) |
+
+### Disaster Response
+
+| Crate | Description | RuVector Integration | crates.io |
+|-------|-------------|---------------------|-----------|
+| [`wifi-densepose-mat`](wifi-densepose-mat/) | Mass Casualty Assessment Tool -- survivor detection, triage, multi-AP localization | `ruvector-solver`, `ruvector-temporal-tensor` | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-mat.svg)](https://crates.io/crates/wifi-densepose-mat) |
+
+### Hardware & Deployment
+
+| Crate | Description | crates.io |
+|-------|-------------|-----------|
+| [`wifi-densepose-hardware`](wifi-densepose-hardware/) | ESP32, Intel 5300, Atheros CSI sensor interfaces (pure Rust, no FFI) | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-hardware.svg)](https://crates.io/crates/wifi-densepose-hardware) |
+| [`wifi-densepose-wasm`](wifi-densepose-wasm/) | WebAssembly bindings for browser-based disaster dashboard | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-wasm.svg)](https://crates.io/crates/wifi-densepose-wasm) |
+| [`wifi-densepose-sensing-server`](wifi-densepose-sensing-server/) | Axum server: ESP32 UDP ingestion, WebSocket broadcast, sensing UI | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-sensing-server.svg)](https://crates.io/crates/wifi-densepose-sensing-server) |
+
+### Applications
+
+| Crate | Description | crates.io |
+|-------|-------------|-----------|
+| [`wifi-densepose-api`](wifi-densepose-api/) | REST + WebSocket API layer | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-api.svg)](https://crates.io/crates/wifi-densepose-api) |
+| [`wifi-densepose-cli`](wifi-densepose-cli/) | Command-line tool for MAT disaster scanning | [![crates.io](https://img.shields.io/crates/v/wifi-densepose-cli.svg)](https://crates.io/crates/wifi-densepose-cli) |
+
+---
+
+## Architecture
+
+```
+                          wifi-densepose-core
+                         (types, traits, errors)
+                                  |
+              +-------------------+-------------------+
+              |                   |                   |
+    wifi-densepose-signal   wifi-densepose-nn   wifi-densepose-hardware
+    (CSI processing)        (inference)         (ESP32, Intel 5300)
+    + ruvector-mincut       + ONNX Runtime          |
+    + ruvector-attn-mincut  + PyTorch (tch)   wifi-densepose-vitals
+    + ruvector-attention    + Candle          (breathing, heart rate)
+    + ruvector-solver            |
+              |                  |             wifi-densepose-wifiscan
+              +--------+---------+            (BSSID scanning)
+                       |
+          +------------+------------+
+          |                         |
+  wifi-densepose-train    wifi-densepose-mat
+  (training pipeline)     (disaster response)
+  + ALL 5 ruvector        + ruvector-solver
+                          + ruvector-temporal-tensor
+                                |
+              +-----------------+-----------------+
+              |                 |                 |
+    wifi-densepose-api  wifi-densepose-wasm  wifi-densepose-cli
+    (REST/WS)           (browser WASM)       (CLI tool)
+              |
+    wifi-densepose-sensing-server
+    (Axum + WebSocket)
+```
+
+## RuVector Integration
+
+All [RuVector](https://github.com/ruvnet/ruvector) crates at **v2.0.4** from crates.io:
+
+| RuVector Crate | Used In | Purpose |
+|----------------|---------|---------|
+| [`ruvector-mincut`](https://crates.io/crates/ruvector-mincut) | signal, train | Dynamic min-cut for subcarrier selection & person matching |
+| [`ruvector-attn-mincut`](https://crates.io/crates/ruvector-attn-mincut) | signal, train | Attention-weighted min-cut for antenna gating & spectrograms |
+| [`ruvector-temporal-tensor`](https://crates.io/crates/ruvector-temporal-tensor) | train, mat | Tiered temporal compression (4-10x memory reduction) |
+| [`ruvector-solver`](https://crates.io/crates/ruvector-solver) | signal, train, mat | Sparse Neumann solver for interpolation & triangulation |
+| [`ruvector-attention`](https://crates.io/crates/ruvector-attention) | signal, train | Scaled dot-product attention for spatial features & BVP |
+
+## Signal Processing Algorithms
+
+Six state-of-the-art algorithms implemented in `wifi-densepose-signal`:
+
+| Algorithm | Paper | Year | Module |
+|-----------|-------|------|--------|
+| Conjugate Multiplication | SpotFi (SIGCOMM) | 2015 | `csi_ratio.rs` |
+| Hampel Filter | WiGest | 2015 | `hampel.rs` |
+| Fresnel Zone Model | FarSense (MobiCom) | 2019 | `fresnel.rs` |
+| CSI Spectrogram | Standard STFT | 2018+ | `spectrogram.rs` |
+| Subcarrier Selection | WiDance (MobiCom) | 2017 | `subcarrier_selection.rs` |
+| Body Velocity Profile | Widar 3.0 (MobiSys) | 2019 | `bvp.rs` |
+
+## Quick Start
+
+### As a Library
+
+```rust
+use wifi_densepose_core::{CsiFrame, CsiMetadata, SignalProcessor};
+use wifi_densepose_signal::{CsiProcessor, CsiProcessorConfig};
+
+// Configure the CSI processor
+let config = CsiProcessorConfig::default();
+let processor = CsiProcessor::new(config);
+
+// Process a CSI frame
+let frame = CsiFrame { /* ... */ };
+let processed = processor.process(&frame)?;
+```
+
+### Vital Sign Monitoring
+
+```rust
+use wifi_densepose_vitals::{
+    CsiVitalPreprocessor, BreathingExtractor, HeartRateExtractor,
+    VitalAnomalyDetector,
+};
+
+let mut preprocessor = CsiVitalPreprocessor::new(56); // 56 subcarriers
+let mut breathing = BreathingExtractor::new(100.0);    // 100 Hz sample rate
+let mut heartrate = HeartRateExtractor::new(100.0);
+
+// Feed CSI frames and extract vitals
+for frame in csi_stream {
+    let residuals = preprocessor.update(&frame.amplitudes);
+    if let Some(bpm) = breathing.push_residuals(&residuals) {
+        println!("Breathing: {:.1} BPM", bpm);
+    }
+}
+```
+
+### Disaster Response (MAT)
+
+```rust
+use wifi_densepose_mat::{DisasterResponse, DisasterConfig, DisasterType};
+
+let config = DisasterConfig {
+    disaster_type: DisasterType::Earthquake,
+    max_scan_zones: 16,
+    ..Default::default()
+};
+
+let mut responder = DisasterResponse::new(config);
+responder.add_scan_zone(zone)?;
+responder.start_continuous_scan().await?;
+```
+
+### Hardware (ESP32)
+
+```rust
+use wifi_densepose_hardware::{Esp32CsiParser, CsiFrame};
+
+let parser = Esp32CsiParser::new();
+let raw_bytes: &[u8] = /* UDP packet from ESP32 */;
+let frame: CsiFrame = parser.parse(raw_bytes)?;
+println!("RSSI: {} dBm, {} subcarriers", frame.metadata.rssi, frame.subcarriers.len());
+```
+
+### Training
+
+```bash
+# Check training crate (no GPU needed)
+cargo check -p wifi-densepose-train --no-default-features
+
+# Run training with GPU (requires tch/libtorch)
+cargo run -p wifi-densepose-train --features tch-backend --bin train -- \
+    --config training.toml --dataset /path/to/mmfi
+
+# Verify deterministic training proof
+cargo run -p wifi-densepose-train --features tch-backend --bin verify-training
+```
+
+## Building
+
+```bash
+# Clone the repository
+git clone https://github.com/ruvnet/wifi-densepose.git
+cd wifi-densepose/rust-port/wifi-densepose-rs
+
+# Check workspace (no GPU dependencies)
+cargo check --workspace --no-default-features
+
+# Run all tests
+cargo test --workspace --no-default-features
+
+# Build release
+cargo build --release --workspace
+```
+
+### Feature Flags
+
+| Crate | Feature | Description |
+|-------|---------|-------------|
+| `wifi-densepose-nn` | `onnx` (default) | ONNX Runtime backend |
+| `wifi-densepose-nn` | `tch-backend` | PyTorch (libtorch) backend |
+| `wifi-densepose-nn` | `candle-backend` | Candle (pure Rust) backend |
+| `wifi-densepose-nn` | `cuda` | CUDA GPU acceleration |
+| `wifi-densepose-train` | `tch-backend` | Enable GPU training modules |
+| `wifi-densepose-mat` | `ruvector` (default) | RuVector graph algorithms |
+| `wifi-densepose-mat` | `api` (default) | REST + WebSocket API |
+| `wifi-densepose-mat` | `distributed` | Multi-node coordination |
+| `wifi-densepose-mat` | `drone` | Drone-mounted scanning |
+| `wifi-densepose-hardware` | `esp32` | ESP32 protocol support |
+| `wifi-densepose-hardware` | `intel5300` | Intel 5300 CSI Tool |
+| `wifi-densepose-hardware` | `linux-wifi` | Linux commodity WiFi |
+| `wifi-densepose-wifiscan` | `wlanapi` | Windows WLAN API async scanning |
+| `wifi-densepose-core` | `serde` | Serialization support |
+| `wifi-densepose-core` | `async` | Async trait support |
+
+## Testing
+
+```bash
+# Unit tests (all crates)
+cargo test --workspace --no-default-features
+
+# Signal processing benchmarks
+cargo bench -p wifi-densepose-signal
+
+# Training benchmarks
+cargo bench -p wifi-densepose-train --no-default-features
+
+# Detection benchmarks
+cargo bench -p wifi-densepose-mat
+```
+
+## Supported Hardware
+
+| Hardware | Crate Feature | CSI Subcarriers | Cost |
+|----------|---------------|-----------------|------|
+| ESP32-S3 Mesh (3-6 nodes) | `hardware/esp32` | 52-56 | ~$54 |
+| Intel 5300 NIC | `hardware/intel5300` | 30 | ~$50 |
+| Atheros AR9580 | `hardware/linux-wifi` | 56 | ~$100 |
+| Any WiFi (Windows/Linux) | `wifiscan` | RSSI-only | $0 |
+
+## Architecture Decision Records
+
+Key design decisions documented in [`docs/adr/`](https://github.com/ruvnet/wifi-densepose/tree/main/docs/adr):
+
+| ADR | Title | Status |
+|-----|-------|--------|
+| [ADR-014](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-014-sota-signal-processing.md) | SOTA Signal Processing | Accepted |
+| [ADR-015](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-015-public-dataset-training-strategy.md) | MM-Fi + Wi-Pose Training Datasets | Accepted |
+| [ADR-016](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-016-ruvector-integration.md) | RuVector Training Pipeline | Accepted (Complete) |
+| [ADR-017](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-017-ruvector-signal-mat-integration.md) | RuVector Signal + MAT Integration | Accepted |
+| [ADR-021](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-021-vital-sign-detection.md) | Vital Sign Detection Pipeline | Accepted |
+| [ADR-022](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-022-windows-wifi-enhanced.md) | Windows WiFi Enhanced Sensing | Accepted |
+| [ADR-024](https://github.com/ruvnet/wifi-densepose/blob/main/docs/adr/ADR-024-contrastive-csi-embedding.md) | Contrastive CSI Embedding Model | Accepted |
+
+## Related Projects
+
+- **[WiFi-DensePose](https://github.com/ruvnet/wifi-densepose)** -- Main repository (Python v1 + Rust v2)
+- **[RuVector](https://github.com/ruvnet/ruvector)** -- Graph algorithms for neural networks (5 crates, v2.0.4)
+- **[rUv](https://github.com/ruvnet)** -- Creator and maintainer
+
+## License
+
+All crates are dual-licensed under [MIT](https://opensource.org/licenses/MIT) OR [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0).
+
+Copyright (c) 2024 rUv