fix(hf-spaces): install mediapipe native libraries

README.md

@@ -85,6 +85,8 @@ The runtime uses these defaults:
 The MediaPipe Tasks backend tries its GPU delegate on ZeroGPU and falls back to CPU if unavailable.
 The older `mp.solutions.pose` path remains CPU-only. The Torch exercise router loads and predicts
 inside its ZeroGPU-wrapped function, so model objects are not pickled across the API boundary.
+The root `packages.txt` installs the native GLES/EGL/OpenGL libraries required by MediaPipe Tasks
+on the Hugging Face runtime.
 
 When running in real mode, the UI summary now shows:
 

packages.txt

@@ -0,0 +1,4 @@
+libegl1
+libgl1
+libgles2
+libglib2.0-0

src/pozify/steps/pose_backends/__init__.py

@@ -1,6 +1,10 @@
 from __future__ import annotations
 
-from pozify.steps.pose_backends.base import PoseBackend, PoseDetection
+from pozify.steps.pose_backends.base import (
+    PoseBackend,
+    PoseBackendUnavailableError,
+    PoseDetection,
+)
 from pozify.steps.pose_backends.landmarks import (
     LANDMARK_NAMES,
     LANDMARK_SCHEMA,
@@ -20,6 +24,7 @@ __all__ = [
     "MediaPipePoseBackend",
     "MockPoseBackend",
     "PoseBackend",
+    "PoseBackendUnavailableError",
     "PoseDetection",
     "create_pose_backend",
     "landmark_list_to_dict",

src/pozify/steps/pose_backends/base.py

@@ -11,6 +11,10 @@ class PoseDetection:
     source: str
 
 
+class PoseBackendUnavailableError(RuntimeError):
+    pass
+
+
 class PoseBackend(Protocol):
     source: str
 

src/pozify/steps/pose_backends/mediapipe.py

@@ -6,7 +6,10 @@ from typing import Any
 from urllib.request import urlretrieve
 
 from pozify.hf_spaces import zero_gpu_enabled
-from pozify.steps.pose_backends.base import PoseDetection
+from pozify.steps.pose_backends.base import (
+    PoseBackendUnavailableError,
+    PoseDetection,
+)
 from pozify.steps.pose_backends.landmarks import landmark_list_to_dict
 
 
@@ -53,21 +56,27 @@ class MediaPipePoseBackend:
         try:
             import mediapipe as mp
         except ImportError as exc:
-            raise RuntimeError(
+            raise PoseBackendUnavailableError(
                 "MediaPipe is required for the mediapipe pose backend. Install dependencies with uv sync."
             ) from exc
 
         if hasattr(mp, "solutions"):
-            return mp.solutions.pose.Pose(
-                static_image_mode=False,
-                model_complexity=1,
-                smooth_landmarks=False,
-                enable_segmentation=False,
-                min_detection_confidence=0.5,
-                min_tracking_confidence=0.5,
-            )
+            try:
+                return mp.solutions.pose.Pose(
+                    static_image_mode=False,
+                    model_complexity=1,
+                    smooth_landmarks=False,
+                    enable_segmentation=False,
+                    min_detection_confidence=0.5,
+                    min_tracking_confidence=0.5,
+                )
+            except OSError as exc:
+                raise _native_library_error(exc) from exc
 
-        return _MediaPipeTasksPoseAdapter(mp, _ensure_pose_task_model())
+        try:
+            return _MediaPipeTasksPoseAdapter(mp, _ensure_pose_task_model())
+        except OSError as exc:
+            raise _native_library_error(exc) from exc
 
 
 class _MediaPipeTasksPoseAdapter:
@@ -149,3 +158,11 @@ def _ensure_pose_task_model() -> Path:
     model_path.parent.mkdir(parents=True, exist_ok=True)
     urlretrieve(POSE_TASK_MODEL_URL, model_path)
     return model_path
+
+
+def _native_library_error(exc: OSError) -> PoseBackendUnavailableError:
+    return PoseBackendUnavailableError(
+        "MediaPipe could not load native system libraries. On Hugging Face Spaces, "
+        "add libgles2, libegl1, libgl1, and libglib2.0-0 to packages.txt. "
+        f"Original error: {exc}"
+    )

src/pozify/steps/pose_landmarker.py

@@ -12,6 +12,7 @@ from pozify.steps.pose_backends import (
     LANDMARK_SCHEMA,
     MockPoseBackend,
     PoseBackend,
+    PoseBackendUnavailableError,
     create_pose_backend,
 )
 from pozify.steps.video_qc import sample_frame_indices
@@ -120,6 +121,33 @@ def _empty_sequence() -> PoseSequence:
     )
 
 
+def _unavailable_sequence(reason: str) -> PoseSequence:
+    return PoseSequence(
+        frames=[
+            PoseFrame(
+                frame_index=0,
+                timestamp_sec=0.0,
+                landmarks={},
+                world_landmarks={},
+                pose_quality={
+                    "mean_visibility": 0.0,
+                    "critical_landmarks_visible": False,
+                    "full_body_visibility_proxy": 0.0,
+                    "landmark_count": 0,
+                    "pose_warning": "pose_backend_unavailable",
+                    "source": "none",
+                    "landmark_schema": LANDMARK_SCHEMA,
+                    "coordinate_source": "none",
+                    "reason": reason,
+                },
+            )
+        ],
+        normalized=False,
+        smoothing_method="none",
+        pose_valid_ratio=0.0,
+    )
+
+
 def _run_with_backend(manifest: VideoManifest, backend: PoseBackend) -> PoseSequence:
     if not manifest.analysis_allowed or not manifest.video_path:
         return _empty_sequence()
@@ -167,7 +195,10 @@ def _gpu_duration(*_args: Any, **_kwargs: Any) -> int:
 
 @spaces_gpu(duration=_gpu_duration)
 def _run_named_backend(manifest: VideoManifest, backend_name: str) -> PoseSequence:
-    selected_backend = create_pose_backend(backend_name)
+    try:
+        selected_backend = create_pose_backend(backend_name)
+    except PoseBackendUnavailableError as exc:
+        return _unavailable_sequence(str(exc))
     return _run_with_backend(manifest, selected_backend)
 
 

tests/test_pose_steps.py

@@ -19,7 +19,11 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
 
 from pozify.contracts import PoseFrame, PoseSequence, VideoManifest
 from pozify.steps import pose_cleaning, pose_landmarker
-from pozify.steps.pose_backends import PoseDetection, landmark_list_to_dict
+from pozify.steps.pose_backends import (
+    PoseBackendUnavailableError,
+    PoseDetection,
+    landmark_list_to_dict,
+)
 from pozify.steps.pose_backends.mediapipe import _MediaPipeTasksPoseAdapter
 
 
@@ -133,6 +137,40 @@ class PoseStepTests(unittest.TestCase):
 
         self.assertEqual(len(sequence.frames), 130)
 
+    def test_pose_landmarker_returns_unavailable_sequence_for_missing_backend_libs(
+        self,
+    ) -> None:
+        path = self._write_video()
+        manifest = VideoManifest(
+            video_path=str(path),
+            fps=30.0,
+            duration_sec=0.133,
+            total_frames=4,
+            sampled_frames=4,
+            width=640,
+            height=480,
+            codec="mp4v",
+            container="mp4",
+            brightness_mean=120.0,
+            blur_laplacian_var=100.0,
+            quality_warnings=[],
+            analysis_allowed=True,
+        )
+
+        with patch(
+            "pozify.steps.pose_landmarker.create_pose_backend",
+            side_effect=PoseBackendUnavailableError("missing libGLESv2.so.2"),
+        ):
+            sequence = pose_landmarker.run(manifest, backend_name="mediapipe")
+
+        self.assertEqual(sequence.pose_valid_ratio, 0.0)
+        self.assertEqual(len(sequence.frames), 1)
+        self.assertEqual(
+            sequence.frames[0].pose_quality["pose_warning"],
+            "pose_backend_unavailable",
+        )
+        self.assertIn("libGLESv2", sequence.frames[0].pose_quality["reason"])
+
     def test_dense_video_iteration_reads_sequentially_without_reseeking(self) -> None:
         class FakeCapture:
             def __init__(self) -> None: