From bb7de84cb4d34f73e9382097b084f178a5323c73 Mon Sep 17 00:00:00 2001 From: ruv Date: Fri, 29 May 2026 19:50:21 -0400 Subject: [PATCH] docs: add Phase 3+5 scripts to user guide and README world model row MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - User guide: full retrain workflow (record → vqvae → transformer → serve) with checkpoint path usage - README: note fine-tune capability in world model capability row Co-Authored-By: claude-flow --- README.md | 2 +- docs/user-guide.md | 27 +++++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index cc486147..4856f602 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,7 @@ RuView turns ordinary WiFi into a contactless sensor. A $9 ESP32 board reads the > | 🚶 **Motion / activity** | Motion-band power + phase acceleration | Real-time | > | 🤸 **Fall detection** | Phase-acceleration threshold + 3-frame debounce + 5 s cooldown ([#263](https://github.com/ruvnet/RuView/issues/263)) | < 200 ms | > | 🧮 **Multi-person count** | Adaptive P95 normalisation + runtime-tunable dedup factor (`/api/v1/config/dedup-factor`, [#491](https://github.com/ruvnet/RuView/pull/491)). Six specialised learned counters available as Cogs: `occupancy-zones`, `elevator-count`, `queue-length`, `customer-flow`, `clean-room`, `person-matching` | Real-time, self-calibrating | -> | 🌍 **World model prediction** | OccWorld TransVQVAE — 15-frame future occupancy prediction, 209 ms inference, 3.4 GB VRAM on RTX 5080 ([ADR-147](docs/adr/ADR-147-nvidia-cosmos-world-foundation-model-integration.md)) | 15 frames × 200×200×16 vox | +> | 🌍 **World model prediction** | OccWorld TransVQVAE — 15-frame future occupancy prediction, 209 ms inference, 3.4 GB VRAM on RTX 5080; fine-tune on your space with `occworld_retrain.py` ([ADR-147](docs/adr/ADR-147-nvidia-cosmos-world-foundation-model-integration.md)) | 15 frames × 200×200×16 vox | > | 🧱 **Through-wall sensing** | Fresnel-zone geometry + multipath modeling | Up to ~5 m, signal-dependent | > | 🧠 **Edge intelligence** | **105-cog catalog** ([ADR-102](docs/adr/ADR-102-edge-module-registry.md)) live from `app-registry.json` — health, security, building, retail, industrial, research, AI, swarm, signal, network, and developer modules. Optional Cognitum Seed adds persistent vector store + kNN + witness chain | $140 total BOM | > | 🎯 **Camera-free pre-training** | Self-supervised contrastive encoder, 12.2M training steps on 60K frames, shipped on Hugging Face | 84 s/epoch retrain on M4 Pro | diff --git a/docs/user-guide.md b/docs/user-guide.md index d727b9d1..1734dac8 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1300,6 +1300,33 @@ and the [benchmark proof](adr/ADR-147-benchmark-proof.md) for full details. The Rust crate `wifi-densepose-worldmodel` connects over that Unix socket and injects trajectory priors into the pose tracker automatically when the server is running. +**Accumulate training data and fine-tune for your space (improves prediction accuracy):** +```bash +# 1. Record WorldGraph snapshots while people move through the space (~1 hour minimum) +python3 scripts/occworld_retrain.py record \ + --server http://localhost:8080 \ + --out-dir /tmp/snapshots/scene_live \ + --duration 3600 + +# 2. Fine-tune VQVAE tokenizer on indoor occupancy +python3 scripts/occworld_retrain.py vqvae \ + --snapshots /tmp/snapshots/ \ + --work-dir out/ruview_vqvae + +# 3. Fine-tune autoregressive transformer +python3 scripts/occworld_retrain.py transformer \ + --snapshots /tmp/snapshots/ \ + --vqvae-checkpoint out/ruview_vqvae/latest.pth \ + --work-dir out/ruview_occworld + +# 4. Restart the server with your checkpoint +~/ml-env/bin/python3 scripts/occworld_server.py /tmp/occworld.sock out/ruview_occworld/latest.pth +``` + +`scripts/ruview_occ_dataset.py` is the domain adapter used internally by the retraining +pipeline — it converts WorldGraph JSON snapshots to OccWorld-format tensors with indoor +class remapping and zero ego-poses. See ADR-147 Phase 3 for details. + --- ## Training a Model