opensportslib 0.1.3.dev1__tar.gz → 0.1.3.dev3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.1.3.dev1
+Version: 0.1.3.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
@@ -57,6 +57,7 @@ OpenSportsLib is designed for **researchers, ML engineers, and sports analytics
 ## Quick links
 
 - **Documentation:** https://opensportslab.github.io/opensportslib/
+- **OSL JSON format:** https://opensportslab.github.io/opensportslib/data/osl-json-format/
 - **PyPI:** https://pypi.org/project/opensportslib/
 - **Issues:** https://github.com/OpenSportsLab/opensportslib/issues
 
@@ -113,7 +114,85 @@ Use it as the main entry point to find:
 - 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 annotation files use the **OSL JSON v2.0** format. A dataset JSON
+contains top-level metadata, a shared `labels` schema, and a `data` array where
+each sample points to one or more inputs.
+
+Minimal classification sample:
+
+```json
+{
+  "labels": {
+    "action": {
+      "type": "single_label",
+      "labels": ["pass", "shot"]
+    }
+  },
+  "data": [
+    {
+      "id": "clip_0001",
+      "inputs": [
+        {
+          "type": "video",
+          "path": "clips/clip_0001.mp4",
+          "fps": 25.0
+        }
+      ],
+      "labels": {
+        "action": {
+          "label": "shot"
+        }
+      }
+    }
+  ]
+}
+```
+
+Minimal localization sample:
+
+```json
+{
+  "labels": {
+    "action": {
+      "type": "single_label",
+      "labels": ["pass", "shot"]
+    }
+  },
+  "data": [
+    {
+      "id": "game_0001",
+      "inputs": [
+        {
+          "type": "video",
+          "path": "games/game_0001.mp4",
+          "fps": 25.0
+        }
+      ],
+      "events": [
+        {
+          "head": "action",
+          "label": "pass",
+          "position_ms": 1240
+        }
+      ]
+    }
+  ]
+}
+```
+
+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
+[OSL JSON format guide](docs/data/osl-json-format.md) for field definitions,
+multi-modal examples, prediction payloads, and conversion notes.
+
+---
 
 ## Quickstart
 
@@ -131,7 +210,7 @@ from opensportslib.apis import ClassificationModel
 
 my_model = ClassificationModel(
     config="/path/to/classification.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 my_model.train(
@@ -147,7 +226,7 @@ from opensportslib.apis import ClassificationModel
 
 my_model = ClassificationModel(
     config="/path/to/classification.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 predictions = my_model.infer(
@@ -178,7 +257,7 @@ from opensportslib.apis import LocalizationModel
 
 my_model = LocalizationModel(
     config="/path/to/localization.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 predictions = my_model.infer(
@@ -220,8 +299,8 @@ from opensportslib.tools import (
 ### 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
+python tools/download/download_osl_hf.py --repo-id <org/repo> --revision main --split test --format parquet --output-dir downloaded_data
+python tools/download/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>`.
@@ -238,9 +317,13 @@ Predict when key events happen in long untrimmed sports videos.
 
 ### Action Retrieval
 Search and retrieve relevant clips or moments from a collection of sports videos.
+This is part of the roadmap and OSL data model, not a first-class OpenSportsLib
+training workflow yet.
 
 ### Action Description / Captioning
 Generate text descriptions for sports events and temporal segments.
+This is part of the roadmap and OSL data model, not a first-class OpenSportsLib
+training workflow yet.
 
 ---
 
@@ -260,6 +343,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/
+- 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/
 - Example configs: [examples/configs/](examples/configs/)

{opensportslib-0.1.3.dev1 → opensportslib-0.1.3.dev3}/README.md

@@ -22,6 +22,7 @@ OpenSportsLib is designed for **researchers, ML engineers, and sports analytics
 ## Quick links
 
 - **Documentation:** https://opensportslab.github.io/opensportslib/
+- **OSL JSON format:** https://opensportslab.github.io/opensportslib/data/osl-json-format/
 - **PyPI:** https://pypi.org/project/opensportslib/
 - **Issues:** https://github.com/OpenSportsLab/opensportslib/issues
 
@@ -78,7 +79,85 @@ Use it as the main entry point to find:
 - 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 annotation files use the **OSL JSON v2.0** format. A dataset JSON
+contains top-level metadata, a shared `labels` schema, and a `data` array where
+each sample points to one or more inputs.
+
+Minimal classification sample:
+
+```json
+{
+  "labels": {
+    "action": {
+      "type": "single_label",
+      "labels": ["pass", "shot"]
+    }
+  },
+  "data": [
+    {
+      "id": "clip_0001",
+      "inputs": [
+        {
+          "type": "video",
+          "path": "clips/clip_0001.mp4",
+          "fps": 25.0
+        }
+      ],
+      "labels": {
+        "action": {
+          "label": "shot"
+        }
+      }
+    }
+  ]
+}
+```
+
+Minimal localization sample:
+
+```json
+{
+  "labels": {
+    "action": {
+      "type": "single_label",
+      "labels": ["pass", "shot"]
+    }
+  },
+  "data": [
+    {
+      "id": "game_0001",
+      "inputs": [
+        {
+          "type": "video",
+          "path": "games/game_0001.mp4",
+          "fps": 25.0
+        }
+      ],
+      "events": [
+        {
+          "head": "action",
+          "label": "pass",
+          "position_ms": 1240
+        }
+      ]
+    }
+  ]
+}
+```
+
+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
+[OSL JSON format guide](docs/data/osl-json-format.md) for field definitions,
+multi-modal examples, prediction payloads, and conversion notes.
+
+---
 
 ## Quickstart
 
@@ -96,7 +175,7 @@ from opensportslib.apis import ClassificationModel
 
 my_model = ClassificationModel(
     config="/path/to/classification.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 my_model.train(
@@ -112,7 +191,7 @@ from opensportslib.apis import ClassificationModel
 
 my_model = ClassificationModel(
     config="/path/to/classification.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 predictions = my_model.infer(
@@ -143,7 +222,7 @@ from opensportslib.apis import LocalizationModel
 
 my_model = LocalizationModel(
     config="/path/to/localization.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 predictions = my_model.infer(
@@ -185,8 +264,8 @@ from opensportslib.tools import (
 ### 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
+python tools/download/download_osl_hf.py --repo-id <org/repo> --revision main --split test --format parquet --output-dir downloaded_data
+python tools/download/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>`.
@@ -203,9 +282,13 @@ Predict when key events happen in long untrimmed sports videos.
 
 ### Action Retrieval
 Search and retrieve relevant clips or moments from a collection of sports videos.
+This is part of the roadmap and OSL data model, not a first-class OpenSportsLib
+training workflow yet.
 
 ### Action Description / Captioning
 Generate text descriptions for sports events and temporal segments.
+This is part of the roadmap and OSL data model, not a first-class OpenSportsLib
+training workflow yet.
 
 ---
 
@@ -225,6 +308,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/
+- 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/
 - Example configs: [examples/configs/](examples/configs/)

{opensportslib-0.1.3.dev1 → opensportslib-0.1.3.dev3}/examples/quickstart/basic_classification.py

@@ -9,7 +9,7 @@ def main():
 
     my_model = ClassificationModel(
         config="examples/configs/classification_video.yaml",
-        weights="/path/to/weights.pt",  # optional
+        weights=None,  # optional: path or Hugging Face model ID
     )
 
     my_model.train(

{opensportslib-0.1.3.dev1 → opensportslib-0.1.3.dev3}/examples/quickstart/basic_localization.py

@@ -9,7 +9,7 @@ def main():
 
     my_model = LocalizationModel(
         config="examples/configs/localization.yaml",
-        weights="/path/to/weights.pt",  # optional
+        weights=None,  # optional: path or Hugging Face model ID
     )
 
     my_model.train(

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.1.3.dev1
+Version: 0.1.3.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
@@ -57,6 +57,7 @@ OpenSportsLib is designed for **researchers, ML engineers, and sports analytics
 ## Quick links
 
 - **Documentation:** https://opensportslab.github.io/opensportslib/
+- **OSL JSON format:** https://opensportslab.github.io/opensportslib/data/osl-json-format/
 - **PyPI:** https://pypi.org/project/opensportslib/
 - **Issues:** https://github.com/OpenSportsLab/opensportslib/issues
 
@@ -113,7 +114,85 @@ Use it as the main entry point to find:
 - 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 annotation files use the **OSL JSON v2.0** format. A dataset JSON
+contains top-level metadata, a shared `labels` schema, and a `data` array where
+each sample points to one or more inputs.
+
+Minimal classification sample:
+
+```json
+{
+  "labels": {
+    "action": {
+      "type": "single_label",
+      "labels": ["pass", "shot"]
+    }
+  },
+  "data": [
+    {
+      "id": "clip_0001",
+      "inputs": [
+        {
+          "type": "video",
+          "path": "clips/clip_0001.mp4",
+          "fps": 25.0
+        }
+      ],
+      "labels": {
+        "action": {
+          "label": "shot"
+        }
+      }
+    }
+  ]
+}
+```
+
+Minimal localization sample:
+
+```json
+{
+  "labels": {
+    "action": {
+      "type": "single_label",
+      "labels": ["pass", "shot"]
+    }
+  },
+  "data": [
+    {
+      "id": "game_0001",
+      "inputs": [
+        {
+          "type": "video",
+          "path": "games/game_0001.mp4",
+          "fps": 25.0
+        }
+      ],
+      "events": [
+        {
+          "head": "action",
+          "label": "pass",
+          "position_ms": 1240
+        }
+      ]
+    }
+  ]
+}
+```
+
+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
+[OSL JSON format guide](docs/data/osl-json-format.md) for field definitions,
+multi-modal examples, prediction payloads, and conversion notes.
+
+---
 
 ## Quickstart
 
@@ -131,7 +210,7 @@ from opensportslib.apis import ClassificationModel
 
 my_model = ClassificationModel(
     config="/path/to/classification.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 my_model.train(
@@ -147,7 +226,7 @@ from opensportslib.apis import ClassificationModel
 
 my_model = ClassificationModel(
     config="/path/to/classification.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 predictions = my_model.infer(
@@ -178,7 +257,7 @@ from opensportslib.apis import LocalizationModel
 
 my_model = LocalizationModel(
     config="/path/to/localization.yaml",
-    weights="/path/to/weights.pt",  # optional
+    weights=None,  # optional: path or Hugging Face model ID
 )
 
 predictions = my_model.infer(
@@ -220,8 +299,8 @@ from opensportslib.tools import (
 ### 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
+python tools/download/download_osl_hf.py --repo-id <org/repo> --revision main --split test --format parquet --output-dir downloaded_data
+python tools/download/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>`.
@@ -238,9 +317,13 @@ Predict when key events happen in long untrimmed sports videos.
 
 ### Action Retrieval
 Search and retrieve relevant clips or moments from a collection of sports videos.
+This is part of the roadmap and OSL data model, not a first-class OpenSportsLib
+training workflow yet.
 
 ### Action Description / Captioning
 Generate text descriptions for sports events and temporal segments.
+This is part of the roadmap and OSL data model, not a first-class OpenSportsLib
+training workflow yet.
 
 ---
 
@@ -260,6 +343,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/
+- 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/
 - Example configs: [examples/configs/](examples/configs/)

{opensportslib-0.1.3.dev1 → opensportslib-0.1.3.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opensportslib"
-version = "0.1.3.dev1"
+version = "0.1.3.dev3"
 description = "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."
 readme = "README.md"
 requires-python = ">=3.12"

{opensportslib-0.1.3.dev1 → opensportslib-0.1.3.dev3}/tools/training/classification.py

@@ -7,9 +7,9 @@ def parse_args():
     parser = argparse.ArgumentParser(description="Minimal classification training script.")
     parser.add_argument("--config", required=True, help="Path to the YAML config file.")
     parser.add_argument("--weights", default=None, help="Path to pretrained weights (optional).")
-    parser.add_argument("--train-set", required=True, help="Path to train annotations JSON.")
-    parser.add_argument("--valid-set", required=True, help="Path to validation annotations JSON.")
-    parser.add_argument("--test-set", required=True, help="Path to test annotations JSON.")
+    parser.add_argument("--train-set", default=None, help="Path to train annotations JSON. Defaults to DATA.train.path from the config.")
+    parser.add_argument("--valid-set", default=None, help="Path to validation annotations JSON. Defaults to DATA.valid.path from the config.")
+    parser.add_argument("--test-set", default=None, help="Path to test annotations JSON. Defaults to DATA.test.path from the config.")
     return parser.parse_args()
 
 

{opensportslib-0.1.3.dev1 → opensportslib-0.1.3.dev3}/tools/training/localization.py

@@ -7,9 +7,9 @@ def parse_args():
     parser = argparse.ArgumentParser(description="Minimal localization training script.")
     parser.add_argument("--config", required=True, help="Path to the YAML config file.")
     parser.add_argument("--weights", default=None, help="Path to pretrained weights (optional).")
-    parser.add_argument("--train-set", required=True, help="Path to train annotations JSON.")
-    parser.add_argument("--valid-set", required=True, help="Path to validation annotations JSON.")
-    parser.add_argument("--test-set", required=True, help="Path to test annotations JSON.")
+    parser.add_argument("--train-set", default=None, help="Path to train annotations JSON. Defaults to DATA.train.path from the config.")
+    parser.add_argument("--valid-set", default=None, help="Path to validation annotations JSON. Defaults to DATA.valid.path from the config.")
+    parser.add_argument("--test-set", default=None, help="Path to test annotations JSON. Defaults to DATA.test.path from the config.")
     return parser.parse_args()