opensportslib 0.1.3.dev3__tar.gz → 0.1.3.dev4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.1.3.dev3
+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.
 
@@ -188,7 +189,7 @@ Minimal localization sample:
 ```
 
 Relative paths in `inputs[].path` are resolved from the split media root in the
-YAML config, for example `DATA.train.video_path`. See the full
+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.
 
@@ -345,7 +346,7 @@ 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.dev3 → 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.
 
@@ -153,7 +154,7 @@ Minimal localization sample:
 ```
 
 Relative paths in `inputs[].path` are resolved from the split media root in the
-YAML config, for example `DATA.train.video_path`. See the full
+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.
 
@@ -310,7 +311,7 @@ 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.dev3 → 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.dev3 → 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(

{opensportslib-0.1.3.dev3 → opensportslib-0.1.3.dev4}/opensportslib/apis/localization.py

@@ -3,6 +3,18 @@ import os
 import time
 
 from opensportslib.apis.base_task_model import BaseTaskModel
+from opensportslib.core.config.accessors import (
+    get_data_classes,
+    get_loader_backend,
+    get_system_gpu_count,
+    get_system_seed,
+    set_system_path,
+    get_train_trainer_type,
+    get_train_execution,
+    get_split_annotation_path,
+    get_split_cfg,
+    set_split_annotation_path,
+)
 from opensportslib.core.utils.config import expand
 
 
@@ -21,44 +33,33 @@ class LocalizationModel(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."
         )
 
     def _set_split_path(self, split: str, value: str) -> str:
         resolved = expand(value)
-        data_cfg = getattr(self.config, "DATA", None)
-        split_cfg = getattr(data_cfg, split, None)
-
-        if split_cfg is not None and hasattr(split_cfg, "path"):
-            split_cfg.path = resolved
-            return resolved
-
-        annotations_cfg = getattr(data_cfg, "annotations", None)
-        if annotations_cfg is not None and hasattr(annotations_cfg, split):
-            setattr(annotations_cfg, split, resolved)
-            return resolved
-
-        raise ValueError(
-            f"Could not set path for split '{split}'. "
-            f"Expected DATA.{split}.path or DATA.annotations.{split}."
-        )
+        set_split_annotation_path(self.config, split, resolved)
+        return resolved
+
+    def _gate_multi_gpu_by_device(self, device) -> None:
+        """Disable TRAIN.execution.multi_gpu when effective device is CPU."""
+        execution = getattr(getattr(self.config, "TRAIN", None), "execution", None)
+        if execution is None:
+            return
+
+        multi_gpu = bool(getattr(execution, "multi_gpu", False))
+        if device.type == "cpu" and multi_gpu:
+            execution.multi_gpu = False
+            logging.warning(
+                "Detected SYSTEM.device=%s; forcing TRAIN.execution.multi_gpu=false for localization runtime.",
+                device,
+            )
 
     def load_weights(
         self,
@@ -78,13 +79,8 @@ class LocalizationModel(BaseTaskModel):
         if weights is None:
             raise ValueError("`weights` must be provided to load_weights().")
 
-        model_cfg = getattr(self.config, "MODEL", None)
-        if not self.train_flag:
-            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)
+        self._gate_multi_gpu_by_device(device)
         if self.model is None:
             self.model = build_model(self.config, device=device)
 
@@ -93,7 +89,11 @@ class LocalizationModel(BaseTaskModel):
             inner_model = getattr(self.model, "model", self.model)
 
         if is_local_path(weights):
-            self.config.SYSTEM.work_dir = os.path.dirname(os.path.abspath(weights))
+            set_system_path(
+                self.config,
+                "work_dir",
+                os.path.dirname(os.path.abspath(weights)),
+            )
 
         if default_args is not None:
             logging.info("Building optimizer + scaler for checkpoint restore...")
@@ -135,7 +135,7 @@ class LocalizationModel(BaseTaskModel):
 
         best_criterion_valid = checkpoint.get(
             "best_criterion_valid",
-            0 if self.config.TRAIN.criterion_valid == "map" else float("inf")
+            0 if get_train_execution(self.config).get("criterion_valid") == "map" else float("inf")
         )
         self._resume_state = {
             "optimizer": optimizer,
@@ -146,10 +146,6 @@ class LocalizationModel(BaseTaskModel):
             "best_criterion_valid": best_criterion_valid,
         }
 
-        if not self.train_flag:
-            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,
@@ -178,6 +174,9 @@ class LocalizationModel(BaseTaskModel):
         valid_set = self._resolve_split_path("valid", valid_set)
         self._set_split_path("train", train_set)
         self._set_split_path("valid", valid_set)
+        # E2E validation mAP uses the `valid_data_frames` split; keep it in sync
+        # with explicit valid annotation overrides.
+        self._set_split_path("valid_data_frames", valid_set)
         
         self.config = resolve_config_omega(self.config, weights=weights)
         check_config(self.config, split="train")
@@ -203,34 +202,34 @@ class LocalizationModel(BaseTaskModel):
             torch.backends.cudnn.benchmark = False
             torch.use_deterministic_algorithms(True, warn_only=True)
 
-        set_seed(self.config.SYSTEM.seed)
+        set_seed(get_system_seed(self.config))
 
         start = time.time()
 
         data_obj_train = build_dataset(self.config, split="train")
         dataset_train = data_obj_train.building_dataset(
             cfg=data_obj_train.cfg,
-            gpu=self.config.SYSTEM.GPU,
+            gpu=get_system_gpu_count(self.config),
             default_args=data_obj_train.default_args,
         )
         train_loader = data_obj_train.building_dataloader(
             dataset_train,
             cfg=data_obj_train.cfg.dataloader,
-            gpu=self.config.SYSTEM.GPU,
-            dali=self.config.dali,
+            gpu=get_system_gpu_count(self.config),
+            dali=(get_loader_backend(self.config) == "dali"),
         )
 
         data_obj_valid = build_dataset(self.config, split="valid")
         dataset_valid = data_obj_valid.building_dataset(
             cfg=data_obj_valid.cfg,
-            gpu=self.config.SYSTEM.GPU,
+            gpu=get_system_gpu_count(self.config),
             default_args=data_obj_valid.default_args,
         )
         valid_loader = data_obj_valid.building_dataloader(
             dataset_valid,
             cfg=data_obj_valid.cfg.dataloader,
-            gpu=self.config.SYSTEM.GPU,
-            dali=self.config.dali,
+            gpu=get_system_gpu_count(self.config),
+            dali=(get_loader_backend(self.config) == "dali"),
         )
 
         default_args = get_default_args_trainer(self.config, len(train_loader))
@@ -241,6 +240,7 @@ class LocalizationModel(BaseTaskModel):
                 self.load_weights(weights=effective_weights, default_args=default_args)
         elif self.model is None:
             device = select_device(self.config.SYSTEM)
+            self._gate_multi_gpu_by_device(device)
             self.model = build_model(self.config, device=device)
 
         self.trainer = build_trainer(
@@ -257,8 +257,8 @@ class LocalizationModel(BaseTaskModel):
                 self.model,
                 train_loader,
                 valid_loader,
-                self.config.DATA.classes,
-                self.config.TRAIN.type,
+                get_data_classes(self.config),
+                get_train_trainer_type(self.config),
             )
         )
 
@@ -291,10 +291,9 @@ class LocalizationModel(BaseTaskModel):
         test_set = self._resolve_split_path("test", test_set)
         self._set_split_path("test", test_set)
 
-        self.config.MODEL.multi_gpu = False
         self.config = resolve_config_omega(self.config, weights=weights)
         check_config(self.config, split="test")
-        self.config.infer_split = whether_infer_split(self.config.DATA.test)
+        self.config.infer_split = whether_infer_split(get_split_cfg(self.config, "test"))
 
         init_wandb(
             self.config_path,
@@ -315,22 +314,23 @@ class LocalizationModel(BaseTaskModel):
                 self.load_weights(weights=effective_weights)
         elif self.model is None:
             device = select_device(self.config.SYSTEM)
+            self._gate_multi_gpu_by_device(device)
             self.model = build_model(self.config, device=device)
 
         data_obj_test = build_dataset(self.config, split="test")
         dataset_test = data_obj_test.building_dataset(
             cfg=data_obj_test.cfg,
-            gpu=self.config.SYSTEM.GPU,
+            gpu=get_system_gpu_count(self.config),
             default_args=data_obj_test.default_args,
         )
         test_loader = data_obj_test.building_dataloader(
             dataset_test,
             cfg=data_obj_test.cfg.dataloader,
-            gpu=self.config.SYSTEM.GPU,
-            dali=self.config.dali,
+            gpu=get_system_gpu_count(self.config),
+            dali=(get_loader_backend(self.config) == "dali"),
         )
 
-        inferer = build_inferer(cfg=self.config.MODEL, model=self.model)
+        inferer = build_inferer(cfg=self.config, model=self.model)
         predictions = inferer.infer(
             cfg=self.config,
             data=dataset_test,
@@ -361,10 +361,9 @@ class LocalizationModel(BaseTaskModel):
 
         test_set = self._resolve_split_path("test", test_set)
         self._set_split_path("test", test_set)
-        self.config.MODEL.multi_gpu = False
         self.config = resolve_config_omega(self.config, weights=weights)
         check_config(self.config, split="test")
-        self.config.infer_split = whether_infer_split(self.config.DATA.test)
+        self.config.infer_split = whether_infer_split(get_split_cfg(self.config, "test"))
 
         init_wandb(
             self.config_path,
@@ -382,16 +381,17 @@ class LocalizationModel(BaseTaskModel):
 
         metrics = None
 
-        if has_localization_events(self.config.DATA.test.path):
+        test_path = get_split_annotation_path(self.config, "test")
+        if has_localization_events(test_path):
             logging.info("Ground truth labels detected -> running evaluation")
             evaluator = build_evaluator(cfg=self.config)
             eval_input = (
-                self.config.DATA.test.results
+                getattr(get_split_cfg(self.config, "test"), "results")
                 if isinstance(predictions, dict)
                 else predictions
             )
             metrics = evaluator.evaluate(
-                cfg_testset=self.config.DATA.test,
+                cfg_testset=get_split_cfg(self.config, "test"),
                 json_gz_file=eval_input,
             )
         else: