docs: update README + user guide with v0.5.4 capabilities

README:
- Test badge 1300+ → 1463
- Updated capability table (171K emb/s, 100% presence, 0.012ms)
- Added "What's New in v0.5.4" section with full benchmark table
- Training pipeline quick start commands

User guide:
- Camera-Free Pose Training section (10 sensor signals, 5-phase pipeline)
- ruvllm Training Pipeline section (5 phases, quantization options)
- Publishing to HuggingFace section
- Updated table of contents

Co-Authored-By: claude-flow <ruv@ruv.net>
This commit is contained in:
ruv
2026-04-02 23:11:30 -04:00
parent ba82fcfc37
commit 73d4cb9fc2
2 changed files with 173 additions and 6 deletions
+111 -1
View File
@@ -38,7 +38,10 @@ WiFi DensePose turns commodity WiFi signals into real-time human pose estimation
14. [Hardware Setup](#hardware-setup)
- [ESP32-S3 Mesh](#esp32-s3-mesh)
- [Intel 5300 / Atheros NIC](#intel-5300--atheros-nic)
15. [Docker Compose (Multi-Service)](#docker-compose-multi-service)
15. [Camera-Free Pose Training](#camera-free-pose-training)
16. [ruvllm Training Pipeline](#ruvllm-training-pipeline)
17. [Publishing to HuggingFace](#publishing-to-huggingface)
18. [Docker Compose (Multi-Service)](#docker-compose-multi-service)
16. [Testing Firmware Without Hardware (QEMU)](#testing-firmware-without-hardware-qemu)
- [What You Need](#what-you-need)
- [Your First Test Run](#your-first-test-run)
@@ -1008,6 +1011,113 @@ These are advanced setups. See the respective driver documentation for installat
---
## Camera-Free Pose Training
RuView can train a 17-keypoint COCO pose model **without any camera** by fusing 10 sensor signals from the ESP32 nodes and Cognitum Seed:
| Signal | Source | What it provides |
|--------|--------|-----------------|
| PIR sensor | Seed GPIO 6 | Binary presence ground truth |
| BME280 temperature | Seed I2C | Occupancy proxy (temp rises with people) |
| BME280 humidity | Seed I2C | Breathing confirmation |
| Cross-node RSSI | 2x ESP32 | Rough XY position (triangulation) |
| Vitals stability | ESP32 DSP | Activity level (stable HR = stationary) |
| Temporal CSI patterns | ESP32 DSP | Walk (periodic), sit (stable), empty (flat) |
| kNN clusters | Seed vector store | Natural state groupings |
| Boundary fragility | Seed graph analysis | Regime changes (enter/exit) |
| Reed switch | Seed GPIO 5 | Door open/close events |
| Vibration sensor | Seed GPIO 13 | Footstep detection |
### How It Works
The pipeline generates weak labels from sensor fusion, then trains in 5 phases:
1. **Multi-modal collection** — Syncs CSI frames with Seed sensor events
2. **Weak label generation** — RSSI triangulation for head position, subcarrier asymmetry for hands, vibration for feet
3. **5-keypoint pose proxy** — Trains head/hands/feet positions from fused signals
4. **17-keypoint interpolation** — Derives full COCO skeleton using bone length constraints
5. **Self-refinement** — Bootstraps from confident predictions (3 rounds)
```bash
# With Cognitum Seed connected (all 10 signals):
node scripts/train-camera-free.js \
--data data/recordings/pretrain-*.csi.jsonl \
--seed-url https://169.254.42.1:8443 \
--seed-token "$SEED_TOKEN"
# Without Seed (CSI-only, 3 signals — still works):
node scripts/train-camera-free.js \
--data data/recordings/pretrain-*.csi.jsonl --no-seed
```
**Output:** 82.8 KB model (8 KB at 4-bit) with 17-keypoint predictions, 0 skeleton violations, LoRA per-node adapters, and EWC protection against forgetting.
See [ADR-071](adr/ADR-071-ruvllm-training-pipeline.md) and the [pretraining tutorial](tutorials/cognitum-seed-pretraining.md) for the full walkthrough.
---
## ruvllm Training Pipeline
All training uses **ruvllm** — a Rust-native ML runtime. No Python, no PyTorch, no GPU drivers required. Runs on any machine with Node.js.
### 5-Phase Training
| Phase | What | Duration (M4 Pro) |
|-------|------|--------------------|
| Contrastive pretraining | Triplet + InfoNCE loss on CSI embeddings | ~5s |
| Task head training | Presence, activity, vitals classifiers | ~10s |
| LoRA refinement | Per-node room adaptation (rank-4) | ~4s |
| TurboQuant quantization | 2/4/8-bit with <0.5% quality loss | <1s |
| EWC consolidation | Prevent catastrophic forgetting | <1s |
```bash
# Basic training
node scripts/train-ruvllm.js --data data/recordings/pretrain-*.csi.jsonl
# Benchmark
node scripts/benchmark-ruvllm.js --model models/csi-ruvllm
```
### Quantization Options
| Bits | Size | Compression | Quality Loss | Use Case |
|------|------|-------------|-------------|----------|
| fp32 | 48 KB | 1x | 0% | Development |
| 8-bit | 16 KB | 4x | <0.01% | Cognitum Seed inference |
| 4-bit | 8 KB | 8x | <0.1% | Recommended for deployment |
| 2-bit | 4 KB | 16x | <1% | ESP32-S3 SRAM (edge inference) |
### Key Features
- **SONA adaptation** — Adapts to new rooms in <1ms without retraining
- **LoRA adapters** — 2,048 parameters per room, hot-swappable
- **EWC protection** — Learns new rooms without forgetting previous ones
- **Deterministic** — Same seed always produces same model (reproducible)
- **10x data augmentation** — Temporal interpolation, noise injection, cross-node blending
---
## Publishing to HuggingFace
Trained models can be published to HuggingFace Hub for community use:
```bash
# Publish (uses API key from GCloud Secrets)
bash scripts/publish-huggingface.sh --version v0.5.4
# Or with Python
python scripts/publish-huggingface.py --version v0.5.4
# Dry run (preview without uploading)
bash scripts/publish-huggingface.sh --dry-run
```
The HuggingFace API key is stored in Google Cloud Secrets (`HUGGINGFACE_API_KEY` in project `cognitum-20260110`). Alternatively, set the `SEED_TOKEN` environment variable directly.
Published artifacts include: SafeTensors model, quantized variants (2/4/8-bit), LoRA adapters, training metrics, and a beginner-friendly model card.
---
## Docker Compose (Multi-Service)
For production deployments with both Rust and Python services: