opensportslib 0.3.1.dev22__tar.gz → 0.3.1.dev24__tar.gz

opensportslib-0.3.1.dev24/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: opensportslib
+Version: 0.3.1.dev24
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSE-COMMERCIAL
+Requires-Dist: SoccerNet
+Requires-Dist: av
+Requires-Dist: decord; platform_system != "Darwin" and platform_machine != "arm64" and platform_machine != "aarch64"
+Requires-Dist: evaluate
+Requires-Dist: scikit-learn
+Requires-Dist: torch
+Requires-Dist: torchvision
+Requires-Dist: transformers==4.57.3
+Requires-Dist: tokenizers==0.22.1
+Requires-Dist: accelerate
+Requires-Dist: wandb
+Requires-Dist: opencv-python
+Requires-Dist: omegaconf
+Requires-Dist: timm
+Requires-Dist: seaborn
+Requires-Dist: tabulate
+Requires-Dist: pytorch-lightning
+Requires-Dist: pandas
+Requires-Dist: pyarrow
+Requires-Dist: h5py==3.16.0
+Requires-Dist: huggingface_hub
+Requires-Dist: datasets<6,>=5.0.0
+Requires-Dist: easydict
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pytest-json-report; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Dynamic: license-file
+
+# OpenSportsLib
+
+<img src="docs/assets/osl.jpg" height="400">
+
+OpenSportsLib is a modular Python library for sports video understanding.
+
+It provides a unified framework to **train, evaluate, and run inference** for key temporal understanding tasks in sports video, including:
+
+- **Action classification**
+- **Action localization / spotting**
+- **Visual Question Answering (VQA)**
+
+Retrieval and action description/captioning are roadmap areas. They do not yet
+have first-class task wrappers or training workflows in this package.
+
+OpenSportsLib is designed for **researchers, ML engineers, and sports analytics teams** who want reproducible and extensible workflows for sports video AI.
+
+## Why OpenSportsLib?
+
+- Unified workflow for training and inference
+- Modular design for adding new tasks, datasets, and models
+- Config driven experiments for reproducibility
+- Optional SpoTTA test-time adaptation for E2ESpot inference
+- Support for multiple modalities and sports workflows
+- Research friendly while still usable in applied settings
+
+## Quick links
+
+- **Documentation:** https://opensportslab.github.io/opensportslib/
+- **OSL JSON format:** https://opensportslab.github.io/opensportslib/data/osl-json-format/
+- **Inference server:** [server/README.md](server/README.md)
+- **PyPI:** https://pypi.org/project/opensportslib/
+- **Issues:** https://github.com/OpenSportsLab/opensportslib/issues
+
+---
+
+## Installation
+
+> Requires **Python 3.12+**.  
+> Supports CUDA 12.6 / 12.8 / 13.0 (with CPU fallback).  
+> PyTorch Geometric uses a dedicated PyTorch 2.12.1 compatibility profile.
+
+### Create conda env
+
+```bash
+conda create -n osl python=3.12 pip -y
+conda activate osl
+```
+
+### Stable release
+
+```bash
+pip install opensportslib
+```
+
+### Pre release
+
+```bash
+pip install --pre opensportslib
+```
+
+### Source development version
+
+```bash
+pip install -e .
+```
+
+### Setup Environment (PyTorch, CUDA aware & Optional Dependencies)
+```bash
+# Install PyTorch (CPU/GPU auto-detected)
+opensportslib setup
+
+# Optional: install PyTorch Geometric support. This replaces the installed
+# Torch stack with the PyG-compatible PyTorch 2.12.1 profile.
+opensportslib setup --pyg
+
+# Optional: install for DALI support
+opensportslib setup --dali
+
+# Optional: install the X-VARS-compatible VQA dependency profile
+opensportslib setup --vqa_xvars
+
+# Optional: install the Qwen-compatible VQA dependency profile
+opensportslib setup --vqa_qwen
+```
+---
+
+**Note:**  
+Run `opensportslib setup` to automatically configure dependencies.  
+If issues occur, manually install compatible versions of `torch`, `torchvision`, and related libraries according to your CUDA version or system compatibility.
+
+For VQA, use exactly one backend-specific dependency profile:
+
+- `--vqa_xvars` installs the X-VARS-compatible Hugging Face stack from `XVARS_DEPENDENCY_PINS`
+- `--vqa_qwen` installs the Qwen-compatible Hugging Face stack from `QWEN_DEPENDENCY_PINS`
+
+The `vqa_qwen` config supports `Qwen/Qwen2.5-7B-Instruct` and `Qwen/Qwen3.5-9B-Base`.
+
+---
+
+## Data and pretrained models
+
+OpenSportsLib uses external annotation files, datasets, and pretrained checkpoints.
+
+Public assets are hosted under the **OpenSportsLab Hugging Face organization**:
+
+**https://huggingface.co/OpenSportsLab**
+
+Use it as the main entry point to find:
+- datasets
+- annotation files
+- extracted features
+- pretrained models and checkpoints
+
+See the [Model Zoo](docs/model-zoo.md) for available pretrained models,
+reported scores, datasets, and loading snippets.
+
+---
+
+## Dataset format
+
+OpenSportsLib uses the **OSL JSON v2.0** annotation format for multimodal
+datasets and predictions. See the [OSL JSON format guide](docs/data/osl-json-format.md)
+for its schema, examples, and conversion notes.
+
+---
+
+## Quickstart
+
+### Classification
+
+```python
+from opensportslib.apis import ClassificationModel
+
+my_model = ClassificationModel(
+    config="/path/to/classification.yaml",
+    weights=None,  # optional: path or Hugging Face model ID
+)
+
+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")
+my_model.save_predictions(
+    output_path="/path/to/predictions.json",
+    predictions=predictions,
+)
+```
+
+For localization, VQA, and additional end-to-end examples, see the
+[API guide](opensportslib/apis/README.md), [quickstart scripts](examples/quickstart/),
+and [VQA guide](docs/tools/vqa.md).
+
+
+---
+
+## Hugging Face Dataset Transfer
+
+OpenSportsLib provides APIs and scripts for downloading and uploading OSL datasets with Hugging Face.
+
+For SN-GAR classification and action-spotting configurations, setup, caching,
+and training commands, see the [SN-GAR examples](examples/sngar/README.md).
+
+### Python API
+
+```python
+from opensportslib.tools import (
+    download_dataset_split_from_hf,
+    download_dataset_sample_inputs_from_hf,
+    upload_dataset_inputs_from_json_to_hf,
+    upload_dataset_as_parquet_to_hf,
+)
+```
+
+### Scripts
+
+```bash
+python tools/download/download_osl_hf.py --repo-id <org/repo> --revision main --split test --format parquet --output-dir downloaded_data --annotations-only
+python tools/download/upload_osl_hf.py --repo-id <org/repo> --json-path <local_dataset.json> --split test --revision main
+```
+
+---
+
+## Examples and documentation
+
+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/config/configuration-guide/
+- Example configs: [examples/configs/](examples/configs/)
+- Quickstart scripts: [examples/quickstart/](examples/quickstart/)
+- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Developer guide: [DEVELOPERS.md](DEVELOPERS.md)
+
+---
+
+## Development setup
+
+For contributors who want to work from source:
+
+```bash
+git clone https://github.com/OpenSportsLab/opensportslib.git
+cd opensportslib
+pip install -e .
+```
+
+### Conda option
+
+If you prefer conda:
+
+```bash
+conda create -n osl python=3.12 pip
+conda activate osl
+pip install -e .
+```
+
+### Setup Environment (PyTorch, CUDA aware & Optional Dependencies)
+```bash
+# Install PyTorch (CPU/GPU auto-detected)
+opensportslib setup
+
+# Optional: install PyTorch Geometric support. This replaces the installed
+# Torch stack with the PyG-compatible PyTorch 2.12.1 profile.
+opensportslib setup --pyg
+
+# Optional: install for DALI support
+opensportslib setup --dali
+
+# Optional: install the X-VARS-compatible VQA dependency profile
+opensportslib setup --vqa_xvars
+
+# Optional: install the Qwen-compatible VQA dependency profile
+opensportslib setup --vqa_qwen
+```
+
+---
+
+## Contributing
+
+We welcome contributions. Pull requests must target `dev`, and each
+GitHub-linked commit author must accept the [Individual Contributor License
+Agreement](.github/CLA.md) when prompted by the `CLA check`.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow and
+[DEVELOPERS.md](DEVELOPERS.md) for architecture and extension guidance.
+
+---
+
+## License
+
+OpenSportsLib is available under dual licensing.
+
+### Open source license
+[AGPL 3.0](LICENSE) for research, academic, and community use.
+
+### Commercial license
+For proprietary or commercial deployment, please refer to [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL).
+
+---
+
+## Citation
+
+If you use OpenSportsLib in your research, please cite the project.
+
+```bibtex
+@misc{opensportslib,
+  title={OpenSportsLib},
+  author={OpenSportsLab},
+  year={2026},
+  howpublished={\url{https://github.com/OpenSportsLab/opensportslib}}
+}
+```
+
+---
+
+## Acknowledgments
+
+OpenSportsLib is developed within the broader OpenSportsLab effort for sports
+video understanding. Core contributors affiliated with KAUST include:
+
+- [Jeet Vora](https://jeetv.github.io/) — Remote Research Engineer
+- [Dr. Merey Ramazanova](https://meryusha.github.io/) — Post-Doc
+- [Dr. Silvio Giancola](https://www.silviogiancola.com/) — Research Scientist

opensportslib-0.3.1.dev24/README.md

@@ -0,0 +1,287 @@
+# OpenSportsLib
+
+<img src="docs/assets/osl.jpg" height="400">
+
+OpenSportsLib is a modular Python library for sports video understanding.
+
+It provides a unified framework to **train, evaluate, and run inference** for key temporal understanding tasks in sports video, including:
+
+- **Action classification**
+- **Action localization / spotting**
+- **Visual Question Answering (VQA)**
+
+Retrieval and action description/captioning are roadmap areas. They do not yet
+have first-class task wrappers or training workflows in this package.
+
+OpenSportsLib is designed for **researchers, ML engineers, and sports analytics teams** who want reproducible and extensible workflows for sports video AI.
+
+## Why OpenSportsLib?
+
+- Unified workflow for training and inference
+- Modular design for adding new tasks, datasets, and models
+- Config driven experiments for reproducibility
+- Optional SpoTTA test-time adaptation for E2ESpot inference
+- Support for multiple modalities and sports workflows
+- Research friendly while still usable in applied settings
+
+## Quick links
+
+- **Documentation:** https://opensportslab.github.io/opensportslib/
+- **OSL JSON format:** https://opensportslab.github.io/opensportslib/data/osl-json-format/
+- **Inference server:** [server/README.md](server/README.md)
+- **PyPI:** https://pypi.org/project/opensportslib/
+- **Issues:** https://github.com/OpenSportsLab/opensportslib/issues
+
+---
+
+## Installation
+
+> Requires **Python 3.12+**.  
+> Supports CUDA 12.6 / 12.8 / 13.0 (with CPU fallback).  
+> PyTorch Geometric uses a dedicated PyTorch 2.12.1 compatibility profile.
+
+### Create conda env
+
+```bash
+conda create -n osl python=3.12 pip -y
+conda activate osl
+```
+
+### Stable release
+
+```bash
+pip install opensportslib
+```
+
+### Pre release
+
+```bash
+pip install --pre opensportslib
+```
+
+### Source development version
+
+```bash
+pip install -e .
+```
+
+### Setup Environment (PyTorch, CUDA aware & Optional Dependencies)
+```bash
+# Install PyTorch (CPU/GPU auto-detected)
+opensportslib setup
+
+# Optional: install PyTorch Geometric support. This replaces the installed
+# Torch stack with the PyG-compatible PyTorch 2.12.1 profile.
+opensportslib setup --pyg
+
+# Optional: install for DALI support
+opensportslib setup --dali
+
+# Optional: install the X-VARS-compatible VQA dependency profile
+opensportslib setup --vqa_xvars
+
+# Optional: install the Qwen-compatible VQA dependency profile
+opensportslib setup --vqa_qwen
+```
+---
+
+**Note:**  
+Run `opensportslib setup` to automatically configure dependencies.  
+If issues occur, manually install compatible versions of `torch`, `torchvision`, and related libraries according to your CUDA version or system compatibility.
+
+For VQA, use exactly one backend-specific dependency profile:
+
+- `--vqa_xvars` installs the X-VARS-compatible Hugging Face stack from `XVARS_DEPENDENCY_PINS`
+- `--vqa_qwen` installs the Qwen-compatible Hugging Face stack from `QWEN_DEPENDENCY_PINS`
+
+The `vqa_qwen` config supports `Qwen/Qwen2.5-7B-Instruct` and `Qwen/Qwen3.5-9B-Base`.
+
+---
+
+## Data and pretrained models
+
+OpenSportsLib uses external annotation files, datasets, and pretrained checkpoints.
+
+Public assets are hosted under the **OpenSportsLab Hugging Face organization**:
+
+**https://huggingface.co/OpenSportsLab**
+
+Use it as the main entry point to find:
+- datasets
+- annotation files
+- extracted features
+- pretrained models and checkpoints
+
+See the [Model Zoo](docs/model-zoo.md) for available pretrained models,
+reported scores, datasets, and loading snippets.
+
+---
+
+## Dataset format
+
+OpenSportsLib uses the **OSL JSON v2.0** annotation format for multimodal
+datasets and predictions. See the [OSL JSON format guide](docs/data/osl-json-format.md)
+for its schema, examples, and conversion notes.
+
+---
+
+## Quickstart
+
+### Classification
+
+```python
+from opensportslib.apis import ClassificationModel
+
+my_model = ClassificationModel(
+    config="/path/to/classification.yaml",
+    weights=None,  # optional: path or Hugging Face model ID
+)
+
+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")
+my_model.save_predictions(
+    output_path="/path/to/predictions.json",
+    predictions=predictions,
+)
+```
+
+For localization, VQA, and additional end-to-end examples, see the
+[API guide](opensportslib/apis/README.md), [quickstart scripts](examples/quickstart/),
+and [VQA guide](docs/tools/vqa.md).
+
+
+---
+
+## Hugging Face Dataset Transfer
+
+OpenSportsLib provides APIs and scripts for downloading and uploading OSL datasets with Hugging Face.
+
+For SN-GAR classification and action-spotting configurations, setup, caching,
+and training commands, see the [SN-GAR examples](examples/sngar/README.md).
+
+### Python API
+
+```python
+from opensportslib.tools import (
+    download_dataset_split_from_hf,
+    download_dataset_sample_inputs_from_hf,
+    upload_dataset_inputs_from_json_to_hf,
+    upload_dataset_as_parquet_to_hf,
+)
+```
+
+### Scripts
+
+```bash
+python tools/download/download_osl_hf.py --repo-id <org/repo> --revision main --split test --format parquet --output-dir downloaded_data --annotations-only
+python tools/download/upload_osl_hf.py --repo-id <org/repo> --json-path <local_dataset.json> --split test --revision main
+```
+
+---
+
+## Examples and documentation
+
+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/config/configuration-guide/
+- Example configs: [examples/configs/](examples/configs/)
+- Quickstart scripts: [examples/quickstart/](examples/quickstart/)
+- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Developer guide: [DEVELOPERS.md](DEVELOPERS.md)
+
+---
+
+## Development setup
+
+For contributors who want to work from source:
+
+```bash
+git clone https://github.com/OpenSportsLab/opensportslib.git
+cd opensportslib
+pip install -e .
+```
+
+### Conda option
+
+If you prefer conda:
+
+```bash
+conda create -n osl python=3.12 pip
+conda activate osl
+pip install -e .
+```
+
+### Setup Environment (PyTorch, CUDA aware & Optional Dependencies)
+```bash
+# Install PyTorch (CPU/GPU auto-detected)
+opensportslib setup
+
+# Optional: install PyTorch Geometric support. This replaces the installed
+# Torch stack with the PyG-compatible PyTorch 2.12.1 profile.
+opensportslib setup --pyg
+
+# Optional: install for DALI support
+opensportslib setup --dali
+
+# Optional: install the X-VARS-compatible VQA dependency profile
+opensportslib setup --vqa_xvars
+
+# Optional: install the Qwen-compatible VQA dependency profile
+opensportslib setup --vqa_qwen
+```
+
+---
+
+## Contributing
+
+We welcome contributions. Pull requests must target `dev`, and each
+GitHub-linked commit author must accept the [Individual Contributor License
+Agreement](.github/CLA.md) when prompted by the `CLA check`.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow and
+[DEVELOPERS.md](DEVELOPERS.md) for architecture and extension guidance.
+
+---
+
+## License
+
+OpenSportsLib is available under dual licensing.
+
+### Open source license
+[AGPL 3.0](LICENSE) for research, academic, and community use.
+
+### Commercial license
+For proprietary or commercial deployment, please refer to [LICENSE-COMMERCIAL](LICENSE-COMMERCIAL).
+
+---
+
+## Citation
+
+If you use OpenSportsLib in your research, please cite the project.
+
+```bibtex
+@misc{opensportslib,
+  title={OpenSportsLib},
+  author={OpenSportsLab},
+  year={2026},
+  howpublished={\url{https://github.com/OpenSportsLab/opensportslib}}
+}
+```
+
+---
+
+## Acknowledgments
+
+OpenSportsLib is developed within the broader OpenSportsLab effort for sports
+video understanding. Core contributors affiliated with KAUST include:
+
+- [Jeet Vora](https://jeetv.github.io/) — Remote Research Engineer
+- [Dr. Merey Ramazanova](https://meryusha.github.io/) — Post-Doc
+- [Dr. Silvio Giancola](https://www.silviogiancola.com/) — Research Scientist