opensportslib 0.3.1.dev6__tar.gz → 0.3.1.dev8__tar.gz

{opensportslib-0.3.1.dev6/opensportslib.egg-info → opensportslib-0.3.1.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.3.1.dev6
+Version: 0.3.1.dev8
 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,15 @@ 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.
+
+See the [complete inference server guide](docs/server/inference-server.md) for
+installation, registry administration, curl requests, single-video inference,
+full-test-set and per-sample remote inference, job polling, and sessions.
+
 ## Configuration From Hugging Face
 
 Prepare and inspect configuration before model weights are allocated:

{opensportslib-0.3.1.dev6 → opensportslib-0.3.1.dev8}/README.md

@@ -1,5 +1,14 @@
 # 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.
+
+See the [complete inference server guide](docs/server/inference-server.md) for
+installation, registry administration, curl requests, single-video inference,
+full-test-set and per-sample remote inference, job polling, and sessions.
+
 ## Configuration From Hugging Face
 
 Prepare and inspect configuration before model weights are allocated:

{opensportslib-0.3.1.dev6 → opensportslib-0.3.1.dev8}/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.dev6 → opensportslib-0.3.1.dev8}/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.dev8/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.dev6 → opensportslib-0.3.1.dev8/opensportslib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: opensportslib
-Version: 0.3.1.dev6
+Version: 0.3.1.dev8
 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,15 @@ 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.
+
+See the [complete inference server guide](docs/server/inference-server.md) for
+installation, registry administration, curl requests, single-video inference,
+full-test-set and per-sample remote inference, job polling, and sessions.
+
 ## Configuration From Hugging Face
 
 Prepare and inspect configuration before model weights are allocated:

{opensportslib-0.3.1.dev6 → opensportslib-0.3.1.dev8}/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
@@ -165,6 +166,8 @@ 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.dev6 → opensportslib-0.3.1.dev8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "opensportslib"
-version = "0.3.1.dev6"
+version = "0.3.1.dev8"
 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.dev8/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.dev8/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"]