From 3a4576a5f8df718bb4094aa6dfdb5be15129c00a Mon Sep 17 00:00:00 2001
From: lockewerks <59770696+lockewerks@users.noreply.github.com>
Date: Mon, 25 May 2026 16:51:13 -0600
Subject: [PATCH] docs(cog-pose): mark inference path wired and update README
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the stale "centred-skeleton stub returning confidence=0,
wiring is a separate PR" sentence with a description of what now
ships:

- `InferenceEngine::with_weights` loads `pose_v1.safetensors` through
  Candle and runs the documented Conv1d + Linear forward pass
- output shape is 17 (x, y) keypoint pairs with the published
  confidence = 0.185 (validation PCK@50)
- when the weights file is missing on disk, the engine logs a
  `tracing::warn!` and falls back to the centred-skeleton stub so the
  runtime contract is preserved

The 3% PCK@20 / 18.5% PCK@50 accuracy table and the "Honest reading"
section are unchanged — wiring the weights does not change the
trained model, only stops the cog from emitting placeholder values.
---
 v2/crates/cog-pose-estimation/cog/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/v2/crates/cog-pose-estimation/cog/README.md b/v2/crates/cog-pose-estimation/cog/README.md
index b17e07fa..718e82f1 100644
--- a/v2/crates/cog-pose-estimation/cog/README.md
+++ b/v2/crates/cog-pose-estimation/cog/README.md
@@ -58,7 +58,7 @@ Loss curve: 0.181 (epoch 0) → 0.014 (epoch 399), eval loss 0.010. **400 epochs
 - Re-train with the same Candle pipeline (already validated to converge in seconds on RTX 5080).
 - Hailo HEF export via the Dataflow Compiler on a self-hosted runner.
 
-The cog's runtime inference path is currently a centred-skeleton stub returning `confidence=0`. Wiring the `pose_v1.safetensors` weights into `src/inference.rs` is the next code change — separate PR.
+The cog's runtime inference path now loads `pose_v1.safetensors` directly through Candle in `src/inference.rs` — see `InferenceEngine::with_weights` and the `weights_load_and_forward_produces_seventeen_keypoint_pairs` test in the same file. The forward pass mirrors the training script (`Conv1d 56→64→128→128` encoder with dilations `[1, 2, 4]`, `GlobalMeanPool`, `Linear 128→256→34`, sigmoid) and emits `[17, 2]` keypoints with the published `confidence = 0.185` (PCK@50). If the safetensors file is missing on disk, the engine logs a `tracing::warn!` and falls back to the centred-skeleton stub (`confidence = 0`) so the runtime contract is preserved and the dashboard surfaces "no model yet" instead of crashing. The 3% PCK@20 / 18.5% PCK@50 numbers above remain the right way to read this model — wiring the weights does not improve accuracy, only replaces the placeholder output with the trained values.
 
 ## See also