From 946acf2d106265d6c10bc1becec0c7f4650751e3 Mon Sep 17 00:00:00 2001 From: ruv Date: Sun, 31 May 2026 05:04:35 -0400 Subject: [PATCH] docs(cog-pose): correct misleading adapter cross-reference The --adapter docs claimed the adapter is produced by aether-arena/calibration/calibrate.py, but that reference tool targets the MM-Fi *transformer* model and emits .npz with proj/head LoRA keys, while this cog runs a *conv+MLP* model expecting safetensors with fc1.a/fc1.b/ fc2.a/fc2.b. Same LoRA mechanism, different model -> adapters are model-specific and NOT interchangeable. Clarify the expected key layout and that the Python tool is a mechanism reference, not a drop-in producer. 6/6 tests pass. Co-Authored-By: claude-flow --- v2/crates/cog-pose-estimation/src/inference.rs | 10 +++++++--- v2/crates/cog-pose-estimation/src/main.rs | 8 +++++--- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/v2/crates/cog-pose-estimation/src/inference.rs b/v2/crates/cog-pose-estimation/src/inference.rs index 8980aee3..fc675e2c 100644 --- a/v2/crates/cog-pose-estimation/src/inference.rs +++ b/v2/crates/cog-pose-estimation/src/inference.rs @@ -205,9 +205,13 @@ impl InferenceEngine { } /// Create an engine with a shared base **and an optional per-room calibration - /// adapter** (ADR-150 §3.5). The adapter is a tiny LoRA safetensors fitted from a - /// short labeled in-room capture (`aether-arena/calibration/calibrate.py`); attaching - /// it recovers SOTA-level pose in an unseen room/person. `None` = uncalibrated base. + /// adapter** (ADR-150 §3.5). The adapter is a tiny LoRA **safetensors with keys + /// `fc1.a`/`fc1.b`/`fc2.a`/`fc2.b`** — low-rank deltas for *this* engine's conv+MLP + /// pose head, fitted from a short labeled in-room capture. (It applies the same LoRA + /// calibration *mechanism* demonstrated by the reference tool in + /// `aether-arena/calibration/`, but that reference targets the MM-Fi transformer model + /// and emits a different key layout — adapters are model-specific and not interchangeable.) + /// `None` = uncalibrated base. pub fn with_weights_and_adapter( weights_path: Option<&Path>, adapter_path: Option<&Path>, diff --git a/v2/crates/cog-pose-estimation/src/main.rs b/v2/crates/cog-pose-estimation/src/main.rs index da947045..99e12b85 100644 --- a/v2/crates/cog-pose-estimation/src/main.rs +++ b/v2/crates/cog-pose-estimation/src/main.rs @@ -42,9 +42,11 @@ enum Cmd { /// Path to runtime config JSON. See `cog/config.schema.json`. #[arg(long, value_name = "PATH")] config: PathBuf, - /// Optional per-room LoRA calibration adapter (ADR-150 §3.5). Fit one with - /// `aether-arena/calibration/calibrate.py`; attaching it recovers SOTA-level - /// pose in an unseen room/person. + /// Optional per-room LoRA calibration adapter (ADR-150 §3.5): a safetensors with + /// `fc1.a`/`fc1.b`/`fc2.a`/`fc2.b` low-rank deltas for this model's pose head, + /// fitted from a short labeled in-room capture. Attaching it recovers accuracy in + /// an unseen room/person. (Same mechanism as `aether-arena/calibration/`, but that + /// reference tool targets the MM-Fi transformer model — adapters are model-specific.) #[arg(long, value_name = "PATH")] adapter: Option, },