opensportslib 0.1.1.dev6__tar.gz → 0.1.2.dev1__tar.gz

{opensportslib-0.1.1.dev6/opensportslib.egg-info → opensportslib-0.1.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.1.1.dev6
+Version: 0.1.2.dev1
 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
@@ -125,14 +125,14 @@ print("OpenSportsLib imported successfully")
 ```python
 from opensportslib import model
 
-myModel = model.classification(
-    config="/path/to/classification.yaml"
+myModel = model.ClassificationModel(
+    config="/path/to/classification.yaml",
+    weights="/path/to/weights.pt",  # optional
 )
 
 myModel.train(
     train_set="/path/to/train_annotations.json",
     valid_set="/path/to/valid_annotations.json",
-    pretrained="/path/to/pretrained.pt",  # optional
 )
 ```
 
@@ -142,13 +142,16 @@ myModel.train(
 from opensportslib import model
 
 myModel = model.classification(
-    config="/path/to/classification.yaml"
+    config="/path/to/classification.yaml",
+    weights="/path/to/weights.pt",  # optional
+)
+
+predictions = myModel.infer(
+    test_set="/path/to/test_annotations.json",
 )
 
-metrics = myModel.infer(
+metrics = myModel.evaluate(
     test_set="/path/to/test_annotations.json",
-    pretrained="/path/to/checkpoints/final_model",
-    predictions="/path/to/predictions.json"
 )
 
 print(metrics)

{opensportslib-0.1.1.dev6 → opensportslib-0.1.2.dev1}/README.md

@@ -94,14 +94,14 @@ print("OpenSportsLib imported successfully")
 ```python
 from opensportslib import model
 
-myModel = model.classification(
-    config="/path/to/classification.yaml"
+myModel = model.ClassificationModel(
+    config="/path/to/classification.yaml",
+    weights="/path/to/weights.pt",  # optional
 )
 
 myModel.train(
     train_set="/path/to/train_annotations.json",
     valid_set="/path/to/valid_annotations.json",
-    pretrained="/path/to/pretrained.pt",  # optional
 )
 ```
 
@@ -111,13 +111,16 @@ myModel.train(
 from opensportslib import model
 
 myModel = model.classification(
-    config="/path/to/classification.yaml"
+    config="/path/to/classification.yaml",
+    weights="/path/to/weights.pt",  # optional
+)
+
+predictions = myModel.infer(
+    test_set="/path/to/test_annotations.json",
 )
 
-metrics = myModel.infer(
+metrics = myModel.evaluate(
     test_set="/path/to/test_annotations.json",
-    pretrained="/path/to/checkpoints/final_model",
-    predictions="/path/to/predictions.json"
 )
 
 print(metrics)

{opensportslib-0.1.1.dev6 → opensportslib-0.1.2.dev1}/examples/quickstart/basic_classification.py

@@ -1,4 +1,4 @@
-from opensportslib import model
+from opensportslib.apis import ClassificationModel
 
 
 def main():
@@ -7,20 +7,24 @@ def main():
     Update config and dataset paths before running.
     """
 
-    my_model = model.classification(
-        config="examples/configs/classification_video.yaml"
+    my_model = ClassificationModel(
+        config="examples/configs/classification_video.yaml",
+        weights="/path/to/weights.pt",  # optional
     )
 
     my_model.train(
         train_set="/path/to/train_annotations.json",
         valid_set="/path/to/valid_annotations.json",
-        pretrained="/path/to/pretrained.pt",  # optional
     )
 
-    metrics = my_model.infer(
+    predictions = my_model.infer(
+        test_set="/path/to/test_annotations.json",
+    )
+
+    print(predictions)
+
+    metrics = my_model.evaluate(
         test_set="/path/to/test_annotations.json",
-        pretrained="/path/to/checkpoints/best.pt",
-        predictions="/path/to/predictions.json",
     )
 
     print(metrics)

{opensportslib-0.1.1.dev6 → opensportslib-0.1.2.dev1}/examples/quickstart/basic_localization.py

@@ -1,4 +1,4 @@
-from opensportslib import model
+from opensportslib.apis import LocalizationModel
 
 
 def main():
@@ -7,20 +7,24 @@ def main():
     Update config and dataset paths before running.
     """
 
-    my_model = model.localization(
-        config="examples/configs/localization.yaml"
+    my_model = LocalizationModel(
+        config="examples/configs/localization.yaml",
+        weights="/path/to/weights.pt",  # optional
     )
 
     my_model.train(
         train_set="/path/to/train_annotations.json",
         valid_set="/path/to/valid_annotations.json",
-        pretrained="/path/to/pretrained.pt",  # optional
     )
     
-    metrics = my_model.infer(
+    predictions = my_model.infer(
+        test_set="/path/to/test_annotations.json",
+    )
+
+    print(predictions)
+
+    metrics = my_model.evaluate(
         test_set="/path/to/test_annotations.json",
-        pretrained="/path/to/checkpoints/best.pt",
-        predictions="/path/to/predictions.json",
     )
 
     print(metrics)

opensportslib-0.1.2.dev1/opensportslib/apis/__init__.py

@@ -0,0 +1,15 @@
+# opensportslib/apis/__init__.py
+
+# Import task APIs
+from opensportslib.apis.base_task_model import BaseTaskModel
+from opensportslib.apis.classification import ClassificationModel
+from opensportslib.apis.localization import LocalizationModel
+import warnings
+warnings.filterwarnings("ignore")
+
+# Expose only these
+__all__ = [
+    "BaseTaskModel",
+    "ClassificationModel",
+    "LocalizationModel",
+]

opensportslib-0.1.2.dev1/opensportslib/apis/base_task_model.py

@@ -0,0 +1,96 @@
+"""Shared task-level wrapper base for OpenSportsLib APIs."""
+
+from __future__ import annotations
+
+import json
+import os
+import uuid
+from abc import ABC, abstractmethod
+
+from opensportslib.core.utils.config import expand, load_config_omega
+
+
+class BaseTaskModel(ABC):
+    """Thin shared contract for task-level OpenSportsLib wrappers."""
+
+    def __init__(self, config=None, weights=None):
+        if config is None:
+            raise ValueError("config path is required")
+
+        self.config_path = expand(config)
+        self.config = load_config_omega(self.config_path)
+
+        data_cfg = getattr(self.config, "DATA", None)
+        if data_cfg is not None and hasattr(data_cfg, "data_dir"):
+            data_cfg.data_dir = expand(data_cfg.data_dir)
+
+        self.run_id = os.environ.get("RUN_ID") or str(uuid.uuid4())[:8]
+        os.environ["RUN_ID"] = self.run_id
+
+        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)
+
+    @abstractmethod
+    def load_weights(
+        self,
+        weights: str | None = None,
+        **kwargs,
+    ) -> None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def train(
+        self,
+        train_set: str | None = None,
+        valid_set: str | None = None,
+        weights: str | None = None,
+        use_wandb: bool = True,
+        **kwargs,
+    ) -> str | None:
+        raise NotImplementedError
+
+    @abstractmethod
+    def infer(
+        self,
+        test_set: str | None = None,
+        weights: str | None = None,
+        use_wandb: bool = True,
+        **kwargs,
+    ) -> dict:
+        raise NotImplementedError
+
+    @abstractmethod
+    def evaluate(
+        self,
+        test_set: str | None = None,
+        weights: str | None = None,
+        use_wandb: bool = True,
+        **kwargs,
+    ) -> dict | str | None:
+        raise NotImplementedError
+
+    def save_predictions(
+        self,
+        output_path: str,
+        predictions: dict,
+    ) -> str:
+        """Persist in-memory prediction JSON payload to a target file path."""
+
+        dst = expand(output_path)
+        os.makedirs(os.path.dirname(dst) or ".", exist_ok=True)
+
+        if not isinstance(predictions, dict):
+            raise TypeError(
+                f"Unsupported predictions type: {type(predictions).__name__}. "
+                "Expected dict."
+            )
+
+        with open(dst, "w", encoding="utf-8") as f:
+            json.dump(predictions, f)
+        return dst

opensportslib-0.1.2.dev1/opensportslib/apis/classification.py

@@ -0,0 +1,322 @@
+# opensportslib/apis/classification.py
+
+"""Public API for classification tasks."""
+
+import logging
+import os
+
+from opensportslib.apis.base_task_model import BaseTaskModel
+from opensportslib.core.utils.config import expand
+
+
+class ClassificationModel(BaseTaskModel):
+    """Top-level task wrapper for classification."""
+
+    def _resolve_split_path(self, split: str, override: str | None = None) -> str:
+        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
+        )
+        if path:
+            return expand(path)
+
+        raise ValueError(
+            f"Could not resolve path for split '{split}'. "
+            f"Expected DATA.{split}.path or DATA.annotations.{split}."
+        )
+
+    # -----------------------------------------------------------------
+    # internal DDP worker
+    # -----------------------------------------------------------------
+    @staticmethod
+    def _worker_ddp(
+        rank,
+        world_size,
+        mode,
+        config_path,
+        config,
+        return_queue=None,
+        train_set=None,
+        valid_set=None,
+        test_set=None,
+        weights=None,
+        use_wandb=False,
+    ):
+        """Execute one training/inference job on a single process."""
+        import torch
+        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
+        from opensportslib.core.utils.seed import set_reproducibility
+        from opensportslib.datasets.builder import build_dataset
+        from opensportslib.models.builder import build_model
+
+        logging.basicConfig(
+            level=logging.INFO,
+            format=f"[RANK {rank}] %(asctime)s | %(levelname)s | %(message)s",
+            force=True,
+        )
+        if rank != 0:
+            logging.getLogger().setLevel(logging.ERROR)
+
+        if rank == 0:
+            init_wandb(
+                config_path,
+                config,
+                run_id=os.environ["RUN_ID"],
+                use_wandb=use_wandb,
+            )
+
+        if getattr(config.SYSTEM, "use_seed", False):
+            set_reproducibility(config.SYSTEM.seed)
+
+        is_ddp = world_size > 1
+        if is_ddp:
+            torch.cuda.set_device(rank)
+            ddp_setup(rank, world_size)
+            device = torch.device(f"cuda:{rank}")
+        else:
+            from opensportslib.core.utils.config import select_device
+
+            device = select_device(config.SYSTEM)
+
+        trainer = Trainer_Classification(config)
+        trainer.device = device
+
+        if weights:
+            model, processor, _, _ = trainer.load(weights)
+        else:
+            model, processor = build_model(config, device)
+
+        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)
+
+        if is_ddp:
+            ddp_cleanup()
+
+    def load_weights(
+        self,
+        weights: str | None = None,
+        **kwargs,
+    ) -> None:
+        from opensportslib.core.trainer.classification_trainer import Trainer_Classification
+
+        del kwargs
+        if weights is None:
+            raise ValueError("`weights` must be provided to load_weights().")
+
+        self.trainer = Trainer_Classification(self.config)
+        loaded = self.trainer.load(weights)
+        self.model = loaded[0]
+
+        if getattr(self.config.MODEL, "type", "custom") == "huggingface":
+            self.processor = loaded[1]
+
+        self.last_loaded_weights = weights
+        self.best_checkpoint = weights
+
+    # -----------------------------------------------------------------
+    # public training interface
+    # -----------------------------------------------------------------
+
+    def train(
+        self,
+        train_set=None,
+        valid_set=None,
+        test_set=None,
+        weights=None,
+        use_ddp=False,
+        use_wandb=True,
+        **kwargs,
+    ):
+        """Run full training and return best checkpoint path."""
+        import torch
+        import torch.multiprocessing as mp
+        from opensportslib.core.utils.config import resolve_config_omega
+
+        del test_set  # retained for API compatibility
+
+        train_set = self._resolve_split_path("train", train_set)
+        valid_set = self._resolve_split_path("valid", valid_set)
+
+        self.config = resolve_config_omega(self.config)
+        logging.info("Configuration:")
+        logging.info(self.config)
+
+        del kwargs
+
+        world_size = torch.cuda.device_count() or self.config.SYSTEM.GPU
+        use_ddp = use_ddp and world_size > 1
+
+        ctx = mp.get_context("spawn")
+        queue = ctx.Queue()
+
+        if use_ddp:
+            logging.info(f"Launching DDP on {world_size} GPUs")
+            mp.spawn(
+                ClassificationModel._worker_ddp,
+                args=(
+                    world_size,
+                    "train",
+                    self.config_path,
+                    self.config,
+                    queue,
+                    train_set,
+                    valid_set,
+                    None,
+                    weights,
+                    use_wandb,
+                ),
+                nprocs=world_size,
+            )
+        else:
+            logging.info("Single GPU training")
+            ClassificationModel._worker_ddp(
+                rank=0,
+                world_size=1,
+                mode="train",
+                config_path=self.config_path,
+                config=self.config,
+                return_queue=queue,
+                train_set=train_set,
+                valid_set=valid_set,
+                weights=weights,
+                use_wandb=use_wandb,
+            )
+
+        self.best_checkpoint = queue.get()
+        self.last_loaded_weights = self.best_checkpoint
+        return self.best_checkpoint
+
+    def infer(
+        self,
+        test_set=None,
+        weights=None,
+        use_ddp=False,
+        use_wandb=True,
+        **kwargs,
+    ):
+        """Run model inference and return predictions in OSL JSON format."""
+        del kwargs
+
+        import torch
+        import torch.multiprocessing as mp
+        from opensportslib.core.utils.config import resolve_config_omega
+
+        test_set = self._resolve_split_path("test", test_set)
+
+        self.config = resolve_config_omega(self.config)
+        logging.info("Configuration:")
+        logging.info(self.config)
+
+        world_size = torch.cuda.device_count()
+        use_ddp = use_ddp and world_size > 1
+
+        ctx = mp.get_context("spawn")
+        queue = ctx.Queue()
+
+        if use_ddp:
+            mp.spawn(
+                ClassificationModel._worker_ddp,
+                args=(
+                    world_size,
+                    "infer",
+                    self.config_path,
+                    self.config,
+                    queue,
+                    None,
+                    None,
+                    test_set,
+                    weights,
+                    use_wandb,
+                ),
+                nprocs=world_size,
+            )
+        else:
+            ClassificationModel._worker_ddp(
+                rank=0,
+                world_size=1,
+                mode="infer",
+                config_path=self.config_path,
+                config=self.config,
+                return_queue=queue,
+                test_set=test_set,
+                weights=weights,
+                use_wandb=use_wandb,
+            )
+
+        predictions = queue.get()
+        return predictions
+
+    def evaluate(
+        self,
+        test_set=None,
+        weights=None,
+        use_ddp=False,
+        use_wandb=True,
+        **kwargs,
+    ):
+        """Run inference on test set and return evaluation metrics."""
+        del kwargs
+
+        from opensportslib.datasets.builder import build_dataset
+        from opensportslib.core.trainer.classification_trainer import Trainer_Classification
+        from opensportslib.core.utils.config import resolve_config_omega
+
+        test_set = self._resolve_split_path("test", test_set)
+
+        self.config = resolve_config_omega(self.config)
+        logging.info("Configuration:")
+        logging.info(self.config)
+        predictions = self.infer(
+            test_set=test_set,
+            weights=weights,
+            use_ddp=use_ddp,
+            use_wandb=use_wandb,
+        )
+
+        self.trainer = self.trainer or Trainer_Classification(self.config)
+        test_data = build_dataset(self.config, test_set, None, split="test")
+        metrics = self.trainer.evaluate(
+            pred_path=predictions,
+            gt_path=test_set,
+            class_names=test_data.label_map,
+            exclude_labels=test_data.exclude_labels,
+        )
+
+        logging.info(f"TEST METRICS : {metrics}")
+        return metrics