opensportslib 0.1.3.dev2__tar.gz → 0.1.3.dev4__tar.gz

{opensportslib-0.1.3.dev2/opensportslib.egg-info → opensportslib-0.1.3.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.1.3.dev2
+Version: 0.1.3.dev4
 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
@@ -34,6 +34,7 @@ Requires-Dist: pytest-cov; extra == "test"
 Dynamic: license-file
 
 # OpenSportsLib
+<img src="docs/assets/osl.jpg" height="400">
 
 OpenSportsLib is a modular Python library for sports video understanding.
 
@@ -57,6 +58,7 @@ OpenSportsLib is designed for **researchers, ML engineers, and sports analytics
 ## Quick links
 
 - **Documentation:** https://opensportslab.github.io/opensportslib/
+- **OSL JSON format:** https://opensportslab.github.io/opensportslib/data/osl-json-format/
 - **PyPI:** https://pypi.org/project/opensportslib/
 - **Issues:** https://github.com/OpenSportsLab/opensportslib/issues
 
@@ -116,7 +118,82 @@ Use it as the main entry point to find:
 See the [Model Zoo](docs/model-zoo.md) for available pretrained models,
 reported scores, datasets, and loading snippets.
 
---
+---
+
+## Dataset format
+
+OpenSportsLib annotation files use the **OSL JSON v2.0** format. A dataset JSON
+contains top-level metadata, a shared `labels` schema, and a `data` array where
+each sample points to one or more inputs.
+
+Minimal classification sample:
+
+```json
+{
+  "labels": {
+    "action": {
+      "type": "single_label",
+      "labels": ["pass", "shot"]
+    }
+  },
+  "data": [
+    {
+      "id": "clip_0001",
+      "inputs": [
+        {
+          "type": "video",
+          "path": "clips/clip_0001.mp4",
+          "fps": 25.0
+        }
+      ],
+      "labels": {
+        "action": {
+          "label": "shot"
+        }
+      }
+    }
+  ]
+}
+```
+
+Minimal localization sample:
+
+```json
+{
+  "labels": {
+    "action": {
+      "type": "single_label",
+      "labels": ["pass", "shot"]
+    }
+  },
+  "data": [
+    {
+      "id": "game_0001",
+      "inputs": [
+        {
+          "type": "video",
+          "path": "games/game_0001.mp4",
+          "fps": 25.0
+        }
+      ],
+      "events": [
+        {
+          "head": "action",
+          "label": "pass",
+          "position_ms": 1240
+        }
+      ]
+    }
+  ]
+}
+```
+
+Relative paths in `inputs[].path` are resolved from the split media root in the
+YAML config, for example `DATA.common.splits.train.source_path`. See the full
+[OSL JSON format guide](docs/data/osl-json-format.md) for field definitions,
+multi-modal examples, prediction payloads, and conversion notes.
+
+---
 
 ## Quickstart
 
@@ -223,8 +300,8 @@ from opensportslib.tools import (
 ### Scripts
 
 ```bash
-python tools/download_osl_hf.py --repo-id <org/repo> --revision main --split test --format parquet --output-dir downloaded_data
-python tools/upload_osl_hf.py --repo-id <org/repo> --json-path <local_dataset.json> --split test --revision main
+python tools/download/download_osl_hf.py --repo-id <org/repo> --revision main --split test --format parquet --output-dir downloaded_data
+python tools/download/upload_osl_hf.py --repo-id <org/repo> --json-path <local_dataset.json> --split test --revision main
 ```
 
 Downloads are placed under `<output-dir>/<revision>/<split>`.
@@ -241,9 +318,13 @@ Predict when key events happen in long untrimmed sports videos.
 
 ### Action Retrieval
 Search and retrieve relevant clips or moments from a collection of sports videos.
+This is part of the roadmap and OSL data model, not a first-class OpenSportsLib
+training workflow yet.
 
 ### Action Description / Captioning
 Generate text descriptions for sports events and temporal segments.
+This is part of the roadmap and OSL data model, not a first-class OpenSportsLib
+training workflow yet.
 
 ---
 
@@ -263,8 +344,9 @@ Generate text descriptions for sports events and temporal segments.
 Use the README for the fast start, then go deeper through:
 
 - Full documentation: https://opensportslab.github.io/opensportslib/
+- OSL JSON format: [docs/data/osl-json-format.md](docs/data/osl-json-format.md)
 - High-level API guide: [opensportslib/apis/README.md](opensportslib/apis/README.md)
-- Configuration guide: https://opensportslab.github.io/opensportslib/tni/config-guide/
+- Configuration guide: https://opensportslab.github.io/opensportslib/config/configuration-guide/
 - Example configs: [examples/configs/](examples/configs/)
 - Quickstart scripts: [examples/quickstart/](examples/quickstart/)
 - Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)

{opensportslib-0.1.3.dev2 → opensportslib-0.1.3.dev4}/README.md

@@ -1,4 +1,5 @@
 # OpenSportsLib
+<img src="docs/assets/osl.jpg" height="400">
 
 OpenSportsLib is a modular Python library for sports video understanding.
 
@@ -22,6 +23,7 @@ OpenSportsLib is designed for **researchers, ML engineers, and sports analytics
 ## Quick links
 
 - **Documentation:** https://opensportslab.github.io/opensportslib/
+- **OSL JSON format:** https://opensportslab.github.io/opensportslib/data/osl-json-format/
 - **PyPI:** https://pypi.org/project/opensportslib/
 - **Issues:** https://github.com/OpenSportsLab/opensportslib/issues
 
@@ -81,7 +83,82 @@ Use it as the main entry point to find:
 See the [Model Zoo](docs/model-zoo.md) for available pretrained models,
 reported scores, datasets, and loading snippets.
 
---
+---
+
+## Dataset format
+
+OpenSportsLib annotation files use the **OSL JSON v2.0** format. A dataset JSON
+contains top-level metadata, a shared `labels` schema, and a `data` array where
+each sample points to one or more inputs.
+
+Minimal classification sample:
+
+```json
+{
+  "labels": {
+    "action": {
+      "type": "single_label",
+      "labels": ["pass", "shot"]
+    }
+  },
+  "data": [
+    {
+      "id": "clip_0001",
+      "inputs": [
+        {
+          "type": "video",
+          "path": "clips/clip_0001.mp4",
+          "fps": 25.0
+        }
+      ],
+      "labels": {
+        "action": {
+          "label": "shot"
+        }
+      }
+    }
+  ]
+}
+```
+
+Minimal localization sample:
+
+```json
+{
+  "labels": {
+    "action": {
+      "type": "single_label",
+      "labels": ["pass", "shot"]
+    }
+  },
+  "data": [
+    {
+      "id": "game_0001",
+      "inputs": [
+        {
+          "type": "video",
+          "path": "games/game_0001.mp4",
+          "fps": 25.0
+        }
+      ],
+      "events": [
+        {
+          "head": "action",
+          "label": "pass",
+          "position_ms": 1240
+        }
+      ]
+    }
+  ]
+}
+```
+
+Relative paths in `inputs[].path` are resolved from the split media root in the
+YAML config, for example `DATA.common.splits.train.source_path`. See the full
+[OSL JSON format guide](docs/data/osl-json-format.md) for field definitions,
+multi-modal examples, prediction payloads, and conversion notes.
+
+---
 
 ## Quickstart
 
@@ -188,8 +265,8 @@ from opensportslib.tools import (
 ### Scripts
 
 ```bash
-python tools/download_osl_hf.py --repo-id <org/repo> --revision main --split test --format parquet --output-dir downloaded_data
-python tools/upload_osl_hf.py --repo-id <org/repo> --json-path <local_dataset.json> --split test --revision main
+python tools/download/download_osl_hf.py --repo-id <org/repo> --revision main --split test --format parquet --output-dir downloaded_data
+python tools/download/upload_osl_hf.py --repo-id <org/repo> --json-path <local_dataset.json> --split test --revision main
 ```
 
 Downloads are placed under `<output-dir>/<revision>/<split>`.
@@ -206,9 +283,13 @@ Predict when key events happen in long untrimmed sports videos.
 
 ### Action Retrieval
 Search and retrieve relevant clips or moments from a collection of sports videos.
+This is part of the roadmap and OSL data model, not a first-class OpenSportsLib
+training workflow yet.
 
 ### Action Description / Captioning
 Generate text descriptions for sports events and temporal segments.
+This is part of the roadmap and OSL data model, not a first-class OpenSportsLib
+training workflow yet.
 
 ---
 
@@ -228,8 +309,9 @@ Generate text descriptions for sports events and temporal segments.
 Use the README for the fast start, then go deeper through:
 
 - Full documentation: https://opensportslab.github.io/opensportslib/
+- OSL JSON format: [docs/data/osl-json-format.md](docs/data/osl-json-format.md)
 - High-level API guide: [opensportslib/apis/README.md](opensportslib/apis/README.md)
-- Configuration guide: https://opensportslab.github.io/opensportslib/tni/config-guide/
+- Configuration guide: https://opensportslab.github.io/opensportslib/config/configuration-guide/
 - Example configs: [examples/configs/](examples/configs/)
 - Quickstart scripts: [examples/quickstart/](examples/quickstart/)
 - Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)

{opensportslib-0.1.3.dev2 → opensportslib-0.1.3.dev4}/opensportslib/apis/base_task_model.py

@@ -9,6 +9,7 @@ import uuid
 from abc import ABC, abstractmethod
 from typing import Any
 
+from opensportslib.core.config.accessors import get_component_name_by_kind
 from opensportslib.core.utils.config import expand, load_config_omega, fetch_and_merge_config_from_HF
 
 
@@ -23,6 +24,8 @@ class BaseTaskModel(ABC):
 
         self.config_path = expand(config)
         self.config = load_config_omega(self.config_path)
+        self.last_loaded_weights = None
+        self.best_checkpoint = None
 
         if weights is not None:
             self.config = fetch_and_merge_config_from_HF(self.config, weights, merge_policy="compatibility")
@@ -41,15 +44,23 @@ class BaseTaskModel(ABC):
 
         system_cfg = getattr(self.config, "SYSTEM", None)
         if system_cfg is not None:
-            base_save_dir = expand(getattr(system_cfg, "save_dir", None) or "./checkpoints")
-            model_cfg = getattr(self.config, "MODEL", None)
-            backbone_cfg = getattr(model_cfg, "backbone", None)
-            model_name = getattr(backbone_cfg, "type", None) or "model"
+            system_paths = getattr(system_cfg, "paths", None)
+            base_save_dir = expand(
+                getattr(system_paths, "save_dir", None)
+                or getattr(system_cfg, "save_dir", None)
+                or "./checkpoints"
+            )
+            model_name = get_component_name_by_kind(self.config, "encoder") or "model"
             run_save_dir = os.path.join(base_save_dir, model_name, self.run_id)
             self.save_dir = run_save_dir
-            system_cfg.save_dir = run_save_dir
-            if hasattr(system_cfg, "work_dir"):
-                system_cfg.work_dir = run_save_dir
+            if system_paths is not None:
+                system_paths.save_dir = run_save_dir
+                if hasattr(system_paths, "work_dir"):
+                    system_paths.work_dir = run_save_dir
+            else:
+                system_cfg.save_dir = run_save_dir
+                if hasattr(system_cfg, "work_dir"):
+                    system_cfg.work_dir = run_save_dir
             os.makedirs(run_save_dir, exist_ok=True)
         else:
             self.save_dir = expand("./checkpoints")
@@ -60,8 +71,6 @@ class BaseTaskModel(ABC):
         self.model = None
         self.processor = None
         self.trainer = None
-        self.best_checkpoint = None
-        self.last_loaded_weights = None
 
         if weights is not None:
             self.load_weights(weights=weights)

{opensportslib-0.1.3.dev2 → opensportslib-0.1.3.dev4}/opensportslib/apis/classification.py

@@ -4,8 +4,17 @@
 
 import logging
 import os
+import json
 
 from opensportslib.apis.base_task_model import BaseTaskModel
+from opensportslib.core.config.accessors import (
+    get_component_provider_by_kind,
+    get_data_modality,
+    get_split_annotation_path,
+    get_system_gpu_count,
+    get_system_seed,
+    get_system_use_seed,
+)
 from opensportslib.core.utils.config import expand
 
 class ClassificationModel(BaseTaskModel):
@@ -15,24 +24,13 @@ class ClassificationModel(BaseTaskModel):
         if override is not None:
             return expand(override)
 
-        data_cfg = getattr(self.config, "DATA", None)
-        split_cfg = getattr(data_cfg, split, None)
-        path = getattr(split_cfg, "path", None) if split_cfg is not None else None
-        if path:
-            return expand(path)
-
-        annotations_cfg = getattr(data_cfg, "annotations", None)
-        path = (
-            getattr(annotations_cfg, split, None)
-            if annotations_cfg is not None
-            else None
-        )
+        path = get_split_annotation_path(self.config, split)
         if path:
             return expand(path)
 
         raise ValueError(
             f"Could not resolve path for split '{split}'. "
-            f"Expected DATA.{split}.path or DATA.annotations.{split}."
+            f"Expected DATA.common.splits.{split}.annotation_path."
         )
 
     # -----------------------------------------------------------------
@@ -54,6 +52,7 @@ class ClassificationModel(BaseTaskModel):
     ):
         """Execute one training/inference job on a single process."""
         import torch
+        import wandb
         from opensportslib.core.trainer.classification_trainer import Trainer_Classification
         from opensportslib.core.utils.ddp import ddp_cleanup, ddp_setup
         from opensportslib.core.utils.wandb import init_wandb
@@ -77,8 +76,8 @@ class ClassificationModel(BaseTaskModel):
                 use_wandb=use_wandb,
             )
 
-        if getattr(config.SYSTEM, "use_seed", False):
-            set_reproducibility(config.SYSTEM.seed)
+        if get_system_use_seed(config):
+            set_reproducibility(get_system_seed(config))
 
         is_ddp = world_size > 1
         if is_ddp:
@@ -100,32 +99,50 @@ class ClassificationModel(BaseTaskModel):
 
         trainer.model = model
 
-        if mode == "train":
-            train_data = build_dataset(config, train_set, processor, split="train")
-            valid_data = build_dataset(config, valid_set, processor, split="valid")
-            best_ckpt = trainer.train(
-                model,
-                train_data,
-                valid_data,
-                rank=rank,
-                world_size=world_size,
-            )
-            if rank == 0 and return_queue is not None:
-                best_ckpt = best_ckpt or getattr(trainer.trainer, "best_checkpoint_path", None)
-                return_queue.put(best_ckpt)
-
-        elif mode == "infer":
-            test_data = build_dataset(config, test_set, processor, split="test")
-            predictions = trainer.infer(
-                test_data,
-                rank=rank,
-                world_size=world_size,
-            )
-            if rank == 0 and return_queue is not None:
-                return_queue.put(predictions)
+        modality = get_data_modality(config)
+        use_tracking_collate = modality in {"tracking", "tracking_parquet"}
+        logging.info(
+            "Worker setup | mode=%s | modality=%s | tracking_collate=%s",
+            mode,
+            modality,
+            use_tracking_collate,
+        )
 
-        if is_ddp:
-            ddp_cleanup()
+        try:
+            if mode == "train":
+                train_data = build_dataset(config, train_set, processor, split="train")
+                valid_data = build_dataset(config, valid_set, processor, split="valid")
+                best_ckpt = trainer.train(
+                    model,
+                    train_data,
+                    valid_data,
+                    rank=rank,
+                    world_size=world_size,
+                )
+                if rank == 0 and return_queue is not None:
+                    best_ckpt = best_ckpt or getattr(trainer.trainer, "best_checkpoint_path", None)
+                    return_queue.put(best_ckpt)
+
+            elif mode == "infer":
+                test_data = build_dataset(config, test_set, processor, split="test")
+                _ = trainer.infer(
+                    test_data,
+                    rank=rank,
+                    world_size=world_size,
+                )
+                if rank == 0 and return_queue is not None:
+                    if world_size > 1:
+                        return_queue.put(getattr(trainer, "predictions_path", None))
+                    else:
+                        return_queue.put(getattr(trainer, "predictions_payload", None))
+        finally:
+            if rank == 0 and use_wandb and getattr(wandb, "run", None) is not None:
+                try:
+                    wandb.finish(quiet=True)
+                except Exception:
+                    pass
+            if is_ddp:
+                ddp_cleanup()
 
     def load_weights(
         self,
@@ -142,7 +159,7 @@ class ClassificationModel(BaseTaskModel):
         loaded = self.trainer.load(weights)
         self.model = loaded[0]
 
-        if getattr(self.config.MODEL, "type", "custom") == "huggingface":
+        if get_component_provider_by_kind(self.config, "encoder") == "huggingface":
             self.processor = loaded[1]
 
         self.last_loaded_weights = weights
@@ -180,11 +197,11 @@ class ClassificationModel(BaseTaskModel):
 
         effective_weights = weights if weights is not None else self.last_loaded_weights
 
-        world_size = torch.cuda.device_count() or self.config.SYSTEM.GPU
+        world_size = torch.cuda.device_count() or get_system_gpu_count(self.config)
         use_ddp = use_ddp and world_size > 1
 
         ctx = mp.get_context("spawn")
-        queue = ctx.Queue()
+        queue = ctx.SimpleQueue()
 
         if use_ddp:
             logging.info(f"Launching DDP on {world_size} GPUs")
@@ -283,6 +300,9 @@ class ClassificationModel(BaseTaskModel):
             )
 
         predictions = queue.get()
+        if use_ddp and isinstance(predictions, str):
+            with open(predictions, encoding="utf-8") as f:
+                predictions = json.load(f)
         return predictions
 
     def evaluate(