Repository navigation
docs: match the entity count, presence claim and capture tier to the code - #2536
Open
rudycelekli wants to merge 1 commit into
Open
rudycelekli wants to merge 1 commit into
rudycelekli wants to merge 1 commit into
Conversation
…code Three headline claims disagree with the tree. Entity count. README said 21 entities per node and listed meeting-in-progress, bathroom-occupied, bed-exit and multi-room-transition among them. DiscoveryBuilder::enabled_entities filters out every kind without a server source, and mqtt/discovery.rs asserts the result is 15; the sibling test unsourced_entities_are_never_announced asserts those four are never announced (ruvnet#2085 — announcing them left them "unknown" in HA forever). docs/integrations/home-assistant.md already says 15 (9 raw + 6 semantic). Use 15 and drop the four unsourced entries. Presence. The 82.3% figure is held-out temporal-triplet accuracy, an embedding-quality metric, and was filed as the presence number under "Real & validated / MEASURED". The published head on top of that encoder is degenerate: bias 8.19 exceeds weight norm 3.67, so on L2-normalised embeddings every logit lands in [4.52, 11.86] and `absent` is unreachable (ruvnet#1521). model_gates.rs documents the same arithmetic and the ADR-298 gate rejects the head. Keep the encoder number, label it as embedding quality, and state the head's status. Capture tier. The provisioning example prescribes --edge-tier 2 with no note that tier 2 replaces raw CSI with on-node derived values, while the room-learning CLI requires edge_tier=0 (room.rs:4, :73; ADR-061 lists tier 0 as raw CSI passthrough). Say which tier to use for capture. Docs only.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three headline claims disagree with the tree. All three are the shape AGENTS.md already legislates for — "do not copy volatile counts into documentation", and the
MEASURED/CLAIMED/SYNTHETICvocabulary — so this extends the existing honest-labelling discipline (ADR-187) rather than introducing a new one.1. Entity count: 21 → 15
README.md:39said "Ships 21 entities per node (11 raw signals + 10 inferred semantic states: … meeting-in-progress, bathroom-occupied, … bed-exit, … multi-room-transition)".DiscoveryBuilder::enabled_entitiesdeclares 21 kinds and then filters out every kind without a server source. The crate's own tests pin the result:mqtt/discovery.rs:606—assert_eq!(entities.len(), 15);unsourced_entities_are_never_announced— assertsZoneOccupancy, BathroomOccupied, BedExit, MultiRoomTransition, MeetingInProgress, PoseKeypointsare never announced, with the comment "HA discovery announces entities that never receive state #2085: announcing these left them 'unknown' in HA forever."Four of those six were in the README's list of ten.
docs/integrations/home-assistant.mdalready says 15 entities (9 raw + 6 semantic) and even explains the gap at:406("not announced yet (zones, bathroom, bed exit, meeting)"). So the README was the only place still carrying 21.Now 15 (9 raw + 6 semantic), with the four unsourced entries removed. README,
discovery.rsand the HA doc agree.2. Presence: separate the encoder metric from the head's status
README.md:338filed presence under Real & validated / MEASURED / published with "Presence = 82.3% held-out temporal-triplet accuracy … the pose/presence numbers the project stands behind today", anddocs/user-guide.md:1465carried ✅ with the same number.Two things are conflated there. The 82.3% is
heldout_triplet_acc— an embedding-quality metric, not a presence decision rate. And the published head on top of that encoder is degenerate: bias 8.19 exceeds weight norm 3.67, so on L2-normalised embeddings every logit lands in[4.52, 11.86],p(present) ≥ 0.989for every input, andabsentis unreachable (#1521).This is not a new assertion — the repo already states it.
v2/crates/wifi-densepose-train/src/model_gates.rs:9documents "logit positive (8.19 − 3.67 = 4.52 > 0), so predicted presence probability is ≥ ~0.989 for every valid input", ADR-298 is Accepted, and the gate's tests are named for the issue. I ran them atce8d296c:So the encoder number stays and is labelled as what it measures; the head's status is stated. The artifact itself lives in the HF repo and is not changed here.
3. Capture tier
docs/user-guide.mdprescribes--edge-tier 2in the provisioning example with no note that tier 2 replaces raw CSI with on-node derived values, while the room-learning CLI requires tier 0:v2/crates/wifi-densepose-cli/src/room.rs:4— "requiresedge_tier=0raw CSI"room.rs:73— "raw CSI; provision with--edge-tier 0"edge_tier=0as "Raw CSI passthrough (no DSP)"Added a short note saying which tier to provision for capture/training versus on-node vitals. (The NVS table's documented default of
0is correct and unchanged — the gap was only in the worked example.)Validation
Docs only; no code paths touched. I verified every cited path and ADR resolves, and that the three entity figures now agree. No markdown gate exists in
.github/workflows/, so there is nothing further to run — I am not claiming a test proves a documentation change.Happy to split this into three PRs if you would rather review them separately.