cortexgrid 0.2.92__tar.gz → 0.2.94__tar.gz

{cortexgrid-0.2.92 → cortexgrid-0.2.94}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.5
 Name: cortexgrid
-Version: 0.2.92
+Version: 0.2.94
 Summary: Connect your ML code to the RoboLab compute cluster — Ray, MLflow, and S3
 Project-URL: Homepage, https://github.com/robodatalab/cortexgrid
 Project-URL: Repository, https://github.com/robodatalab/cortexgrid
 Project-URL: Documentation, https://github.com/robodatalab/cortexgrid/blob/main/docs/cortexgrid/README.md
 License-Expression: Apache-2.0
 License-File: LICENSE
-Requires-Python: >=3.11
+Requires-Python: <3.12,>=3.11
 Requires-Dist: boto3>=1.34
 Requires-Dist: cloudpickle>=3.0
 Requires-Dist: fabric>=3.2.3
@@ -178,6 +178,8 @@ deployed = cortexgrid.deploy_model("qwen", "instruct", saved.run_name, wait=True
 print(deployed.url)
 ```
 
+`save_model` saves a new copy under every run - meant for weights the run produced (e.g. a fine-tune). For a model produced elsewhere (e.g. a pretrained base model), `cortexgrid.import_model(source, MyServeApp, family, suffix)` uploads it once under `run_name=cortexgrid.IMPORTED` and is a no-op on later runs; deploy it with `deploy_model(family, suffix, cortexgrid.IMPORTED)`.
+
 `save_model` is synchronous (registry lifecycle: `uploading` -> `ready`); `deploy_model` schedules the serving lifecycle (`deploying` -> `running`). With `wait=True` a failed deploy raises `cortexgrid.ModelDeployFailed`; `cortexgrid.wait_for_model_serving(family, suffix, run_name, timeout=...)` waits on a deploy started elsewhere, and re-deploying a failed model retries it from scratch. See [model-serving.md](https://github.com/robodatalab/cortexgrid/blob/main/docs/cortexgrid/model-serving.md) for both lifecycles end to end - upload/deploy/undeploy/delete, status queries (`model_registry_status`, `model_serving_status`), and error handling.
 
 ### API reference

{cortexgrid-0.2.92 → cortexgrid-0.2.94}/cortexgrid/__init__.py

@@ -74,8 +74,10 @@ from cortexgrid.ray_util import (
 )
 from cortexgrid.s3_util import delete_prefix, download, get_s3_client, upload, upload_dir
 from cortexgrid.model_storage import (
+    IMPORTED,
     SavedModel,
     delete_model,
+    import_model,
     list_models,
     load_model,
     model_registry_status,
@@ -119,7 +121,11 @@ def save_model(
     weights_dir: str | Path, serve_app: type, family: str, suffix: str
 ) -> SavedModel:
     """Persist a weights directory under the current Experiment's run, paired
-    with the serve-app class that will front it at deploy time."""
+    with the serve-app class that will front it at deploy time.
+
+    Every run saves a new copy under its own run_name - meant for weights the
+    run produced (e.g. a fine-tune). For a model produced elsewhere that should
+    be uploaded once and reused across runs, use `import_model`."""
     experiment = Experiment.get_instance()
     return _save_model_storage(
         weights_dir,
@@ -179,8 +185,10 @@ __all__ = [
     "list_secrets",
     "delete_secret",
     # Model registry
+    "IMPORTED",
     "SavedModel",
     "save_model",
+    "import_model",
     "load_model",
     "list_models",
     "model_registry_status",

{cortexgrid-0.2.92 → cortexgrid-0.2.94}/cortexgrid/_serve_entry.py

@@ -3,7 +3,8 @@
 Ray Serve's REST `import_path` resolves to `cortexgrid._serve_entry:build`.
 On the cluster replica, `build` imports the serve-app class bundled at
 `save_model` time (its import path was stored as an MLflow tag), applies Ray's
-ingress with the app it was marked with by `cortexgrid.serve.ingress`, reads its
+ingress with the app it was marked with by `cortexgrid.serve.ingress` (again on
+each replica, see `_IngressOnReplica`), reads its
 `num_gpus`/`num_replicas` class attributes for actor placement, wraps it as a
 Ray Serve deployment, and binds it with the (family, suffix, run_name)
 identifiers.
@@ -31,6 +32,33 @@ from ray.serve.deployment import Application
 from cortexgrid.serve import ingress_app
 
 
+# Requests one replica handles at once before Ray queues the rest.
+_MAX_ONGOING_REQUESTS = 100
+
+class _IngressOnReplica:
+    """Mixin that re-applies Ray's ingress to `_serve_app` in the replica's own
+    process, as Ray creates the replica instance.
+
+    Ray's ingress rewrites the signature of each route method, in place, so
+    FastAPI injects the replica instance as `self`. `build` applies it in the
+    build process only. The replica imports the serve-app's module afresh, and
+    its route methods carry no rewrite. FastAPI < 0.137 analysed routes once,
+    in the build process, and the replica received the result. FastAPI >= 0.137
+    analyses them in the replica on the first request, and without the rewrite
+    reads `self` as a required query parameter (HTTP 422).
+
+    Hooked on `__new__`, not `__init__`: Ray calls `__new__` alone, before the
+    serve-app's `__init__`, whether that is sync or async."""
+
+    _serve_app: type
+
+    def __new__(cls, *args: Any, **kwargs: Any) -> Any:
+        # Applied for its side effect on the route methods; the wrapper it
+        # returns is not needed.
+        serve.ingress(ingress_app(cls._serve_app))(cls._serve_app)
+        return super().__new__(cls)
+
+
 def build(args: dict[str, Any]) -> Application:
     module_name, class_name = args["class_import_path"].split(":")
     serve_app = getattr(importlib.import_module(module_name), class_name)
@@ -38,10 +66,18 @@ def build(args: dict[str, Any]) -> Application:
     # mark and are deployed as they are.
     app = ingress_app(serve_app)
     if app is not None:
-        serve_app = serve.ingress(app)(serve_app)
+        on_replica = type(
+            serve_app.__name__,
+            (_IngressOnReplica, serve_app),
+            {"_serve_app": serve_app},
+        )
+        serve_app = serve.ingress(app)(on_replica)
     num_gpus = getattr(serve_app, "num_gpus", 0)
     num_replicas = getattr(serve_app, "num_replicas", 1)
     return serve.deployment(serve_app).options(
         num_replicas=num_replicas,
+        # Ray 2.32 lowered the default from 100 to 5; keep what serve-apps
+        # had on Ray 2.9.
+        max_ongoing_requests=_MAX_ONGOING_REQUESTS,
         ray_actor_options={"num_gpus": num_gpus},
     ).bind(args["family"], args["suffix"], args["run_name"])

{cortexgrid-0.2.92 → cortexgrid-0.2.94}/cortexgrid/model_storage.py

@@ -6,7 +6,14 @@ Mapping cortexgrid taxonomy <-> MLflow Registry:
     family, suffix      -> ModelVersion.tags["family"], ["suffix"]   (denormalized)
     weights blob path   -> ModelVersion.source =
                            "s3://<bucket>/models/<run_name>/<family>/<suffix>/weights/"
-    run linkage         -> ModelVersion.run_id  (built-in MLflow field)
+    run linkage         -> ModelVersion.run_id  (built-in MLflow field; unset
+                           for imported models)
+
+Two ways in: `save_model` registers a fresh copy under the calling run's
+run_name every time it runs (fine-tuned output); `import_model` registers a
+model produced elsewhere once, under the fixed run_name IMPORTED, and is a
+no-op after that. Both write the same layout, so every
+(family, suffix, run_name) consumer - load_model, deploy_model - handles both.
 
 storage.py is pure: it takes run_id/run_name as explicit args and never reads
 the active Experiment singleton. The facade that fills those in lives in
@@ -20,7 +27,7 @@ from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 import tempfile
-from typing import Any
+from typing import Any, Callable
 
 from mlflow.exceptions import MlflowException
 from mlflow.tracking import MlflowClient
@@ -49,6 +56,11 @@ _PHASE_BROKEN = "broken"
 # derived lazily on read (see `_phase_for`); nothing is written back.
 _UPLOAD_DEADLINE = timedelta(hours=3)
 
+# run_name under which `import_model` registers a model: imported weights belong
+# to no run, so they share one fixed key and outlive the run that imported
+# them. Run names are haikunator "word-word-NN", so no run can take this name.
+IMPORTED = "imported"
+
 
 @dataclass
 class SavedModel:
@@ -137,6 +149,10 @@ def save_model(
     """Upload a weights directory to S3 and register a new MLflow ModelVersion
     paired with the serve-app that fronts it.
 
+    Meant for weights the calling run produced (e.g. a fine-tune): every run
+    saves its own copy under its own run_name, so running the same code twice
+    yields two models. For weights produced elsewhere, use `import_model`.
+
     cortexgrid stores the weights as an opaque directory: it never inspects,
     serializes, or reconstructs their contents, so the on-disk format
     (HuggingFace `save_pretrained`, `torch.save`, ONNX, anything) is entirely
@@ -148,6 +164,55 @@ def save_model(
     Its code is bundled and its import path, bundle URL, and pip list are
     stored as tags on the ModelVersion so `deploy_model` can bind it later
     without the caller holding the class object."""
+    return _upload_model(weights_dir, serve_app, suffix, family, run_id, run_name)
+
+
+def import_model(
+    source: str | Path | Callable[[], str | Path],
+    serve_app: type,
+    family: str,
+    suffix: str,
+) -> SavedModel:
+    """Register a model produced elsewhere (e.g. a pretrained base model) under
+    the fixed key (family, suffix, IMPORTED), once.
+
+    `source` is the weights directory, or a callable returning it; the callable
+    runs only when the upload actually happens, so an expensive download can be
+    skipped on every run after the first.
+
+    If a version is already registered under the key:
+      - "ready": no-op, returns it. `source` and `serve_app` are ignored; to
+        replace the weights or the serve-app, `delete_model` it first.
+      - "uploading": raises RuntimeError - another process is importing it.
+      - "upload_failed" / "broken": deleted and imported again.
+
+    The version is linked to no MLflow run, so deleting a run leaves it in
+    place. Deploy it like any saved model:
+    `deploy_model(family, suffix, IMPORTED)`."""
+    existing = model_registry_status(family, suffix, IMPORTED)
+    if existing is not None:
+        if existing.phase == _PHASE_READY:
+            return existing
+        if existing.phase == _PHASE_UPLOADING:
+            raise RuntimeError(
+                f"Model {family}/{suffix}/{IMPORTED} is being imported by "
+                "another process"
+            )
+        delete_model(family, suffix, IMPORTED)
+    weights_dir = source() if callable(source) else source
+    return _upload_model(weights_dir, serve_app, suffix, family, None, IMPORTED)
+
+
+def _upload_model(
+    weights_dir: str | Path,
+    serve_app: type,
+    suffix: str,
+    family: str,
+    run_id: str | None,
+    run_name: str,
+) -> SavedModel:
+    """Register a ModelVersion in "uploading", upload the weights and the
+    serve-app bundle, and flip it to "ready" (or "upload_failed")."""
     bucket = get_s3_bucket()
     prefix = f"models/{run_name}/{family}/{suffix}"
     size_bytes = _dir_size_bytes(weights_dir)

{cortexgrid-0.2.92 → cortexgrid-0.2.94}/docs/cortexgrid/README.md

@@ -150,6 +150,8 @@ deployed = cortexgrid.deploy_model("qwen", "instruct", saved.run_name, wait=True
 print(deployed.url)
 ```
 
+`save_model` saves a new copy under every run - meant for weights the run produced (e.g. a fine-tune). For a model produced elsewhere (e.g. a pretrained base model), `cortexgrid.import_model(source, MyServeApp, family, suffix)` uploads it once under `run_name=cortexgrid.IMPORTED` and is a no-op on later runs; deploy it with `deploy_model(family, suffix, cortexgrid.IMPORTED)`.
+
 `save_model` is synchronous (registry lifecycle: `uploading` -> `ready`); `deploy_model` schedules the serving lifecycle (`deploying` -> `running`). With `wait=True` a failed deploy raises `cortexgrid.ModelDeployFailed`; `cortexgrid.wait_for_model_serving(family, suffix, run_name, timeout=...)` waits on a deploy started elsewhere, and re-deploying a failed model retries it from scratch. See [model-serving.md](https://github.com/robodatalab/cortexgrid/blob/main/docs/cortexgrid/model-serving.md) for both lifecycles end to end - upload/deploy/undeploy/delete, status queries (`model_registry_status`, `model_serving_status`), and error handling.
 
 ### API reference

{cortexgrid-0.2.92 → cortexgrid-0.2.94}/pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "cortexgrid"
-version = "0.2.92"
+version = "0.2.94"
 description = "Connect your ML code to the RoboLab compute cluster — Ray, MLflow, and S3"
 readme = "docs/cortexgrid/README.md"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
-requires-python = ">=3.11"
+requires-python = ">=3.11,<3.12"
 dependencies = [
     "ray[default]>=2.9,<3",
     "mlflow>=3.11,<4",