opensportslib 0.3.1.dev5__tar.gz → 0.3.1.dev7__tar.gz

{opensportslib-0.3.1.dev5/opensportslib.egg-info → opensportslib-0.3.1.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.3.1.dev5
+Version: 0.3.1.dev7
 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
@@ -36,6 +36,11 @@ Dynamic: license-file
 
 # OpenSportsLib
 
+OpenSportsLib inference servers support runtime model registration through
+`RemoteModelRegistry`. Its unified `register_model()` method accepts Hugging
+Face or server-local weights; the returned model ID is then used by the existing
+remote task APIs. Unregistered model IDs are rejected.
+
 ## Configuration From Hugging Face
 
 Prepare and inspect configuration before model weights are allocated:

{opensportslib-0.3.1.dev5 → opensportslib-0.3.1.dev7}/README.md

@@ -1,5 +1,10 @@
 # OpenSportsLib
 
+OpenSportsLib inference servers support runtime model registration through
+`RemoteModelRegistry`. Its unified `register_model()` method accepts Hugging
+Face or server-local weights; the returned model ID is then used by the existing
+remote task APIs. Unregistered model IDs are rejected.
+
 ## Configuration From Hugging Face
 
 Prepare and inspect configuration before model weights are allocated:

{opensportslib-0.3.1.dev5 → opensportslib-0.3.1.dev7}/opensportslib/__init__.py

@@ -1,5 +1,7 @@
 import importlib
 
+from opensportslib.remote_registry import RemoteModelRegistry, RemoteRegistryError
+
 
 def __getattr__(name):
     if name == "model":
@@ -15,4 +17,7 @@ def __getattr__(name):
     raise AttributeError(f"module 'opensportslib' has no attribute '{name}'")
 
 
-__all__ = ["model", "metrics", "datasets", "core", "tools"]
+__all__ = [
+    "model", "metrics", "datasets", "core", "tools",
+    "RemoteModelRegistry", "RemoteRegistryError",
+]

{opensportslib-0.3.1.dev5 → opensportslib-0.3.1.dev7}/opensportslib/apis/__init__.py

@@ -6,6 +6,7 @@ from opensportslib.apis.base_task_model import BaseTaskModel
 from opensportslib.apis.classification import ClassificationModel
 from opensportslib.apis.localization import LocalizationModel
 from opensportslib.apis.vqa import VQAModel
+from opensportslib.remote_registry import RemoteModelRegistry, RemoteRegistryError
 import warnings
 warnings.filterwarnings("ignore")
 
@@ -16,4 +17,6 @@ __all__ = [
     "ClassificationModel",
     "LocalizationModel",
     "VQAModel",
+    "RemoteModelRegistry",
+    "RemoteRegistryError",
 ]

opensportslib-0.3.1.dev7/opensportslib/remote_registry.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+from urllib import error, parse, request
+
+
+class RemoteRegistryError(RuntimeError):
+    def __init__(self, status_code: int, detail: Any):
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"Remote model registry returned HTTP {status_code}: {detail}")
+
+
+class RemoteModelRegistry:
+    """Administrative client for an OpenSportsLib server model registry."""
+
+    def __init__(self, remote: str, admin_token: str, timeout: float = 30.0):
+        if not remote:
+            raise ValueError("remote is required.")
+        if not admin_token:
+            raise ValueError("admin_token is required.")
+        self.remote = remote.rstrip("/")
+        self.admin_token = admin_token
+        self.timeout = float(timeout)
+        if self.timeout <= 0:
+            raise ValueError("timeout must be positive.")
+
+    def register_model(
+        self,
+        *,
+        task_type: str,
+        huggingface_model_id: str | None = None,
+        weights_path: str | Path | None = None,
+        config_path: str | Path | None = None,
+        model_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Register exactly one Hugging Face or server-local model source."""
+        if (huggingface_model_id is None) == (weights_path is None):
+            raise ValueError("Provide exactly one of huggingface_model_id or weights_path.")
+        if huggingface_model_id is not None:
+            if config_path is not None:
+                raise ValueError("config_path applies only to local models.")
+            if model_id is not None and model_id != huggingface_model_id:
+                raise ValueError("A Hugging Face model uses its repository ID as model_id.")
+            payload = {
+                "task_type": task_type,
+                "source": {"type": "huggingface", "model_id": huggingface_model_id},
+            }
+        else:
+            payload = {
+                "task_type": task_type,
+                "model_id": model_id,
+                "source": {
+                    "type": "local",
+                    "weights_path": str(weights_path),
+                    "config_path": str(config_path) if config_path is not None else None,
+                },
+            }
+        return self._request("POST", "/models", payload, authenticated=True)
+
+    def list_models(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/models")["models"]
+
+    def get_model(self, model_id: str) -> dict[str, Any]:
+        query = parse.urlencode({"model_id": model_id})
+        return self._request("GET", f"/models/status?{query}")
+
+    def get_operation(self, operation_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/model-operations/{parse.quote(operation_id, safe='')}", authenticated=True)
+
+    def wait_for_operation(
+        self,
+        operation_id: str,
+        *,
+        timeout: float = 7200.0,
+        poll_interval: float = 1.0,
+    ) -> dict[str, Any]:
+        deadline = time.monotonic() + timeout
+        while True:
+            operation = self.get_operation(operation_id)
+            if operation["status"] == "succeeded":
+                return operation
+            if operation["status"] == "failed":
+                raise RuntimeError(operation.get("error") or "Model operation failed.")
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Timed out waiting for model operation `{operation_id}`.")
+            time.sleep(poll_interval)
+
+    def set_default(self, task_type: str, model_id: str) -> dict[str, Any]:
+        task = parse.quote(task_type, safe="")
+        return self._request("PUT", f"/models/defaults/{task}", {"model_id": model_id}, authenticated=True)
+
+    def unregister_model(self, model_id: str) -> dict[str, Any]:
+        encoded = parse.quote(model_id, safe="")
+        return self._request("DELETE", f"/models/{encoded}", authenticated=True)
+
+    def _request(
+        self,
+        method: str,
+        endpoint: str,
+        payload: dict[str, Any] | None = None,
+        authenticated: bool = False,
+    ) -> dict[str, Any]:
+        body = json.dumps(payload).encode() if payload is not None else None
+        headers = {"Content-Type": "application/json"}
+        if authenticated:
+            headers["Authorization"] = f"Bearer {self.admin_token}"
+        outgoing = request.Request(self.remote + endpoint, data=body, method=method, headers=headers)
+        try:
+            with request.urlopen(outgoing, timeout=self.timeout) as response:
+                return json.loads(response.read().decode())
+        except error.HTTPError as exc:
+            detail = exc.read().decode(errors="replace")
+            try:
+                parsed = json.loads(detail)
+                detail = parsed.get("detail", parsed)
+            except json.JSONDecodeError:
+                pass
+            raise RemoteRegistryError(exc.code, detail) from exc
+        except error.URLError as exc:
+            raise ConnectionError(f"Could not reach remote server `{self.remote}`: {exc.reason}") from exc

{opensportslib-0.3.1.dev5 → opensportslib-0.3.1.dev7/opensportslib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.3.1.dev5
+Version: 0.3.1.dev7
 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
@@ -36,6 +36,11 @@ Dynamic: license-file
 
 # OpenSportsLib
 
+OpenSportsLib inference servers support runtime model registration through
+`RemoteModelRegistry`. Its unified `register_model()` method accepts Hugging
+Face or server-local weights; the returned model ID is then used by the existing
+remote task APIs. Unregistered model IDs are rejected.
+
 ## Configuration From Hugging Face
 
 Prepare and inspect configuration before model weights are allocated:

{opensportslib-0.3.1.dev5 → opensportslib-0.3.1.dev7}/opensportslib.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ examples/quickstart/basic_localization.py
 examples/quickstart/basic_vqa.py
 opensportslib/__init__.py
 opensportslib/cli.py
+opensportslib/remote_registry.py
 opensportslib.egg-info/PKG-INFO
 opensportslib.egg-info/SOURCES.txt
 opensportslib.egg-info/dependency_links.txt
@@ -142,6 +143,7 @@ opensportslib/tools/_common.py
 opensportslib/tools/hf_transfer.py
 opensportslib/tools/osl_json_to_parquet.py
 opensportslib/tools/parquet_to_osl_json.py
+scripts/release_versions.py
 scripts/run_h5_header_rule_inference.py
 tests/conftest.py
 tests/test_classification_dataset_paths.py
@@ -163,6 +165,9 @@ tests/test_optional_hf_config.py
 tests/test_package_smoke.py
 tests/test_pretrained_config_merge_policy.py
 tests/test_public_apis_smoke.py
+tests/test_release_versions.py
+tests/test_remote_model_registry.py
+tests/test_server_model_registry.py
 tests/test_setup_cli.py
 tests/test_spotta_e2e.py
 tests/test_subset_train_infer_integration.py

{opensportslib-0.3.1.dev5 → opensportslib-0.3.1.dev7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opensportslib"
-version = "0.3.1.dev5"
+version = "0.3.1.dev7"
 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.1.dev7/scripts/release_versions.py

@@ -0,0 +1,84 @@
+"""Keep the library version and the server's library pin in sync."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+
+STABLE_VERSION = re.compile(r"^(?P<version>\d+\.\d+\.\d+)$")
+DEV_VERSION = re.compile(r"^(?P<base>\d+\.\d+\.\d+)\.dev(?P<number>\d+)$")
+PROJECT_VERSION = re.compile(
+    r'(?ms)(^\[project\]\s*.*?^version\s*=\s*")[^"]+("\s*$)'
+)
+SERVER_PIN = re.compile(r'("opensportslib==)[^"]+("[,\s]*$)', re.MULTILINE)
+
+
+def next_dev_version(current: str) -> str:
+    """Return the next development release for an existing dev version."""
+    match = DEV_VERSION.fullmatch(current)
+    if not match:
+        raise ValueError(f"expected X.Y.Z.devN, got {current!r}")
+    return f"{match.group('base')}.dev{int(match.group('number')) + 1}"
+
+
+def stable_version(tag: str) -> str:
+    """Return a stable version from a vX.Y.Z release tag."""
+    if not tag.startswith("v"):
+        raise ValueError(f"release tag must start with 'v', got {tag!r}")
+    version = tag[1:]
+    if not STABLE_VERSION.fullmatch(version):
+        raise ValueError(f"release tag must have the form vX.Y.Z, got {tag!r}")
+    return version
+
+
+def read_project_version(pyproject: Path) -> str:
+    text = pyproject.read_text()
+    match = PROJECT_VERSION.search(text)
+    if not match:
+        raise ValueError(f"project.version not found in {pyproject}")
+    return text[match.start(0) + len(match.group(1)) : match.end(0) - len(match.group(2))]
+
+
+def synchronize(version: str, root_pyproject: Path, server_pyproject: Path) -> None:
+    """Write one OpenSportsLib version to both release metadata files."""
+    if not (STABLE_VERSION.fullmatch(version) or DEV_VERSION.fullmatch(version)):
+        raise ValueError(f"unsupported release version {version!r}")
+
+    root_text = root_pyproject.read_text()
+    server_text = server_pyproject.read_text()
+    if len(PROJECT_VERSION.findall(root_text)) != 1:
+        raise ValueError(f"expected one project.version in {root_pyproject}")
+    if len(SERVER_PIN.findall(server_text)) != 1:
+        raise ValueError(f"expected one opensportslib dependency pin in {server_pyproject}")
+
+    root_updated = PROJECT_VERSION.sub(rf"\g<1>{version}\g<2>", root_text)
+    server_updated = SERVER_PIN.sub(rf"\g<1>{version}\g<2>", server_text)
+    root_pyproject.write_text(root_updated)
+    server_pyproject.write_text(server_updated)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("command", choices=("bump-dev", "set-stable"))
+    parser.add_argument("value", nargs="?", help="vX.Y.Z tag for set-stable")
+    parser.add_argument("--root", type=Path, default=Path("pyproject.toml"))
+    parser.add_argument("--server", type=Path, default=Path("server/pyproject.toml"))
+    args = parser.parse_args()
+
+    if args.command == "bump-dev":
+        if args.value is not None:
+            parser.error("bump-dev does not accept a value")
+        version = next_dev_version(read_project_version(args.root))
+    else:
+        if args.value is None:
+            parser.error("set-stable requires a vX.Y.Z tag")
+        version = stable_version(args.value)
+
+    synchronize(version, args.root, args.server)
+    print(version)
+
+
+if __name__ == "__main__":
+    main()

opensportslib-0.3.1.dev7/tests/test_release_versions.py

@@ -0,0 +1,56 @@
+import importlib.util
+from pathlib import Path
+
+import pytest
+
+
+SCRIPT = Path(__file__).parents[1] / "scripts" / "release_versions.py"
+SPEC = importlib.util.spec_from_file_location("release_versions", SCRIPT)
+release_versions = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+SPEC.loader.exec_module(release_versions)
+
+
+def test_next_dev_version_increments_counter():
+    assert release_versions.next_dev_version("0.3.1.dev5") == "0.3.1.dev6"
+
+
+@pytest.mark.parametrize("version", ["0.3.1", "0.3.1rc1", "invalid"])
+def test_next_dev_version_rejects_non_dev_versions(version):
+    with pytest.raises(ValueError, match="expected X.Y.Z.devN"):
+        release_versions.next_dev_version(version)
+
+
+def test_stable_version_requires_stable_v_tag():
+    assert release_versions.stable_version("v0.3.1") == "0.3.1"
+    with pytest.raises(ValueError, match="vX.Y.Z"):
+        release_versions.stable_version("v0.3.1.dev1")
+
+
+def test_synchronize_updates_root_and_server_pin_only(tmp_path):
+    root = tmp_path / "pyproject.toml"
+    server = tmp_path / "server.toml"
+    root.write_text('[project]\nname = "opensportslib"\nversion = "0.3.1.dev5"\n')
+    server.write_text(
+        '[project]\nname = "opensportslib-server"\nversion = "0.1.0"\n'
+        'dependencies = [\n  "opensportslib==0.3.1.dev5",\n  "fastapi",\n]\n'
+    )
+
+    release_versions.synchronize("0.3.1.dev6", root, server)
+
+    assert 'version = "0.3.1.dev6"' in root.read_text()
+    assert 'version = "0.1.0"' in server.read_text()
+    assert '"opensportslib==0.3.1.dev6"' in server.read_text()
+
+
+def test_synchronize_fails_before_writing_when_server_pin_is_missing(tmp_path):
+    root = tmp_path / "pyproject.toml"
+    server = tmp_path / "server.toml"
+    original = '[project]\nversion = "0.3.1.dev5"\n'
+    root.write_text(original)
+    server.write_text('[project]\nversion = "0.1.0"\n')
+
+    with pytest.raises(ValueError, match="dependency pin"):
+        release_versions.synchronize("0.3.1.dev6", root, server)
+
+    assert root.read_text() == original

opensportslib-0.3.1.dev7/tests/test_remote_model_registry.py

@@ -0,0 +1,94 @@
+import json
+from unittest.mock import patch
+
+import pytest
+
+from opensportslib import RemoteModelRegistry, RemoteRegistryError
+
+
+class FakeResponse:
+    def __init__(self, payload):
+        self.payload = payload
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return False
+
+    def read(self):
+        return json.dumps(self.payload).encode()
+
+
+def test_register_huggingface_uses_one_registration_method():
+    client = RemoteModelRegistry("http://server", "secret")
+    with patch("opensportslib.remote_registry.request.urlopen") as urlopen:
+        urlopen.return_value = FakeResponse({"model_id": "org/model", "status": "registering"})
+        result = client.register_model(task_type="classification", huggingface_model_id="org/model")
+
+    outgoing = urlopen.call_args.args[0]
+    assert json.loads(outgoing.data) == {
+        "task_type": "classification",
+        "source": {"type": "huggingface", "model_id": "org/model"},
+    }
+    assert outgoing.headers["Authorization"] == "Bearer secret"
+    assert result["model_id"] == "org/model"
+
+
+def test_register_local_supports_custom_or_generated_model_id():
+    client = RemoteModelRegistry("http://server", "secret")
+    with patch("opensportslib.remote_registry.request.urlopen") as urlopen:
+        urlopen.return_value = FakeResponse({"model_id": "custom", "status": "registering"})
+        client.register_model(
+            task_type="localization",
+            model_id="custom",
+            weights_path="/models/custom/model.pth",
+            config_path="/models/custom/config.yaml",
+        )
+
+    payload = json.loads(urlopen.call_args.args[0].data)
+    assert payload["model_id"] == "custom"
+    assert payload["source"] == {
+        "type": "local",
+        "weights_path": "/models/custom/model.pth",
+        "config_path": "/models/custom/config.yaml",
+    }
+
+
+@pytest.mark.parametrize(
+    "kwargs",
+    [
+        {},
+        {"huggingface_model_id": "org/model", "weights_path": "/models/model"},
+    ],
+)
+def test_register_model_requires_exactly_one_source(kwargs):
+    client = RemoteModelRegistry("http://server", "secret")
+    with pytest.raises(ValueError, match="exactly one"):
+        client.register_model(task_type="classification", **kwargs)
+
+
+def test_huggingface_model_cannot_be_renamed():
+    client = RemoteModelRegistry("http://server", "secret")
+    with pytest.raises(ValueError, match="repository ID"):
+        client.register_model(
+            task_type="classification",
+            huggingface_model_id="org/model",
+            model_id="alias",
+        )
+
+
+def test_http_errors_preserve_structured_detail():
+    from urllib.error import HTTPError
+    from io import BytesIO
+
+    client = RemoteModelRegistry("http://server", "secret")
+    response = HTTPError(
+        "http://server/models", 409, "Conflict", {},
+        BytesIO(json.dumps({"detail": {"code": "MODEL_NOT_READY"}}).encode()),
+    )
+    with patch("opensportslib.remote_registry.request.urlopen", side_effect=response):
+        with pytest.raises(RemoteRegistryError) as raised:
+            client.get_model("model")
+    assert raised.value.status_code == 409
+    assert raised.value.detail == {"code": "MODEL_NOT_READY"}

opensportslib-0.3.1.dev7/tests/test_server_model_registry.py

@@ -0,0 +1,100 @@
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+
+SERVER_ROOT = Path(__file__).parents[1] / "server"
+sys.path.insert(0, str(SERVER_ROOT))
+
+from config.model_registry import (  # noqa: E402
+    ModelRegistry,
+    generated_local_model_id,
+    public_record,
+    resolve_local_source,
+    validate_local_model_id,
+)
+
+
+class FakeRedis:
+    def __init__(self):
+        self.hashes = {}
+
+    def hget(self, key, field):
+        return self.hashes.get(key, {}).get(field)
+
+    def hvals(self, key):
+        return list(self.hashes.get(key, {}).values())
+
+    def hset(self, key, field, value):
+        self.hashes.setdefault(key, {})[field] = value
+
+    def hsetnx(self, key, field, value):
+        values = self.hashes.setdefault(key, {})
+        if field in values:
+            return 0
+        values[field] = value
+        return 1
+
+    def hdel(self, key, field):
+        self.hashes.get(key, {}).pop(field, None)
+
+    def hgetall(self, key):
+        return dict(self.hashes.get(key, {}))
+
+
+def record(model_id="model", source="org/model"):
+    return {
+        "model_id": model_id,
+        "task_type": "classification",
+        "source_type": "huggingface",
+        "source": source,
+        "config_path": None,
+        "status": "ready",
+        "generation": 1,
+        "created_at": "now",
+        "updated_at": "now",
+        "error": None,
+    }
+
+
+def test_registry_reserves_idempotently_and_rejects_conflicts():
+    registry = ModelRegistry(SimpleNamespace(redis_url="redis://unused"), FakeRedis())
+    _, created = registry.reserve(record())
+    assert created
+    existing, created = registry.reserve(record())
+    assert not created
+    assert existing["source"] == "org/model"
+    with pytest.raises(FileExistsError):
+        registry.reserve(record(source="other/model"))
+
+
+def test_local_source_stays_inside_model_root(tmp_path):
+    root = tmp_path / "models"
+    folder = root / "custom"
+    folder.mkdir(parents=True)
+    (folder / "config.yaml").write_text("MODEL: {}")
+    settings = SimpleNamespace(model_root=root)
+
+    weights, config = resolve_local_source(settings, str(folder), None)
+    assert weights == folder
+    assert config == folder / "config.yaml"
+    assert generated_local_model_id(folder).startswith("local:custom-")
+
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    with pytest.raises(ValueError, match="OSL_MODEL_ROOT"):
+        resolve_local_source(settings, str(outside), None)
+
+
+def test_custom_id_and_public_local_record_validation():
+    assert validate_local_model_id("football-model:v2") == "football-model:v2"
+    with pytest.raises(ValueError):
+        validate_local_model_id("folder/model")
+    local = record()
+    local.update({"source_type": "local", "source": "/secret/model", "config_path": "/secret/config", "error": "at /secret/model"})
+    visible = public_record(local)
+    assert "source" not in visible
+    assert "config_path" not in visible
+    assert "/secret" not in visible["error"]