opensportslib 0.3.1.dev14__tar.gz → 0.3.1.dev16__tar.gz

{opensportslib-0.3.1.dev14/opensportslib.egg-info → opensportslib-0.3.1.dev16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.3.1.dev14
+Version: 0.3.1.dev16
 Summary: OpenSportsLib is the professional library, designed for advanced video understanding in sports. It provides state-of-the-art tools for action recognition, spotting, retrieval, and captioning, making it ideal for researchers, analysts, and developers working with sports video data.
 Author: Jeet Vora
 Requires-Python: >=3.12
@@ -32,6 +32,8 @@ Requires-Dist: easydict
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-json-report; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
 Dynamic: license-file
 
 # OpenSportsLib
@@ -45,9 +47,9 @@ See the [complete inference server guide](docs/server/inference-server.md) for
 installation, registry administration, curl requests, single-video inference,
 full-test-set and per-sample remote inference, job polling, and sessions.
 
-For Docker administration, set `OSL_MODEL_ADMIN_TOKEN` in the private
-`server/.env` file, recreate the containers after changes, and use the exact
-same value as the Python client's `admin_token`. Never commit the real token.
+Hugging Face registration is authorized by repository access. Set `HF_TOKEN`
+on the worker or pass `hf_token` per request. The optional `OSL_API_KEY`
+protects local-model and general administrative operations.
 
 ## Configuration From Hugging Face
 
@@ -138,7 +140,7 @@ OpenSportsLib is designed for **researchers, ML engineers, and sports analytics
 
 > Requires **Python 3.12+**.  
 > Supports CUDA 12.6 / 12.8 / 13.0 (with CPU fallback).  
-> PyTorch Geometric is supported up to PyTorch 2.10.*.
+> PyTorch Geometric uses a dedicated PyTorch 2.12.1 compatibility profile.
 
 ### Create conda env
 
@@ -170,7 +172,8 @@ pip install -e .
 # Install PyTorch (CPU/GPU auto-detected)
 opensportslib setup
 
-# Optional: install PyTorch Geometric support
+# Optional: install PyTorch Geometric support. This replaces the installed
+# Torch stack with the PyG-compatible PyTorch 2.12.1 profile.
 opensportslib setup --pyg
 
 # Optional: install for DALI support
@@ -554,7 +557,8 @@ pip install -e .
 # Install PyTorch (CPU/GPU auto-detected)
 opensportslib setup
 
-# Optional: install PyTorch Geometric support
+# Optional: install PyTorch Geometric support. This replaces the installed
+# Torch stack with the PyG-compatible PyTorch 2.12.1 profile.
 opensportslib setup --pyg
 
 # Optional: install for DALI support
@@ -635,8 +639,8 @@ this repository, activate a fresh Python 3.12 or newer environment and install t
 
 ```bash
 pip install -e ./server
-bash server/scripts/setup_env.sh
-bash server/scripts/start_all.sh
+server/scripts/serverctl setup
+server/scripts/serverctl start
 ```
 
 The server installs the OpenSportsLib release from PyPI pinned to the root project

{opensportslib-0.3.1.dev14 → opensportslib-0.3.1.dev16}/README.md

@@ -9,9 +9,9 @@ See the [complete inference server guide](docs/server/inference-server.md) for
 installation, registry administration, curl requests, single-video inference,
 full-test-set and per-sample remote inference, job polling, and sessions.
 
-For Docker administration, set `OSL_MODEL_ADMIN_TOKEN` in the private
-`server/.env` file, recreate the containers after changes, and use the exact
-same value as the Python client's `admin_token`. Never commit the real token.
+Hugging Face registration is authorized by repository access. Set `HF_TOKEN`
+on the worker or pass `hf_token` per request. The optional `OSL_API_KEY`
+protects local-model and general administrative operations.
 
 ## Configuration From Hugging Face
 
@@ -102,7 +102,7 @@ OpenSportsLib is designed for **researchers, ML engineers, and sports analytics
 
 > Requires **Python 3.12+**.  
 > Supports CUDA 12.6 / 12.8 / 13.0 (with CPU fallback).  
-> PyTorch Geometric is supported up to PyTorch 2.10.*.
+> PyTorch Geometric uses a dedicated PyTorch 2.12.1 compatibility profile.
 
 ### Create conda env
 
@@ -134,7 +134,8 @@ pip install -e .
 # Install PyTorch (CPU/GPU auto-detected)
 opensportslib setup
 
-# Optional: install PyTorch Geometric support
+# Optional: install PyTorch Geometric support. This replaces the installed
+# Torch stack with the PyG-compatible PyTorch 2.12.1 profile.
 opensportslib setup --pyg
 
 # Optional: install for DALI support
@@ -518,7 +519,8 @@ pip install -e .
 # Install PyTorch (CPU/GPU auto-detected)
 opensportslib setup
 
-# Optional: install PyTorch Geometric support
+# Optional: install PyTorch Geometric support. This replaces the installed
+# Torch stack with the PyG-compatible PyTorch 2.12.1 profile.
 opensportslib setup --pyg
 
 # Optional: install for DALI support
@@ -599,8 +601,8 @@ this repository, activate a fresh Python 3.12 or newer environment and install t
 
 ```bash
 pip install -e ./server
-bash server/scripts/setup_env.sh
-bash server/scripts/start_all.sh
+server/scripts/serverctl setup
+server/scripts/serverctl start
 ```
 
 The server installs the OpenSportsLib release from PyPI pinned to the root project

{opensportslib-0.3.1.dev14 → opensportslib-0.3.1.dev16}/opensportslib/adaptation/spotta.py

@@ -59,7 +59,6 @@ class SpoTTAConfig:
     drift_scale: float = 10.0
     drift_threshold: float = 1.0
     drift_gamma: float = 0.2
-    augmentation: bool = True
 
     @classmethod
     def from_mapping(cls, value: Any) -> "SpoTTAConfig":
@@ -70,7 +69,6 @@ class SpoTTAConfig:
         memory = _mapping(root.get("memory"))
         optimizer = _mapping(root.get("optimizer"))
         teacher = _mapping(root.get("teacher"))
-        augmentation = _mapping(root.get("augmentation"))
 
         _require_supported_value(
             root,
@@ -78,34 +76,6 @@ class SpoTTAConfig:
             "adapt_then_predict",
             "adaptation",
         )
-        _require_supported_value(tether, "mode", "bayesian", "robust_bn.tether")
-        _require_supported_value(
-            gate,
-            "uncertainty",
-            "one_minus_max_probability",
-            "confidence_gate",
-        )
-        _require_supported_value(
-            gate,
-            "aggregation",
-            "min_over_predicted_action_frames",
-            "confidence_gate",
-        )
-        _require_supported_value(optimizer, "type", "Adam", "optimizer")
-        _require_supported_value(
-            optimizer,
-            "trainable_parameters",
-            "batch_norm_affine_only",
-            "optimizer",
-        )
-        _require_supported_value(teacher, "type", "ema", "teacher")
-        _require_supported_value(
-            teacher, "adaptive_from_bn_drift", True, "teacher"
-        )
-        _require_supported_value(
-            augmentation, "mode", "framewise_rotta_strong", "augmentation"
-        )
-
         config = cls(
             alpha=float(robust_bn.get("alpha", cls.alpha)),
             tether_cap=float(tether.get("cap", cls.tether_cap)),
@@ -133,7 +103,6 @@ class SpoTTAConfig:
                 teacher.get("drift_threshold", cls.drift_threshold)
             ),
             drift_gamma=float(teacher.get("drift_gamma", cls.drift_gamma)),
-            augmentation=bool(augmentation.get("enabled", cls.augmentation)),
         )
         config.validate()
         return config
@@ -577,13 +546,10 @@ class SpoTTA:
         with torch.no_grad():
             teacher_logits = _logits(self.teacher(clips))
 
-        if self.config.augmentation:
-            batch, time, channels, height, width = clips.shape
-            augmented = self.augmentation(
-                clips.reshape(batch * time, channels, height, width)
-            ).reshape(batch, time, channels, height, width)
-        else:
-            augmented = clips
+        batch, time, channels, height, width = clips.shape
+        augmented = self.augmentation(
+            clips.reshape(batch * time, channels, height, width)
+        ).reshape(batch, time, channels, height, width)
 
         self.student.train()
         student_logits = _logits(self.student(augmented))

{opensportslib-0.3.1.dev14 → opensportslib-0.3.1.dev16}/opensportslib/configs/localization/e2e_spotta.yaml

@@ -39,6 +39,7 @@ DATA:
         resize:
           height: 224
           width: 398
+          preserve_aspect_ratio: true
       params:
         crop_dim: 224
         dilate_len: 0
@@ -69,13 +70,10 @@ MODEL:
       robust_bn:
         alpha: 0.05
         tether:
-          mode: bayesian
           cap: 0.5
       confidence_gate:
         action_class_index: 1
         min_action_frames: 1
-        uncertainty: one_minus_max_probability
-        aggregation: min_over_predicted_action_frames
         threshold: 0.3
       memory:
         capacity: 8
@@ -83,21 +81,14 @@ MODEL:
         lambda_t: 1.0
         lambda_u: 1.0
       optimizer:
-        type: Adam
         learning_rate: 0.001
         beta: 0.9
-        trainable_parameters: batch_norm_affine_only
       teacher:
-        type: ema
         base_nu: 0.001
-        adaptive_from_bn_drift: true
         max_nu: 0.02
         drift_scale: 10.0
         drift_threshold: 1.0
         drift_gamma: 0.2
-      augmentation:
-        enabled: true
-        mode: framewise_rotta_strong
 
 TRAIN:
   execution:

{opensportslib-0.3.1.dev14 → opensportslib-0.3.1.dev16}/opensportslib/core/config/loader.py

@@ -206,9 +206,27 @@ def _preferred_loader_backend(payload: dict[str, Any]) -> str | None:
     if _declares_opencv_split_types(payload):
         return "opencv"
 
+    # DALI cannot run on CPU, regardless of an explicit preference in a
+    # configuration.  This safety fallback also remaps DALI split types below.
     mode = str(system.get("device", "auto")).lower()
     if mode == "cpu":
         return "opencv"
+
+    data = payload.get("DATA", {})
+    common = data.get("common", {}) if isinstance(data, dict) else {}
+    runtime = common.get("runtime", {}) if isinstance(common, dict) else {}
+    configured_backend = (
+        str(runtime.get("loader_backend", "auto")).lower()
+        if isinstance(runtime, dict)
+        else "auto"
+    )
+    # An explicit backend is part of the configuration contract.  Runtime
+    # detection is only a default for configs which leave that choice as auto.
+    if configured_backend == "opencv":
+        return "opencv"
+    if configured_backend == "dali":
+        return "dali" if _dali_available() else "opencv"
+
     if mode == "cuda":
         return "dali" if _dali_available() else "opencv"
     if mode == "auto":

{opensportslib-0.3.1.dev14 → opensportslib-0.3.1.dev16}/opensportslib/core/utils/video_processing.py

@@ -145,9 +145,8 @@ def distribute_elements(batch_size, len_devices):
     """
     quotient, remainder = divmod(batch_size, len_devices)
     distribution = [quotient] * len_devices
-    if remainder > 0:
-        for i in range(len(distribution)):
-            distribution[i] += 1
+    for i in range(remainder):
+        distribution[i] += 1
 
     return distribution
 

{opensportslib-0.3.1.dev14 → opensportslib-0.3.1.dev16}/opensportslib/datasets/localization_dataset.py

@@ -161,6 +161,7 @@ class LocalizationDataset(Dataset):
             imagenet_std=normalization.get("std"),
             target_height=resize.get("height"),
             target_width=resize.get("width"),
+            preserve_aspect_ratio=resize.get("preserve_aspect_ratio", False),
         )
         annotation_path = annotations_path or getattr(
             split_cfg, "annotation_path", getattr(split_cfg, "path", None)
@@ -346,6 +347,7 @@ class LocalizationDataset(Dataset):
                 IMAGENET_STD=self.data_cfg.imagenet_std,
                 TARGET_HEIGHT=self.data_cfg.target_height,
                 TARGET_WIDTH=self.data_cfg.target_width,
+                preserve_aspect_ratio=self.data_cfg.preserve_aspect_ratio,
             )
         elif dataset_type == "VideoGameWithOpencvVideo":
             dataset = ActionSpotVideoDataset(
@@ -362,6 +364,7 @@ class LocalizationDataset(Dataset):
                 IMAGENET_STD=self.data_cfg.imagenet_std,
                 TARGET_HEIGHT=self.data_cfg.target_height,
                 TARGET_WIDTH=self.data_cfg.target_width,
+                preserve_aspect_ratio=self.data_cfg.preserve_aspect_ratio,
             )
         elif dataset_type == "VideoGameWithDali":
             if not DALI_AVAILABLE:
@@ -543,6 +546,7 @@ class FrameReader:
         sample_fps=2,
         TARGET_HEIGHT=224,
         TARGET_WIDTH=398,
+        preserve_aspect_ratio=False,
     ):
         self._is_flow = modality == "flow"
         self._crop_transform = crop_transform
@@ -551,6 +555,37 @@ class FrameReader:
         self._sample_fps = sample_fps
         self.TARGET_HEIGHT = TARGET_HEIGHT
         self.TARGET_WIDTH = TARGET_WIDTH
+        self.preserve_aspect_ratio = preserve_aspect_ratio
+
+    def _resize_frame_ocv(self, frame):
+        """Resize an OpenCV frame using the configured spatial policy.
+
+        With aspect preservation enabled, ``TARGET_HEIGHT`` fixes the output
+        height and the width is derived from the source aspect ratio. If no
+        target height is configured, ``TARGET_WIDTH`` fixes the output width.
+        """
+        import cv2
+
+        height, width = frame.shape[:2]
+        if self.preserve_aspect_ratio:
+            if self.TARGET_HEIGHT is not None and self.TARGET_HEIGHT > 0:
+                scale = self.TARGET_HEIGHT / height
+            elif self.TARGET_WIDTH is not None and self.TARGET_WIDTH > 0:
+                scale = self.TARGET_WIDTH / width
+            else:
+                return frame
+
+            output_height = max(1, round(height * scale))
+            output_width = max(1, round(width * scale))
+        else:
+            output_height = self.TARGET_HEIGHT
+            output_width = self.TARGET_WIDTH
+
+        if output_height is None or output_width is None:
+            return frame
+        if (height, width) == (output_height, output_width):
+            return frame
+        return cv2.resize(frame, (output_width, output_height))
 
     def adapt_frame_ocv(self, frame):
         """Apply some modifications to the frame to have the expected shape and format.
@@ -675,8 +710,7 @@ class FrameReader:
             ret, frame = vc.read()
             if ret:
                 if i % stride_extract == 0:
-                    if frame.shape[0] != oh or frame.shape[1] != ow:
-                        frame = cv2.resize(frame, (ow, oh))
+                    frame = self._resize_frame_ocv(frame)
                     img = self.adapt_frame_ocv(frame)
                     if self._crop_transform:
                         if self._same_transform:
@@ -781,6 +815,7 @@ class ActionSpotDataset(Dataset):
         IMAGENET_STD=[0.229, 0.224, 0.225],
         TARGET_HEIGHT=224,
         TARGET_WIDTH=398,
+        preserve_aspect_ratio=False,
     ):
         import random
         from opensportslib.core.utils.load_annotations import annotationstoe2eformat
@@ -850,7 +885,8 @@ class ActionSpotDataset(Dataset):
             same_transform,
             extract_fps,
             self.TARGET_HEIGHT,
-            self.TARGET_WIDTH
+            self.TARGET_WIDTH,
+            preserve_aspect_ratio,
         )
 
     def load_frame_gpu(self, batch, device):
@@ -973,7 +1009,7 @@ class ActionSpotDataset(Dataset):
         return self._dataset_len
 
     def print_info(self):
-        from core.utils.config import _print_info_helper
+        from opensportslib.core.utils.config import _print_info_helper
         _print_info_helper(self._src_file, self._labels)
 
 
@@ -1097,6 +1133,7 @@ class ActionSpotVideoDataset(Dataset, DatasetVideoSharedMethods):
         IMAGENET_STD=[0.229, 0.224, 0.225],
         TARGET_HEIGHT=224,
         TARGET_WIDTH=398,
+        preserve_aspect_ratio=False,
     ):
         from opensportslib.core.utils.load_annotations import annotationstoe2eformat, construct_labels
         from opensportslib.core.utils.video_processing import _get_img_transforms
@@ -1138,7 +1175,8 @@ class ActionSpotVideoDataset(Dataset, DatasetVideoSharedMethods):
             False,
             extract_fps,
             self.TARGET_HEIGHT,
-            self.TARGET_WIDTH
+            self.TARGET_WIDTH,
+            preserve_aspect_ratio,
         )
 
         self._flip = flip
@@ -1960,7 +1998,7 @@ if DALI_AVAILABLE:
             return labels
 
         def print_info(self):
-            from core.utils.config import _print_info_helper
+            from opensportslib.core.utils.config import _print_info_helper
             _print_info_helper(self._src_file, self._labels)
 
 

{opensportslib-0.3.1.dev14 → opensportslib-0.3.1.dev16}/opensportslib/remote_registry.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import json
 import time
+import warnings
 from pathlib import Path
 from typing import Any
 from urllib import error, parse, request
@@ -17,13 +18,23 @@ class RemoteRegistryError(RuntimeError):
 class RemoteModelRegistry:
     """Administrative client for an OpenSportsLib server model registry."""
 
-    def __init__(self, remote: str, admin_token: str, timeout: float = 30.0):
+    def __init__(
+        self,
+        remote: str,
+        api_key: str | None = None,
+        timeout: float = 30.0,
+        *,
+        admin_token: str | None = None,
+    ):
         if not remote:
             raise ValueError("remote is required.")
-        if not admin_token:
-            raise ValueError("admin_token is required.")
+        if admin_token is not None:
+            warnings.warn("admin_token is deprecated; use api_key.", DeprecationWarning, stacklevel=2)
+            if api_key is not None and api_key != admin_token:
+                raise ValueError("api_key and admin_token must match when both are provided.")
+            api_key = admin_token
         self.remote = remote.rstrip("/")
-        self.admin_token = admin_token
+        self.api_key = api_key
         self.timeout = float(timeout)
         if self.timeout <= 0:
             raise ValueError("timeout must be positive.")
@@ -36,6 +47,7 @@ class RemoteModelRegistry:
         weights_path: str | Path | None = None,
         config_path: str | Path | None = None,
         model_id: str | None = None,
+        hf_token: str | None = None,
     ) -> dict[str, Any]:
         """Register exactly one Hugging Face or server-local model source."""
         if (huggingface_model_id is None) == (weights_path is None):
@@ -45,9 +57,12 @@ class RemoteModelRegistry:
                 raise ValueError("config_path applies only to local models.")
             if model_id is not None and model_id != huggingface_model_id:
                 raise ValueError("A Hugging Face model uses its repository ID as model_id.")
+            source = {"type": "huggingface", "model_id": huggingface_model_id}
+            if hf_token is not None:
+                source["hf_token"] = hf_token
             payload = {
                 "task_type": task_type,
-                "source": {"type": "huggingface", "model_id": huggingface_model_id},
+                "source": source,
             }
         else:
             payload = {
@@ -59,7 +74,7 @@ class RemoteModelRegistry:
                     "config_path": str(config_path) if config_path is not None else None,
                 },
             }
-        return self._request("POST", "/models", payload, authenticated=True)
+        return self._request("POST", "/models", payload, authenticated=weights_path is not None)
 
     def list_models(self) -> list[dict[str, Any]]:
         return self._request("GET", "/models")["models"]
@@ -69,7 +84,7 @@ class RemoteModelRegistry:
         return self._request("GET", f"/models/status?{query}")
 
     def get_operation(self, operation_id: str) -> dict[str, Any]:
-        return self._request("GET", f"/model-operations/{parse.quote(operation_id, safe='')}", authenticated=True)
+        return self._request("GET", f"/model-operations/{parse.quote(operation_id, safe='')}")
 
     def wait_for_operation(
         self,
@@ -93,9 +108,9 @@ class RemoteModelRegistry:
         task = parse.quote(task_type, safe="")
         return self._request("PUT", f"/models/defaults/{task}", {"model_id": model_id}, authenticated=True)
 
-    def unregister_model(self, model_id: str) -> dict[str, Any]:
+    def unregister_model(self, model_id: str, hf_token: str | None = None) -> dict[str, Any]:
         encoded = parse.quote(model_id, safe="")
-        return self._request("DELETE", f"/models/{encoded}", authenticated=True)
+        return self._request("DELETE", f"/models/{encoded}", authenticated=True, hf_token=hf_token)
 
     def reconcile_runtime(
         self,
@@ -117,11 +132,14 @@ class RemoteModelRegistry:
         endpoint: str,
         payload: dict[str, Any] | None = None,
         authenticated: bool = False,
+        hf_token: str | None = None,
     ) -> dict[str, Any]:
         body = json.dumps(payload).encode() if payload is not None else None
         headers = {"Content-Type": "application/json"}
-        if authenticated:
-            headers["Authorization"] = f"Bearer {self.admin_token}"
+        if authenticated and self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if hf_token:
+            headers["X-HF-Token"] = hf_token
         outgoing = request.Request(self.remote + endpoint, data=body, method=method, headers=headers)
         try:
             with request.urlopen(outgoing, timeout=self.timeout) as response:

{opensportslib-0.3.1.dev14 → opensportslib-0.3.1.dev16}/opensportslib/setup/setup.py

@@ -1,6 +1,7 @@
 import platform
 import subprocess
 import sys
+import tempfile
 
 
 CUDA_WHEEL_VERSIONS = {
@@ -14,6 +15,20 @@ LEGACY_GPU_CUDA_WHEEL = "cu126"
 LEGACY_GPU_CUDA_WHEEL_MAX_COMPUTE_CAPABILITY = (9, 0)
 CUDA13_REQUIRED_MIN_COMPUTE_CAPABILITY = (10, 0)
 
+# PyG extension wheels are published for a narrower PyTorch matrix than the
+# base PyTorch packages.  Keep this profile explicit: selecting ``--pyg`` is
+# allowed to replace an otherwise newer PyTorch installation.
+PYG_TORCH_VERSION = "2.12.1"
+PYG_TORCH_PACKAGES = (
+    f"torch=={PYG_TORCH_VERSION}",
+    "torchvision==0.27.1",
+)
+PYG_EXTENSION_PACKAGES = (
+    "pyg-lib",
+    "torch-scatter",
+    "torch-sparse",
+)
+
 XVARS_DEPENDENCY_PINS = {
     "transformers": "4.38.2",
     "peft": "0.9.0",
@@ -154,10 +169,17 @@ def install_xvars_dependencies(DEPENDENCY_PINS):
     subprocess.check_call([python, "-m", "pip", "install", *pinned_packages])
     print("Dependencies installed successfully.")
 
-def install_torch():
+def install_torch(*, pyg_compatible=False):
+    """Install the default Torch stack or the pinned PyG-compatible stack."""
     python = sys.executable
     subprocess.call([python, "-m", "pip", "uninstall", "-y", "torch", "torchvision", "torchaudio"])
-    packages = select_torch_packages(GPU_COMPUTE_CAPABILITIES)
+    packages = PYG_TORCH_PACKAGES if pyg_compatible else select_torch_packages(GPU_COMPUTE_CAPABILITIES)
+
+    if pyg_compatible:
+        print(
+            "\nInstalling the PyTorch Geometric compatibility profile: "
+            f"PyTorch {PYG_TORCH_VERSION}. This replaces the installed Torch stack.\n"
+        )
 
     subprocess.check_call([
         python, "-m", "pip", "install",
@@ -168,6 +190,30 @@ def install_torch():
     print(f"\nSuccess with {CUDA_TAG}: {', '.join(packages)}")
     return CUDA_TAG
 
+
+def pyg_wheel_url(torch_version=None, cuda_tag=None):
+    torch_version = torch_version or PYG_TORCH_VERSION
+    cuda_tag = CUDA_TAG if cuda_tag is None else cuda_tag
+    suffix = "cpu" if cuda_tag == "cpu" else cuda_tag
+    return f"https://data.pyg.org/whl/torch-{torch_version}+{suffix}.html"
+
+
+def validate_pyg_wheels():
+    """Ensure every required PyG wheel exists before replacing Torch.
+
+    ``--only-binary`` is intentional: pip otherwise falls back to a source
+    build, which is both slow and incompatible with its isolated build
+    environment unless Torch is installed there as well.
+    """
+    python = sys.executable
+    url = pyg_wheel_url()
+    print("\nChecking PyTorch Geometric wheels before replacing the Torch stack...\n")
+    with tempfile.TemporaryDirectory(prefix="opensportslib-pyg-wheel-check-") as download_dir:
+        subprocess.check_call([
+            python, "-m", "pip", "download", "--no-deps", "--only-binary=:all:",
+            "--dest", download_dir, *PYG_EXTENSION_PACKAGES, "-f", url,
+        ])
+
 def install_dali():
 
     python = sys.executable
@@ -202,36 +248,24 @@ def install_dali():
 
 def install_pyg():
     import torch
-    from packaging import version
 
     python = sys.executable
-    torch_version = "2.10.0" if version.parse(torch.__version__.split("+")[0]) > version.parse("2.10.0") else torch.__version__.split("+")[0]
-    cuda_tag = CUDA_TAG
+    torch_version = torch.__version__.split("+")[0]
+    if torch_version != PYG_TORCH_VERSION:
+        raise RuntimeError(
+            "PyTorch Geometric extensions require the OpenSportsLib PyG compatibility "
+            f"profile (PyTorch {PYG_TORCH_VERSION}); found PyTorch {torch_version}. "
+            "Run 'opensportslib setup --pyg' so the matching Torch stack is installed."
+        )
     print("\nInstalling Py-Geometric ecosystem...\n")
-    if cuda_tag == "cpu":
-        url =  f"https://data.pyg.org/whl/torch-{torch_version}+cpu.html"
-    else:
-        url = f"https://data.pyg.org/whl/torch-{torch_version}+{cuda_tag}.html"
+    url = pyg_wheel_url(torch_version)
 
     subprocess.check_call([
-        python, "-m", "pip", "install",
-        "torch-geometric", "-f", url
-    ])
-    subprocess.check_call([
-        python, "-m", "pip", "install",
-        "torch-scatter", "-f", url
+        python, "-m", "pip", "install", "torch-geometric",
     ])
     subprocess.check_call([
         python, "-m", "pip", "install",
-        "torch-sparse", "-f", url
-    ])
-    subprocess.check_call([
-        python, "-m", "pip", "install",
-        "torch-cluster", "-f", url
-    ])
-    subprocess.check_call([
-        python, "-m", "pip", "install",
-        "torch-spline-conv", "-f", url
+        *PYG_EXTENSION_PACKAGES, "--only-binary=:all:", "-f", url
     ])
 
 def install_extras(dali=False, pyg=False):
@@ -256,7 +290,9 @@ def verify():
         print("Running on CPU")
 
 def setup(dali=False, pyg=False, vqa_xvars=False, vqa_qwen=False):
-    install_torch()
+    if pyg:
+        validate_pyg_wheels()
+    install_torch(pyg_compatible=pyg)
     install_extras(dali=dali, pyg=pyg)
     if vqa_xvars:
         install_xvars_dependencies(XVARS_DEPENDENCY_PINS)