opensportslib 0.2.0.dev2__py3-none-any.whl → 0.2.0.dev4__py3-none-any.whl

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/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/configs/vqa/{xvars_lora.yaml → default.yaml}

@@ -1,14 +1,13 @@
-TASK: VQA
+TASK: vqa
 VERSION: 2
 
 SYSTEM:
   paths:
-    log_dir: ./logs
-    save_dir: ./checkpoints_vqa_lora
-    work_dir: ./checkpoints_vqa_lora
+    save_dir: ./checkpoints_vqa
+    work_dir: ${SYSTEM.paths.save_dir}
   device: cuda
   gpu:
-    count: 4
+    count: 1
     id: 0
   reproducibility:
     use_seed: true
@@ -90,41 +89,11 @@ MODEL:
     strict: true
     map_location: null
     format: auto
-  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: {}
   topology:
     - from: video_encoder
       to: mm_projector
     - from: mm_projector
       to: llm_decoder
-  metadata:
-    backend: xvars_videochatgpt
 
 IO:
   inputs:
@@ -137,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
@@ -159,45 +123,22 @@ TRAIN:
     acc_grad_iter: 8
     log_interval: 1
     dry_run: false
-
     xvars:
       feature_mode: strict_xvars
-      # Optional: path to a separate mm_projector checkpoint.
-      # null means use the projector already embedded in base_model_videoChatGPT.
       projection_path: null
-
     prompt:
       style: detailed
-      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.
       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
-
-    # 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"]
-    
-    # OpenSportsLib-native VQA evaluation config. This does not correspond to
-    # an upstream X-VARS benchmark scorer.
     eval_profile:
       metric_set: [exact_match, contains_match, token_f1, referee_semantic]
       aggregation: mean
       exclusions: []
-
     sft:
       max_seq_length: 480
       include_video_tokens: true
@@ -205,11 +146,7 @@ TRAIN:
       reference_mode: all
       append_eos_token: true
       gradient_checkpointing: true
-      save_strategy: "epoch"
-
-    hf:
-      tokenizer_id: ${MODEL.components.llm_decoder.params.repo_id}
-
+      save_strategy: epoch
     lora:
       r: 16
       alpha: 32
@@ -218,26 +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
-
-    # LoRA adapter save policy:
-    # save_adapter: true saves the LoRA adapter artifacts.
-    # merge_and_save: false keeps the base model and adapter separate.
-    # If you set merge_and_save: true, it would export a merged model for standalone inference.
     checkpoint:
       save_adapter: true
       merge_and_save: false
-
   selection:
     monitor: loss
     mode: min
-
   checkpoint:
     save_every: 1
     save_best: true

opensportslib/configs/vqa/qwen.yaml

@@ -1,95 +1,8 @@
-TASK: VQA
-VERSION: 2
-
 SYSTEM:
   paths:
-    log_dir: ./logs
     save_dir: ./checkpoints_vqa_qwen
-    work_dir: ./checkpoints_vqa_qwen
-  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
   components:
     video_encoder:
       kind: encoder
@@ -114,83 +27,19 @@ MODEL:
       kind: decoder
       source:
         provider: huggingface
-        # Qwen/Qwen2.5-7B-Instruct or Qwen/Qwen3.5-9B-Base 
+        # Supported models: 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        
+        # Supported models: 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:
-    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
       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
-      disable_tqdm: false
-      reference_mode: all
-      append_eos_token: true
-      gradient_checkpointing: true
-      save_strategy: epoch
 
     hf:
       tokenizer_id: ${MODEL.components.llm_decoder.params.repo_id}
@@ -198,31 +47,3 @@ TRAIN:
       local_files_only: false
       device_map: auto
       offload_folder: ./hf_offload_qwen
-
-    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/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/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/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.dist-info → opensportslib-0.2.0.dev4.dist-info}/METADATA

@@ -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