mirror of
https://github.com/ruvnet/RuView
synced 2026-07-05 14:33:19 +00:00
ruv
f21daf9aa8
New sub-package `wifi_densepose.client` (no PyO3, no Rust deps):
- ws.SensingClient — asyncio websockets>=12 wrapper for the Rust
sensing-server /ws/sensing endpoint. Yields typed dataclasses
(ConnectionEstablishedMessage, EdgeVitalsMessage, PoseDataMessage)
with raw-payload fallback for forward-compat with unknown types.
Malformed frames log+drop without breaking the stream.
- mqtt.RuViewMqttClient — paho-mqtt v2 wrapper using the explicit
CallbackAPIVersion.VERSION2 API. Per-instance unique client_id by
default (rumqttc memory lesson). MQTT v5-spec-correct topic
wildcard matcher: + as whole-level wildcard, # matches the prefix
itself plus all sub-levels. Auto-resubscribes on reconnect.
Handler exceptions are caught and logged so a misbehaving callback
can't crash the network loop.
- primitives.SemanticPrimitiveListener — typed router for the 10
HA-MIND fused inference outputs from ADR-115 §3.12
(SomeoneSleeping, PossibleDistress, RoomActive, ElderlyInactivity-
Anomaly, MeetingInProgress, BathroomOccupied, FallRiskElevated,
BedExit, NoMovementSafety, MultiRoomTransition). Decodes both
JSON payloads with confidence+explanation AND plain HA state
strings ("ON"/"OFF"/numeric). Pluggable into RuViewMqttClient.
- ha.HABlueprintHelper — read-only parser for the
homeassistant/<kind>/wifi_densepose_<node>/<id>/config payload
family. Aggregator queries: entities_for_node, by_device_class,
nodes. Useful for blueprint authors + dashboard introspection.
Test coverage (63 new tests, 156 total in Python suite):
- test_client_ha — 18 tests (topic+payload parsing, aggregator)
- test_client_primitives — 13 tests (enum coverage, listener routing)
- test_client_mqtt — 17 tests (matcher parametrize, dispatch path,
on_connect, exception isolation) — no broker needed
- test_client_ws — 6 tests including end-to-end against an in-process
websockets.serve() fixture exercising all 4 message types plus a
malformed-frame survival check
Post-bridge wheel size: 238 KB (well under ADR §5.4 5 MB budget).
Refs: docs/adr/ADR-117-pip-wifi-densepose-modernization.md §5.6
Refs: docs/adr/ADR-115-home-assistant-integration.md §3.12
Refs: #785
Co-Authored-By: claude-flow <ruv@ruv.net>
85 lines
3.4 KiB
Markdown
85 lines
3.4 KiB
Markdown
# `wifi-densepose` v2.x — PyO3 bindings for the Rust core
|
||
|
||
This directory contains the source for the `wifi-densepose` PyPI wheel
|
||
(v2.0+). It's a PyO3 + maturin build that wraps the Rust crates in
|
||
[`v2/crates/`](../v2/crates/) and replaces the legacy pure-Python
|
||
`wifi-densepose==1.1.0` (released 2025-06-07).
|
||
|
||
See [ADR-117](../docs/adr/ADR-117-pip-wifi-densepose-modernization.md)
|
||
for the full modernization plan.
|
||
|
||
## Build locally
|
||
|
||
```bash
|
||
# Install maturin + dev deps
|
||
pip install maturin pytest
|
||
|
||
# Develop-install — builds the Rust extension in-place
|
||
cd python
|
||
maturin develop
|
||
|
||
# Run the smoke tests
|
||
pytest tests/
|
||
```
|
||
|
||
The `maturin develop` command produces a debug-build wheel installed
|
||
into your current Python environment. For release builds:
|
||
|
||
```bash
|
||
maturin build --release --strip
|
||
```
|
||
|
||
The wheel lands under `python/target/wheels/`.
|
||
|
||
## Layout
|
||
|
||
```
|
||
python/
|
||
├── Cargo.toml # PyO3 + abi3-py310 + Rust deps
|
||
├── pyproject.toml # maturin backend + Python metadata
|
||
├── README.md # this file
|
||
├── src/
|
||
│ └── lib.rs # #[pymodule] — Rust binding glue
|
||
├── wifi_densepose/ # pure-Python facade (the user-facing API)
|
||
│ ├── __init__.py # re-exports compiled module symbols
|
||
│ └── py.typed # PEP 561 typed-package marker
|
||
└── tests/
|
||
└── test_smoke.py # P1 acceptance tests
|
||
```
|
||
|
||
## Phase status (per ADR-117 §6)
|
||
|
||
- ✅ **P1 — Scaffold**: module loads, version constant exposed,
|
||
6 smoke tests pass via `maturin develop`.
|
||
- ✅ **P2 — Core type bindings**: `Keypoint`, `KeypointType`,
|
||
`BoundingBox`, `PersonPose`, `PoseEstimate`. 51 additional tests.
|
||
- ✅ **P3 — Vitals + signal DSP**: `VitalStatus`, `VitalEstimate`,
|
||
`VitalReading`, `BreathingExtractor`, `HeartRateExtractor` with
|
||
`py.allow_threads` GIL release on hot loops (Q5 tokio audit on
|
||
2026-05-24 confirmed core/vitals/signal are pure-sync). 17 tests.
|
||
- ✅ **P3.5 — BFLD bindings (stub Rust)**: `BfldKind`, `BfldFrame`,
|
||
`BfldReport` — forward-compatible Python surface for 802.11ac/ax/be
|
||
Beamforming Feedback Loop Data. numpy Complex64 bridge. 19 tests.
|
||
Real Rust ingestion lands post-v2.0 in a `wifi-densepose-bfld`
|
||
crate (see ADR-117 §11.11/12); the Python API does not change.
|
||
- ✅ **P4 — WS/MQTT client**: pure-Python `wifi_densepose.client` extra
|
||
(no Rust). `SensingClient` (asyncio websockets), `RuViewMqttClient`
|
||
(paho-mqtt v2 with VERSION2 callbacks), `HABlueprintHelper` (HA
|
||
discovery payload parser), `SemanticPrimitiveListener` (typed router
|
||
for the 10 HA-MIND primitives from ADR-115 §3.12). 63 tests including
|
||
end-to-end against an in-process `websockets.serve` fixture.
|
||
- ⏳ **P5 — cibuildwheel + PyPI publish**: Linux/macOS/Windows × abi3-py310.
|
||
- ⏳ **P-tomb — v1.99.0 tombstone wheel**: pure-Python ImportError
|
||
with migration URL, published to PyPI to soft-fence v1.x users
|
||
before v2.0 ships.
|
||
|
||
Each phase ends with a checkbox PR. Tests are additive — every phase's
|
||
smoke tests must still pass after later phases land.
|
||
|
||
## Migrating from v1.x
|
||
|
||
The v1 line was a separate pure-Python implementation. v2 is a hard
|
||
break (semver-justified by 11.5 months of stack drift). Migration
|
||
guide ships in [docs/migrations/wifi-densepose-1-to-2.md](../docs/migrations/wifi-densepose-1-to-2.md)
|
||
(landing in P5).
|