opensportslib 0.2.0.dev2__tar.gz → 0.2.0.dev4__tar.gz

{opensportslib-0.2.0.dev2/opensportslib.egg-info → opensportslib-0.2.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.2.0.dev2
+Version: 0.2.0.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
@@ -93,13 +93,26 @@ 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
@@ -287,7 +300,7 @@ metrics_from_file = my_model.evaluate(
 from opensportslib.apis import VQAModel
 
 my_model = VQAModel(
-    config="/path/to/vqa.yaml",
+    config="opensportslib/configs/vqa/qwen.yaml",
     weights=None,  # optional: path or Hugging Face model ID
 )
 
@@ -300,13 +313,20 @@ single_prediction = my_model.infer(
     video_path="/path/to/video.mp4",
     question="What card would you give? Why?",
 )
-
-metrics = my_model.evaluate(
-    test_set="/path/to/test_annotations.json",
-    predictions=predictions,
-)
 ```
 
+Use `opensportslib/configs/vqa/xvars.yaml` with `opensportslib setup --vqa_xvars`
+for the X-VARS-compatible backend, or `opensportslib/configs/vqa/qwen.yaml` with
+`opensportslib setup --vqa_qwen` for the Qwen-compatible backend. The Qwen
+backend currently supports `Qwen/Qwen2.5-7B-Instruct` and
+`Qwen/Qwen3.5-9B-Base`.
+
+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/tools/vqa.md](docs/tools/vqa.md) for the full
+VQA setup workflow.
+
 
 ---
 
@@ -414,6 +434,12 @@ 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
 ```
 
 ### Git workflow

{opensportslib-0.2.0.dev2 → opensportslib-0.2.0.dev4}/README.md

@@ -58,13 +58,26 @@ 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
@@ -252,7 +265,7 @@ metrics_from_file = my_model.evaluate(
 from opensportslib.apis import VQAModel
 
 my_model = VQAModel(
-    config="/path/to/vqa.yaml",
+    config="opensportslib/configs/vqa/qwen.yaml",
     weights=None,  # optional: path or Hugging Face model ID
 )
 
@@ -265,13 +278,20 @@ single_prediction = my_model.infer(
     video_path="/path/to/video.mp4",
     question="What card would you give? Why?",
 )
-
-metrics = my_model.evaluate(
-    test_set="/path/to/test_annotations.json",
-    predictions=predictions,
-)
 ```
 
+Use `opensportslib/configs/vqa/xvars.yaml` with `opensportslib setup --vqa_xvars`
+for the X-VARS-compatible backend, or `opensportslib/configs/vqa/qwen.yaml` with
+`opensportslib setup --vqa_qwen` for the Qwen-compatible backend. The Qwen
+backend currently supports `Qwen/Qwen2.5-7B-Instruct` and
+`Qwen/Qwen3.5-9B-Base`.
+
+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/tools/vqa.md](docs/tools/vqa.md) for the full
+VQA setup workflow.
+
 
 ---
 
@@ -379,6 +399,12 @@ 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
 ```
 
 ### Git workflow

opensportslib-0.2.0.dev4/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.2.0.dev2 → opensportslib-0.2.0.dev4}/opensportslib/cli.py

@@ -11,8 +11,8 @@ def main(argv: Optional[list[str]] = None) -> int:
     parser.add_argument("command", choices=["setup"])
     parser.add_argument("--pyg", action="store_true")
     parser.add_argument("--dali", action="store_true")
-    parser.add_argument("--xvars", action="store_true")
-    parser.add_argument("--qwen", action="store_true")
+    parser.add_argument("--vqa_xvars", action="store_true")
+    parser.add_argument("--vqa_qwen", action="store_true")
 
     args = parser.parse_args(argv)
 
@@ -20,8 +20,8 @@ def main(argv: Optional[list[str]] = None) -> int:
         setup(
             pyg=args.pyg,
             dali=args.dali,
-            xvars=args.xvars,
-            qwen=args.qwen
+            vqa_xvars=args.vqa_xvars,
+            vqa_qwen=args.vqa_qwen
         )
         return 0
 

opensportslib-0.2.0.dev2/opensportslib/configs/vqa/qwen.yaml → opensportslib-0.2.0.dev4/opensportslib/configs/vqa/default.yaml

@@ -1,11 +1,10 @@
-TASK: VQA
+TASK: vqa
 VERSION: 2
 
 SYSTEM:
   paths:
-    log_dir: ./logs
-    save_dir: ./checkpoints_vqa_qwen
-    work_dir: ./checkpoints_vqa_qwen
+    save_dir: ./checkpoints_vqa
+    work_dir: ${SYSTEM.paths.save_dir}
   device: cuda
   gpu:
     count: 1
@@ -90,43 +89,11 @@ MODEL:
     strict: true
     map_location: null
     format: auto
-  components:
-    video_encoder:
-      kind: encoder
-      source:
-        provider: opensportslib
-        name: xvars_clip_features
-      load:
-        weights_path: /home/vorajv/X-VARS/weights/14_model.pth.tar
-      params:
-        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: huggingface
-        # Qwen/Qwen2.5-7B-Instruct or Qwen/Qwen3.5-9B-Base 
-        name: Qwen/Qwen3.5-9B-Base
-      params:
-        # Qwen/Qwen2.5-7B-Instruct or Qwen/Qwen3.5-9B-Base        
-        repo_id: Qwen/Qwen3.5-9B-Base
-      overrides: {}
   topology:
     - from: video_encoder
       to: mm_projector
     - from: mm_projector
       to: llm_decoder
-  metadata:
-    backend: qwen_xvars_infer
 
 IO:
   inputs:
@@ -139,20 +106,15 @@ IO:
 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
@@ -161,28 +123,22 @@ TRAIN:
     acc_grad_iter: 8
     log_interval: 1
     dry_run: false
-
     xvars:
       feature_mode: strict_xvars
       projection_path: null
-
     prompt:
       style: detailed
-      system_prompt: You are a football video assistant. Answer the VQA question using the provided video context and referee priors.
       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
@@ -191,14 +147,6 @@ TRAIN:
       append_eos_token: true
       gradient_checkpointing: true
       save_strategy: epoch
-
-    hf:
-      tokenizer_id: ${MODEL.components.llm_decoder.params.repo_id}
-      prefer_cuda: true
-      local_files_only: false
-      device_map: auto
-      offload_folder: ./hf_offload_qwen
-
     lora:
       r: 16
       alpha: 32
@@ -207,22 +155,18 @@ TRAIN:
       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.2.0.dev4/opensportslib/configs/vqa/qwen.yaml

@@ -0,0 +1,49 @@
+SYSTEM:
+  paths:
+    save_dir: ./checkpoints_vqa_qwen
+
+MODEL:
+  components:
+    video_encoder:
+      kind: encoder
+      source:
+        provider: opensportslib
+        name: xvars_clip_features
+      load:
+        weights_path: /home/vorajv/X-VARS/weights/14_model.pth.tar
+      params:
+        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: huggingface
+        # Supported models: Qwen/Qwen2.5-7B-Instruct or Qwen/Qwen3.5-9B-Base
+        name: Qwen/Qwen3.5-9B-Base
+      params:
+        # Supported models: Qwen/Qwen2.5-7B-Instruct or Qwen/Qwen3.5-9B-Base
+        repo_id: Qwen/Qwen3.5-9B-Base
+      overrides: {}
+  metadata:
+    backend: qwen_xvars_infer
+
+TRAIN:
+  execution:
+    prompt:
+      system_prompt: You are a football video assistant. Answer the VQA question using the provided video context and referee priors.
+
+    hf:
+      tokenizer_id: ${MODEL.components.llm_decoder.params.repo_id}
+      prefer_cuda: true
+      local_files_only: false
+      device_map: auto
+      offload_folder: ./hf_offload_qwen

opensportslib-0.2.0.dev4/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.dev2 → opensportslib-0.2.0.dev4}/opensportslib/core/config/loader.py

@@ -18,7 +18,7 @@ from .migrate import migrate_config
 from .runtime_adapter import maybe_namespace, namespace_to_plain_dict
 
 _YAML_SUFFIXES = {".yaml", ".yml"}
-_TASK_DIRS = {"classification", "localization"}
+_TASK_DIRS = {"classification", "localization", "vqa"}
 _INTERPOLATION_RE = re.compile(r"\$\{([^}]+)\}")
 
 

{opensportslib-0.2.0.dev2 → opensportslib-0.2.0.dev4}/opensportslib/setup/setup.py

@@ -183,12 +183,12 @@ def verify():
     else:
         print("Running on CPU")
 
-def setup(dali=False, pyg=False, xvars=False, qwen=False):
+def setup(dali=False, pyg=False, vqa_xvars=False, vqa_qwen=False):
     install_torch()
     install_extras(dali=dali, pyg=pyg)
-    if xvars:
+    if vqa_xvars:
         install_xvars_dependencies(XVARS_DEPENDENCY_PINS)
-    if qwen:
+    if vqa_qwen:
         install_xvars_dependencies(QWEN_DEPENDENCY_PINS)
     verify()
 
@@ -202,9 +202,9 @@ if __name__ == "__main__":
     parser = argparse.ArgumentParser()
     parser.add_argument("--dali", action="store_true")
     parser.add_argument("--pyg", action="store_true")
-    parser.add_argument("--xvars", action="store_true")
-    parser.add_argument("--qwen", action="store_true")
+    parser.add_argument("--vqa_xvars", action="store_true")
+    parser.add_argument("--vqa_qwen", action="store_true")
 
     args = parser.parse_args()
 
-    setup(dali=args.dali, pyg=args.pyg, xvars=args.xvars, qwen=args.qwen)
+    setup(dali=args.dali, pyg=args.pyg, vqa_xvars=args.vqa_xvars, vqa_qwen=args.vqa_qwen)

{opensportslib-0.2.0.dev2 → opensportslib-0.2.0.dev4/opensportslib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.2.0.dev2
+Version: 0.2.0.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
@@ -93,13 +93,26 @@ 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
@@ -287,7 +300,7 @@ metrics_from_file = my_model.evaluate(
 from opensportslib.apis import VQAModel
 
 my_model = VQAModel(
-    config="/path/to/vqa.yaml",
+    config="opensportslib/configs/vqa/qwen.yaml",
     weights=None,  # optional: path or Hugging Face model ID
 )
 
@@ -300,13 +313,20 @@ single_prediction = my_model.infer(
     video_path="/path/to/video.mp4",
     question="What card would you give? Why?",
 )
-
-metrics = my_model.evaluate(
-    test_set="/path/to/test_annotations.json",
-    predictions=predictions,
-)
 ```
 
+Use `opensportslib/configs/vqa/xvars.yaml` with `opensportslib setup --vqa_xvars`
+for the X-VARS-compatible backend, or `opensportslib/configs/vqa/qwen.yaml` with
+`opensportslib setup --vqa_qwen` for the Qwen-compatible backend. The Qwen
+backend currently supports `Qwen/Qwen2.5-7B-Instruct` and
+`Qwen/Qwen3.5-9B-Base`.
+
+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/tools/vqa.md](docs/tools/vqa.md) for the full
+VQA setup workflow.
+
 
 ---
 
@@ -414,6 +434,12 @@ 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
 ```
 
 ### Git workflow

{opensportslib-0.2.0.dev2 → opensportslib-0.2.0.dev4}/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,8 +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_lora.yaml
+opensportslib/configs/vqa/xvars.yaml
 opensportslib/core/__init__.py
 opensportslib/core/config/__init__.py
 opensportslib/core/config/accessors.py
@@ -136,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.dev2 → opensportslib-0.2.0.dev4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opensportslib"
-version = "0.2.0.dev2"
+version = "0.2.0.dev4"
 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"