opensportslib 0.1.2.dev1__tar.gz → 0.1.2.dev3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.1.2.dev1
+Version: 0.1.2.dev3
 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
@@ -24,6 +24,9 @@ Requires-Dist: timm
 Requires-Dist: seaborn
 Requires-Dist: tabulate
 Requires-Dist: pytorch-lightning
+Requires-Dist: pandas
+Requires-Dist: pyarrow
+Requires-Dist: huggingface_hub
 Provides-Extra: test
 Requires-Dist: pytest; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
@@ -123,14 +126,14 @@ print("OpenSportsLib imported successfully")
 ### Train a classification model
 
 ```python
-from opensportslib import model
+from opensportslib.apis import ClassificationModel
 
-myModel = model.ClassificationModel(
+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",
 )
@@ -139,19 +142,29 @@ myModel.train(
 ### Run inference
 
 ```python
-from opensportslib import model
+from opensportslib.apis import ClassificationModel
 
-myModel = model.classification(
+my_model = ClassificationModel(
     config="/path/to/classification.yaml",
     weights="/path/to/weights.pt",  # optional
 )
 
-predictions = myModel.infer(
+predictions = my_model.infer(
     test_set="/path/to/test_annotations.json",
 )
 
-metrics = myModel.evaluate(
+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)
@@ -160,13 +173,58 @@ 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
+)
+
+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",
+)
 
-myModel = model.localization(
-    config="/path/to/localization.yaml"
+metrics_from_file = my_model.evaluate(
+    test_set="/path/to/test_annotations.json",
+    predictions=saved_predictions,
+)
+```
+
+
+---
+
+## Hugging Face Dataset Transfer
+
+OpenSportsLib provides APIs and scripts for downloading and uploading OSL datasets with Hugging Face.
+
+### Python API
+
+```python
+from opensportslib.tools import (
+    download_dataset_split_from_hf,
+    upload_dataset_inputs_from_json_to_hf,
+    upload_dataset_as_parquet_to_hf,
 )
 ```
 
+### 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
+```
+
+Downloads are placed under `<output-dir>/<revision>/<split>`.
+
 ---
 
 ## What you can do with OpenSportsLib
@@ -201,6 +259,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.dev1 → opensportslib-0.1.2.dev3}/README.md

@@ -92,14 +92,14 @@ print("OpenSportsLib imported successfully")
 ### Train a classification model
 
 ```python
-from opensportslib import model
+from opensportslib.apis import ClassificationModel
 
-myModel = model.ClassificationModel(
+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",
 )
@@ -108,19 +108,29 @@ myModel.train(
 ### Run inference
 
 ```python
-from opensportslib import model
+from opensportslib.apis import ClassificationModel
 
-myModel = model.classification(
+my_model = ClassificationModel(
     config="/path/to/classification.yaml",
     weights="/path/to/weights.pt",  # optional
 )
 
-predictions = myModel.infer(
+predictions = my_model.infer(
     test_set="/path/to/test_annotations.json",
 )
 
-metrics = myModel.evaluate(
+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)
@@ -129,13 +139,58 @@ 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
+)
+
+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",
+)
 
-myModel = model.localization(
-    config="/path/to/localization.yaml"
+metrics_from_file = my_model.evaluate(
+    test_set="/path/to/test_annotations.json",
+    predictions=saved_predictions,
+)
+```
+
+
+---
+
+## Hugging Face Dataset Transfer
+
+OpenSportsLib provides APIs and scripts for downloading and uploading OSL datasets with Hugging Face.
+
+### Python API
+
+```python
+from opensportslib.tools import (
+    download_dataset_split_from_hf,
+    upload_dataset_inputs_from_json_to_hf,
+    upload_dataset_as_parquet_to_hf,
 )
 ```
 
+### 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
+```
+
+Downloads are placed under `<output-dir>/<revision>/<split>`.
+
 ---
 
 ## What you can do with OpenSportsLib
@@ -170,6 +225,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.dev1 → opensportslib-0.1.2.dev3}/examples/quickstart/basic_classification.py

@@ -29,6 +29,18 @@ def main():
 
     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.dev1 → opensportslib-0.1.2.dev3}/examples/quickstart/basic_localization.py

@@ -29,6 +29,18 @@ def main():
 
     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.dev1 → opensportslib-0.1.2.dev3}/opensportslib/__init__.py

@@ -1,8 +1,5 @@
 import importlib
-# from . import apis as model
-# from . import metrics
-# from . import datasets
-# from . import core
+
 
 def __getattr__(name):
     if name == "model":
@@ -13,6 +10,9 @@ def __getattr__(name):
         return importlib.import_module("opensportslib.datasets")
     if name == "core":
         return importlib.import_module("opensportslib.core")
+    if name == "tools":
+        return importlib.import_module("opensportslib.tools")
     raise AttributeError(f"module 'opensportslib' has no attribute '{name}'")
 
-__all__ = ["model", "metrics", "datasets", "core"]
+
+__all__ = ["model", "metrics", "datasets", "core", "tools"]

{opensportslib-0.1.2.dev1 → opensportslib-0.1.2.dev3}/opensportslib/apis/base_task_model.py

@@ -3,9 +3,11 @@
 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
 
@@ -14,6 +16,8 @@ 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")
 
@@ -23,10 +27,29 @@ class BaseTaskModel(ABC):
         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
@@ -36,6 +59,17 @@ class BaseTaskModel(ABC):
         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,
@@ -70,6 +104,7 @@ class BaseTaskModel(ABC):
         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:

{opensportslib-0.1.2.dev1 → opensportslib-0.1.2.dev3}/opensportslib/apis/classification.py

@@ -179,6 +179,8 @@ class ClassificationModel(BaseTaskModel):
 
         del kwargs
 
+        effective_weights = weights if weights is not None else self.last_loaded_weights
+
         world_size = torch.cuda.device_count() or self.config.SYSTEM.GPU
         use_ddp = use_ddp and world_size > 1
 
@@ -198,7 +200,7 @@ class ClassificationModel(BaseTaskModel):
                     train_set,
                     valid_set,
                     None,
-                    weights,
+                    effective_weights,
                     use_wandb,
                 ),
                 nprocs=world_size,
@@ -214,7 +216,7 @@ class ClassificationModel(BaseTaskModel):
                 return_queue=queue,
                 train_set=train_set,
                 valid_set=valid_set,
-                weights=weights,
+                weights=effective_weights,
                 use_wandb=use_wandb,
             )
 
@@ -243,6 +245,8 @@ class ClassificationModel(BaseTaskModel):
         logging.info("Configuration:")
         logging.info(self.config)
 
+        effective_weights = weights if weights is not None else self.last_loaded_weights
+
         world_size = torch.cuda.device_count()
         use_ddp = use_ddp and world_size > 1
 
@@ -261,7 +265,7 @@ class ClassificationModel(BaseTaskModel):
                     None,
                     None,
                     test_set,
-                    weights,
+                    effective_weights,
                     use_wandb,
                 ),
                 nprocs=world_size,
@@ -275,7 +279,7 @@ class ClassificationModel(BaseTaskModel):
                 config=self.config,
                 return_queue=queue,
                 test_set=test_set,
-                weights=weights,
+                weights=effective_weights,
                 use_wandb=use_wandb,
             )
 
@@ -286,6 +290,7 @@ class ClassificationModel(BaseTaskModel):
         self,
         test_set=None,
         weights=None,
+        predictions=None,
         use_ddp=False,
         use_wandb=True,
         **kwargs,
@@ -302,12 +307,13 @@ class ClassificationModel(BaseTaskModel):
         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,
-        )
+        if predictions is None:
+            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")

{opensportslib-0.1.2.dev1 → opensportslib-0.1.2.dev3}/opensportslib/apis/localization.py

@@ -9,6 +9,12 @@ from opensportslib.core.utils.config import expand
 class LocalizationModel(BaseTaskModel):
     """Top-level task wrapper for localization / spotting."""
 
+    def __init__(self, config=None, weights=None):
+        super().__init__(config=config, weights=None)
+        if weights is not None:
+            self.last_loaded_weights = weights
+            self.best_checkpoint = weights
+
     def _resolve_split_path(self, split: str, override: str | None = None) -> str:
         if override is not None:
             return expand(override)
@@ -68,6 +74,11 @@ class LocalizationModel(BaseTaskModel):
         if weights is None:
             raise ValueError("`weights` must be provided to load_weights().")
 
+        model_cfg = getattr(self.config, "MODEL", None)
+        original_multi_gpu = getattr(model_cfg, "multi_gpu", None)
+        if model_cfg is not None and original_multi_gpu is not None:
+            model_cfg.multi_gpu = False
+
         device = select_device(self.config.SYSTEM)
         if self.model is None:
             self.model = build_model(self.config, device=device)
@@ -96,6 +107,9 @@ class LocalizationModel(BaseTaskModel):
         self.last_loaded_weights = weights
         self.best_checkpoint = weights
 
+        if model_cfg is not None and original_multi_gpu is not None:
+            model_cfg.multi_gpu = original_multi_gpu
+
     def train(
         self,
         train_set=None,
@@ -137,6 +151,8 @@ class LocalizationModel(BaseTaskModel):
         logging.info("Configuration:")
         logging.info(self.config)
 
+        effective_weights = weights if weights is not None else self.last_loaded_weights
+
         def set_seed(seed):
             random.seed(seed)
             np.random.seed(seed)
@@ -184,7 +200,7 @@ class LocalizationModel(BaseTaskModel):
             cfg=self.config,
             model=self.model,
             default_args=get_default_args_trainer(self.config, len(train_loader)),
-            resume_from=weights,
+            resume_from=effective_weights,
         )
 
         logging.info("Start training")
@@ -245,8 +261,11 @@ class LocalizationModel(BaseTaskModel):
 
         start = time.time()
 
-        if weights is not None:
-            self.load_weights(weights=weights)
+        effective_weights = weights if weights is not None else self.last_loaded_weights
+
+        if effective_weights is not None:
+            if self.model is None or self.last_loaded_weights != effective_weights:
+                self.load_weights(weights=effective_weights)
         elif self.model is None:
             device = select_device(self.config.SYSTEM)
             self.model = build_model(self.config, device=device)
@@ -278,6 +297,7 @@ class LocalizationModel(BaseTaskModel):
         self,
         test_set=None,
         weights=None,
+        predictions=None,
         use_wandb=True,
         **kwargs,
     ):
@@ -307,11 +327,12 @@ class LocalizationModel(BaseTaskModel):
             use_wandb=use_wandb,
         )
 
-        predictions = self.infer(
-            test_set=test_set,
-            weights=weights,
-            use_wandb=use_wandb,
-        )
+        if predictions is None:
+            predictions = self.infer(
+                test_set=test_set,
+                weights=weights,
+                use_wandb=use_wandb,
+            )
 
         metrics = None
 

opensportslib-0.1.2.dev3/opensportslib/cli.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import argparse
+from typing import Optional
+
+from opensportslib.setup.setup import setup
+
+
+def main(argv: Optional[list[str]] = None) -> int:
+    parser = argparse.ArgumentParser(prog="opensportslib")
+    parser.add_argument("command", choices=["setup"])
+    parser.add_argument("--pyg", action="store_true")
+    parser.add_argument("--dali", action="store_true")
+
+    args = parser.parse_args(argv)
+
+    if args.command == "setup":
+        setup(
+            pyg=args.pyg,
+            dali=args.dali,
+        )
+        return 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{opensportslib-0.1.2.dev1 → opensportslib-0.1.2.dev3}/opensportslib/core/trainer/classification_trainer.py

@@ -517,7 +517,7 @@ class BaseTrainerClassification:
 
             logging.info(f"RESULTS Length: {len(results)}")
             logging.info(f"Predictions are stored at : {save_path}")
-            with open(save_path, "w") as f:
+            with open(save_path, "w", encoding="utf-8") as f:
                 json.dump(submission, f, indent=2)
             self.predictions_payload = submission
 
@@ -1018,7 +1018,7 @@ class Trainer_Classification:
             out_dir = os.path.join(self.config.SYSTEM.save_dir, "final")
             os.makedirs(out_dir, exist_ok=True)
             out_path = os.path.join(out_dir, "predictions_test_epoch_final.json")
-            with open(out_path, "w") as f:
+            with open(out_path, "w", encoding="utf-8") as f:
                 json.dump(submission, f, indent=2)
             self.predictions_payload = submission
             return submission
@@ -1107,14 +1107,14 @@ class Trainer_Classification:
         if isinstance(pred_path, dict):
             pred_data = pred_path
         elif isinstance(pred_path, str):
-            with open(pred_path) as f:
+            with open(pred_path, encoding="utf-8") as f:
                 pred_data = json.load(f)
         else:
             raise TypeError(
                 f"Unsupported predictions type: {type(pred_path).__name__}. Expected dict or str."
             )
 
-        with open(gt_path) as f:
+        with open(gt_path, encoding="utf-8") as f:
             gt_data = json.load(f)
 
         gt_dict = {}

{opensportslib-0.1.2.dev1 → opensportslib-0.1.2.dev3}/opensportslib/core/trainer/localization_trainer.py

@@ -791,7 +791,7 @@ class Evaluator:
         # --------------------------------------------------
         # LOAD GT
         # --------------------------------------------------
-        with open(cfg.path) as f:
+        with open(cfg.path, encoding="utf-8") as f:
             GT_data = json.load(f)
 
         # --------------------------------------------------
@@ -895,7 +895,7 @@ class Evaluator:
                 if not os.path.exists(pred_file):
                     continue
                 
-                with open(pred_file) as f:
+                with open(pred_file, encoding="utf-8") as f:
                     pred_data_local = json.load(f)
 
                 if "data" in pred_data_local:

{opensportslib-0.1.2.dev1 → opensportslib-0.1.2.dev3}/opensportslib/core/utils/config.py

@@ -105,11 +105,11 @@ def expand(path):
 
 
 def load_json(fpath):
-    with open(fpath) as fp:
+    with open(fpath, encoding="utf-8") as fp:
         return json.load(fp)
 
 def load_gz_json(fpath):
-    with gzip.open(fpath, "rt", encoding="ascii") as fp:
+    with gzip.open(fpath, "rt", encoding="utf-8") as fp:
         return json.load(fp)
 
 
@@ -118,12 +118,12 @@ def store_json(fpath, obj, pretty=False):
     if pretty:
         kwargs["indent"] = 4
         kwargs["sort_keys"] = False
-    with open(fpath, "w") as fp:
+    with open(fpath, "w", encoding="utf-8") as fp:
         json.dump(obj, fp, **kwargs)
 
 
 def store_gz_json(fpath, obj):
-    with gzip.open(fpath, "wt", encoding="ascii") as fp:
+    with gzip.open(fpath, "wt", encoding="utf-8") as fp:
         json.dump(obj, fp)