opensportslib 0.2.0.dev3__tar.gz → 0.3.0__tar.gz

{opensportslib-0.2.0.dev3/opensportslib.egg-info → opensportslib-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.2.0.dev3
+Version: 0.3.0
 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
@@ -324,8 +324,8 @@ backend currently supports `Qwen/Qwen2.5-7B-Instruct` and
 For X-VARS, `feature_source: indexed_or_raw_clip` prefers indexed CLIP features
 when available and falls back to extracting CLIP features from raw video during
 `infer()`. Pre-extracted features remain the preferred path for parity, speed,
-and reproducibility. See [docs/xvars_integration_phases.md](docs/xvars_integration_phases.md)
-for the full X-VARS setup workflow.
+and reproducibility. See [docs/tools/vqa.md](docs/tools/vqa.md) for the full
+VQA setup workflow.
 
 
 ---

{opensportslib-0.2.0.dev3 → opensportslib-0.3.0}/README.md

@@ -289,8 +289,8 @@ backend currently supports `Qwen/Qwen2.5-7B-Instruct` and
 For X-VARS, `feature_source: indexed_or_raw_clip` prefers indexed CLIP features
 when available and falls back to extracting CLIP features from raw video during
 `infer()`. Pre-extracted features remain the preferred path for parity, speed,
-and reproducibility. See [docs/xvars_integration_phases.md](docs/xvars_integration_phases.md)
-for the full X-VARS setup workflow.
+and reproducibility. See [docs/tools/vqa.md](docs/tools/vqa.md) for the full
+VQA setup workflow.
 
 
 ---

opensportslib-0.3.0/examples/quickstart/basic_vqa.py

@@ -0,0 +1,37 @@
+from opensportslib.apis import VQAModel
+
+
+def main():
+    """
+    Minimal VQA example.
+    Update config, question, and dataset paths before running.
+    """
+
+    my_model = VQAModel(
+        config="examples/configs/vqa_qwen.yaml",
+        weights=None,  # optional: path or Hugging Face model ID
+    )
+
+    predictions = my_model.infer(
+        test_set="/path/to/test_annotations.json",
+    )
+
+    print(predictions)
+
+    single_prediction = my_model.infer(
+        video_path="/path/to/video.mp4",
+        question="What card would you give? Why?",
+    )
+
+    print(single_prediction)
+
+    metrics = my_model.evaluate(
+        test_set="/path/to/test_annotations.json",
+        predictions=predictions,
+    )
+
+    print(metrics)
+
+
+if __name__ == "__main__":
+    main()

opensportslib-0.3.0/opensportslib/configs/vqa/default.yaml

@@ -0,0 +1,172 @@
+TASK: vqa
+VERSION: 2
+
+SYSTEM:
+  paths:
+    save_dir: ./checkpoints_vqa
+    work_dir: ${SYSTEM.paths.save_dir}
+  device: cuda
+  gpu:
+    count: 1
+    id: 0
+  reproducibility:
+    use_seed: true
+    seed: 42
+
+DATA:
+  common:
+    dataset_name: OSL-XFoul
+    data_root: /home/vorajv/dataset/OSL-XFoul
+    feature_index: /home/vorajv/dataset/OSL-XFoul/feature_index.json
+    prediction_index: /home/vorajv/dataset/OSL-XFoul/prediction_index.json
+    runtime:
+      loader_backend: opencv
+    splits:
+      train:
+        annotation_path: /home/vorajv/dataset/OSL-XFoul/train.json
+        source_path: /home/vorajv/dataset/OSL-XFoul
+        dataloader:
+          batch_size: 1
+          shuffle: true
+          num_workers: 0
+          pin_memory: false
+          mp_context: spawn
+          persistent_workers: false
+      valid:
+        annotation_path: /home/vorajv/dataset/OSL-XFoul/valid.json
+        source_path: /home/vorajv/dataset/OSL-XFoul
+        dataloader:
+          batch_size: 1
+          shuffle: false
+          num_workers: 0
+          pin_memory: false
+          mp_context: spawn
+          persistent_workers: false
+      test:
+        annotation_path: /home/vorajv/dataset/OSL-XFoul/test.json
+        source_path: /home/vorajv/dataset/OSL-XFoul
+        dataloader:
+          batch_size: 1
+          shuffle: false
+          num_workers: 0
+          pin_memory: false
+          mp_context: spawn
+          persistent_workers: false
+  inputs:
+    video:
+      modality: video
+      representation: raw
+      source:
+        format: mp4
+      sampling:
+        num_frames: 100
+        input_fps: 25
+        target_fps: 17
+        start_frame: 63
+        end_frame: 87
+      transform: {}
+      augmentations: {}
+      params: {}
+    question:
+      modality: text
+      representation: raw
+      source:
+        format: json
+      sampling: {}
+      transform: {}
+      augmentations: {}
+      params: {}
+
+MODEL:
+  runtime:
+    dtype: fp16
+    device: auto
+    compile: false
+    freeze: false
+  load:
+    checkpoint_path: null
+    pretrained: false
+    strict: true
+    map_location: null
+    format: auto
+  topology:
+    - from: video_encoder
+      to: mm_projector
+    - from: mm_projector
+      to: llm_decoder
+
+IO:
+  inputs:
+    video: video_encoder
+    question: llm_decoder
+  outputs:
+    answer_text: llm_decoder
+    explanation_text: llm_decoder
+
+TRAIN:
+  trainer:
+    type: vqa
+  epochs: 3
+  criterion:
+    type: CrossEntropyLoss
+  optimizer:
+    type: AdamW
+    lr: 0.0002
+    weight_decay: 0.001
+  scheduler:
+    type: constant
+  execution:
+    enabled: true
+    training_backend: xvars_videochatgpt_lora
+    feature_backend: xvars_clip
+    view_sampling_policy: random_train_deterministic_eval
+    acc_grad_iter: 8
+    log_interval: 1
+    dry_run: false
+    xvars:
+      feature_mode: strict_xvars
+      projection_path: null
+    prompt:
+      style: detailed
+      include_priors: true
+      prediction_prior_adapter: xvars_referee
+      prior_fields: [action, offence, contact, bodypart]
+      video_token_len: 300
+    generation:
+      max_new_tokens: 128
+      temperature: 0.0
+    eval_profile:
+      metric_set: [exact_match, contains_match, token_f1, referee_semantic]
+      aggregation: mean
+      exclusions: []
+    sft:
+      max_seq_length: 480
+      include_video_tokens: true
+      disable_tqdm: false
+      reference_mode: all
+      append_eos_token: true
+      gradient_checkpointing: true
+      save_strategy: epoch
+    lora:
+      r: 16
+      alpha: 32
+      dropout: 0.05
+      bias: none
+      prepare_kbit: true
+      target_modules: [mm_projector, upsample_features, up_proj, down_proj, gate_proj, k_proj, q_proj, v_proj, o_proj]
+      exclude_modules: '^base_lm\.model\.mm_projector$'
+    quantization:
+      enabled: false
+      load_in_4bit: true
+      bnb_4bit_quant_type: nf4
+      compute_dtype: float16
+      bnb_4bit_use_double_quant: true
+    checkpoint:
+      save_adapter: true
+      merge_and_save: false
+  selection:
+    monitor: loss
+    mode: min
+  checkpoint:
+    save_every: 1
+    save_best: true

opensportslib-0.3.0/opensportslib/configs/vqa/xvars.yaml

@@ -0,0 +1,58 @@
+SYSTEM:
+  paths:
+    save_dir: ./checkpoints_vqa_lora
+  gpu:
+    count: 4
+
+MODEL:
+  components:
+    video_encoder:
+      kind: encoder
+      source:
+        provider: opensportslib
+      # XVARS-trained classifier weights to load into that architecture
+      load:
+        weights_path: /home/vorajv/X-VARS/weights/14_model.pth.tar
+      params:
+        # CLIP architecture and image processor to instantiate.
+        feature_source: indexed_or_raw_clip
+        vision_tower: openai/clip-vit-large-patch14
+        feature_dim: 1024
+      overrides: {}
+    mm_projector:
+      kind: projector
+      source:
+        provider: opensportslib
+      params:
+        input_dim: 1024
+      overrides: {}
+    llm_decoder:
+      kind: decoder
+      source:
+        provider: opensportslib
+      params:
+        repo_id: /home/vorajv/X-VARS/weights/base_model_videoChatGPT
+      overrides: {}
+  metadata:
+    backend: xvars_videochatgpt
+
+TRAIN:
+  execution:
+    prompt:
+      system_prompt: You are Video-ChatGPT, a large vision-language assistant. You are able to understand the video content that the user provides, and assist the user with a variety of tasks using natural language.Follow the instructions carefully and explain your answers in detail based on the provided video.
+
+    # Optional XFoul-only generated-answer smoke test.
+    # During LoRA training, this runs generation on one known training sample and
+    # checks that the answer still contains referee-domain terms and avoids known
+    # code-like failure strings. Disable or replace these values for non-XFoul data.
+    generated_validation:
+      enabled: true
+      sample_id: action_0
+      every_steps: 25
+      max_new_tokens: 128
+      require_relevance: true
+      required_terms: [foul, card, challenge, spa, dogso, advantage]
+      forbidden_terms: [get_children, django, httpclient, "```python", "```php"]
+    
+    hf:
+      tokenizer_id: ${MODEL.components.llm_decoder.params.repo_id}

{opensportslib-0.2.0.dev3 → opensportslib-0.3.0/opensportslib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.2.0.dev3
+Version: 0.3.0
 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
@@ -324,8 +324,8 @@ backend currently supports `Qwen/Qwen2.5-7B-Instruct` and
 For X-VARS, `feature_source: indexed_or_raw_clip` prefers indexed CLIP features
 when available and falls back to extracting CLIP features from raw video during
 `infer()`. Pre-extracted features remain the preferred path for parity, speed,
-and reproducibility. See [docs/xvars_integration_phases.md](docs/xvars_integration_phases.md)
-for the full X-VARS setup workflow.
+and reproducibility. See [docs/tools/vqa.md](docs/tools/vqa.md) for the full
+VQA setup workflow.
 
 
 ---

{opensportslib-0.2.0.dev3 → opensportslib-0.3.0}/opensportslib.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ README.md
 pyproject.toml
 examples/quickstart/basic_classification.py
 examples/quickstart/basic_localization.py
+examples/quickstart/basic_vqa.py
 opensportslib/__init__.py
 opensportslib/cli.py
 opensportslib.egg-info/PKG-INFO
@@ -28,7 +29,9 @@ opensportslib/configs/localization/default.yaml
 opensportslib/configs/localization/netvladpp_resnetpca512.yaml
 opensportslib/configs/localization/video_dali.yaml
 opensportslib/configs/localization/video_ocv.yaml
+opensportslib/configs/vqa/default.yaml
 opensportslib/configs/vqa/qwen.yaml
+opensportslib/configs/vqa/xvars.yaml
 opensportslib/core/__init__.py
 opensportslib/core/config/__init__.py
 opensportslib/core/config/accessors.py
@@ -135,9 +138,12 @@ tests/test_localization_dali_filenames.py
 tests/test_package_smoke.py
 tests/test_pretrained_config_merge_policy.py
 tests/test_public_apis_smoke.py
+tests/test_setup_cli.py
 tests/test_subset_train_infer_integration.py
 tests/test_task_model_api_contract.py
+tests/test_vqa_api.py
 tests/test_vqa_metrics_semantic.py
+tests/test_vqa_qwen_xvars.py
 tests/test_vqa_training_lora.py
 tests/test_vqa_xvars_videochatgpt.py
 tools/convert/build_soccernet_gar.py

{opensportslib-0.2.0.dev3 → opensportslib-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opensportslib"
-version = "0.2.0.dev3"
+version = "0.3.0"
 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.3.0/tests/test_setup_cli.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from opensportslib import cli
+from opensportslib.setup import setup as setup_lib
+
+
+def test_cli_setup_forwards_xvars_flag(monkeypatch):
+    captured: dict[str, object] = {}
+
+    def fake_setup(*, dali: bool, pyg: bool, vqa_xvars: bool, vqa_qwen: bool):
+        captured["dali"] = dali
+        captured["pyg"] = pyg
+        captured["vqa_xvars"] = vqa_xvars
+        captured["vqa_qwen"] = vqa_qwen
+
+    monkeypatch.setattr(cli, "setup", fake_setup)
+
+    rc = cli.main(["setup", "--vqa_xvars", "--dali"])
+
+    assert rc == 0
+    assert captured == {"dali": True, "pyg": False, "vqa_xvars": True, "vqa_qwen": False}
+
+
+def test_cli_setup_forwards_qwen_flag(monkeypatch):
+    captured: dict[str, object] = {}
+
+    def fake_setup(*, dali: bool, pyg: bool, vqa_xvars: bool, vqa_qwen: bool):
+        captured["dali"] = dali
+        captured["pyg"] = pyg
+        captured["vqa_xvars"] = vqa_xvars
+        captured["vqa_qwen"] = vqa_qwen
+
+    monkeypatch.setattr(cli, "setup", fake_setup)
+
+    rc = cli.main(["setup", "--vqa_qwen", "--pyg"])
+
+    assert rc == 0
+    assert captured == {"dali": False, "pyg": True, "vqa_xvars": False, "vqa_qwen": True}
+
+
+def test_install_xvars_dependencies_uninstalls_then_reinstalls(monkeypatch):
+    calls: list[tuple[str, list[str]]] = []
+
+    def fake_call(cmd: list[str]):
+        calls.append(("call", cmd))
+        return 0
+
+    def fake_check_call(cmd: list[str]):
+        calls.append(("check_call", cmd))
+        return 0
+
+    monkeypatch.setattr(setup_lib.subprocess, "call", fake_call)
+    monkeypatch.setattr(setup_lib.subprocess, "check_call", fake_check_call)
+    monkeypatch.setattr(setup_lib.sys, "executable", "/usr/bin/python3")
+
+    setup_lib.install_xvars_dependencies(setup_lib.XVARS_DEPENDENCY_PINS)
+
+    assert calls == [
+        (
+            "call",
+            [
+                "/usr/bin/python3",
+                "-m",
+                "pip",
+                "uninstall",
+                "-y",
+                "transformers",
+                "peft",
+                "tokenizers",
+                "accelerate",
+                "trl",
+            ],
+        ),
+        (
+            "check_call",
+            [
+                "/usr/bin/python3",
+                "-m",
+                "pip",
+                "install",
+                "transformers==4.38.2",
+                "peft==0.9.0",
+                "tokenizers==0.15.2",
+                "accelerate==0.27.2",
+                "trl==0.10.1",
+            ],
+        ),
+    ]
+
+
+def test_setup_skips_vqa_dependency_install_when_flags_are_false(monkeypatch):
+    calls: list[str] = []
+
+    monkeypatch.setattr(setup_lib, "install_extras", lambda dali=False, pyg=False: calls.append(f"extras:{dali}:{pyg}"))
+    monkeypatch.setattr(setup_lib, "install_xvars_dependencies", lambda pins: calls.append(f"deps:{sorted(pins)}"))
+    monkeypatch.setattr(setup_lib, "verify", lambda: calls.append("verify"))
+    monkeypatch.setattr(setup_lib, "install_torch", lambda: calls.append("torch"))
+
+    setup_lib.setup(dali=True, pyg=False, vqa_xvars=False, vqa_qwen=False)
+
+    assert calls == ["torch", "extras:True:False", "verify"]