paces 0.0.7__tar.gz → 0.0.8__tar.gz

{paces-0.0.7 → paces-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: paces
-Version: 0.0.7
+Version: 0.0.8
 Summary: Turn instructional media into structured, interactive learning material
 Project-URL: Homepage, https://github.com/thorwhalen/paces
 Project-URL: Repository, https://github.com/thorwhalen/paces
@@ -25,11 +25,15 @@ Requires-Dist: numba>=0.59; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: sphinx-rtd-theme>=1.0; extra == 'docs'
 Requires-Dist: sphinx>=6.0; extra == 'docs'
 Provides-Extra: media
 Requires-Dist: mixing>=0.0.39; extra == 'media'
+Provides-Extra: pose
+Requires-Dist: onnxruntime; extra == 'pose'
+Requires-Dist: rtmlib<0.1,>=0.0.16; extra == 'pose'
 Description-Content-Type: text/markdown
 
 # paces
@@ -93,6 +97,24 @@ recipes persist in a hand-overridable `document.recipes.json` sidecar; the
 `subject_locator=` seam (default: no crop) is where pose-based auto-crop
 plugs in. Design record: `docs/adr/0005-media-derivation.md`.
 
+Auto-crop to the people in frame with `pip install paces[pose]`, then
+`paces derive doc.json --media routine.mp4 --subject-locator paces.pose:rtmlib_pose`
+(or `subject_locator=paces.pose.rtmlib_pose` from Python). It probes each
+excerpt window at ~5 fps and reports every person it sees; the crop policy
+stays in the core, so two people in frame get one box around both. The extra
+itself is [rtmlib](https://github.com/Tau-J/rtmlib) (Apache-2.0, pure Python)
+and onnxruntime (MIT), with model weights downloaded on first use. Detection is
+YOLOX (Apache-2.0); what is barred from every extra here — rather than
+quarantined into one — is the **ultralytics** distribution, which is AGPL-3.0.
+
+What it pulls in is a different question, and worth stating plainly: rtmlib
+requires opencv, and opencv's *bundled FFmpeg* is **GPL-3.0-or-later on macOS
+wheels** (built `--enable-gpl` with libx264/libx265) though LGPL-2.1-or-later
+on manylinux and Windows. This is measured from the shipped binaries — the
+wheels' own `LICENSE-3RD-PARTY.txt` never mentions x264. `paces[media]`
+already brings such a wheel, so `[pose]` adds a second copy rather than a
+higher tier. `paces.pose.check_pose_requirements()` reports what you have.
+
 ## How it thinks
 
 **Analysis and rendering are separate phases** with a serialisable document
@@ -123,6 +145,7 @@ content (`OpenQuestion`), and human edits are protected from regeneration
 | protect edits from regeneration | `apply_edits(doc, patches, by="user:you")` + `merge_regenerated(committed, fresh)` |
 | the committed artifact | `to_document(seg, ...)` → `StepDocument` |
 | real clips/gifs/posters for the page | `derive_document(doc, media=..., doc_path=...)` / `paces derive` (`pip install paces[media]`) |
+| auto-crop those clips to the people in frame | `derive(..., subject_locator=paces.pose.rtmlib_pose)` / `--subject-locator paces.pose:rtmlib_pose` (`pip install paces[pose]`) |
 | a practice page | `render_html(doc)` |
 | wall-clock times from counts | `resolve(doc)` |
 | sanity checks | `validate_document(doc)` |

{paces-0.0.7 → paces-0.0.8}/README.md

@@ -59,6 +59,24 @@ recipes persist in a hand-overridable `document.recipes.json` sidecar; the
 `subject_locator=` seam (default: no crop) is where pose-based auto-crop
 plugs in. Design record: `docs/adr/0005-media-derivation.md`.
 
+Auto-crop to the people in frame with `pip install paces[pose]`, then
+`paces derive doc.json --media routine.mp4 --subject-locator paces.pose:rtmlib_pose`
+(or `subject_locator=paces.pose.rtmlib_pose` from Python). It probes each
+excerpt window at ~5 fps and reports every person it sees; the crop policy
+stays in the core, so two people in frame get one box around both. The extra
+itself is [rtmlib](https://github.com/Tau-J/rtmlib) (Apache-2.0, pure Python)
+and onnxruntime (MIT), with model weights downloaded on first use. Detection is
+YOLOX (Apache-2.0); what is barred from every extra here — rather than
+quarantined into one — is the **ultralytics** distribution, which is AGPL-3.0.
+
+What it pulls in is a different question, and worth stating plainly: rtmlib
+requires opencv, and opencv's *bundled FFmpeg* is **GPL-3.0-or-later on macOS
+wheels** (built `--enable-gpl` with libx264/libx265) though LGPL-2.1-or-later
+on manylinux and Windows. This is measured from the shipped binaries — the
+wheels' own `LICENSE-3RD-PARTY.txt` never mentions x264. `paces[media]`
+already brings such a wheel, so `[pose]` adds a second copy rather than a
+higher tier. `paces.pose.check_pose_requirements()` reports what you have.
+
 ## How it thinks
 
 **Analysis and rendering are separate phases** with a serialisable document
@@ -89,6 +107,7 @@ content (`OpenQuestion`), and human edits are protected from regeneration
 | protect edits from regeneration | `apply_edits(doc, patches, by="user:you")` + `merge_regenerated(committed, fresh)` |
 | the committed artifact | `to_document(seg, ...)` → `StepDocument` |
 | real clips/gifs/posters for the page | `derive_document(doc, media=..., doc_path=...)` / `paces derive` (`pip install paces[media]`) |
+| auto-crop those clips to the people in frame | `derive(..., subject_locator=paces.pose.rtmlib_pose)` / `--subject-locator paces.pose:rtmlib_pose` (`pip install paces[pose]`) |
 | a practice page | `render_html(doc)` |
 | wall-clock times from counts | `resolve(doc)` |
 | sanity checks | `validate_document(doc)` |

paces-0.0.8/paces/pose.py

@@ -0,0 +1,460 @@
+"""The pointable ``subject_locator``: person boxes from rtmlib pose keypoints.
+
+ADR-0005 §3 shipped the ``subject_locator=`` seam with :func:`paces.derivation.full_frame`
+as its default — a real implementation whose honest answer is "no crop" — and pinned
+the contract with fake locators. This module is the pointable replacement: probe the
+excerpt window at ~5 fps, run RTMPose over each probed frame, and hand the core one
+region list per instant, every person seen. It **observes only**; the core still owns
+the one policy pipeline (union → percentile envelope → pad → aspect → clamp → one
+static box per window), which is exactly where the POC measured that crops go wrong.
+
+**Licence perimeter.** What this extra itself adds is permissive: rtmlib is
+Apache-2.0 (a pure-Python wheel, no bundled binaries or weights) and onnxruntime is
+MIT. Its detector is **YOLOX** (Megvii, Apache-2.0) — measured, not assumed: every
+``Body`` mode downloads a ``yolox_*`` checkpoint from download.openmmlab.com, and the
+RTMDet code in rtmlib is not what ``Body`` uses. So the accurate claim is *not* "no
+YOLO" (the issue and ADR-0005 §3 say RTMDet; that is wrong) but the one that actually
+carries the licence: no **ultralytics**, whose YOLOv5/v8/v11 are AGPL-3.0 and whose §13
+network clause reaches users you serve rather than only people you hand a copy to. What
+is barred is that distribution, not the word YOLO.
+``tests/test_pose.py`` guards that perimeter as the packaging fact it is. kodokan's
+``pose``/``track`` split is the fleet's worked example of the same quarantine.
+
+**The closure is NOT uniformly permissive, and the wheel's own notice file will not
+tell you so.** opencv — which rtmlib pulls, and which ``[media]``'s mixing already
+declares — bundles FFmpeg whose licence tier is **platform-dependent** and must be
+read off the binary, because ``LICENSE-3RD-PARTY.txt`` never mentions x264 on any
+platform. Measured per wheel (see the PR for #15 for the commands):
+
+- manylinux (what CI installs) and Windows: no x264/x265, no ``--enable-gpl``;
+  ``libavutil license: LGPL version 2.1 or later``.
+- macOS, **both** arm64 and x86_64: ``--enable-gpl --enable-version3
+  --enable-libx264 --enable-libx265``, libx264/libx265 shipped;
+  ``libavutil license: GPL version 3 or later``.
+
+That tier already arrives with ``[media]``. ``[pose]`` does not raise it — but it is
+not free of it either: rtmlib requires opencv-python *and* opencv-contrib-python,
+both unpinned, so installing it adds a second wheel carrying its own copy of those
+same binaries (issue #20).
+
+**Nothing here is imported until it is used.** ``import paces`` never touches this
+module, and importing *this* module never touches rtmlib: every rtmlib access goes
+through :func:`_import_body` or :func:`_rtmlib_version`, both of which raise an
+``ImportError`` naming the extra. Model weights download on first inference, so CI
+covers the seam's contract through fake locators and never runs a model.
+
+Usage — the shell, then the library::
+
+    paces derive doc.json --media routine.mp4 --subject-locator paces.pose:rtmlib_pose
+
+    from paces.derivation import derive_document
+    from paces.pose import RtmlibPoseLocator, rtmlib_pose
+
+    derive_document(doc, media=..., doc_path=..., subject_locator=rtmlib_pose)
+    derive_document(..., subject_locator=RtmlibPoseLocator(probe_fps=10.0))
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any, Callable, Sequence
+
+from paces.derivation import Box, LocateQuery, SubjectObservation
+
+#: Probe rate across an excerpt window, in samples per second — the POC's rate.
+#: Excerpts are 2.5–6 s loops, so ~5 fps is 13–30 looks: enough for the 4/96
+#: envelope to shrug off a stray frame, cheap enough to run on CPU.
+DFLT_PROBE_FPS = 5.0
+
+#: rtmlib ``Body`` accuracy/latency trade-off: "lightweight" | "balanced" | "performance".
+DFLT_MODE = "balanced"
+
+#: onnxruntime execution device. "cpu" is the portable answer and the only one
+#: CI would ever have; "cuda"/"mps" are a caller's choice, not a default.
+DFLT_DEVICE = "cpu"
+
+#: A keypoint below this score is noise, not evidence, and never widens a box.
+#: This threshold is load-bearing, not decorative: rtmlib's ``Body`` is a
+#: top-down pipeline, so it returns a full 17-keypoint person for a frame with
+#: nobody in it at all. Measured on a blank frame (rtmlib 0.0.15, balanced):
+#: one "person", every score ~0.11-0.13. Without this filter the locator would
+#: hand the core a confident box around nothing, every time.
+DFLT_KEYPOINT_CONFIDENCE = 0.3
+
+#: Fewer confident keypoints than this is not a person — it is a hallucinated
+#: limb or two, and boxing it would hand the core a region with no subject in
+#: it. The second half of the same defence: a real detection clears 0.3 on far
+#: more than four joints, while the blank-frame phantom above clears it on none.
+DFLT_MIN_KEYPOINTS = 4
+
+#: The extra that carries this locator, and the stem of its recorded identity.
+POSE_EXTRA = "pose"
+LOCATOR_STEM = "rtmlib-pose"
+
+#: Opt-in for the real-model smoke test. Unset (CI, always) = no weights, no
+#: inference — the contract is covered by fake locators instead.
+TEST_MODELS_ENVVAR = "PACES_TEST_MODELS"
+
+POSE_EXTRA_MISSING = (
+    "rtmlib is required for the pose subject_locator. Install it with:\n"
+    f"    pip install 'paces[{POSE_EXTRA}]'\n"
+    "That extra is rtmlib (Apache-2.0, pure Python) + onnxruntime (MIT). Its\n"
+    "detector is YOLOX (Megvii, Apache-2.0); what is barred here is the\n"
+    "ultralytics distribution — AGPL-3.0 — not the YOLO family (ADR-0005 §3).\n"
+    "Model weights download on first inference, not on install.\n"
+    "Note what it pulls in: rtmlib requires BOTH opencv-python and\n"
+    "opencv-contrib-python, and opencv's bundled FFmpeg is GPL-3.0-or-later on\n"
+    "macOS (built --enable-gpl with libx264/libx265) though LGPL-2.1-or-later\n"
+    "on manylinux and Windows. paces[media] already brings one such wheel; this\n"
+    "adds a second copy, not a higher tier (issue #20).\n"
+    "The default locator (paces.derivation.full_frame) needs none of this: it\n"
+    "answers 'no crop', which is a real answer rather than a failure."
+)
+
+POSE_METADATA_MISSING = (
+    "rtmlib is importable but has no distribution metadata, so its version\n"
+    "cannot be read — which is what a vendored copy or a source tree on\n"
+    "PYTHONPATH looks like. The version is not cosmetic: the crop recipe\n"
+    "records it, so that a model upgrade re-locates instead of reusing a box a\n"
+    "different model measured (ADR-0005 §3).\n"
+    f"Install rtmlib as a distribution (pip install 'paces[{POSE_EXTRA}]'), or\n"
+    "pass your own estimator — RtmlibPoseLocator(pose_estimator=...) names\n"
+    "itself after that estimator and never reads rtmlib's version."
+)
+
+MEDIA_EXTRA_MISSING = (
+    "the pose locator reads frames through mixing, the same media path derive\n"
+    "itself runs on. Install it with:\n"
+    "    pip install 'paces[media]'"
+)
+
+
+# ── rtmlib, reached from exactly two places ─────────────────────────────────
+
+
+def _import_body():
+    """rtmlib's ``Body`` solution (YOLOX detector + RTMPose, COCO-17).
+
+    Every rtmlib *import* goes through here so the missing-extra message is
+    written once, the way kodokan routes ultralytics through one importer.
+    """
+    try:
+        from rtmlib import Body
+    except ImportError as error:
+        raise ImportError(POSE_EXTRA_MISSING) from error
+    return Body
+
+
+def _rtmlib_version() -> str:
+    """rtmlib's version, from distribution metadata — no import, no model load.
+
+    ``derive`` reads ``locator_name`` *before* it decides whether a recipe may
+    be reused (ADR-0005 §3's re-run semantics), so naming the locator must stay
+    this cheap — and it is reported before any encode work is spent.
+
+    Two different absences, told apart because the fixes differ: no rtmlib at
+    all (install the extra) versus an importable rtmlib carrying no metadata,
+    which is a vendored copy or a source tree on ``PYTHONPATH``.
+    """
+    import importlib.util
+    from importlib.metadata import PackageNotFoundError, version
+
+    try:
+        return version("rtmlib")
+    except PackageNotFoundError as error:
+        importable = importlib.util.find_spec("rtmlib") is not None
+        raise ImportError(
+            POSE_METADATA_MISSING if importable else POSE_EXTRA_MISSING
+        ) from error
+
+
+def _estimator_identity(estimator) -> str:
+    """A stable-enough name for an injected estimator, for the recipe identity.
+
+    Its own ``locator_name`` if it declares one (the way to make an estimator
+    version itself properly), else its qualified name, else its type's.
+    """
+    declared = getattr(estimator, "locator_name", None)
+    if isinstance(declared, str):
+        return declared
+    module = getattr(estimator, "__module__", None)
+    name = getattr(estimator, "__qualname__", None) or type(estimator).__qualname__
+    return f"{module}.{name}" if module else name
+
+
+@lru_cache(maxsize=None)
+def _body_estimator(mode: str, device: str):
+    """One loaded ``Body`` per (mode, device), for the life of the process.
+
+    The first call downloads the ONNX weights; every excerpt window after it
+    reuses the loaded session rather than paying that again.
+    """
+    Body = _import_body()
+    return Body(mode=mode, backend="onnxruntime", device=device)
+
+
+def _frame_reader(media_path: str) -> Callable[[float], Any]:
+    """A ``t_seconds -> frame`` reader over one media file, through ``mixing``.
+
+    All media I/O goes through mixing, never moviepy/cv2 directly (ADR-0005).
+    ``mixing.Video`` indexes by time and hands back cv2's native BGR, which is
+    the layout rtmlib expects.
+    """
+    try:
+        from mixing import Video
+    except ImportError as error:  # pragma: no cover - needs [media] absent
+        raise ImportError(MEDIA_EXTRA_MISSING) from error
+    video = Video(media_path)
+    return lambda t_s: video[t_s]
+
+
+# ── the two pure pieces (no media, no model, no numpy) ──────────────────────
+
+
+def probe_times(
+    start_s: float, end_s: float, *, probe_fps: float = DFLT_PROBE_FPS
+) -> tuple[float, ...]:
+    """The instants to look at: ~``probe_fps`` samples spread inside the window.
+
+    Samples sit at the midpoints of ``n`` equal slices, so each one is strictly
+    inside ``[start_s, end_s)`` — a probe on the closing edge would read the
+    next shot — and a window shorter than one probe interval still gets exactly
+    one look, at its middle.
+
+    >>> tuple(round(t, 3) for t in probe_times(0.0, 1.0, probe_fps=5.0))
+    (0.1, 0.3, 0.5, 0.7, 0.9)
+    >>> tuple(round(t, 3) for t in probe_times(10.0, 10.05))
+    (10.025,)
+    """
+    if not end_s > start_s:
+        raise ValueError(
+            f"an excerpt window must be non-empty; got [{start_s}, {end_s})"
+        )
+    if not probe_fps > 0:
+        raise ValueError(f"probe_fps must be positive; got {probe_fps}")
+    count = max(1, round((end_s - start_s) * probe_fps))
+    step = (end_s - start_s) / count
+    return tuple(start_s + (index + 0.5) * step for index in range(count))
+
+
+def person_boxes(
+    keypoints: Sequence[Sequence[Sequence[float]]] | None,
+    scores: Sequence[Sequence[float]] | None,
+    *,
+    frame_size: tuple[int, int],
+    keypoint_confidence: float = DFLT_KEYPOINT_CONFIDENCE,
+    min_keypoints: int = DFLT_MIN_KEYPOINTS,
+) -> tuple[Box, ...]:
+    """One box per person, spanning that person's *confident* keypoints.
+
+    ``keypoints`` is ``(n_persons, n_keypoints, 2)`` and ``scores`` is
+    ``(n_persons, n_keypoints)`` — rtmlib's output shape, read here as plain
+    nested sequences, so this stays a pure function and numpy remains the
+    extra's business rather than this module's. A person carrying fewer than
+    ``min_keypoints`` confident points is dropped rather than boxed from noise;
+    boxes are clamped into the frame, and a degenerate one is dropped too.
+    Zero detections is ``()`` — evidence that nobody was there, not an error.
+
+    Order is rtmlib's and means nothing: the seam is a *set* of regions per
+    instant (the core unions them), so no person-identity claim is made here.
+
+    >>> person_boxes(
+    ...     [[(10, 20), (30, 60)]], [(0.9, 0.9)],
+    ...     frame_size=(100, 100), min_keypoints=2,
+    ... )
+    ((10, 20, 20, 40),)
+    """
+    if keypoints is None or scores is None:
+        return ()
+    frame_width, frame_height = frame_size
+    boxes: list[Box] = []
+    for person, person_scores in zip(keypoints, scores):
+        confident = [
+            (float(point[0]), float(point[1]))
+            for point, score in zip(person, person_scores)
+            if float(score) >= keypoint_confidence
+        ]
+        if len(confident) < min_keypoints:
+            continue
+        xs = [x for x, _y in confident]
+        ys = [y for _x, y in confident]
+        left = max(0, int(math.floor(min(xs))))
+        top = max(0, int(math.floor(min(ys))))
+        right = min(frame_width, int(math.ceil(max(xs))))
+        bottom = min(frame_height, int(math.ceil(max(ys))))
+        if right - left < 1 or bottom - top < 1:
+            continue
+        boxes.append((left, top, right - left, bottom - top))
+    return tuple(boxes)
+
+
+# ── the locator ─────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, kw_only=True)
+class RtmlibPoseLocator:
+    """The pointable ``subject_locator``: rtmlib pose boxes over a probed window.
+
+    Callable per the ADR-0005 §3 contract — a :class:`~paces.derivation.LocateQuery`
+    in, a :class:`~paces.derivation.SubjectObservation` out, or ``None``, the
+    honest "no crop", when the window showed nobody. It never resolves a box:
+    that is the core's :func:`~paces.derivation.resolve_crop_box`.
+
+    ``pose_estimator`` is the seam inside the seam: any
+    ``callable(frame) -> (keypoints, scores)``. The default is rtmlib's ``Body``
+    (YOLOX + RTMPose, COCO-17); the replacements are already pointable —
+    rtmlib's ``Wholebody``, ``Hand`` and ``Animal`` solutions have exactly this
+    shape, and the ADR's "hands + workpiece for cooking" case is one of them.
+    Tests inject a fake through it, which is how the contract is exercised with
+    no weights downloaded and no network reached.
+
+    All fields are keyword-only, and the defaults are the shipped policy.
+    """
+
+    probe_fps: float = DFLT_PROBE_FPS
+    mode: str = DFLT_MODE
+    device: str = DFLT_DEVICE
+    keypoint_confidence: float = DFLT_KEYPOINT_CONFIDENCE
+    min_keypoints: int = DFLT_MIN_KEYPOINTS
+    pose_estimator: Callable[[Any], tuple[Any, Any]] | None = None
+
+    @property
+    def locator_name(self) -> str:
+        """The policy identity the crop recipe records — **every** input that
+        can move a box, not just the model version.
+
+        ``derive`` reuses a stored box when this name and the core's params
+        still match (ADR-0005 §3), so anything left out of it silently reuses a
+        box that something else measured. That is the whole point of the
+        fingerprint, so the probe rate and both keypoint thresholds are in it
+        alongside the model::
+
+            rtmlib-pose@0.0.16;mode=balanced;fps=5;conf=0.3;minkp=4
+
+        An injected ``pose_estimator`` names *itself* — claiming rtmlib's
+        version for a box rtmlib did not measure would be exactly the false
+        identity this exists to prevent — and drops ``mode``, which is a
+        ``Body`` argument and means nothing to another estimator::
+
+            rtmlib-pose@custom:mypkg.my_estimator;fps=5;conf=0.3;minkp=4
+
+        ``device`` is deliberately absent: it selects an execution provider,
+        not a policy, and putting it in would re-locate every box on a machine
+        change — a false honesty flag, which this codebase treats as the
+        failure mode it is.
+        """
+        if self.pose_estimator is None:
+            engine = _rtmlib_version()
+            terms = [f"mode={self.mode}"]
+        else:
+            engine = f"custom:{_estimator_identity(self.pose_estimator)}"
+            terms = []
+        terms += [
+            f"fps={self.probe_fps:g}",
+            f"conf={self.keypoint_confidence:g}",
+            f"minkp={self.min_keypoints:g}",
+        ]
+        return ";".join([f"{LOCATOR_STEM}@{engine}", *terms])
+
+    def __call__(self, query: LocateQuery) -> SubjectObservation | None:
+        estimate = self.pose_estimator or _body_estimator(self.mode, self.device)
+        read_frame = _frame_reader(query.media_path)
+        frame_size = (query.frame_width, query.frame_height)
+        samples: list[tuple[float, tuple[Box, ...]]] = []
+        unreadable: list[float] = []
+        for t_s in probe_times(query.start_s, query.end_s, probe_fps=self.probe_fps):
+            try:
+                frame = read_frame(t_s)
+            except (ValueError, OSError):
+                # one unreadable probe is a damaged frame, not a verdict on the
+                # window; only losing every probe is a fault worth raising
+                unreadable.append(t_s)
+                continue
+            keypoints, scores = estimate(frame)
+            samples.append(
+                (
+                    t_s,
+                    person_boxes(
+                        keypoints,
+                        scores,
+                        frame_size=frame_size,
+                        keypoint_confidence=self.keypoint_confidence,
+                        min_keypoints=self.min_keypoints,
+                    ),
+                )
+            )
+        if not samples:
+            raise RuntimeError(
+                f"read no frame of {query.media_path} in "
+                f"[{query.start_s}, {query.end_s}) — {len(unreadable)} probes "
+                "all failed; the media is unreadable there, which is a fault, "
+                "not a 'no crop' answer"
+            )
+        if not any(boxes for _t, boxes in samples):
+            # ADR-0005 §3: None is the zero-detections fallback, and no crop
+            # means genuinely uncropped — never letterboxed
+            return None
+        return SubjectObservation(samples=tuple(samples))
+
+
+#: The ready-made locator: no configuration, and the target a CLI
+#: ``--subject-locator paces.pose:rtmlib_pose`` reference resolves to.
+rtmlib_pose = RtmlibPoseLocator()
+
+
+def check_pose_requirements() -> dict:
+    """Preflight for the ``[pose]`` extra, per channel and never silently.
+
+    - ``rtmlib`` / ``onnxruntime`` — the locator and its inference backend.
+    - ``cv2_providers`` — rtmlib declares BOTH ``opencv-python`` and
+      ``opencv-contrib-python``, while the fleet standardises on the contrib
+      superset (mixing's single cv2 provider). An install can therefore end up
+      with two distributions owning one ``cv2`` package. Reported, not fatal:
+      it works until one of them is uninstalled, and a reader deserves to know.
+
+    Downloads nothing: weights arrive on first inference, not on this check.
+    """
+    from importlib.metadata import PackageNotFoundError, version
+
+    def _version(distribution: str) -> str | None:
+        try:
+            return version(distribution)
+        except PackageNotFoundError:
+            return None
+
+    notes: list[str] = []
+    rtmlib_version = _version("rtmlib")
+    onnxruntime_version = _version("onnxruntime")
+    if rtmlib_version is None or onnxruntime_version is None:
+        missing = [
+            name
+            for name, found in (
+                ("rtmlib", rtmlib_version),
+                ("onnxruntime", onnxruntime_version),
+            )
+            if found is None
+        ]
+        notes.append(
+            f"{', '.join(missing)} not installed — install the pose extra: "
+            f"pip install 'paces[{POSE_EXTRA}]'"
+        )
+    cv2_providers = [
+        name
+        for name in ("opencv-python", "opencv-contrib-python")
+        if _version(name) is not None
+    ]
+    if len(cv2_providers) > 1:
+        notes.append(
+            "two distributions provide cv2 "
+            f"({', '.join(cv2_providers)}) — rtmlib declares both; uninstalling "
+            "either can leave the other's cv2 broken"
+        )
+    return {
+        "ok": rtmlib_version is not None and onnxruntime_version is not None,
+        "rtmlib": rtmlib_version,
+        "onnxruntime": onnxruntime_version,
+        "cv2_providers": cv2_providers,
+        "notes": notes,
+    }

{paces-0.0.7 → paces-0.0.8}/paces/tools.py

@@ -338,7 +338,8 @@ def derive(
     explicit store. ``media`` is one local file, or ``{"<source-id>":
     "<path>"}`` when several sources carry excerpts. ``subject_locator`` is
     a lazy ``"module:attr"`` ref to an ADR-0005 §3 locator; the default is
-    no crop. The updated document is written back to ``output`` (default:
+    no crop, and ``paces.pose:rtmlib_pose`` is the shipped pointable one
+    (rtmlib pose boxes, ``pip install paces[pose]``). The updated document is written back to ``output`` (default:
     the document path itself — derive's media side effects and the refs
     pointing at them must not go out of sync); the returned payload carries
     ``flags`` — read them, they are the honesty report.

{paces-0.0.7 → paces-0.0.8}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "paces"
-version = "0.0.7"
+version = "0.0.8"
 description = "Turn instructional media into structured, interactive learning material"
 readme = "README.md"
 license = "MIT"
@@ -59,6 +59,41 @@ media = [
     # get_video_dimensions ship there.
     "mixing>=0.0.39",
 ]
+# The pointable subject_locator (issue #15, ADR-0005 §3): rtmlib pose boxes,
+# reached through `paces.pose:rtmlib_pose`. rtmlib is Apache-2.0 (a pure-Python
+# wheel: no bundled binaries, no vendored weights) and onnxruntime is MIT.
+# Its detector is YOLOX (Megvii, Apache-2.0) — checked by running it, not taken
+# from the issue, which says RTMDet: every `Body` mode fetches a `yolox_*`
+# checkpoint. So the barred thing is the `ultralytics` DISTRIBUTION (AGPL-3.0,
+# §13's network clause reaching served users, not only people handed a copy),
+# not the YOLO family. That bar covers EVERY extra here, and
+# tests/test_pose.py is what notices if it ever stops being true.
+#
+# What this extra pulls in is NOT uniformly permissive, and opencv's own
+# LICENSE-3RD-PARTY.txt does not say so (it never mentions x264, on any
+# platform) — so it was measured off the shipped binaries instead:
+#   manylinux (CI) and Windows: no x264/x265, no --enable-gpl;
+#                               "libavutil license: LGPL version 2.1 or later"
+#   macOS arm64 AND x86_64:     --enable-gpl --enable-version3 with
+#                               libx264/libx265 shipped;
+#                               "libavutil license: GPL version 3 or later"
+# That tier already arrives with [media] (mixing declares opencv-contrib-
+# python). [pose] does not raise it, but it does add a SECOND wheel with its
+# own copy of those binaries, because rtmlib requires opencv-python and
+# opencv-contrib-python both, unpinned — see issue #20.
+#
+# onnxruntime is named rather than left to rtmlib's transitive closure: it is
+# the backend= this locator asks for by name, not an incidental fact.
+# rtmlib is bounded: the licence audit above was done against 0.0.16, and a
+# 0.0.x line promises no stability — a floor without a ceiling would let an
+# unaudited wheel in silently.
+# Not mirrored into [dev] on purpose: the tests are offline and stay on fake
+# locators (no weights, no network), and CI has no reason to take on the second
+# cv2 provider. `check_pose_requirements()` reports that pair when it happens.
+pose = [
+    "rtmlib>=0.0.16,<0.1",
+    "onnxruntime",
+]
 dev = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
@@ -72,6 +107,9 @@ dev = [
     # [media] (the >=0.0.39 floor wins over [audio]'s >=0.0.36).
     "mixing[beats,audio]>=0.0.39",
     "numba>=0.59",
+    # tests/test_pose.py reads pyproject.toml to guard the licence perimeter;
+    # stdlib tomllib is 3.11+, and a skipped guard guards nothing.
+    "tomli>=2.0; python_version < '3.11'",
 ]
 docs = [
     "sphinx>=6.0",
@@ -93,6 +131,38 @@ install.linux = ["sudo apt-get update", "sudo apt-get install -y ffmpeg"]
 install.macos = "brew install ffmpeg"
 install.windows = "choco install ffmpeg -y --no-progress"
 
+# --------------------------------------------------------------------------
+# Licence adjudication
+#
+# paces is MIT and its core dependency is pydantic alone, so `pip install
+# paces` pulls nothing copyleft. No extra reaches AGPL either: `pose` is rtmlib
+# (Apache-2.0) + onnxruntime (MIT), and the AGPL alternative for that job
+# (ultralytics) is barred outright rather than quarantined — kodokan needs a
+# `track` extra because Ultralytics' tracker is genuinely load-bearing there;
+# paces needs boxes, and rtmlib's Apache-2.0 YOLOX gives them. There is nothing
+# to adjudicate at the AGPL tier, hence no [tool.wads.licence.exceptions]
+# table: an entry appearing here later would mean the perimeter moved.
+#
+# What IS copyleft, and stated because a checker reading declared metadata will
+# not find it: opencv's bundled FFmpeg binaries, pulled by both [media] and
+# [pose], are GPL-3.0-or-later on macOS wheels and LGPL-2.1-or-later on
+# manylinux/Windows — measured off the shipped libraries, since the wheels'
+# LICENSE-3RD-PARTY.txt never mentions x264. See the [pose] block above.
+#
+# `include-extras` makes the check look where the exposure is — a check that
+# reads only hard dependencies would report paces clean, which is correct and
+# incomplete. `allowed`/`forbidden` are deliberately unset: they REPLACE wads'
+# defaults rather than extend them, so re-stating the permissive families here
+# would silently narrow the policy every time wads widens it.
+#
+# `enabled` stays false until the gate ships in a released wads and the extras'
+# closures have been walked with it once; flipping it is a one-line change.
+# Until then the perimeter is enforced by tests/test_pose.py, which runs in CI.
+# --------------------------------------------------------------------------
+[tool.wads.licence]
+enabled = false
+include-extras = ["cli", "audio", "media", "pose"]
+
 [tool.hatch.build.targets.wheel]
 packages = ["paces"]
 

paces-0.0.8/tests/test_pose.py

@@ -0,0 +1,520 @@
+"""The rtmlib pose subject_locator (issue #15), and the licence perimeter it sits in.
+
+Offline by construction. Nothing here installs rtmlib, downloads a weight, or
+reaches the network: the locator's contract is exercised with a fake pose
+estimator injected through ``pose_estimator=``, reading real frames out of the
+same synthetic video the derivation tests use. The one test that would run a
+real model is opt-in behind ``PACES_TEST_MODELS`` and skipped everywhere else,
+CI included — which is why ``[pose]`` is deliberately NOT mirrored into ``[dev]``.
+
+The rest is packaging. ``[pose]`` is the only extra that reaches a model
+runtime, and no behaviour in this suite would notice AGPL being slipped into it
+— these tests are what notice.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import mixing  # noqa: F401 — the frame reader is real; fail loudly, never skip
+import pytest
+
+from paces import pose
+from paces.derivation import (
+    LocateQuery,
+    SubjectObservation,
+    derive_document,
+    load_recipes,
+    resolve_crop_box,
+)
+from paces.model import Measure, Source, SourceSpan, Step, StepDocument
+from paces.pose import (
+    DFLT_MIN_KEYPOINTS,
+    POSE_EXTRA_MISSING,
+    TEST_MODELS_ENVVAR,
+    RtmlibPoseLocator,
+    check_pose_requirements,
+    person_boxes,
+    probe_times,
+    rtmlib_pose,
+)
+from video_synth import FRAME_SIZE, practice_video
+
+#: A version to stand in for an installed rtmlib, so the naming contract can be
+#: asserted on a machine that has no rtmlib at all (every CI machine).
+FAKE_RTMLIB_VERSION = "0.0.16"
+
+#: Distributions carrying AGPL terms that must never reach ANY paces extra.
+#: ultralytics pulls the other two itself, and a licence check matches per
+#: distribution name — so all three are named (ADR-0005 §3).
+FORBIDDEN_DISTRIBUTIONS = frozenset(
+    {"ultralytics", "ultralytics-thop", "ultralytics-platform"}
+)
+
+_PYPROJECT = Path(__file__).resolve().parents[1] / "pyproject.toml"
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10
+    import tomli as tomllib
+
+
+@pytest.fixture(scope="module")
+def pyproject():
+    return tomllib.loads(_PYPROJECT.read_text(encoding="utf-8"))
+
+
+@pytest.fixture(scope="module")
+def video(tmp_path_factory):
+    """The derivation suite's fixture clip: a green rect on blue, 2 s at 24 fps."""
+    return practice_video(tmp_path_factory.mktemp("pose") / "practice.mp4")
+
+
+def _people(*boxes, score=0.9):
+    """rtmlib-shaped ``(keypoints, scores)`` for people occupying ``boxes``.
+
+    Four corner keypoints each, which is exactly ``DFLT_MIN_KEYPOINTS``.
+    """
+    keypoints = [
+        [(x, y), (x + w, y), (x, y + h), (x + w, y + h)] for x, y, w, h in boxes
+    ]
+    return keypoints, [(score,) * 4 for _ in boxes]
+
+
+def _query(video, *, start_s=0.0, end_s=2.0):
+    return LocateQuery(
+        media_path=str(video),
+        start_s=start_s,
+        end_s=end_s,
+        frame_width=FRAME_SIZE[0],
+        frame_height=FRAME_SIZE[1],
+        step_id="b4",
+        tags=("performance",),
+    )
+
+
+# ── probe_times (pure) ──────────────────────────────────────────────────────
+
+
+def test_probe_times_spreads_the_asked_rate_inside_the_window():
+    times = probe_times(10.0, 13.0, probe_fps=5.0)
+    assert len(times) == 15  # 3 s at 5 fps
+    assert all(10.0 < t < 13.0 for t in times)
+    assert times == tuple(sorted(times))
+
+
+def test_probe_times_gives_a_short_window_its_middle():
+    # shorter than one probe interval: one look, and not on either edge (a probe
+    # on the closing edge reads the next shot)
+    assert probe_times(4.0, 4.1, probe_fps=5.0) == (4.05,)
+
+
+def test_probe_times_refuses_an_empty_window_and_a_dead_rate():
+    with pytest.raises(ValueError, match="non-empty"):
+        probe_times(2.0, 2.0)
+    with pytest.raises(ValueError, match="probe_fps"):
+        probe_times(0.0, 1.0, probe_fps=0.0)
+
+
+# ── person_boxes (pure) ─────────────────────────────────────────────────────
+
+
+def test_person_boxes_spans_the_confident_keypoints():
+    keypoints, scores = _people((60, 40, 100, 80))
+    assert person_boxes(keypoints, scores, frame_size=FRAME_SIZE) == (
+        (60, 40, 100, 80),
+    )
+
+
+def test_person_boxes_keeps_every_person():
+    # the judo case: two people, two regions, no identity claim and no choosing
+    keypoints, scores = _people((10, 10, 40, 90), (200, 20, 50, 80))
+    assert person_boxes(keypoints, scores, frame_size=FRAME_SIZE) == (
+        (10, 10, 40, 90),
+        (200, 20, 50, 80),
+    )
+
+
+def test_person_boxes_ignores_keypoints_below_the_confidence():
+    keypoints = [[(60, 40), (160, 40), (60, 120), (160, 120), (5, 5)]]
+    scores = [(0.9, 0.9, 0.9, 0.9, 0.05)]  # the stray point is noise
+    assert person_boxes(keypoints, scores, frame_size=FRAME_SIZE) == (
+        (60, 40, 100, 80),
+    )
+
+
+def test_person_boxes_drops_a_person_with_too_little_evidence():
+    keypoints, scores = _people((60, 40, 100, 80))
+    assert (
+        person_boxes(
+            keypoints,
+            scores,
+            frame_size=FRAME_SIZE,
+            min_keypoints=DFLT_MIN_KEYPOINTS + 1,
+        )
+        == ()
+    )
+
+
+def test_person_boxes_clamps_into_the_frame():
+    keypoints, scores = _people((-20, -30, 400, 400))
+    assert person_boxes(keypoints, scores, frame_size=FRAME_SIZE) == (
+        (0, 0, FRAME_SIZE[0], FRAME_SIZE[1]),
+    )
+
+
+def test_person_boxes_reports_zero_detections_as_evidence_not_error():
+    assert person_boxes([], [], frame_size=FRAME_SIZE) == ()
+    assert person_boxes(None, None, frame_size=FRAME_SIZE) == ()
+
+
+# ── the locator, against real frames and a fake model ───────────────────────
+
+
+def test_locator_observes_every_probe_and_every_person(video):
+    seen_shapes = []
+
+    def estimator(frame):
+        seen_shapes.append(frame.shape)
+        return _people((60, 40, 100, 80), (200, 40, 60, 120))
+
+    locator = RtmlibPoseLocator(probe_fps=5.0, pose_estimator=estimator)
+    query = _query(video)
+    observation = locator(query)
+
+    assert isinstance(observation, SubjectObservation)
+    assert len(observation.samples) == 10  # 2 s at 5 fps
+    assert len(seen_shapes) == 10, "every probe must reach the estimator"
+    # real frames, read through mixing: cv2's (height, width, BGR) layout
+    assert set(seen_shapes) == {(FRAME_SIZE[1], FRAME_SIZE[0], 3)}
+    assert all(query.start_s < t < query.end_s for t, _boxes in observation.samples)
+    assert all(
+        boxes == ((60, 40, 100, 80), (200, 40, 60, 120))
+        for _t, boxes in observation.samples
+    )
+
+
+def test_locator_hands_the_core_something_the_policy_can_resolve(video):
+    locator = RtmlibPoseLocator(
+        probe_fps=5.0,
+        pose_estimator=lambda frame: _people((10, 10, 40, 90), (200, 20, 50, 80)),
+    )
+    observation = locator(_query(video))
+    box = resolve_crop_box(observation, frame_size=FRAME_SIZE, pad=0.0, aspect=1.0)
+    assert box is not None
+    x, y, w, h = box
+    # the core unioned both people and kept them inside the frame
+    assert x <= 10 and y <= 10 and x + w >= 250 and x + w <= FRAME_SIZE[0]
+    assert y + h <= FRAME_SIZE[1]
+
+
+def test_locator_answers_none_when_it_sees_nobody(video):
+    locator = RtmlibPoseLocator(probe_fps=5.0, pose_estimator=lambda frame: _people())
+    # ADR-0005 §3: None is the zero-detections fallback, and no crop means
+    # genuinely uncropped rather than letterboxed
+    assert locator(_query(video)) is None
+
+
+def test_locator_raises_rather_than_calling_unreadable_media_uncropped():
+    locator = RtmlibPoseLocator(pose_estimator=lambda frame: _people())
+    query = _query("no-such-file.mp4")
+    with pytest.raises((RuntimeError, ValueError)):
+        locator(query)
+
+
+# ── the recorded identity ───────────────────────────────────────────────────
+
+
+def test_locator_name_carries_the_rtmlib_version(monkeypatch):
+    # the recipe fingerprint reads this: an rtmlib upgrade must re-locate rather
+    # than reuse a box a different model measured (ADR-0005 §3)
+    monkeypatch.setattr(pose, "_rtmlib_version", lambda: FAKE_RTMLIB_VERSION)
+    assert rtmlib_pose.locator_name == (
+        f"rtmlib-pose@{FAKE_RTMLIB_VERSION};mode=balanced;fps=5;conf=0.3;minkp=4"
+    )
+
+
+@pytest.mark.parametrize(
+    "changed",
+    [
+        {"mode": "performance"},
+        {"probe_fps": 10.0},
+        {"keypoint_confidence": 0.5},
+        {"min_keypoints": 6},
+    ],
+)
+def test_every_input_that_moves_a_box_moves_the_locator_name(monkeypatch, changed):
+    # derive gates recipe reuse on this name (derivation.py's _reconcile_recipe),
+    # so anything left out of it silently reuses a box measured under different
+    # settings — precisely what ADR-0005 §3's fingerprint exists to prevent
+    monkeypatch.setattr(pose, "_rtmlib_version", lambda: FAKE_RTMLIB_VERSION)
+    assert RtmlibPoseLocator(**changed).locator_name != rtmlib_pose.locator_name
+
+
+def test_an_injected_estimator_names_itself_instead_of_claiming_rtmlib(monkeypatch):
+    # claiming rtmlib's version for a box rtmlib did not measure would be the
+    # same false identity in the other direction
+    def boom():
+        raise AssertionError("an injected estimator must not read rtmlib's version")
+
+    monkeypatch.setattr(pose, "_rtmlib_version", boom)
+
+    def my_estimator(frame):
+        return _people()
+
+    name = RtmlibPoseLocator(pose_estimator=my_estimator).locator_name
+    assert name.startswith("rtmlib-pose@custom:")
+    assert "my_estimator" in name
+    assert "mode=" not in name  # a Body argument; meaningless to another estimator
+    assert ";fps=5;conf=0.3;minkp=4" in name
+
+
+def test_an_estimator_may_version_itself(monkeypatch):
+    monkeypatch.setattr(pose, "_rtmlib_version", lambda: FAKE_RTMLIB_VERSION)
+
+    def versioned(frame):
+        return _people()
+
+    versioned.locator_name = "my-model@2.1"
+    name = RtmlibPoseLocator(pose_estimator=versioned).locator_name
+    assert name.startswith("rtmlib-pose@custom:my-model@2.1;")
+
+
+def test_naming_the_locator_without_the_extra_names_the_extra(monkeypatch):
+    import importlib.metadata
+    import importlib.util
+
+    def not_installed(distribution, *args, **kwargs):
+        if distribution == "rtmlib":
+            raise importlib.metadata.PackageNotFoundError(distribution)
+        return FAKE_RTMLIB_VERSION
+
+    monkeypatch.setattr(importlib.metadata, "version", not_installed)
+    # patched too, so this describes an absent rtmlib rather than whatever the
+    # developer's machine happens to have installed
+    monkeypatch.setattr(importlib.util, "find_spec", lambda name: None)
+    with pytest.raises(ImportError) as excinfo:
+        rtmlib_pose.locator_name
+    message = str(excinfo.value)
+    assert "paces[pose]" in message
+    assert "rtmlib" in message
+    assert "full_frame" in message, (
+        "the message must name the answer that needs nothing"
+    )
+
+
+def test_running_the_locator_without_the_extra_names_the_extra(monkeypatch):
+    # the calling path, not just the naming one: every rtmlib import goes
+    # through _import_body precisely so this message is written once
+    import builtins
+
+    real_import = builtins.__import__
+
+    def no_rtmlib(name, *args, **kwargs):
+        if name == "rtmlib" or name.startswith("rtmlib."):
+            raise ImportError("No module named 'rtmlib'")
+        return real_import(name, *args, **kwargs)
+
+    monkeypatch.setattr(builtins, "__import__", no_rtmlib)
+    pose._body_estimator.cache_clear()
+    with pytest.raises(ImportError) as excinfo:
+        pose._import_body()
+    assert "paces[pose]" in str(excinfo.value)
+
+
+def test_a_vendored_rtmlib_is_told_apart_from_a_missing_one(monkeypatch):
+    # importable but no dist-info (a vendored copy, or a source tree on
+    # PYTHONPATH): "pip install paces[pose]" is the wrong advice there
+    import importlib.metadata
+    import importlib.util
+
+    def no_metadata(distribution, *args, **kwargs):
+        raise importlib.metadata.PackageNotFoundError(distribution)
+
+    monkeypatch.setattr(importlib.metadata, "version", no_metadata)
+    monkeypatch.setattr(importlib.util, "find_spec", lambda name: object())
+    with pytest.raises(ImportError) as excinfo:
+        rtmlib_pose.locator_name
+    message = str(excinfo.value)
+    assert "no distribution metadata" in message
+    assert "pose_estimator" in message, "the message must name the way out"
+
+
+def test_the_missing_extra_message_states_the_licence_boundary():
+    assert "Apache-2.0" in POSE_EXTRA_MISSING
+    assert "AGPL" in POSE_EXTRA_MISSING
+
+
+# ── the seam, end to end through derive ─────────────────────────────────────
+
+
+def test_derive_records_the_pose_locator_in_the_recipe(tmp_path, video, monkeypatch):
+    monkeypatch.setattr(pose, "_rtmlib_version", lambda: FAKE_RTMLIB_VERSION)
+    document = StepDocument(
+        id="routine",
+        title="Routine",
+        sources=[Source(id="perf", kind="video", uri="https://example.com/v")],
+        steps=[
+            Step(
+                id="b4",
+                name="Step",
+                duration=Measure(value="4", unit="eight"),
+                spans=[
+                    SourceSpan(
+                        source="perf",
+                        role="performance",
+                        start="0.4",
+                        excerpt=("0.4", "1.2"),
+                    )
+                ],
+            )
+        ],
+    )
+    doc_path = tmp_path / "routine.json"
+    doc_path.write_text("{}", encoding="utf-8")
+
+    def one_dancer(frame):
+        return _people((60, 40, 100, 80))
+
+    locator = RtmlibPoseLocator(probe_fps=5.0, pose_estimator=one_dancer)
+    result = derive_document(
+        document,
+        media={"perf": str(video)},
+        doc_path=doc_path,
+        subject_locator=locator,
+        pad=0.0,
+        aspect=1.0,
+        roles=("poster",),
+    )
+    recipes = load_recipes(tmp_path / "routine.recipes.json")
+    entry = recipes.entries["b4/perf/performance/0.4"]
+    # the whole policy identity lands in the sidecar, not just a model version
+    assert entry.locator.startswith("rtmlib-pose@custom:")
+    assert "one_dancer" in entry.locator
+    assert entry.locator.endswith(";fps=5;conf=0.3;minkp=4")
+    assert entry.box is not None
+    x, y, w, h = entry.box
+    # the rect (60, 40, 100, 80) squared to aspect 1.0 about its own centre
+    assert (x, y, w, h) == (60, 30, 100, 100)
+    assert result.document.steps[0].artifacts
+
+
+# ── the extra is genuinely lazy ─────────────────────────────────────────────
+
+
+def test_importing_paces_never_pulls_the_pose_stack():
+    # the guarantee is structural, so assert it structurally: rtmlib and
+    # onnxruntime are heavy, and `import paces` is not where anyone opted in
+    repo_root = Path(pose.__file__).resolve().parents[1]  # holds the `paces` package
+    env = dict(os.environ, PYTHONPATH=str(repo_root))
+    script = (
+        "import sys\n"
+        "import paces\n"
+        "import paces.pose\n"
+        "leaked = {'rtmlib', 'onnxruntime'} & set(sys.modules)\n"
+        "assert not leaked, leaked\n"
+        "print('clean')\n"
+    )
+    completed = subprocess.run(
+        [sys.executable, "-c", script],
+        capture_output=True,
+        text=True,
+        env=env,
+        cwd=str(repo_root),
+    )
+    assert completed.returncode == 0, completed.stderr
+    assert "clean" in completed.stdout
+
+
+def test_check_pose_requirements_reports_channels_without_downloading():
+    report = check_pose_requirements()
+    assert set(report) == {"ok", "rtmlib", "onnxruntime", "cv2_providers", "notes"}
+    assert report["ok"] is (
+        report["rtmlib"] is not None and report["onnxruntime"] is not None
+    )
+    if not report["ok"]:
+        assert any("paces[pose]" in note for note in report["notes"])
+
+
+# ── the licence perimeter (packaging facts, guarded because nothing else is) ─
+
+
+def _distribution_names(requirements):
+    """Bare distribution names out of PEP 508 requirement strings."""
+    for requirement in requirements:
+        head = requirement.split(";")[0].split("[")[0]
+        for separator in ("==", ">=", "<=", "~=", "!=", ">", "<", " ", "@"):
+            head = head.split(separator)[0]
+        yield head.strip().lower().replace("_", "-")
+
+
+def test_core_dependencies_stay_copyleft_free(pyproject):
+    core = set(_distribution_names(pyproject["project"]["dependencies"]))
+    assert core == {"pydantic"}
+
+
+def test_no_extra_reaches_agpl(pyproject):
+    # putting ultralytics into `pose` is the regression this exists to catch:
+    # it is how a user who asked for pose boxes would silently inherit the AGPL.
+    # Scope, stated so nobody reads more into a green run than is there: this
+    # reads paces' OWN pyproject, i.e. what paces declares. It says nothing
+    # about transitive closures, and nothing about what a dependency's wheels
+    # actually ship — opencv's GPL-on-macOS FFmpeg is exactly that gap, which
+    # is why it was measured off the binaries and written down instead.
+    for extra, requirements in pyproject["project"]["optional-dependencies"].items():
+        found = set(_distribution_names(requirements)) & FORBIDDEN_DISTRIBUTIONS
+        assert not found, f"AGPL {sorted(found)} reached the `{extra}` extra"
+
+
+def test_pose_is_the_extra_that_declares_rtmlib(pyproject):
+    requirements = pyproject["project"]["optional-dependencies"]["pose"]
+    assert set(_distribution_names(requirements)) == {"rtmlib", "onnxruntime"}
+    # the licence audit was done against one rtmlib version, and 0.0.x promises
+    # no stability: a floor with no ceiling would let an unaudited wheel in
+    (rtmlib_requirement,) = [r for r in requirements if r.startswith("rtmlib")]
+    assert "<" in rtmlib_requirement, (
+        f"rtmlib must carry an upper bound, got {rtmlib_requirement!r}"
+    )
+
+
+def test_the_licence_table_looks_where_the_exposure_is(pyproject):
+    # wads' LicencePolicy rejects unknown keys deliberately, so a typo here is a
+    # hard error rather than a silent fallback to defaults — keep it parseable.
+    known = {
+        "enabled",
+        "allowed",
+        "forbidden",
+        "exceptions",
+        "include-extras",
+        "unknown-is-failure",
+        "unclassified-is-failure",
+    }
+    table = pyproject["tool"]["wads"]["licence"]
+    assert set(table) <= known, f"unknown keys: {sorted(set(table) - known)}"
+    # every extra is inside the perimeter — a new one must be adjudicated, not
+    # quietly excluded from the check
+    declared = set(pyproject["project"]["optional-dependencies"]) - {"dev", "docs"}
+    assert declared <= set(table["include-extras"])
+    # paces adjudicates nothing: an exceptions table appearing here would mean
+    # the perimeter moved, and that is a decision, not a diff
+    assert "exceptions" not in table
+
+
+# ── the real model: opt-in, never CI ────────────────────────────────────────
+
+
+@pytest.mark.skipif(
+    os.environ.get(TEST_MODELS_ENVVAR) is None,
+    reason=f"set {TEST_MODELS_ENVVAR}=1 to download rtmlib weights and run a real pass",
+)
+def test_real_rtmlib_pass_smoke(video):
+    # not an accuracy claim: the fixture is a green rectangle and RTMPose is
+    # entitled to see nobody in it. What this proves is the wiring — Body
+    # constructs, weights resolve, inference runs, and its output is the shape
+    # person_boxes reads.
+    observation = rtmlib_pose(_query(video))
+    assert observation is None or isinstance(observation, SubjectObservation)
+    assert rtmlib_pose.locator_name.startswith("rtmlib-pose@")