opensportslib 0.1.2__tar.gz → 0.1.2.dev2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.1.2
+Version: 0.1.2.dev2
 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
@@ -123,32 +123,45 @@ print("OpenSportsLib imported successfully")
 ### Train a classification model
 
 ```python
-from opensportslib import model
+from opensportslib.apis import ClassificationModel
 
-myModel = model.classification(
-    config="/path/to/classification.yaml"
+my_model = ClassificationModel(
+    config="/path/to/classification.yaml",
+    weights="/path/to/weights.pt",  # optional
 )
 
-myModel.train(
+my_model.train(
     train_set="/path/to/train_annotations.json",
     valid_set="/path/to/valid_annotations.json",
-    pretrained="/path/to/pretrained.pt",  # optional
 )
 ```
 
 ### Run inference
 
 ```python
-from opensportslib import model
+from opensportslib.apis import ClassificationModel
 
-myModel = model.classification(
-    config="/path/to/classification.yaml"
+my_model = ClassificationModel(
+    config="/path/to/classification.yaml",
+    weights="/path/to/weights.pt",  # optional
 )
 
-metrics = myModel.infer(
+predictions = my_model.infer(
     test_set="/path/to/test_annotations.json",
-    pretrained="/path/to/checkpoints/final_model",
-    predictions="/path/to/predictions.json"
+)
+
+saved_predictions = my_model.save_predictions(
+    output_path="/path/to/predictions.json",
+    predictions=predictions,
+)
+
+metrics = my_model.evaluate(
+    test_set="/path/to/test_annotations.json",
+)
+
+metrics_from_file = my_model.evaluate(
+    test_set="/path/to/test_annotations.json",
+    predictions=saved_predictions,
 )
 
 print(metrics)
@@ -157,10 +170,29 @@ print(metrics)
 ### Localization example
 
 ```python
-from opensportslib import model
+from opensportslib.apis import LocalizationModel
+
+my_model = LocalizationModel(
+    config="/path/to/localization.yaml",
+    weights="/path/to/weights.pt",  # optional
+)
 
-myModel = model.localization(
-    config="/path/to/localization.yaml"
+predictions = my_model.infer(
+    test_set="/path/to/test_annotations.json",
+)
+
+saved_predictions = my_model.save_predictions(
+    output_path="/path/to/predictions.json",
+    predictions=predictions,
+)
+
+metrics = my_model.evaluate(
+    test_set="/path/to/test_annotations.json",
+)
+
+metrics_from_file = my_model.evaluate(
+    test_set="/path/to/test_annotations.json",
+    predictions=saved_predictions,
 )
 ```
 
@@ -198,6 +230,7 @@ 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/
+- High-level API guide: [opensportslib/apis/README.md](opensportslib/apis/README.md)
 - Configuration guide: https://opensportslab.github.io/opensportslib/tni/config-guide/
 - Example configs: [examples/configs/](examples/configs/)
 - Quickstart scripts: [examples/quickstart/](examples/quickstart/)

{opensportslib-0.1.2 → opensportslib-0.1.2.dev2}/README.md

@@ -92,32 +92,45 @@ print("OpenSportsLib imported successfully")
 ### Train a classification model
 
 ```python
-from opensportslib import model
+from opensportslib.apis import ClassificationModel
 
-myModel = model.classification(
-    config="/path/to/classification.yaml"
+my_model = ClassificationModel(
+    config="/path/to/classification.yaml",
+    weights="/path/to/weights.pt",  # optional
 )
 
-myModel.train(
+my_model.train(
     train_set="/path/to/train_annotations.json",
     valid_set="/path/to/valid_annotations.json",
-    pretrained="/path/to/pretrained.pt",  # optional
 )
 ```
 
 ### Run inference
 
 ```python
-from opensportslib import model
+from opensportslib.apis import ClassificationModel
 
-myModel = model.classification(
-    config="/path/to/classification.yaml"
+my_model = ClassificationModel(
+    config="/path/to/classification.yaml",
+    weights="/path/to/weights.pt",  # optional
 )
 
-metrics = myModel.infer(
+predictions = my_model.infer(
     test_set="/path/to/test_annotations.json",
-    pretrained="/path/to/checkpoints/final_model",
-    predictions="/path/to/predictions.json"
+)
+
+saved_predictions = my_model.save_predictions(
+    output_path="/path/to/predictions.json",
+    predictions=predictions,
+)
+
+metrics = my_model.evaluate(
+    test_set="/path/to/test_annotations.json",
+)
+
+metrics_from_file = my_model.evaluate(
+    test_set="/path/to/test_annotations.json",
+    predictions=saved_predictions,
 )
 
 print(metrics)
@@ -126,10 +139,29 @@ print(metrics)
 ### Localization example
 
 ```python
-from opensportslib import model
+from opensportslib.apis import LocalizationModel
+
+my_model = LocalizationModel(
+    config="/path/to/localization.yaml",
+    weights="/path/to/weights.pt",  # optional
+)
 
-myModel = model.localization(
-    config="/path/to/localization.yaml"
+predictions = my_model.infer(
+    test_set="/path/to/test_annotations.json",
+)
+
+saved_predictions = my_model.save_predictions(
+    output_path="/path/to/predictions.json",
+    predictions=predictions,
+)
+
+metrics = my_model.evaluate(
+    test_set="/path/to/test_annotations.json",
+)
+
+metrics_from_file = my_model.evaluate(
+    test_set="/path/to/test_annotations.json",
+    predictions=saved_predictions,
 )
 ```
 
@@ -167,6 +199,7 @@ 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/
+- High-level API guide: [opensportslib/apis/README.md](opensportslib/apis/README.md)
 - Configuration guide: https://opensportslab.github.io/opensportslib/tni/config-guide/
 - Example configs: [examples/configs/](examples/configs/)
 - Quickstart scripts: [examples/quickstart/](examples/quickstart/)

opensportslib-0.1.2.dev2/examples/quickstart/basic_classification.py

@@ -0,0 +1,46 @@
+from opensportslib.apis import ClassificationModel
+
+
+def main():
+    """
+    Minimal classification example.
+    Update config and dataset paths before running.
+    """
+
+    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",
+    )
+
+    predictions = my_model.infer(
+        test_set="/path/to/test_annotations.json",
+    )
+
+    print(predictions)
+
+    metrics = my_model.evaluate(
+        test_set="/path/to/test_annotations.json",
+    )
+
+    print(metrics)
+
+    saved_predictions = my_model.save_predictions(
+        output_path="/path/to/predictions.json",
+        predictions=predictions,
+    )
+
+    metrics_from_file = my_model.evaluate(
+        test_set="/path/to/test_annotations.json",
+        predictions=saved_predictions,
+    )
+
+    print(metrics_from_file)
+
+
+if __name__ == "__main__":
+    main()

opensportslib-0.1.2.dev2/examples/quickstart/basic_localization.py

@@ -0,0 +1,46 @@
+from opensportslib.apis import LocalizationModel
+
+
+def main():
+    """
+    Minimal localization example.
+    Update config and dataset paths before running.
+    """
+
+    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",
+    )
+    
+    predictions = my_model.infer(
+        test_set="/path/to/test_annotations.json",
+    )
+
+    print(predictions)
+
+    metrics = my_model.evaluate(
+        test_set="/path/to/test_annotations.json",
+    )
+
+    print(metrics)
+
+    saved_predictions = my_model.save_predictions(
+        output_path="/path/to/predictions.json",
+        predictions=predictions,
+    )
+
+    metrics_from_file = my_model.evaluate(
+        test_set="/path/to/test_annotations.json",
+        predictions=saved_predictions,
+    )
+
+    print(metrics_from_file)
+
+
+if __name__ == "__main__":
+    main()

opensportslib-0.1.2.dev2/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.dev2/opensportslib/apis/base_task_model.py

@@ -0,0 +1,131 @@
+"""Shared task-level wrapper base for OpenSportsLib APIs."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any
+
+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):
+        self._configure_logging()
+
+        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)
+            logging.info(f"Data directory: {data_cfg.data_dir}")
+
+        self.run_id = os.environ.get("RUN_ID") or str(uuid.uuid4())[:8]
+        os.environ["RUN_ID"] = self.run_id
+
+        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"
+            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
+            os.makedirs(run_save_dir, exist_ok=True)
+        else:
+            self.save_dir = expand("./checkpoints")
+            os.makedirs(self.save_dir, exist_ok=True)
+
+        logging.info(f"Save directory: {self.save_dir}")
+
+        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)
+
+    @staticmethod
+    def _configure_logging() -> None:
+        root_logger = logging.getLogger()
+        if not root_logger.handlers:
+            logging.basicConfig(
+                level=logging.INFO,
+                format="%(asctime)s | %(levelname)s | %(message)s",
+            )
+        elif root_logger.level > logging.INFO:
+            root_logger.setLevel(logging.INFO)
+
+    @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,
+        predictions: str | dict[str, Any] | 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