opensportslib 0.3.0.dev19__tar.gz → 0.3.0.dev21__tar.gz

{opensportslib-0.3.0.dev19/opensportslib.egg-info → opensportslib-0.3.0.dev21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.3.0.dev19
+Version: 0.3.0.dev21
 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

{opensportslib-0.3.0.dev19 → opensportslib-0.3.0.dev21}/opensportslib/setup/setup.py

@@ -13,11 +13,6 @@ LEGACY_GPU_MAX_COMPUTE_CAPABILITY = (7, 4)
 LEGACY_GPU_CUDA_WHEEL = "cu126"
 LEGACY_GPU_CUDA_WHEEL_MAX_COMPUTE_CAPABILITY = (9, 0)
 CUDA13_REQUIRED_MIN_COMPUTE_CAPABILITY = (10, 0)
-LEGACY_GPU_TORCH_PACKAGES = (
-    "torch==2.10.0",
-    "torchvision==0.25.0",
-    "torchaudio==2.10.0",
-)
 
 XVARS_DEPENDENCY_PINS = {
     "transformers": "4.38.2",
@@ -140,10 +135,6 @@ def select_cuda_wheel(cuda_version, compute_capabilities):
 
 
 def select_torch_packages(compute_capabilities):
-    # if compute_capabilities and any(
-    #     capability <= LEGACY_GPU_MAX_COMPUTE_CAPABILITY for capability in compute_capabilities
-    # ):
-    #     return LEGACY_GPU_TORCH_PACKAGES
     return ("torch", "torchvision", "torchaudio")
 
 

{opensportslib-0.3.0.dev19 → opensportslib-0.3.0.dev21}/opensportslib/tools/hf_transfer.py

@@ -117,9 +117,13 @@ def extract_repo_paths_from_json(
                 if not isinstance(inp, dict):
                     continue
                 path = inp.get("path")
-                if not path:
-                    continue
-                repo_paths.append(str(path).lstrip("/"))
+                if path:
+                    repo_paths.append(str(path).lstrip("/"))
+                # player_joints_h5 / player_centroids_h5 inputs may carry a
+                # sidecar ball_path; download it alongside the primary input.
+                ball_path = inp.get("ball_path")
+                if ball_path:
+                    repo_paths.append(str(ball_path).lstrip("/"))
 
     if not repo_paths:
         raise ValueError("No file paths found in the provided JSON (no inputs with 'path').")
@@ -435,6 +439,131 @@ def _download_json_path_from_hf(
     return result
 
 
+_PREFERRED_SPLIT_ORDER = ["train", "valid", "val", "validation", "test", "challenge"]
+_NON_SPLIT_JSON_FILES = {"dataset_infos.json", "dataset_dict.json"}
+
+
+def _sort_splits(splits: set[str]) -> list[str]:
+    def _sort_key(name: str) -> tuple[int, str]:
+        try:
+            rank = _PREFERRED_SPLIT_ORDER.index(name.lower())
+        except ValueError:
+            rank = len(_PREFERRED_SPLIT_ORDER)
+        return (rank, name.lower())
+
+    return sorted(splits, key=_sort_key)
+
+
+def list_dataset_branches_on_hf(
+    repo_id: str,
+    *,
+    token: str | None = None,
+) -> list[str]:
+    cleaned_repo_id = str(repo_id or "").strip()
+    if not cleaned_repo_id:
+        raise ValueError("repo_id is required.")
+
+    HfApi, _, _ = _import_hf_hub()
+    api = HfApi(token=token or None)
+    refs = api.list_repo_refs(cleaned_repo_id, repo_type="dataset")
+    branch_names = [str(branch.name) for branch in getattr(refs, "branches", [])]
+
+    unique_names = sorted(set(branch_names))
+    if "main" in unique_names:
+        unique_names.remove("main")
+        return ["main"] + unique_names
+    return unique_names
+
+
+def list_dataset_splits_on_hf(
+    repo_id: str,
+    revision: str,
+    *,
+    token: str | None = None,
+) -> dict[str, Any]:
+    cleaned_repo_id = str(repo_id or "").strip()
+    cleaned_revision = str(revision or "").strip() or "main"
+    if not cleaned_repo_id:
+        raise ValueError("repo_id is required.")
+
+    HfApi, _, _ = _import_hf_hub()
+    api = HfApi(token=token or None)
+    repo_files = api.list_repo_files(
+        cleaned_repo_id,
+        revision=cleaned_revision,
+        repo_type="dataset",
+    )
+
+    parquet_splits: set[str] = set()
+    json_splits: set[str] = set()
+    for path in repo_files:
+        normalized = _normalize_repo_path(path)
+        if "/" in normalized:
+            folder, filename = normalized.split("/", 1)
+            # Only the canonical Parquet+WebDataset export layout counts as a
+            # parquet split (produced by convert_json_to_parquet / expected by
+            # convert_parquet_to_json): `{split}/metadata.parquet` plus TAR
+            # shards under `{split}/shards/`. A JSON-format dataset can also
+            # reference arbitrary `.parquet` media files (e.g. tensor-encoded
+            # videos) under a folder that happens to share the split's name,
+            # so a loose "any .parquet/.tar anywhere under this folder" check
+            # would misclassify those as Parquet+WebDataset splits.
+            if folder and (
+                filename == "metadata.parquet"
+                or (filename.startswith("shards/") and filename.lower().endswith(".tar"))
+            ):
+                parquet_splits.add(folder)
+        elif normalized.lower().endswith(".json") and normalized not in _NON_SPLIT_JSON_FILES:
+            json_splits.add(normalized[: -len(".json")])
+
+    if parquet_splits:
+        return {"format": "parquet", "splits": _sort_splits(parquet_splits)}
+    if json_splits:
+        return {"format": "json", "splits": _sort_splits(json_splits)}
+    return {"format": None, "splits": []}
+
+
+def download_dataset_splits_from_hf(
+    repo_id: str,
+    revision: str,
+    splits: list[str],
+    output_dir: str,
+    *,
+    download_format: str = "parquet",
+    dry_run: bool = False,
+    token: str | None = None,
+    progress_cb: ProgressCallback | None = None,
+    is_cancelled: CancelCheck | None = None,
+) -> list[dict[str, Any]]:
+    cleaned_splits = [str(split or "").strip() for split in (splits or [])]
+    cleaned_splits = [split for split in cleaned_splits if split]
+    if not cleaned_splits:
+        raise ValueError("At least one split is required.")
+
+    total = len(cleaned_splits)
+    results: list[dict[str, Any]] = []
+    for idx, split in enumerate(cleaned_splits, start=1):
+        _ensure_not_cancelled(is_cancelled)
+
+        def _scoped_progress(message: str, _idx: int = idx, _split: str = split) -> None:
+            _emit_progress(progress_cb, f"[{_idx}/{total}] {_split}: {message}")
+
+        result = download_dataset_split_from_hf(
+            repo_id,
+            revision,
+            split,
+            output_dir,
+            download_format=download_format,
+            dry_run=dry_run,
+            token=token,
+            progress_cb=_scoped_progress,
+            is_cancelled=is_cancelled,
+        )
+        results.append(result)
+
+    return results
+
+
 def download_dataset_split_from_hf(
     repo_id: str,
     revision: str,
@@ -512,28 +641,37 @@ def extract_local_input_upload_entries_from_json(dataset_json_path: str) -> list
         for inp in inputs:
             if not isinstance(inp, dict):
                 continue
-            raw_path = str(inp.get("path") or "").strip()
-            if not raw_path:
-                continue
 
-            local_path = raw_path if os.path.isabs(raw_path) else os.path.join(base_dir, raw_path)
-            local_path = os.path.abspath(local_path)
-            if not os.path.isfile(local_path):
-                raise FileNotFoundError(
-                    f"Input file from dataset JSON not found on disk: {raw_path} (resolved: {local_path})"
+            raw_paths = []
+            path = str(inp.get("path") or "").strip()
+            if path:
+                raw_paths.append(path)
+            # player_joints_h5 / player_centroids_h5 inputs may carry a sidecar
+            # ball_path pointing at a separate ball-tracking h5 file; include it
+            # alongside the primary input when present.
+            ball_path = str(inp.get("ball_path") or "").strip()
+            if ball_path:
+                raw_paths.append(ball_path)
+
+            for raw_path in raw_paths:
+                local_path = raw_path if os.path.isabs(raw_path) else os.path.join(base_dir, raw_path)
+                local_path = os.path.abspath(local_path)
+                if not os.path.isfile(local_path):
+                    raise FileNotFoundError(
+                        f"Input file from dataset JSON not found on disk: {raw_path} (resolved: {local_path})"
+                    )
+
+                path_in_repo = _normalize_repo_path(raw_path)
+                if not path_in_repo:
+                    raise ValueError(f"Invalid input path in dataset JSON: {raw_path}")
+
+                entries.append(
+                    {
+                        "local_path": local_path,
+                        "path_in_repo": path_in_repo,
+                    }
                 )
 
-            path_in_repo = _normalize_repo_path(raw_path)
-            if not path_in_repo:
-                raise ValueError(f"Invalid input path in dataset JSON: {raw_path}")
-
-            entries.append(
-                {
-                    "local_path": local_path,
-                    "path_in_repo": path_in_repo,
-                }
-            )
-
     if not entries:
         raise ValueError("No valid data[].inputs[].path entries found in the provided dataset JSON.")
     return entries

{opensportslib-0.3.0.dev19 → opensportslib-0.3.0.dev21}/opensportslib/tools/osl_json_to_parquet.py

@@ -149,9 +149,14 @@ def _estimate_sample_tar_size(
     for input_item in _extract_inputs_with_path(sample):
         rel_path = str(input_item["path"])
         resolved = _resolve_media_path(media_root, rel_path, missing_policy=missing_policy)
-        if resolved is None:
-            continue
-        total += _tar_member_size(resolved.stat().st_size)
+        if resolved is not None:
+            total += _tar_member_size(resolved.stat().st_size)
+
+        ball_rel_path = str(input_item.get("ball_path") or "").strip()
+        if ball_rel_path:
+            ball_resolved = _resolve_media_path(media_root, ball_rel_path, missing_policy=missing_policy)
+            if ball_resolved is not None:
+                total += _tar_member_size(ball_resolved.stat().st_size)
     return total
 
 
@@ -312,6 +317,7 @@ def convert_json_to_parquet(
                 for input_idx, input_item in enumerate(_extract_inputs_with_path(sample)):
                     rel_path = str(input_item["path"])
                     resolved = _resolve_media_path(media_root, rel_path, missing_policy=missing_policy)
+                    input_type = str(input_item.get("type", "")).strip()
 
                     if resolved is None:
                         total_missing_input_files += 1
@@ -319,25 +325,65 @@ def convert_json_to_parquet(
                             "sample_id": sample_id,
                             "shard_name": shard_name,
                             "input_index": input_idx,
-                            "input_type": str(input_item.get("type", "")).strip(),
+                            "file_role": "primary",
+                            "input_type": input_type,
                             "relative_path": rel_path,
                             "resolved_path": None,
                             "status": "missing",
                         })
+                    else:
+                        ext = resolved.suffix.lstrip(".").lower() or "bin"
+                        arcname = f"{key}.{input_idx}.{ext}"
+                        _add_file_to_tar(tar, resolved, arcname)
+                        shard_manifest.append({
+                            "sample_id": sample_id,
+                            "shard_name": shard_name,
+                            "input_index": input_idx,
+                            "file_role": "primary",
+                            "input_type": input_type,
+                            "relative_path": rel_path,
+                            "resolved_path": str(resolved if not keep_relative_paths_in_parquet else rel_path),
+                            "status": "ok",
+                            "wds_member": arcname,
+                        })
+                        total_input_files_added += 1
+
+                    # player_joints_h5 / player_centroids_h5 inputs may carry a
+                    # sidecar ball_path pointing at a separate ball-tracking h5
+                    # file; bundle it into the same shard, tagged with a distinct
+                    # arcname (".ball.") so it doesn't collide with the primary
+                    # input's tar member.
+                    ball_rel_path = str(input_item.get("ball_path") or "").strip()
+                    if not ball_rel_path:
+                        continue
+                    ball_resolved = _resolve_media_path(media_root, ball_rel_path, missing_policy=missing_policy)
+                    if ball_resolved is None:
+                        total_missing_input_files += 1
+                        shard_manifest.append({
+                            "sample_id": sample_id,
+                            "shard_name": shard_name,
+                            "input_index": input_idx,
+                            "file_role": "ball",
+                            "input_type": input_type,
+                            "relative_path": ball_rel_path,
+                            "resolved_path": None,
+                            "status": "missing",
+                        })
                         continue
 
-                    ext = resolved.suffix.lstrip(".").lower() or "bin"
-                    arcname = f"{key}.{input_idx}.{ext}"
-                    _add_file_to_tar(tar, resolved, arcname)
+                    ball_ext = ball_resolved.suffix.lstrip(".").lower() or "bin"
+                    ball_arcname = f"{key}.{input_idx}.ball.{ball_ext}"
+                    _add_file_to_tar(tar, ball_resolved, ball_arcname)
                     shard_manifest.append({
                         "sample_id": sample_id,
                         "shard_name": shard_name,
                         "input_index": input_idx,
-                        "input_type": str(input_item.get("type", "")).strip(),
-                        "relative_path": rel_path,
-                        "resolved_path": str(resolved if not keep_relative_paths_in_parquet else rel_path),
+                        "file_role": "ball",
+                        "input_type": input_type,
+                        "relative_path": ball_rel_path,
+                        "resolved_path": str(ball_resolved if not keep_relative_paths_in_parquet else ball_rel_path),
                         "status": "ok",
-                        "wds_member": arcname,
+                        "wds_member": ball_arcname,
                     })
                     total_input_files_added += 1
 
@@ -349,14 +395,25 @@ def convert_json_to_parquet(
             ok_manifest = manifest_df[manifest_df["status"] == "ok"].copy()
             if not ok_manifest.empty:
                 ok_manifest["input_index"] = ok_manifest["input_index"].astype(int)
+                primary_manifest = ok_manifest[ok_manifest["file_role"] == "primary"]
+                ball_manifest = ok_manifest[ok_manifest["file_role"] == "ball"]
+
                 by_sample_input_paths: Dict[str, Dict[int, str]] = {}
-                for sample_id, sample_manifest in ok_manifest.groupby("sample_id", sort=False):
+                for sample_id, sample_manifest in primary_manifest.groupby("sample_id", sort=False):
                     sample_manifest = sample_manifest.sort_values("input_index")
                     by_sample_input_paths[str(sample_id)] = {
                         int(rec["input_index"]): str(rec["resolved_path"])
                         for _, rec in sample_manifest.iterrows()
                     }
 
+                by_sample_ball_paths: Dict[str, Dict[int, str]] = {}
+                for sample_id, sample_manifest in ball_manifest.groupby("sample_id", sort=False):
+                    sample_manifest = sample_manifest.sort_values("input_index")
+                    by_sample_ball_paths[str(sample_id)] = {
+                        int(rec["input_index"]): str(rec["resolved_path"])
+                        for _, rec in sample_manifest.iterrows()
+                    }
+
                 def _resolved_payload_for_row(row: pd.Series) -> str:
                     payload = maybe_json_loads(row.get("sample_payload"), {})
                     if not isinstance(payload, dict):
@@ -368,6 +425,7 @@ def convert_json_to_parquet(
                         return json_dumps_compact(payload_copy)
 
                     resolved_by_index = by_sample_input_paths.get(str(row.get("sample_id")), {})
+                    resolved_ball_by_index = by_sample_ball_paths.get(str(row.get("sample_id")), {})
                     with_path_idx = 0
                     rewritten: List[Any] = []
                     for inp in inputs_value:
@@ -379,6 +437,10 @@ def convert_json_to_parquet(
                             resolved = resolved_by_index.get(with_path_idx)
                             if resolved is not None:
                                 inp_copy["path"] = resolved
+                            if inp_copy.get("ball_path"):
+                                resolved_ball = resolved_ball_by_index.get(with_path_idx)
+                                if resolved_ball is not None:
+                                    inp_copy["ball_path"] = resolved_ball
                             with_path_idx += 1
                         rewritten.append(inp_copy)
                     payload_copy["inputs"] = rewritten

{opensportslib-0.3.0.dev19 → opensportslib-0.3.0.dev21}/opensportslib/tools/parquet_to_osl_json.py

@@ -52,18 +52,23 @@ def _extract_sample_media_from_tar(
     sample_index: int,
     output_media_root: Path,
     original_paths: List[str],
+    original_ball_paths: Optional[List[Optional[str]]] = None,
     overwrite: bool = False,
 ) -> int:
     """
-    Extract all input files for *sample_index* from the shard.
+    Extract all input files for *sample_index* from the shard, including any
+    sidecar ball-tracking files (tar members named ``<key>.<idx>.ball.<ext>``).
 
-    Files are written to ``output_media_root / original_path``, preserving the
-    original relative path structure so that ``inputs[].path`` values stay valid.
+    Files are written to ``output_media_root / original_path`` (or
+    ``output_media_root / original_ball_path`` for ball members), preserving
+    the original relative path structure so that ``inputs[].path`` /
+    ``inputs[].ball_path`` values stay valid.
 
     Returns the number of files extracted.
     """
     key_prefix = f"{sample_index:09d}."
     extracted = 0
+    ball_paths = original_ball_paths or []
 
     with tarfile.open(tar_path, "r") as tar:
         members = [
@@ -72,20 +77,27 @@ def _extract_sample_media_from_tar(
             if m.isfile() and m.name.startswith(key_prefix) and not m.name.endswith(".json")
         ]
 
-        def _input_idx(m: tarfile.TarInfo) -> int:
-            part = m.name[len(key_prefix) :].split(".", 1)[0]
+        def _member_info(m: tarfile.TarInfo) -> tuple[int, bool]:
+            parts = m.name[len(key_prefix) :].split(".")
             try:
-                return int(part)
+                idx = int(parts[0])
             except ValueError:
-                return 0
+                idx = 0
+            is_ball = len(parts) >= 3 and parts[1] == "ball"
+            return idx, is_ball
 
-        members.sort(key=_input_idx)
+        members.sort(key=_member_info)
 
         for member in members:
-            input_idx = _input_idx(member)
-            if input_idx >= len(original_paths):
-                continue
-            out_path = output_media_root / original_paths[input_idx]
+            input_idx, is_ball = _member_info(member)
+            if is_ball:
+                if input_idx >= len(ball_paths) or not ball_paths[input_idx]:
+                    continue
+                out_path = output_media_root / ball_paths[input_idx]
+            else:
+                if input_idx >= len(original_paths):
+                    continue
+                out_path = output_media_root / original_paths[input_idx]
             if out_path.exists() and not overwrite:
                 extracted += 1
                 continue
@@ -230,16 +242,20 @@ def convert_parquet_to_json(
 
         if extract_media:
             inputs = sample.get("inputs", []) if isinstance(sample, dict) else []
-            original_input_paths = [
-                str(inp["path"])
-                for inp in inputs
-                if isinstance(inp, dict) and inp.get("path")
-            ]
+            original_input_paths: List[str] = []
+            original_ball_paths: List[Optional[str]] = []
+            for inp in inputs:
+                if not isinstance(inp, dict) or not inp.get("path"):
+                    continue
+                original_input_paths.append(str(inp["path"]))
+                ball_path = inp.get("ball_path")
+                original_ball_paths.append(str(ball_path) if ball_path else None)
             extracted_media_count += _extract_sample_media_from_tar(
                 tar_path=tar_path,
                 sample_index=sample_index,
                 output_media_root=output_media_root_path,
                 original_paths=original_input_paths,
+                original_ball_paths=original_ball_paths,
                 overwrite=overwrite_media,
             )
 

{opensportslib-0.3.0.dev19 → opensportslib-0.3.0.dev21/opensportslib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.3.0.dev19
+Version: 0.3.0.dev21
 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

{opensportslib-0.3.0.dev19 → opensportslib-0.3.0.dev21}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opensportslib"
-version = "0.3.0.dev19"
+version = "0.3.0.dev21"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.12"

{opensportslib-0.3.0.dev19 → opensportslib-0.3.0.dev21}/tests/test_hf_transfer_tools.py

@@ -12,11 +12,14 @@ from opensportslib.tools.hf_transfer import (
     create_dataset_repo_on_hf,
     dataset_repo_exists_on_hf,
     download_dataset_split_from_hf,
+    download_dataset_splits_from_hf,
     extract_local_input_upload_entries_from_json,
     extract_repo_paths_from_json,
     is_hf_download_url_not_found_error,
     is_hf_repo_not_found_error,
     is_hf_revision_not_found_error,
+    list_dataset_branches_on_hf,
+    list_dataset_splits_on_hf,
     read_hf_source_metadata_from_dataset,
     upload_dataset_as_parquet_to_hf,
     upload_dataset_inputs_from_json_to_hf,
@@ -226,6 +229,164 @@ def test_dataset_repo_exists_on_hf_returns_false_for_repo_not_found(monkeypatch)
     assert dataset_repo_exists_on_hf("OpenSportsLab/missing-repo", token="hf_token") is False
 
 
+def test_list_dataset_branches_on_hf_puts_main_first_then_alphabetical(monkeypatch):
+    class _FakeRefs:
+        branches = [
+            type("_Ref", (), {"name": "zeta"})(),
+            type("_Ref", (), {"name": "main"})(),
+            type("_Ref", (), {"name": "alpha"})(),
+        ]
+
+    class _FakeApi:
+        def __init__(self, token=None):
+            pass
+
+        def list_repo_refs(self, repo_id, repo_type=None):
+            return _FakeRefs()
+
+    monkeypatch.setattr(
+        "opensportslib.tools.hf_transfer._import_hf_hub",
+        lambda: (_FakeApi, object(), object()),
+    )
+
+    assert list_dataset_branches_on_hf("OpenSportsLab/repo") == ["main", "alpha", "zeta"]
+
+
+def test_list_dataset_splits_on_hf_detects_parquet_layout(monkeypatch):
+    class _FakeApi:
+        def __init__(self, token=None):
+            pass
+
+        def list_repo_files(self, repo_id, revision=None, repo_type=None):
+            return [
+                "README.md",
+                "train/metadata.parquet",
+                "train/shard_manifest.parquet",
+                "train/shards/shard-000000.tar",
+                "test/metadata.parquet",
+                "test/shards/shard-000000.tar",
+            ]
+
+    monkeypatch.setattr(
+        "opensportslib.tools.hf_transfer._import_hf_hub",
+        lambda: (_FakeApi, object(), object()),
+    )
+
+    result = list_dataset_splits_on_hf("OpenSportsLab/repo", "main")
+
+    assert result == {"format": "parquet", "splits": ["train", "test"]}
+
+
+def test_list_dataset_splits_on_hf_treats_json_dataset_with_parquet_media_as_json(monkeypatch):
+    """
+    A JSON-format dataset can reference arbitrary media files (e.g. tensor-encoded
+    videos serialized as .parquet) inside a folder that happens to share a split's
+    name. That must not be misdetected as the canonical Parquet+WebDataset export
+    layout, which requires `{split}/metadata.parquet` + `{split}/shards/*.tar`.
+    Regression test for OpenSportsLab/SNGAR-Action-Spotting-Tracking.
+    """
+
+    class _FakeApi:
+        def __init__(self, token=None):
+            pass
+
+        def list_repo_files(self, repo_id, revision=None, repo_type=None):
+            return [
+                "README.md",
+                "train.json",
+                "valid.json",
+                "test.json",
+                "train/videos/10502.parquet",
+                "train/videos/10503.parquet",
+                "valid/videos/3841.parquet",
+                "test/videos/3850.parquet",
+            ]
+
+    monkeypatch.setattr(
+        "opensportslib.tools.hf_transfer._import_hf_hub",
+        lambda: (_FakeApi, object(), object()),
+    )
+
+    result = list_dataset_splits_on_hf("OpenSportsLab/repo", "main")
+
+    assert result == {"format": "json", "splits": ["train", "valid", "test"]}
+
+
+def test_list_dataset_splits_on_hf_detects_json_layout(monkeypatch):
+    class _FakeApi:
+        def __init__(self, token=None):
+            pass
+
+        def list_repo_files(self, repo_id, revision=None, repo_type=None):
+            return [
+                "dataset_infos.json",
+                "train.json",
+                "challenge.json",
+                "valid.json",
+            ]
+
+    monkeypatch.setattr(
+        "opensportslib.tools.hf_transfer._import_hf_hub",
+        lambda: (_FakeApi, object(), object()),
+    )
+
+    result = list_dataset_splits_on_hf("OpenSportsLab/repo", "main")
+
+    assert result == {"format": "json", "splits": ["train", "valid", "challenge"]}
+
+
+def test_list_dataset_splits_on_hf_returns_none_format_when_nothing_matches(monkeypatch):
+    class _FakeApi:
+        def __init__(self, token=None):
+            pass
+
+        def list_repo_files(self, repo_id, revision=None, repo_type=None):
+            return ["README.md", "dataset_infos.json"]
+
+    monkeypatch.setattr(
+        "opensportslib.tools.hf_transfer._import_hf_hub",
+        lambda: (_FakeApi, object(), object()),
+    )
+
+    assert list_dataset_splits_on_hf("OpenSportsLab/repo", "main") == {"format": None, "splits": []}
+
+
+def test_download_dataset_splits_from_hf_downloads_each_split_with_prefixed_progress(monkeypatch, tmp_path):
+    progress_messages = []
+    calls = []
+
+    def _fake_download_dataset_split_from_hf(repo_id, revision, split, output_dir, **kwargs):
+        calls.append((repo_id, revision, split, output_dir))
+        kwargs["progress_cb"](f"working on {split}")
+        return {"split": split, "json_path": str(tmp_path / f"{split}.json")}
+
+    monkeypatch.setattr(
+        "opensportslib.tools.hf_transfer.download_dataset_split_from_hf",
+        _fake_download_dataset_split_from_hf,
+    )
+
+    results = download_dataset_splits_from_hf(
+        "OpenSportsLab/repo",
+        "main",
+        ["train", "valid"],
+        str(tmp_path),
+        download_format="json",
+        progress_cb=progress_messages.append,
+    )
+
+    assert [call[2] for call in calls] == ["train", "valid"]
+    assert [result["split"] for result in results] == ["train", "valid"]
+    assert progress_messages == [
+        "[1/2] train: working on train",
+        "[2/2] valid: working on valid",
+    ]
+
+
+def test_download_dataset_splits_from_hf_requires_at_least_one_split():
+    with pytest.raises(ValueError):
+        download_dataset_splits_from_hf("OpenSportsLab/repo", "main", [], "/tmp/out")
+
+
 def test_upload_dataset_inputs_from_json_to_hf_uploads_inputs_and_json(monkeypatch, tmp_path):
     clip_path = tmp_path / "train" / "clip_0.mp4"
     clip_path.parent.mkdir(parents=True)