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

opensportslib/apis/__init__.py

@@ -1,6 +1,7 @@
 # opensportslib/apis/__init__.py
 
 # Import task APIs
+from opensportslib.apis.config import Config
 from opensportslib.apis.base_task_model import BaseTaskModel
 from opensportslib.apis.classification import ClassificationModel
 from opensportslib.apis.localization import LocalizationModel
@@ -10,6 +11,7 @@ warnings.filterwarnings("ignore")
 
 # Expose only these
 __all__ = [
+    "Config",
     "BaseTaskModel",
     "ClassificationModel",
     "LocalizationModel",

opensportslib/apis/base_task_model.py

@@ -16,10 +16,12 @@ from typing import Any
 from urllib import error as urlerror
 from urllib import request as urlrequest
 
+from opensportslib.apis.configuration import ConfigurationMixin
 from opensportslib.core.config.accessors import get_component_name_by_kind
+from opensportslib.core.config.editable import Config
+from opensportslib.core.config.runtime_adapter import dict_to_namespace
 from opensportslib.core.utils.config import (
     expand,
-    load_config_omega,
     fetch_and_merge_config_from_HF,
     resolve_config_path,
     resolve_inference_class_metadata,
@@ -55,8 +57,7 @@ def _manifest_media_references(payload: dict[str, Any]):
                     if isinstance(value, str):
                         yield value, lambda replacement, values=values, index=index: values.__setitem__(index, replacement)
 
-
-class BaseTaskModel(ABC):
+class BaseTaskModel(ConfigurationMixin, ABC):
     """Thin shared contract for task-level OpenSportsLib wrappers."""
 
     def __init__(
@@ -78,11 +79,38 @@ class BaseTaskModel(ABC):
         if self.remote_timeout <= 0 or self.remote_poll_interval <= 0 or self.remote_result_timeout <= 0:
             raise ValueError("Remote timeout values must be positive.")
 
-        if config is None:
-            raise ValueError("config path is required")
+        self._config_editor = copy.deepcopy(config) if isinstance(config, Config) else None
+        if self._config_editor is not None:
+            weights = weights if weights is not None else self._config_editor.weights
+            config = self._config_editor.source
+            if self.is_remote:
+                self._config_editor.remote_overrides()
+
+        if config is None and self._config_editor is None:
+            from huggingface_hub.utils import HFValidationError, validate_repo_id
 
-        self.config_path = resolve_config_path(config)
-        self.config = load_config_omega(self.config_path)
+            if (not isinstance(weights, str) or os.path.exists(expand(weights))
+                    or weights.endswith((".pt", ".pth", ".tar"))):
+                raise ValueError("config path is required unless weights is a Hugging Face model ID")
+            try:
+                validate_repo_id(weights)
+            except HFValidationError as exc:
+                raise ValueError("config path is required unless weights is a Hugging Face model ID") from exc
+            try:
+                config = resolve_config_path(weights)
+            except Exception as exc:
+                raise ValueError(
+                    f"Could not load OpenSportsLib config.yaml from {weights!r}; "
+                    "provide config explicitly or publish a compatible config.yaml."
+                ) from exc
+
+        if self._config_editor is not None:
+            self.config_path = self._config_editor.source
+            self.config = dict_to_namespace(self._config_editor.get_config())
+        else:
+            self.config_path = resolve_config_path(config)
+            self._config_editor = Config.from_file(self.config_path)
+            self.config = dict_to_namespace(self._config_editor.get_config())
         self.last_loaded_weights = None
         self.best_checkpoint = None
 
@@ -96,6 +124,7 @@ class BaseTaskModel(ABC):
             self.last_loaded_weights = weights
             self.best_checkpoint = weights
 
+        self.config = self._effective_config(self.config)
         self.train_flag = False  # Flag to indicate whether we're in training mode (affects checkpoint loading behavior)
 
         data_cfg = getattr(self.config, "DATA", None)
@@ -253,7 +282,7 @@ class BaseTaskModel(ABC):
         model_id: str | None = None,
         task_options: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        """Submit a single uploaded video, primarily for direct VQA inference."""
+        """Submit one video for direct task inference."""
 
         if not self.remote:
             raise RuntimeError("Remote inference is not configured. Pass `remote=` to the model constructor.")
@@ -405,6 +434,8 @@ class BaseTaskModel(ABC):
         return self._open_request(request)
 
     def _post_multipart(self, endpoint: str, *, fields: dict[str, str], files: dict[str, Path]) -> dict[str, Any]:
+        if endpoint == "/predict":
+            fields = self._config_request_fields(fields)
         boundary = f"----OpenSportsLib{uuid.uuid4().hex}"
         chunks: list[bytes] = []
         for name, value in fields.items():

opensportslib/apis/classification.py

@@ -7,6 +7,7 @@ import os
 import json
 
 from opensportslib.apis.base_task_model import BaseTaskModel
+from opensportslib.apis.configuration import config_operation
 from opensportslib.core.config.accessors import (
     get_component_provider_by_kind,
     get_data_modality,
@@ -180,6 +181,7 @@ class ClassificationModel(BaseTaskModel):
     # public training interface
     # -----------------------------------------------------------------
 
+    @config_operation
     def train(
         self,
         train_set=None,
@@ -200,7 +202,7 @@ class ClassificationModel(BaseTaskModel):
         train_set = self._resolve_split_path("train", train_set)
         valid_set = self._resolve_split_path("valid", valid_set)
         
-        self.config = resolve_config_omega(self.config, weights=weights)
+        self.config = self._effective_config(resolve_config_omega(self.config, weights=weights))
         logging.info("Configuration:")
         logging.info(self.config)
 
@@ -251,15 +253,19 @@ class ClassificationModel(BaseTaskModel):
         self.last_loaded_weights = self.best_checkpoint
         return self.best_checkpoint
 
+    @config_operation
     def infer(
         self,
         test_set=None,
         weights=None,
         use_ddp=False,
         use_wandb=True,
+        video_path: str | None = None,
         **kwargs,
     ):
         """Run model inference and return predictions in OSL JSON format."""
+        if test_set is not None and video_path is not None:
+            raise ValueError("Provide either `test_set` or `video_path`, not both.")
         remote_mode_provided = "remote_mode" in kwargs
         remote_mode = kwargs.pop("remote_mode", "full_test_set")
         if self.is_remote:
@@ -267,6 +273,17 @@ class ClassificationModel(BaseTaskModel):
             remote_task_options = kwargs.pop("remote_task_options", None)
             if kwargs:
                 raise TypeError(f"Unsupported remote inference options: {', '.join(kwargs)}")
+            if video_path is not None:
+                if remote_mode != "full_test_set":
+                    raise ValueError("`remote_mode=per_sample` requires `test_set`, not direct video input.")
+                job = self.submit_video_inference(
+                    task_type="classification",
+                    video_path=video_path,
+                    model_id=remote_model_id,
+                    task_options=remote_task_options,
+                )
+                self.last_remote_failures = []
+                return self.wait_for_remote_result(job["job_id"])["result"]["predictions"]
             test_set = self._resolve_split_path("test", test_set)
             if remote_mode == "per_sample":
                 batch = self.submit_per_sample_inference(
@@ -294,13 +311,27 @@ class ClassificationModel(BaseTaskModel):
             raise ValueError("`remote_mode` is available only when `remote` is configured.")
         del kwargs
 
+        if video_path is not None:
+            from opensportslib.core.utils.direct_video import direct_video_manifest
+            from opensportslib.core.utils.config import resolve_config_omega
+
+            manifest_config = self._effective_config(resolve_config_omega(self.config, weights=weights))
+            manifest_config = resolve_inference_class_metadata(manifest_config)
+            with direct_video_manifest(manifest_config, video_path, "classification") as manifest:
+                return self.infer(
+                    test_set=manifest,
+                    weights=weights,
+                    use_ddp=use_ddp,
+                    use_wandb=use_wandb,
+                )
+
         import torch
         import torch.multiprocessing as mp
         from opensportslib.core.utils.config import resolve_config_omega
 
         test_set = self._resolve_split_path("test", test_set)
 
-        self.config = resolve_config_omega(self.config, weights=weights)
+        self.config = self._effective_config(resolve_config_omega(self.config, weights=weights))
         self.config = resolve_inference_class_metadata(self.config)
         logging.info("Configuration:")
         logging.info(self.config)
@@ -349,6 +380,7 @@ class ClassificationModel(BaseTaskModel):
                 predictions = json.load(f)
         return predictions
 
+    @config_operation
     def evaluate(
         self,
         test_set=None,
@@ -367,7 +399,7 @@ class ClassificationModel(BaseTaskModel):
 
         test_set = self._resolve_split_path("test", test_set)
 
-        self.config = resolve_config_omega(self.config, weights=weights)
+        self.config = self._effective_config(resolve_config_omega(self.config, weights=weights))
         self.config = resolve_inference_class_metadata(self.config)
         logging.info("Configuration:")
         logging.info(self.config)

opensportslib/apis/config.py

@@ -0,0 +1,5 @@
+"""Public configuration API."""
+
+from opensportslib.core.config.editable import Config
+
+__all__ = ["Config"]

opensportslib/apis/configuration.py

@@ -0,0 +1,145 @@
+"""Configuration lifecycle shared by task wrappers."""
+
+from copy import deepcopy
+from functools import wraps
+import inspect
+import os
+import json
+from threading import RLock
+from urllib.parse import urlencode
+from urllib.request import Request
+
+from opensportslib.core.config.editable import Config, _get, _set
+from opensportslib.core.config.runtime_adapter import dict_to_namespace, namespace_to_plain_dict
+
+
+def config_operation(method):
+    """Serialize operations and prevent edits while an operation is active."""
+    @wraps(method)
+    def wrapped(self, *args, **kwargs):
+        lock = self.__dict__.setdefault("_config_lock", RLock())
+        with lock:
+            depth = getattr(self, "_operation_depth", 0)
+            self._operation_depth = depth + 1
+            before = namespace_to_plain_dict(self.config)
+            previous_inputs = getattr(self, "_call_config_inputs", {})
+            bound = inspect.signature(method).bind(self, *args, **kwargs)
+            self._call_config_inputs = {**previous_inputs, **{
+                name.removesuffix("_set"): os.path.abspath(os.path.expanduser(str(value)))
+                for name, value in bound.arguments.items()
+                if name in {"train_set", "valid_set", "test_set"} and value is not None
+            }}
+            try:
+                if method.__name__ == "train" and self.is_remote:
+                    raise ValueError("Remote training is not supported")
+                return method(self, *args, **kwargs)
+            finally:
+                self._operation_depth = depth
+                self._call_config_inputs = previous_inputs
+                if depth == 0:
+                    # Local localization helpers write temporary input paths into
+                    # config. Restore only those defaults, preserving model state.
+                    current = namespace_to_plain_dict(self.config)
+                    for split, cfg in _get(before, "DATA.common.splits", {}).items():
+                        for key in ("annotation_path", "source_path"):
+                            if key in cfg:
+                                _set(current, f"DATA.common.splits.{split}.{key}", cfg[key])
+                    self.config = dict_to_namespace(current)
+                    self._refresh_config_references()
+    return wrapped
+
+
+class ConfigurationMixin:
+    def _effective_config(self, config):
+        editor = getattr(self, "_config_editor", None)
+        result = dict_to_namespace(editor.apply_to(config)) if editor is not None else config
+        if getattr(self, "_call_config_inputs", None):
+            doc = namespace_to_plain_dict(result)
+            for split, path in self._call_config_inputs.items():
+                _set(doc, f"DATA.common.splits.{split}.annotation_path", path)
+                if split == "valid" and _get(doc, "DATA.common.splits.valid_data_frames"):
+                    _set(doc, "DATA.common.splits.valid_data_frames.annotation_path", path)
+            result = dict_to_namespace(doc)
+        return result
+
+    def _refresh_config_references(self):
+        for owner in (getattr(self, "model", None), getattr(self, "trainer", None)):
+            if owner is None:
+                continue
+            for key in ("config", "cfg", "cfg_model"):
+                if hasattr(owner, key):
+                    setattr(owner, key, self.config)
+
+    def get_config(self):
+        return deepcopy(namespace_to_plain_dict(self.config))
+
+    def config_options(self):
+        editor = deepcopy(getattr(self, "_config_editor", None)) or Config(self.get_config(), source=self.config_path)
+        # Inspection reflects normalization and runtime-selected checkpoint data.
+        editor._document = self.get_config()
+        return editor.options()
+
+    def update_config(self, **options):
+        lock = self.__dict__.setdefault("_config_lock", RLock())
+        if not lock.acquire(blocking=False):
+            raise RuntimeError("Cannot update configuration during an active operation")
+        try:
+            if getattr(self, "_operation_depth", 0):
+                raise RuntimeError("Cannot update configuration during an active operation")
+            original = getattr(self, "_config_editor", None)
+            editor = deepcopy(original) if original is not None else Config(self.get_config(), source=self.config_path)
+            # Carry current runtime values while retaining expressions and prior
+            # explicit updates from the editable source.
+            current = self.get_config()
+            editor._document = editor.apply_to(current)
+            if original is not None:
+                from opensportslib.core.config.editable import _leaves
+                for path, value in _leaves(original._document):
+                    if isinstance(value, str) and "${" in value:
+                        _set(editor._document, path, value)
+            previous = deepcopy(editor._updates)
+            editor.update(**options)
+            safe = []
+            for name, spec in editor._registry().items():
+                if not spec.requires_initialization and name.split(".")[0] in {"data", "training", "inference", "runtime", "scheduler", "training_sampling", "sft", "prompt"}:
+                    safe.extend(spec.paths)
+            changed = [p for p, value in editor._updates.items() if p not in previous or previous[p] != value]
+            for path in changed:
+                if not any(path == p for p in safe):
+                    raise ValueError(f"{path} requires a new model; update Config before initialization")
+            if self.is_remote:
+                editor.remote_overrides()
+            candidate = dict_to_namespace(editor.apply_to(current))
+            self.config = candidate
+            self._config_editor = editor
+            self._refresh_config_references()
+            return self
+        finally:
+            lock.release()
+
+    def _config_request_fields(self, fields):
+        fields = dict(fields)
+        editor = getattr(self, "_config_editor", None)
+        overrides = editor.remote_overrides() if editor is not None else {}
+        task_options = json.loads(fields.get("task_options") or "{}")
+        if "config_overrides" in task_options:
+            raise ValueError("Use Config.update(inference=...) for remote configuration overrides")
+        if not overrides:
+            return fields
+        query = urlencode({"model_id": fields.get("model_id", ""), "task_type": fields.get("task_type", "")})
+        try:
+            capabilities = self._open_request(Request(f"{self.remote}/config-capabilities?{query}"))
+        except Exception as exc:
+            raise ValueError("Server does not expose configuration capabilities; upgrade the server or omit overrides") from exc
+        if capabilities.get("version") != 1:
+            raise ValueError("Unsupported server configuration protocol version")
+        allowed = capabilities.get("options", {})
+        for name, value in overrides.items():
+            if name not in allowed:
+                raise ValueError(f"Server does not support inference.{name}")
+            spec = allowed[name]
+            if spec.get("minimum") is not None and value < spec["minimum"] or spec.get("maximum") is not None and value > spec["maximum"]:
+                raise ValueError(f"inference.{name} exceeds server limits")
+        task_options["config_overrides"] = {"version": 1, "inference": overrides}
+        fields["task_options"] = json.dumps(task_options)
+        return fields

opensportslib/apis/localization.py

@@ -4,6 +4,7 @@ import time
 from types import SimpleNamespace
 
 from opensportslib.apis.base_task_model import BaseTaskModel
+from opensportslib.apis.configuration import config_operation
 from opensportslib.core.config.accessors import (
     get_data_classes,
     get_loader_backend,
@@ -290,6 +291,7 @@ class LocalizationModel(BaseTaskModel):
             "best_criterion_valid": best_criterion_valid,
         }
 
+    @config_operation
     def train(
         self,
         train_set=None,
@@ -327,7 +329,7 @@ class LocalizationModel(BaseTaskModel):
         # with explicit valid annotation overrides.
         self._set_split_path("valid_data_frames", valid_set)
 
-        self.config = resolve_config_omega(self.config, weights=weights)
+        self.config = self._effective_config(resolve_config_omega(self.config, weights=weights))
         self.config = resolve_inference_class_metadata(self.config)
         effective_weights = weights if weights is not None else self.last_loaded_weights
         self._adapt_hf_backend_for_device(effective_weights)
@@ -418,14 +420,18 @@ class LocalizationModel(BaseTaskModel):
         logging.info(f"Total Execution Time is {time.time()-start} seconds")
         return self.best_checkpoint
 
+    @config_operation
     def infer(
         self,
         test_set=None,
         weights=None,
         use_wandb=True,
+        video_path: str | None = None,
         **kwargs,
     ):
         """Run model inference and return predictions in OSL JSON format."""
+        if test_set is not None and video_path is not None:
+            raise ValueError("Provide either `test_set` or `video_path`, not both.")
         remote_mode_provided = "remote_mode" in kwargs
         remote_mode = kwargs.pop("remote_mode", "full_test_set")
         if self.is_remote:
@@ -433,6 +439,17 @@ class LocalizationModel(BaseTaskModel):
             remote_task_options = kwargs.pop("remote_task_options", None)
             if kwargs:
                 raise TypeError(f"Unsupported remote inference options: {', '.join(kwargs)}")
+            if video_path is not None:
+                if remote_mode != "full_test_set":
+                    raise ValueError("`remote_mode=per_sample` requires `test_set`, not direct video input.")
+                job = self.submit_video_inference(
+                    task_type="localization",
+                    video_path=video_path,
+                    model_id=remote_model_id,
+                    task_options=remote_task_options,
+                )
+                self.last_remote_failures = []
+                return self.wait_for_remote_result(job["job_id"])["result"]["predictions"]
             test_set = self._resolve_split_path("test", test_set)
             if remote_mode == "per_sample":
                 batch = self.submit_per_sample_inference(
@@ -458,6 +475,18 @@ class LocalizationModel(BaseTaskModel):
             return self.wait_for_remote_result(job["job_id"])["result"]["predictions"]
         if remote_mode_provided:
             raise ValueError("`remote_mode` is available only when `remote` is configured.")
+        if video_path is not None:
+            from opensportslib.core.utils.direct_video import direct_video_manifest
+            from opensportslib.core.utils.config import resolve_config_omega
+
+            manifest_config = self._effective_config(resolve_config_omega(self.config, weights=weights))
+            manifest_config = resolve_inference_class_metadata(manifest_config)
+            with direct_video_manifest(manifest_config, video_path, "localization") as manifest:
+                return self.infer(
+                    test_set=manifest,
+                    weights=weights,
+                    use_wandb=use_wandb,
+                )
         from opensportslib.datasets.builder import build_dataset
         from opensportslib.models.builder import build_model
         from opensportslib.core.trainer.localization_trainer import build_inferer
@@ -473,7 +502,7 @@ class LocalizationModel(BaseTaskModel):
         test_set = self._resolve_split_path("test", test_set)
         self._set_split_path("test", test_set)
 
-        self.config = resolve_config_omega(self.config, weights=weights)
+        self.config = self._effective_config(resolve_config_omega(self.config, weights=weights))
         self.config = resolve_inference_class_metadata(self.config)
         effective_weights = weights if weights is not None else self.last_loaded_weights
         self._adapt_hf_backend_for_device(effective_weights)
@@ -530,6 +559,7 @@ class LocalizationModel(BaseTaskModel):
         logging.info(f"Total Execution Time is {time.time()-start} seconds")
         return predictions
 
+    @config_operation
     def evaluate(
         self,
         test_set=None,
@@ -551,7 +581,7 @@ class LocalizationModel(BaseTaskModel):
 
         test_set = self._resolve_split_path("test", test_set)
         self._set_split_path("test", test_set)
-        self.config = resolve_config_omega(self.config, weights=weights)
+        self.config = self._effective_config(resolve_config_omega(self.config, weights=weights))
         self.config = resolve_inference_class_metadata(self.config)
         effective_weights = weights if weights is not None else self.last_loaded_weights
         self._adapt_hf_backend_for_device(effective_weights)

opensportslib/apis/vqa.py

@@ -8,6 +8,7 @@ import os
 from typing import Any
 
 from opensportslib.apis.base_task_model import BaseTaskModel
+from opensportslib.apis.configuration import config_operation
 from opensportslib.core.config.accessors import get_split_annotation_path, get_system_gpu_count, get_train_execution, get_vqa_backend
 from opensportslib.core.utils.config import expand, resolve_config_omega
 
@@ -132,6 +133,7 @@ class VQAModel(BaseTaskModel):
         self.last_loaded_weights = weights
         self.best_checkpoint = weights
 
+    @config_operation
     def train(
         self,
         train_set: str | None = None,
@@ -144,7 +146,7 @@ class VQAModel(BaseTaskModel):
     ) -> str | None:
         del kwargs
 
-        self.config = resolve_config_omega(self.config, weights=weights)
+        self.config = self._effective_config(resolve_config_omega(self.config, weights=weights))
         execution = get_train_execution(self.config)
         backend = str(execution.get("training_backend", "placeholder")).lower()
         vqa_backend = get_vqa_backend(self.config)
@@ -227,6 +229,7 @@ class VQAModel(BaseTaskModel):
             "Only 'xvars_videochatgpt_lora' and 'qwen_xvars_lora' are supported."
         )
 
+    @config_operation
     def infer(
         self,
         test_set: str | None = None,
@@ -309,7 +312,7 @@ class VQAModel(BaseTaskModel):
         if direct_requested and (not video_path or not str(question or "").strip()):
             raise ValueError("Direct VQA inference requires both `video_path` and a non-empty `question`.")
 
-        self.config = resolve_config_omega(self.config, weights=weights)
+        self.config = self._effective_config(resolve_config_omega(self.config, weights=weights))
         backend = get_vqa_backend(self.config)
         effective_weights = weights if weights is not None else self.last_loaded_weights
         _set_model_checkpoint_path(self.config, effective_weights)
@@ -346,6 +349,7 @@ class VQAModel(BaseTaskModel):
         self._init_wandb(use_wandb=use_wandb)
         return self.trainer.infer(model, test_data, use_wandb=use_wandb)
 
+    @config_operation
     def evaluate(
         self,
         test_set: str | None = None,
@@ -358,7 +362,7 @@ class VQAModel(BaseTaskModel):
         from opensportslib.core.trainer.vqa_trainer import Trainer_VQA
         from opensportslib.datasets.builder import build_dataset
 
-        self.config = resolve_config_omega(self.config, weights=weights)
+        self.config = self._effective_config(resolve_config_omega(self.config, weights=weights))
         test_set = self._resolve_split_path("test", test_set)
         test_data = build_dataset(self.config, test_set, None, split="test")
         self._init_wandb(use_wandb=use_wandb)