cortexgrid 0.3.2__tar.gz → 0.3.4__tar.gz

{cortexgrid-0.3.2 → cortexgrid-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexgrid
-Version: 0.3.2
+Version: 0.3.4
 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
@@ -234,7 +234,7 @@ The requirements are part of the model, not of the serve-app class: GPUs, RAM an
 
 Anything else the serve-app has to know about the model - which model a provider should be asked for, an endpoint, the name of a secret to read - goes in a free-form string mapping on the same entry: `save_model(..., config={"model": "claude-opus-5"})`. The serve-app reads it in `__init__` with `cortexgrid.model_config(family, suffix, run_name)`; `cortexgrid.set_model_config(family, suffix, run_name, config)` or the model card replaces it. cortexgrid stores the mapping without interpreting it, and a tag is readable by anyone with registry access, so a credential belongs in `set_secret` with only its name in the config.
 
-`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 on later runs only re-bundles `MyServeApp` if its code changed; deploy it with `deploy_model(family, suffix, cortexgrid.IMPORTED)`.
+`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 on later runs only re-bundles `MyServeApp` if its code changed; deploy it with `deploy_model(family, suffix, cortexgrid.IMPORTED)`. A model with no weights to stage - one behind a provider's API, e.g. Gemini or OpenAI - is registered the same way by `cortexgrid.register_model(MyServeApp, family, suffix, config=...)`: same key, same reuse, only the bundle stored. [Serving a hosted-API model](https://github.com/robodatalab/cortexgrid/blob/main/docs/cortexgrid/model-serving.md#serving-a-hosted-api-model) walks through one end to end - serve-app, API key, registration, deploy.
 
 `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.
 

{cortexgrid-0.3.2 → cortexgrid-0.3.4}/cortexgrid/__init__.py

@@ -85,6 +85,7 @@ 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,
+    NO_WEIGHTS,
     SavedModel,
     delete_model,
     list_models,
@@ -95,6 +96,7 @@ from cortexgrid.model_storage import (
     set_model_requirements,
 )
 from cortexgrid.model_storage import import_model as _import_model_storage
+from cortexgrid.model_storage import register_model as _register_model_storage
 from cortexgrid.model_storage import save_model as _save_model_storage
 from cortexgrid.model_serving import (
     Deployment,
@@ -199,6 +201,32 @@ def import_model(
     return model
 
 
+def register_model(
+    serve_app: type,
+    family: str,
+    suffix: str,
+    requirements: ModelRequirements | None = None,
+    config: dict[str, str] | None = None,
+) -> SavedModel:
+    """Register a model with no weights of its own once - a serve-app that
+    forwards to a hosted API stages nothing - reuse it on every later call, and
+    record on the current Experiment's run which one it used.
+
+    `import_model` without the import: everything it needs beyond its code goes
+    in `config`, which the serve-app reads with `model_config` at construction
+    (see `cortexgrid.model_storage.register_model`). The model belongs to no
+    run, so the run keeps the link the same way, under the same tag
+    `imported_model/<family>/<suffix>`."""
+    experiment = Experiment.get_instance()
+    model = _register_model_storage(
+        serve_app, family, suffix, requirements, config
+    )
+    get_mlflow_client().set_tag(
+        experiment.run_id, f"imported_model/{family}/{suffix}", model.created_at
+    )
+    return model
+
+
 __all__ = [
     "Experiment",
     "delete_experiment",
@@ -255,9 +283,11 @@ __all__ = [
     "delete_secret",
     # Model registry
     "IMPORTED",
+    "NO_WEIGHTS",
     "SavedModel",
     "save_model",
     "import_model",
+    "register_model",
     "load_model",
     "list_models",
     "model_registry_status",

{cortexgrid-0.3.2 → cortexgrid-0.3.4}/cortexgrid/model_serving.py

@@ -485,6 +485,25 @@ def _clear_failed_application(
         time.sleep(_SERVING_POLL_INTERVAL_S)
 
 
+def _spec_already_deployed(spec: dict[str, Any]) -> bool:
+    """True when this exact spec is already the app's target, so PUTting it
+    again would only disturb the controller.
+
+    Re-PUTting is not a no-op. While an app's build task is in flight its target
+    code version is unset, so Ray cancels that build and starts a new one no
+    matter what the config says - and since every PUT re-sends the whole
+    applications list, it restarts the in-flight builds of the other apps too.
+    Our build task downloads the model bundle and may create a pip virtualenv,
+    so a caller redeploying faster than that could keep it from ever finishing.
+
+    A DEPLOY_FAILED or DELETING app never reaches here: `_clear_failed_application`
+    has already removed it, and an identical PUT over a failed app is exactly the
+    no-op that leaves it failed.
+    """
+    app = get_serve_details().get("applications", {}).get(spec["name"])
+    return app is not None and app.get("deployed_app_config") == spec
+
+
 def deploy_model(
     family: str,
     suffix: str,
@@ -507,6 +526,11 @@ def deploy_model(
     or an app still DELETING, is waited out before the new spec is PUT, so the
     deploy starts afresh instead of Ray reusing the failed deployment.
 
+    Re-deploying a model that is already live with exactly this spec skips the
+    PUT rather than restating it: see `_spec_already_deployed` for what a
+    redundant PUT costs. The call still reports the app's phase, and with
+    `wait=True` still blocks until it is RUNNING.
+
     With `wait=True`, blocks as `wait_for_model_serving` does until the Serve
     controller reports the app RUNNING. `timeout` (default 300) caps the whole
     call, clearing a failed app included; exceeding it raises TimeoutError, and
@@ -520,11 +544,14 @@ def deploy_model(
         family, suffix, run_name, meta, requirements, num_replicas
     )
     _clear_failed_application(family, suffix, run_name, timeout, deadline)
-    existing = [a for a in _current_application_specs() if a["name"] != spec["name"]]
-    # The controller registers the app, sets it DEPLOYING and stamps
-    # last_deployed_time_s before the PUT returns, so the wait below neither
-    # misses the app nor reads a status left by an earlier deploy.
-    put_serve_applications([*existing, spec])
+    if not _spec_already_deployed(spec):
+        existing = [
+            a for a in _current_application_specs() if a["name"] != spec["name"]
+        ]
+        # The controller registers the app, sets it DEPLOYING and stamps
+        # last_deployed_time_s before the PUT returns, so the wait below neither
+        # misses the app nor reads a status left by an earlier deploy.
+        put_serve_applications([*existing, spec])
     if wait:
         _wait_for_application_running(spec["name"], timeout, deadline)
     app = get_serve_details().get("applications", {}).get(spec["name"], {})

{cortexgrid-0.3.2 → cortexgrid-0.3.4}/cortexgrid/model_storage.py

@@ -6,17 +6,21 @@ 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/"
+                           (NO_WEIGHTS for a model registered without any)
     run linkage         -> ModelVersion.run_id  (built-in MLflow field; unset
                            for imported models)
     requirements        -> ModelVersion.tags["num_gpus"], ["ram_gb"], ["vram_gb"]
     config              -> ModelVersion.tags["config"]  (JSON object)
 
-Two ways in: `save_model` registers a fresh copy under the calling run's
+Three 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 after
-that only re-bundles the serve-app when its code changed. Both write the same
-layout, so every
-(family, suffix, run_name) consumer - load_model, deploy_model - handles both.
+that only re-bundles the serve-app when its code changed; `register_model`
+registers a model that stages no weights at all - a serve-app that forwards to
+a hosted API holds none - under that same fixed key. All three write the same
+layout, so every (family, suffix, run_name) consumer - deploy_model, the
+dashboard - handles them alike; only `load_model` parts them, having nothing to
+hand back for a model registered without weights.
 
 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
@@ -86,6 +90,13 @@ _UPLOAD_DEADLINE = timedelta(hours=3)
 # them. Run names are haikunator "word-word-NN", so no run can take this name.
 IMPORTED = "imported"
 
+# ModelVersion.source of a model registered with no weights of its own: nothing
+# was staged, so there is no blob to point at. Spelled as a URI rather than left
+# blank because MLflow rejects a source that is empty or a local path, and
+# because every reader - `load_model`, the dashboard's storage field - then sees
+# why there is no path instead of an empty one.
+NO_WEIGHTS = "cortexgrid://no-weights"
+
 
 @dataclass
 class SavedModel:
@@ -93,7 +104,9 @@ class SavedModel:
     suffix: str
     run_name: str
     created_at: str
+    # Where the weights live, or NO_WEIGHTS for a model registered without any.
     data_blob_path: str
+    # Size of the weights; 0 for a model registered without any.
     size_bytes: int
     # Registry lifecycle phase: "uploading" while save_model streams the weights
     # and serve bundle to storage, "ready" once that finishes, "upload_failed"
@@ -107,6 +120,13 @@ class SavedModel:
     # versions stored without any.
     config: dict[str, str] = field(default_factory=dict)
 
+    @property
+    def has_weights(self) -> bool:
+        """Whether this model staged weights of its own. False for one
+        registered with `register_model`, whose serve-app holds no bytes to
+        store; `load_model` on it raises."""
+        return self.data_blob_path != NO_WEIGHTS
+
 
 def _phase_for(version: Any) -> str:
     """Registry lifecycle phase of a version, expiring stale uploads to "broken".
@@ -269,6 +289,52 @@ def import_model(
     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)`."""
+    return _register_imported(
+        source, serve_app, family, suffix, requirements, config
+    )
+
+
+def register_model(
+    serve_app: type,
+    family: str,
+    suffix: str,
+    requirements: ModelRequirements | None = None,
+    config: dict[str, str] | None = None,
+) -> SavedModel:
+    """Register a model that stages no weights under the fixed key
+    (family, suffix, IMPORTED), once.
+
+    For a model whose bytes are not ours to hold: a serve-app that forwards
+    requests to a hosted API, or one that reaches for the weights itself at
+    startup. There is nothing to upload, so only `serve_app`'s bundle is
+    stored and the version's source reads NO_WEIGHTS - `load_model` on such a
+    model raises, and `SavedModel.has_weights` is False. What it needs instead
+    of weights - which model a provider should be asked for, the name of the
+    secret holding the key - belongs in `config`, which the serve-app reads
+    with `model_config` at construction.
+
+    Registration is otherwise `import_model`'s, down to the phase an already
+    registered version leaves it in ("ready" is reused and its bundle
+    refreshed, "uploading" raises, "upload_failed"/"broken" is replaced), so
+    the entry is indistinguishable from an imported one to `deploy_model`,
+    `list_models` and the dashboard."""
+    return _register_imported(
+        None, serve_app, family, suffix, requirements, config
+    )
+
+
+def _register_imported(
+    weights: str | Path | Callable[[], str | Path] | None,
+    serve_app: type,
+    family: str,
+    suffix: str,
+    requirements: ModelRequirements | None,
+    config: dict[str, str] | None,
+) -> SavedModel:
+    """Register `weights` under (family, suffix, IMPORTED) unless a version is
+    already there - the once-only registration `import_model` and
+    `register_model` share; `weights` is None for the model that stages
+    none."""
     existing = model_registry_status(family, suffix, IMPORTED)
     if existing is not None:
         if existing.phase == _PHASE_READY:
@@ -287,7 +353,7 @@ def import_model(
             )
         delete_model(family, suffix, IMPORTED)
     return _upload_model(
-        source, serve_app, suffix, family, None, IMPORTED, requirements, config
+        weights, serve_app, suffix, family, None, IMPORTED, requirements, config
     )
 
 
@@ -348,7 +414,7 @@ def _set_missing_config(
 
 
 def _upload_model(
-    weights: str | Path | Callable[[], str | Path],
+    weights: str | Path | Callable[[], str | Path] | None,
     serve_app: type,
     suffix: str,
     family: str,
@@ -359,10 +425,17 @@ def _upload_model(
 ) -> SavedModel:
     """Register a ModelVersion in "uploading", resolve `weights` to a directory
     (calling it when it is a callable), upload the weights and the serve-app
-    bundle, and flip it to "ready" (or "upload_failed")."""
-    bucket = get_s3_bucket()
+    bundle, and flip it to "ready" (or "upload_failed").
+
+    `weights` is None for a model that stages none: its source reads
+    NO_WEIGHTS and the bundle is the only thing uploaded. The phases are the
+    same either way, so one registration path covers both."""
     prefix = f"models/{run_name}/{family}/{suffix}"
-    source = f"s3://{bucket}/{prefix}/weights/"
+    source = (
+        NO_WEIGHTS
+        if weights is None
+        else f"s3://{get_s3_bucket()}/{prefix}/weights/"
+    )
     name = f"{family}__{suffix}"
     client = MlflowClient(tracking_uri=get_mlflow_tracking_uri())
     _ensure_registered_model(client, name)
@@ -371,7 +444,9 @@ def _upload_model(
     # fetched and uploaded, and a concurrent `import_model` sees the import in
     # flight for the whole download instead of starting one of its own. The
     # size is stamped once the directory exists; the bundle tags and the flip
-    # to "ready" happen only after the upload lands. No requirements and no
+    # to "ready" happen only after the upload lands. A weights-less
+    # registration has only its bundle to upload, and passes through the same
+    # phases. No requirements and no
     # config leave their tags unset, so a later `import_model` can still store
     # them.
     version = client.create_model_version(
@@ -388,11 +463,12 @@ def _upload_model(
         },
     )
     try:
-        weights_dir = weights() if callable(weights) else weights
-        client.set_model_version_tag(
-            name, version.version, "size_bytes", str(_dir_size_bytes(weights_dir))
-        )
-        s3_util.upload_dir(str(weights_dir), dest_path=f"{prefix}/weights")
+        if weights is not None:
+            weights_dir = weights() if callable(weights) else weights
+            client.set_model_version_tag(
+                name, version.version, "size_bytes", str(_dir_size_bytes(weights_dir))
+            )
+            s3_util.upload_dir(str(weights_dir), dest_path=f"{prefix}/weights")
         bundle_meta = bundle_class(serve_app, family, suffix, run_name)
         for key, value in metadata_to_tags(bundle_meta).items():
             client.set_model_version_tag(name, version.version, key, value)
@@ -414,7 +490,10 @@ def load_model(family: str, suffix: str, run_name: str) -> Path:
     contents; the serve-app reconstructs the model from it however it likes
     (`from_pretrained`, `torch.load`, ...). The returned directory persists
     after this call - the caller (typically a serve-app loading weights at
-    startup) owns its lifetime."""
+    startup) owns its lifetime.
+
+    Raises ValueError for a model registered with `register_model`: it stages
+    no weights, so there is none to hand back."""
     client = MlflowClient(tracking_uri=get_mlflow_tracking_uri())
     name = f"{family}__{suffix}"
     versions = client.search_model_versions(
@@ -422,6 +501,11 @@ def load_model(family: str, suffix: str, run_name: str) -> Path:
     )
     if not versions or not versions[0].source:
         raise ValueError(f"No model {family}/{suffix}/{run_name}")
+    if versions[0].source == NO_WEIGHTS:
+        raise ValueError(
+            f"Model {family}/{suffix}/{run_name} was registered without "
+            "weights; there is nothing to load"
+        )
     return _download_s3_uri(versions[0].source, None)
 
 

{cortexgrid-0.3.2 → cortexgrid-0.3.4}/docs/cortexgrid/README.md

@@ -206,7 +206,7 @@ The requirements are part of the model, not of the serve-app class: GPUs, RAM an
 
 Anything else the serve-app has to know about the model - which model a provider should be asked for, an endpoint, the name of a secret to read - goes in a free-form string mapping on the same entry: `save_model(..., config={"model": "claude-opus-5"})`. The serve-app reads it in `__init__` with `cortexgrid.model_config(family, suffix, run_name)`; `cortexgrid.set_model_config(family, suffix, run_name, config)` or the model card replaces it. cortexgrid stores the mapping without interpreting it, and a tag is readable by anyone with registry access, so a credential belongs in `set_secret` with only its name in the config.
 
-`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 on later runs only re-bundles `MyServeApp` if its code changed; deploy it with `deploy_model(family, suffix, cortexgrid.IMPORTED)`.
+`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 on later runs only re-bundles `MyServeApp` if its code changed; deploy it with `deploy_model(family, suffix, cortexgrid.IMPORTED)`. A model with no weights to stage - one behind a provider's API, e.g. Gemini or OpenAI - is registered the same way by `cortexgrid.register_model(MyServeApp, family, suffix, config=...)`: same key, same reuse, only the bundle stored. [Serving a hosted-API model](https://github.com/robodatalab/cortexgrid/blob/main/docs/cortexgrid/model-serving.md#serving-a-hosted-api-model) walks through one end to end - serve-app, API key, registration, deploy.
 
 `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.
 

{cortexgrid-0.3.2 → cortexgrid-0.3.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cortexgrid"
-version = "0.3.2"
+version = "0.3.4"
 description = "Connect your ML code to the RoboLab compute cluster — Ray, MLflow, and S3"
 readme = "docs/cortexgrid/README.md"
 license = "Apache-2.0"