Ruview/docs/adr/ADR-048-adaptive-csi-classifier.md

# ADR-048: Adaptive CSI Activity Classifier

| Field | Value |
|-------|-------|
| Status | Accepted |
| Date | 2026-03-05 |
| Deciders | ruv |
| Depends on | ADR-024 (AETHER Embeddings), ADR-039 (Edge Processing), ADR-045 (AMOLED Display) |

## Context

WiFi-based activity classification using ESP32 Channel State Information (CSI) relies on hand-tuned thresholds to distinguish between activity states (absent, present_still, present_moving, active). These static thresholds are brittle — they don't account for:

- **Environment-specific signal patterns**: Room geometry, furniture, wall materials, and ESP32 placement all affect how CSI signals respond to human activity.
- **Temporal noise characteristics**: Real ESP32 CSI data at ~10 FPS has significant frame-to-frame jitter that causes classification to jump between states.
- **Vital signs estimation noise**: Heart rate and breathing rate estimates from Goertzel filter banks produce large swings (50+ BPM frame-to-frame) at low confidence levels.

The existing threshold-based approach produces noisy, unstable classifications that degrade the user experience in the Observatory visualization and the main dashboard.

## Decision

### 1. Three-Stage Signal Smoothing Pipeline

All CSI-derived metrics pass through a three-stage pipeline before reaching the UI:

#### Stage 1: Adaptive Baseline Subtraction
- EMA with α=0.003 (~30s time constant) tracks the "quiet room" noise floor
- Only updates during low-motion periods to avoid inflating baseline during activity
- 50-frame warm-up period for initial baseline learning
- Subtracts 70% of baseline from raw motion score to remove environmental drift

#### Stage 2: EMA + Median Filtering
- **Motion score**: Blended from 4 signals (temporal diff 40%, variance 20%, motion band power 25%, change points 15%), then EMA-smoothed with α=0.15
- **Vital signs**: 21-frame sliding window → trimmed mean (drop top/bottom 25%) → EMA with α=0.02 (~5s time constant)
- **Dead-band**: HR won't update unless trimmed mean differs by >2 BPM; BR needs >0.5 BPM
- **Outlier rejection**: HR jumps >8 BPM/frame and BR jumps >2 BPM/frame are discarded

#### Stage 3: Hysteresis Debounce
- Activity state transitions require 4 consecutive frames (~0.4s) of agreement before committing
- Prevents rapid flickering between states
- Independent candidate tracking resets on new direction changes

### 2. Adaptive Classifier Module (`adaptive_classifier.rs`)

A Rust-native environment-tuned classifier that learns from labeled JSONL recordings:

#### Feature Extraction (15 features)
| # | Feature | Source | Discriminative Power |
|---|---------|--------|---------------------|
| 0 | variance | Server | Medium — temporal CSI spread |
| 1 | motion_band_power | Server | Medium — high-frequency subcarrier energy |
| 2 | breathing_band_power | Server | Low — respiratory band energy |
| 3 | spectral_power | Server | Low — mean squared amplitude |
| 4 | dominant_freq_hz | Server | Low — peak subcarrier index |
| 5 | change_points | Server | Medium — threshold crossing count |
| 6 | mean_rssi | Server | Low — received signal strength |
| 7 | amp_mean | Subcarrier | Medium — mean amplitude across 56 subcarriers |
| 8 | amp_std | Subcarrier | **High** — amplitude spread (motion increases spread) |
| 9 | amp_skew | Subcarrier | Medium — asymmetry of amplitude distribution |
| 10 | amp_kurt | Subcarrier | **High** — peakedness (presence creates peaks) |
| 11 | amp_iqr | Subcarrier | Medium — inter-quartile range |
| 12 | amp_entropy | Subcarrier | **High** — spectral entropy (motion increases disorder) |
| 13 | amp_max | Subcarrier | Medium — peak amplitude value |
| 14 | amp_range | Subcarrier | Medium — amplitude dynamic range |

#### Training Algorithm
- **Multiclass logistic regression** with softmax output
- **Mini-batch SGD** (batch size 32, 200 epochs, linear learning rate decay)
- **Z-score normalisation** using global mean/stddev computed from all training data
- Per-class statistics (mean, stddev) stored for Mahalanobis distance fallback
- Deterministic shuffling (LCG PRNG, seed 42) for reproducible results

#### Training Data Pipeline
1. Record labeled CSI sessions via `POST /api/v1/recording/start {"id":"train_<label>"}`
2. Filename-based label assignment: `*empty*`→absent, `*still*`→present_still, `*walking*`→present_moving, `*active*`→active
3. Train via `POST /api/v1/adaptive/train`
4. Model saved to `data/adaptive_model.json`, auto-loaded on server restart

#### Inference Pipeline
1. Extract 15-feature vector from current CSI frame
2. Z-score normalise using stored global mean/stddev
3. Compute softmax probabilities across 4 classes
4. Blend adaptive model confidence (70%) with smoothed threshold confidence (30%)
5. Override classification only when adaptive model is loaded

### 3. API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/adaptive/train` | Train classifier from `train_*` recordings |
| GET | `/api/v1/adaptive/status` | Check model status, accuracy, class stats |
| POST | `/api/v1/adaptive/unload` | Revert to threshold-based classification |
| POST | `/api/v1/recording/start` | Start recording CSI frames (JSONL) |
| POST | `/api/v1/recording/stop` | Stop recording |
| GET | `/api/v1/recording/list` | List available recordings |

### 4. Vital Signs Smoothing

| Parameter | Value | Rationale |
|-----------|-------|-----------|
| Median window | 21 frames | ~2s of history, robust to transients |
| Aggregation | Trimmed mean (middle 50%) | More stable than pure median, less noisy than raw mean |
| EMA alpha | 0.02 | ~5s time constant — readings change very slowly |
| HR dead-band | ±2 BPM | Prevents display creep from micro-fluctuations |
| BR dead-band | ±0.5 BPM | Same for breathing rate |
| HR max jump | 8 BPM/frame | Outlier rejection threshold |
| BR max jump | 2 BPM/frame | Outlier rejection threshold |

## Consequences

### Benefits
- **Stable UI**: Vital signs readings hold steady for 5-10+ seconds instead of jumping every frame
- **Environment adaptation**: Classifier learns the specific room's signal characteristics
- **Graceful fallback**: If no adaptive model is loaded, threshold-based classification with smoothing still works
- **No external dependencies**: Pure Rust implementation, no Python/ML frameworks needed
- **Fast training**: 3,000+ frames train in <1 second on commodity hardware
- **Portable model**: JSON serialisation, loadable on any platform

### Limitations
- **Single-link**: With one ESP32, the feature space is limited. Multi-AP setups (ADR-029) would dramatically improve separability.
- **No temporal features**: Current frame-level classification doesn't use sequence models (LSTM/Transformer). Could be added later.
- **Label quality**: Training accuracy depends heavily on recording quality (distinct activities, actual room vacancy for "empty").
- **Linear classifier**: Logistic regression may underfit non-linear decision boundaries. Could upgrade to 2-layer MLP if needed.

### Future Work
- **Online learning**: Continuously update model weights from user corrections
- **Sequence models**: Use sliding window of N frames as input for temporal pattern recognition
- **Contrastive pretraining**: Leverage ADR-024 AETHER embeddings for self-supervised feature learning
- **Multi-AP fusion**: Use ADR-029 multistatic sensing for richer feature space
- **Edge deployment**: Export learned thresholds to ESP32 firmware (ADR-039 Tier 2) for on-device classification

## Files

| File | Purpose |
|------|---------|
| `crates/wifi-densepose-sensing-server/src/adaptive_classifier.rs` | Adaptive classifier module (feature extraction, training, inference) |
| `crates/wifi-densepose-sensing-server/src/main.rs` | Smoothing pipeline, API endpoints, integration |
| `ui/observatory/js/hud-controller.js` | UI-side lerp smoothing (4% per frame) |
| `data/adaptive_model.json` | Trained model (auto-created by training endpoint) |
| `data/recordings/train_*.jsonl` | Labeled training recordings |