docs(adr-117): point README + user-guide at the live PyPI releases

Both packages are now live on PyPI; bring the in-repo docs up to match. Keep both updates brief — the canonical surface documentation lives on the PyPI project pages themselves. Root README (Option 4 block): - Switch the default `pip install` example to `ruview` (the brand name) and note `wifi-densepose` is equivalent. - Add live PyPI version badges for both packages. docs/user-guide.md (§Python wheel): - Replace the single-install example with a table showing both PyPI projects and their import names so users see the choice immediately. - Add three short usage snippets (vitals, live sensing-server WS, HA-MIND semantic-primitive MQTT listener) so the guide doubles as a "what does this thing do?" reference for someone landing via pip. - Note the cibuildwheel matrix for multi-arch wheels. - Add the `pytest tests/` + `pytest bench/` source-build verify steps. No code or test changes. Refs: docs/adr/ADR-117-pip-wifi-densepose-modernization.md Refs: #786 Co-Authored-By: claude-flow <ruv@ruv.net>
2026-06-12 10:43:19 +00:00 · 2026-05-24 13:12:29 -04:00
2 changed files with 51 additions and 14 deletions
@@ -112,12 +112,19 @@ node scripts/rf-scan.js --port 5006           # Live RF room scan
 node scripts/snn-csi-processor.js --port 5006  # SNN real-time learning
 node scripts/mincut-person-counter.js --port 5006  # Correct person counting

-# Option 4: Python — talk to a RuView node from your own code (ADR-117)
-pip install "wifi-densepose[client]"  # ~250 KB compiled wheel, abi3-py310
+# Option 4: Python — live on PyPI (ADR-117)
+pip install ruview                        # or: pip install wifi-densepose
+# Both ship the same compiled PyO3 wheel (~250 KB, abi3-py310, Linux/macOS/Windows).
+# Add [client] for the asyncio WebSocket + paho-mqtt clients:
+pip install "ruview[client]"              # or: pip install "wifi-densepose[client]"
+
+# from ruview import BreathingExtractor, HeartRateExtractor   # equivalent to:
 # from wifi_densepose import BreathingExtractor, HeartRateExtractor
-# from wifi_densepose.client import SensingClient, RuViewMqttClient
+# from ruview.client import SensingClient, RuViewMqttClient
 ```

+[![PyPI ruview](https://img.shields.io/pypi/v/ruview?label=ruview)](https://pypi.org/project/ruview/) [![PyPI wifi-densepose](https://img.shields.io/pypi/v/wifi-densepose?label=wifi-densepose)](https://pypi.org/project/wifi-densepose/)
+
 > [!NOTE]
 > **CSI-capable hardware recommended.** Presence, vital signs, through-wall sensing, and all advanced capabilities require Channel State Information (CSI) from an ESP32-S3 ($9) or research NIC. The Docker image runs with simulated data for evaluation. Consumer WiFi laptops provide RSSI-only presence detection.

@@ -166,24 +166,48 @@ See the full crate list and dependency order in [CLAUDE.md](../CLAUDE.md#crate-p

 ### Python wheel (pip) — ADR-117

-The `wifi-densepose` PyPI wheel is a PyO3 binding to the Rust core. It
-ships compiled DSP (~250 KB, Linux/macOS/Windows × abi3-py310) plus an
-opt-in pure-Python WebSocket/MQTT client for talking to a live RuView
-sensing-server.
+The Python API ships as **two interchangeable PyPI packages** — same
+compiled PyO3 wheel under both names; pick whichever import name
+reads better in your code:
+
+| PyPI | Install | Latest | Import |
+|---|---|---|---|
+| [`ruview`](https://pypi.org/project/ruview/) | `pip install ruview` | `2.0.0a1` | `from ruview import ...` |
+| [`wifi-densepose`](https://pypi.org/project/wifi-densepose/) | `pip install wifi-densepose` | `2.0.0a1` | `from wifi_densepose import ...` |

 ```bash
-pip install wifi-densepose                  # core DSP only
-pip install "wifi-densepose[client]"        # + websockets + paho-mqtt
+pip install ruview                        # core DSP (~250 KB compiled wheel)
+pip install "ruview[client]"              # + asyncio WebSocket + paho-mqtt
 ```

 ```python
-from wifi_densepose import BreathingExtractor, HeartRateExtractor
-from wifi_densepose.client import SensingClient, RuViewMqttClient
+# vitals
+from ruview import BreathingExtractor, HeartRateExtractor
+br = BreathingExtractor.esp32_default()   # 56 subcarriers @ 100 Hz, 30s window
+
+# live sensing-server stream
+from ruview.client import SensingClient, EdgeVitalsMessage
+async with SensingClient("ws://localhost:8765/ws/sensing") as c:
+    async for msg in c.stream():
+        if isinstance(msg, EdgeVitalsMessage):
+            print(msg.breathing_rate_bpm, msg.heartrate_bpm)
+
+# Home Assistant semantic primitives (ADR-115 HA-MIND)
+from ruview.client import (
+    RuViewMqttClient, SemanticPrimitive, SemanticPrimitiveListener,
+)
 ```

-The legacy `wifi-densepose==1.1.0` FastAPI server is end-of-life;
-`wifi-densepose==1.99.0` is a tombstone that raises `ImportError`
-with a migration URL.
+The wheels ship for Linux (x86_64, aarch64 via sdist), macOS (sdist),
+and Windows (amd64 wheel). Stable ABI (`abi3-py310`) — one binary
+covers Python 3.10+. Multi-arch native wheels are produced by the
+[pip-release.yml](../.github/workflows/pip-release.yml) cibuildwheel
+matrix on each `v*-pip` tag.
+
+> **Migrating from v1.x?** The legacy `wifi-densepose==1.1.0` FastAPI
+> server is end-of-life. `wifi-densepose==1.99.0` is a tombstone that
+> raises `ImportError` with a migration URL; upgrade to `>=2.0.0a1`
+> (or switch to `ruview`).

 To build the wheel from source (e.g. for a local change):

@@ -192,8 +216,14 @@ git clone https://github.com/ruvnet/RuView.git
 cd RuView/python
 pip install maturin>=1.7
 maturin develop --release
+pytest tests/                              # 183 tests
+pytest bench/ --benchmark-only             # 12 hot-path benchmarks
 ```

+Full API + tests breakdown is on the PyPI front page:
+[wifi-densepose on PyPI](https://pypi.org/project/wifi-densepose/) ·
+[ruview on PyPI](https://pypi.org/project/ruview/).
+
 ### Guided Installer

 An interactive installer that detects your hardware and recommends a profile: