Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 27 additions & 12 deletions .github/workflows/pip-release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,9 @@
# dedicated follow-up commit (drop `password:`, add the OIDC id-token
# permission + `environment: pypi`) so there is no capability gap between.
#
# Production publishing fails closed until the ADR-117 §11.3 v2 witness
# hash exists. TestPyPI remains usable to validate release artifacts.
# Every v2 publish (PyPI or TestPyPI) fails closed unless the committed
# ADR-117 §11.3 v2 witness hash exists and matches a fresh witness run of
# the Linux x86_64 wheel being published.

name: pip-release

Expand Down Expand Up @@ -82,10 +83,15 @@ jobs:
arch: x86_64
- os: ubuntu-latest
arch: aarch64
# macos_target: rustc's minimum macOS deployment target. Without it
# cibuildwheel tags x86_64 wheels 10.9 and delocate-wheel rejects
# the 10.12 .so that rustc emits.
- os: macos-15-intel # x86_64 runner
arch: x86_64
- os: macos-14 # arm64 runner
macos_target: "10.12"
- os: macos-15 # arm64 runner (the macos-14 label is no longer supported)
arch: arm64
macos_target: "11.0"
- os: windows-latest
arch: AMD64
runs-on: ${{ matrix.os }}
Expand All @@ -108,6 +114,7 @@ jobs:
CIBW_ARCHS_LINUX: ${{ matrix.arch }}
CIBW_ARCHS_MACOS: ${{ matrix.arch }}
CIBW_ARCHS_WINDOWS: ${{ matrix.arch }}
MACOSX_DEPLOYMENT_TARGET: ${{ matrix.macos_target }}
CIBW_BUILD_FRONTEND: "build"
CIBW_BEFORE_BUILD: "pip install maturin>=1.7"
# The PyO3 sdist landing depends on the cargo/Rust toolchain
Expand Down Expand Up @@ -289,15 +296,6 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
- name: Enforce production witness gate
if: |
startsWith(github.ref, 'refs/tags/v2.') ||
(github.event_name == 'workflow_dispatch' && inputs.publish_to == 'pypi')
run: |
test -s archive/v1/data/proof/expected_features_v2.sha256 || {
echo "::error::ADR-117 §11.3 release gate is incomplete: archive/v1/data/proof/expected_features_v2.sha256 is missing or empty"
exit 1
}
- name: Gather all artifacts into dist/
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
with:
Expand All @@ -307,6 +305,23 @@ jobs:
mkdir -p dist
find dist-staging -type f \( -name '*.whl' -o -name '*.tar.gz' \) -exec cp -v {} dist/ \;
ls -lh dist/
# ADR-117 §11.3 release gate: the committed v2 witness hash must exist
# AND match a fresh run of the exact Linux x86_64 wheel being published
# (python -m wifi_densepose.witness, see python/wifi_densepose/witness.py).
- name: Enforce witness gate (committed hash must match the built wheel)
run: |
set -euo pipefail
EXPECTED="$GITHUB_WORKSPACE/archive/v1/data/proof/expected_features_v2.sha256"
DATA="$GITHUB_WORKSPACE/archive/v1/data/proof/sample_csi_data.json"
test -s "$EXPECTED" || {
echo "::error::ADR-117 §11.3 release gate is incomplete: archive/v1/data/proof/expected_features_v2.sha256 is missing or empty"
exit 1
}
whl="$(ls dist/*manylinux*x86_64.whl | head -1)"
python3 -m venv "$RUNNER_TEMP/wv"
"$RUNNER_TEMP/wv/bin/pip" install "$whl"
cd "$RUNNER_TEMP" # away from the repo root's stray wifi_densepose/
"$RUNNER_TEMP/wv/bin/python" -I -m wifi_densepose.witness --data "$DATA" --expected "$EXPECTED"
# API-token auth (active path). See TODO(ADR-184 P1b) in the header
# before replacing `password:` with the OIDC id-token permission.
- name: Publish to TestPyPI (dry-run target)
Expand Down
67 changes: 67 additions & 0 deletions .github/workflows/python-ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ on:
- 'v2/crates/wifi-densepose-mat/**'
- 'v2/crates/wifi-densepose-train/**'
- 'v2/crates/wifi-densepose-signal/**'
- 'archive/v1/data/proof/sample_csi_data.json'
- 'archive/v1/data/proof/expected_features_v2.sha256'
- '.github/workflows/python-ci.yml'
pull_request:
paths:
Expand All @@ -47,6 +49,8 @@ on:
- 'v2/crates/wifi-densepose-mat/**'
- 'v2/crates/wifi-densepose-train/**'
- 'v2/crates/wifi-densepose-signal/**'
- 'archive/v1/data/proof/sample_csi_data.json'
- 'archive/v1/data/proof/expected_features_v2.sha256'
- '.github/workflows/python-ci.yml'
workflow_dispatch:

Expand Down Expand Up @@ -168,3 +172,66 @@ jobs:
exit 1
fi
echo "Default wheel is within the 5 MiB budget."

# ADR-117 §11.3 / ADR-028 — v2 witness hash. Builds the release wheel with
# the same Rust pin as pip-release.yml (1.89), feeds the synthetic
# reference signal through the Rust vitals pipeline twice, and requires
# both hashes to agree. The hash is uploaded as an artifact (this is where
# the committed `expected_features_v2.sha256` came from) and, once that
# file is committed, must equal it.
witness-v2:
name: v2 witness hash (ADR-117 §11.3)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
with:
submodules: recursive

- name: Set up Python
uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
with:
python-version: '3.12'

- name: Install Rust 1.89 (same pin as pip-release.yml)
run: |
rustup toolchain install 1.89 --profile minimal
rustup default 1.89
rustc --version

- name: Build release wheel
working-directory: python
run: |
python -m pip install --upgrade pip "maturin>=1.7,<2.0"
maturin build --release --out "$RUNNER_TEMP/wheel"

- name: Generate witness hash twice and compare
run: |
set -euo pipefail
python -m venv "$RUNNER_TEMP/wv"
"$RUNNER_TEMP/wv/bin/pip" install "$RUNNER_TEMP"/wheel/*.whl
DATA="$GITHUB_WORKSPACE/archive/v1/data/proof/sample_csi_data.json"
EXPECTED="$GITHUB_WORKSPACE/archive/v1/data/proof/expected_features_v2.sha256"
# Run outside the checkout: the repo root has a legacy
# wifi_densepose/ directory that would shadow the installed wheel.
cd "$RUNNER_TEMP"
"$RUNNER_TEMP/wv/bin/python" -I -m wifi_densepose.witness --data "$DATA" | tee run1.txt
"$RUNNER_TEMP/wv/bin/python" -I -m wifi_densepose.witness --data "$DATA" | tee run2.txt
h1="$(awk '/^sha256:/ {print $2}' run1.txt)"
h2="$(awk '/^sha256:/ {print $2}' run2.txt)"
if [ -z "$h1" ] || [ "$h1" != "$h2" ]; then
echo "::error::witness is not deterministic: '$h1' vs '$h2'"
exit 1
fi
mkdir -p "$RUNNER_TEMP/witness"
echo "$h1" > "$RUNNER_TEMP/witness/expected_features_v2.sha256"
if [ -s "$EXPECTED" ]; then
"$RUNNER_TEMP/wv/bin/python" -I -m wifi_densepose.witness --data "$DATA" --expected "$EXPECTED"
else
echo "::warning::expected_features_v2.sha256 not committed yet; generated $h1"
fi

- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
with:
name: witness-v2-hash
path: ${{ runner.temp }}/witness/expected_features_v2.sha256
if-no-files-found: error
1 change: 1 addition & 0 deletions archive/v1/data/proof/expected_features_v2.sha256
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
92d867f2ed7ec9a96b4466b26903d81ff544b6d95dfeb71bb79d14ac633cd3cc
21 changes: 21 additions & 0 deletions docs/adr/ADR-028-esp32-capability-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -236,9 +236,30 @@ python scripts/provision.py --port COM7 \
| Generator | `archive/v1/data/proof/generate_reference_signal.py` | Deterministic multipath model |
| Verifier | `archive/v1/data/proof/verify.py` | SHA-256 hash comparison |
| Expected hash | `archive/v1/data/proof/expected_features.sha256` | `0b82bd45...` |
| v2 verifier (Rust pipeline) | `python/wifi_densepose/witness.py` | `python -I -m wifi_densepose.witness` over the PyO3 wheel |
| v2 expected hash | `archive/v1/data/proof/expected_features_v2.sha256` | `92d867f2...` (ADR-117 §11.3) |

**Audit-time result:** PASS. Hash regenerated with numpy 2.4.2 + scipy 1.17.1. Pipeline hash: `8c0680d7d285739ea9597715e84959d9c356c87ee3ad35b5f1e69a4ca41151c6`.

**v2 witness (ADR-117 §11.3, 2026-11-10).** The v2 hash covers the Rust vitals
pipeline, not the v1 Python processor. Antenna 0 of each of the 1,000 reference
frames goes through `CsiVitalPreprocessor`, `BreathingExtractor` and
`HeartRateExtractor` (all `esp32_default()`, called through the PyO3 bindings).
The residuals and estimates are rounded to 6 decimals, packed as little-endian
float64 and hashed with SHA-256; `witness.py` documents the byte layout. The
`witness-v2` job in `python-ci.yml` generated the committed value
`92d867f2ed7ec9a96b4466b26903d81ff544b6d95dfeb71bb79d14ac633cd3cc`
([run 42955822833](https://github.com/ruvnet/RuView/actions/runs/42955822833),
Rust 1.89, Linux x86_64, release wheel). It ran the witness twice, and both runs
agreed. A local Rust 1.89 build on Linux x86_64 gave the same hash. Of the 1,000
frames, 501 produce a heart-rate estimate and none produce a breathing estimate:
the breathing stage needs 10 s of history, and at the 10 s mark the signal is
out of band. `python-ci.yml` re-checks the committed hash on every
`python/**` PR. `pip-release.yml` re-checks it against the manylinux x86_64
wheel it is about to publish. The hash is pinned for Linux x86_64 only; other
platforms are expected to match because of the rounding, but they are not
gated.

### 5.4 Security Posture

- JWT authentication (`python-jose[cryptography]`)
Expand Down
4 changes: 3 additions & 1 deletion docs/adr/ADR-117-pip-wifi-densepose-modernization.md
Original file line number Diff line number Diff line change
Expand Up @@ -524,9 +524,11 @@ scaffold core vitals+ client publish deferred
- [ ] GIL release (`py.allow_threads`) on all calls >0.5 ms (measured in bench).
- [ ] Integration test: feed 1,000 frames from `archive/v1/data/proof/sample_csi_data.json`
through the PyO3 vitals pipeline; assert output is deterministic across runs.
- [ ] Re-implement `witness/verify.py` using P3 bindings; compare SHA-256 against the
- [x] Re-implement `witness/verify.py` using P3 bindings; compare SHA-256 against the
v1 expected hash. **Note:** the hash will differ because the Rust and Python
processors are not identical — generate and publish a new `expected_features_v2.sha256`.
*Done 2026-11-10:* `python/wifi_densepose/witness.py`, hash generated in CI,
provenance in ADR-028 §5.3.

### P4 — WS/MQTT client layer (1 week)

Expand Down
11 changes: 7 additions & 4 deletions docs/integrations/pypi-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,9 @@ Per ADR-117 §7.3, the tombstone publishes first so it claims the
2. Verify: `pip install wifi-densepose==1.99.0; python -c "import
wifi_densepose"` → ImportError with migration URL.
3. Confirm `archive/v1/data/proof/expected_features_v2.sha256` is
committed and non-empty. Production publishing fails closed without it.
committed. Every v2 publish fails closed unless it matches a fresh
`python -I -m wifi_densepose.witness` run of the manylinux x86_64 wheel
(see ADR-028 §5.3 for how the hash was generated).
4. `git tag v2.0.0-pip && git push origin v2.0.0-pip` → the v2
`wifi-densepose` wheel matrix and matching `ruview` wheel/sdist are
published together. Their versions and dependency pin are checked in CI.
Expand All @@ -60,9 +62,10 @@ Per ADR-117 §7.3, the tombstone publishes first so it claims the

## Off-loop manual gates

- **Q3** (ADR-117 §11.3) — generate
`archive/v1/data/proof/expected_features_v2.sha256` from the v2 Rust
pipeline before a production v2 publish. The workflow enforces this gate.
- **Q3** (ADR-117 §11.3) — done. `expected_features_v2.sha256` was
generated by the `witness-v2` job in `python-ci.yml`. To regenerate it
after an intentional pipeline change, take the `witness-v2-hash`
artifact from that job, commit it, and record the run in ADR-028 §5.3.
- **OIDC Trusted Publisher** — not used. The workflow is token-based;
this is a deliberate choice to keep the secret refresh entirely in
GCP. If the project migrates to OIDC later, remove `password:`
Expand Down
2 changes: 1 addition & 1 deletion python/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion python/Cargo.toml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[package]
name = "wifi-densepose-py"
version = "2.0.0-alpha.1"
version = "2.0.0"
# The `python/` crate is intentionally OUTSIDE the `v2/` Cargo
# workspace (ADR-117 §5.2) so maturin's `python-source` + `module-name`
# config stays self-contained and `cargo test --workspace` in v2/
Expand Down
59 changes: 49 additions & 10 deletions python/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,21 +17,31 @@ for talking to a live RuView sensing-server over WebSocket or MQTT.

## Features

- **17-keypoint pose** — full-body skeletal estimate from WiFi CSI, no camera
- **Vital signs** — respiratory rate (6–30 BPM) and heart rate (40–120 BPM)
with a confidence score and clinical-grade / degraded / unreliable status
- **Presence, person count, fall detection, motion** — fused outputs from
the same CSI stream
- **10 semantic primitives** (HA-MIND) — someone-sleeping, possible-distress,
room-active, bathroom-occupied, fall-risk-elevated, bed-exit, … — ready
to wire into Home Assistant or Apple Home automations
In the compiled wheel (runs offline, no server needed):

- **Vital signs** — the Rust 3-stage pipeline: `CsiVitalPreprocessor`
(static-component suppression), `BreathingExtractor` (6–30 BPM) and
`HeartRateExtractor` (40–120 BPM), each estimate carrying a confidence
score and a valid / degraded / unreliable status
- **Pose types** — `Keypoint`, `PoseEstimate`, `PersonPose`, `BoundingBox`
for the 17-keypoint skeletons a RuView sensing-server produces
- **Beamforming Feedback (BFLD) support** — 802.11ac/ax/be compressed feedback
matrices on top of the receiver-side CSI path
- **Witness check** — `wifi_densepose.verify_witness()` re-runs the published
deterministic pipeline proof (ADR-117 §11.3)
- **GIL-releasing DSP** — extract loops run with the GIL released, so a
tokio-backed web server can call into the pipeline without stalling its
event loop
- **Tiny wheel** — ~240 KB compiled (one binary per OS/arch covers Python
3.10+ via the stable ABI)
- **Small wheel** — under 400 KB compiled (one binary per OS/arch covers
Python 3.10+ via the stable ABI)

With the `[client]` extra, from a live RuView sensing-server:

- **Pose, presence, person count, fall detection, motion** — streamed over
WebSocket (`SensingClient`) or MQTT (`RuViewMqttClient`)
- **10 semantic primitives** (HA-MIND) — someone-sleeping, possible-distress,
room-active, bathroom-occupied, fall-risk-elevated, bed-exit, … — ready
to wire into Home Assistant automations

## Install

Expand Down Expand Up @@ -66,6 +76,35 @@ Runnable examples: [`examples/reid_from_csi.py`](examples/reid_from_csi.py),
[`examples/cross_room_calibrate.py`](examples/cross_room_calibrate.py),
[`examples/mat_triage.py`](examples/mat_triage.py).

## Quickstart

Runs as-is after `pip install wifi-densepose`. It feeds 30 seconds of
synthetic CSI through the Rust pipeline and prints the recovered rates
(about 15 breaths/min and 72 beats/min):

```python
import math

from wifi_densepose import BreathingExtractor, CsiVitalPreprocessor, HeartRateExtractor

pre = CsiVitalPreprocessor.esp32_default() # 56 subcarriers, EMA static suppression
br = BreathingExtractor.esp32_default() # 0.1-0.5 Hz band, 30 s window
hr = HeartRateExtractor.esp32_default() # 0.8-2.0 Hz band, 15 s window

# 30 s of synthetic CSI at 100 Hz: 15 breaths/min (0.25 Hz) + 72 beats/min (1.2 Hz).
for i in range(3000):
t = i / 100.0
a = 10.0 + 0.5 * math.sin(2 * math.pi * 0.25 * t) + 0.05 * math.sin(2 * math.pi * 1.2 * t)
residuals = pre.process([a] * 56)
breathing = br.extract(residuals, [])
heart = hr.extract(residuals, [])

print("breathing:", breathing)
print("heart: ", heart)
```

The signal is synthetic; this shows the API, not accuracy on real CSI.

## Usage

### Extract breathing rate from a CSI stream
Expand Down
4 changes: 2 additions & 2 deletions python/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ build-backend = "maturin"
[project]
name = "wifi-densepose"
version = "2.0.0"
description = "WiFi-based human pose estimation, vital sign extraction, and ambient intelligence from Channel State Information (CSI). PyO3 bindings for the Rust core."
description = "WiFi CSI sensing for Python: Rust-compiled breathing and heart-rate DSP, pose and keypoint types, and WebSocket/MQTT clients for a RuView sensing-server."
readme = "README.md"
requires-python = ">=3.10"
license = { text = "MIT" }
Expand Down Expand Up @@ -71,7 +71,7 @@ dev = [
]

[project.urls]
Homepage = "https://github.com/ruvnet/RuView"
Homepage = "https://ruv.io"
Repository = "https://github.com/ruvnet/RuView"
Issues = "https://github.com/ruvnet/RuView/issues"
Documentation = "https://github.com/ruvnet/RuView/tree/main/docs"
Expand Down
22 changes: 15 additions & 7 deletions python/ruview-meta/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,13 @@ re-exports its full API under the `ruview` namespace — so you can
write either of these and they do the same thing:

```python
from ruview import BreathingExtractor, SensingClient
from wifi_densepose import BreathingExtractor, SensingClient
from ruview import BreathingExtractor, HeartRateExtractor
from wifi_densepose import BreathingExtractor, HeartRateExtractor
```

The WebSocket/MQTT clients live in `wifi_densepose.client` (install the
`[client]` extra).

## Install

```bash
Expand All @@ -26,14 +29,19 @@ pip install "ruview[client]" # + WebSocket/MQTT clients

## Usage

Runs as-is after `pip install ruview` (synthetic signal, about 15 breaths/min):

```python
from ruview import BreathingExtractor
import math

from ruview import BreathingExtractor, CsiVitalPreprocessor

pre = CsiVitalPreprocessor.esp32_default()
br = BreathingExtractor.esp32_default() # 56 subcarriers @ 100 Hz, 30s window
for residuals, weights in csi_source:
est = br.extract(residuals=residuals, weights=weights)
if est is not None:
print(f"{est.value_bpm:.1f} BPM (confidence={est.confidence:.2f})")
for i in range(3000):
a = 10.0 + 0.5 * math.sin(2 * math.pi * 0.25 * i / 100.0)
est = br.extract(pre.process([a] * 56), [])
print(est)
```

Full API + WebSocket / MQTT / Home Assistant integration docs:
Expand Down
2 changes: 1 addition & 1 deletion python/ruview-meta/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ dependencies = [
client = ["wifi-densepose[client]==2.0.0"]

[project.urls]
Homepage = "https://github.com/ruvnet/RuView"
Homepage = "https://ruv.io"
Repository = "https://github.com/ruvnet/RuView"
Issues = "https://github.com/ruvnet/RuView/issues"
Documentation = "https://github.com/ruvnet/RuView/tree/main/docs"
Expand Down
Loading
Loading