cortexgrid 0.2.86__tar.gz → 0.2.87__tar.gz

{cortexgrid-0.2.86 → cortexgrid-0.2.87}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cortexgrid
-Version: 0.2.86
+Version: 0.2.87
 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
@@ -155,9 +155,24 @@ s3_client = cortexgrid.get_s3_client()           # boto3 S3 client
 
 #### Model registry and serving
 
-Save a trained model's weights together with the serve-app that fronts it, then deploy it as a Ray Serve application:
+Save a trained model's weights together with the serve-app that fronts it, then deploy it as a Ray Serve application. A serve-app is a class fronted by a FastAPI app, marked with cortexgrid's `serve.ingress` (not Ray's):
 
 ```python
+from cortexgrid import serve
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@serve.ingress(app)
+class MyServeApp:
+    num_gpus = 1
+
+    def __init__(self, family: str, suffix: str, run_name: str) -> None:
+        self._weights_dir = cortexgrid.load_model(family, suffix, run_name)
+
+    @app.post("/complete")
+    async def complete(self, body: dict): ...
+
 saved = cortexgrid.save_model(weights_dir, MyServeApp, family="qwen", suffix="instruct")
 deployed = cortexgrid.deploy_model("qwen", "instruct", saved.run_name, wait=True)
 print(deployed.url)

{cortexgrid-0.2.86 → cortexgrid-0.2.87}/cortexgrid/_bundle.py

@@ -100,7 +100,10 @@ def bundle(seed: Path) -> BundleDesc:
 
 def stage(files: set[Path], dest: Path) -> None:
     """Copy `files` under `dest`, each at its import path (relative to the
-    sys.path entry it lives under), so `dest` on sys.path imports them all."""
+    sys.path entry it lives under), so `dest` on sys.path imports them all.
+    `dest` is created even when `files` is empty (e.g. code that lives entirely
+    in installed distributions)."""
+    dest.mkdir(parents=True, exist_ok=True)
     for file in files:
         target = dest / file.relative_to(_sys_path_root(file))
         target.parent.mkdir(parents=True, exist_ok=True)

{cortexgrid-0.2.86 → cortexgrid-0.2.87}/cortexgrid/_serve_entry.py

@@ -2,7 +2,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), reads its
+`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
 `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.
@@ -27,10 +28,17 @@ from typing import Any
 from ray import serve
 from ray.serve.deployment import Application
 
+from cortexgrid.serve import ingress_app
+
 
 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)
+    # Models saved with a class wrapped by ray.serve.ingress itself carry no
+    # mark and are deployed as they are.
+    app = ingress_app(serve_app)
+    if app is not None:
+        serve_app = serve.ingress(app)(serve_app)
     num_gpus = getattr(serve_app, "num_gpus", 0)
     num_replicas = getattr(serve_app, "num_replicas", 1)
     return serve.deployment(serve_app).options(

{cortexgrid-0.2.86 → cortexgrid-0.2.87}/cortexgrid/model_serving.py

@@ -104,7 +104,18 @@ def bundle_class(
 
     Returns the metadata `deploy_model` needs later; callers (typically
     `save_model`) persist it on the ModelVersion so the deploy step can run
-    without holding the class object."""
+    without holding the class object.
+
+    Raises ValueError for a class wrapped by `ray.serve.ingress`: that wrapper
+    is a subclass Ray defines in its own module, and on older Ray (e.g. 2.9) it
+    reports that module as its own, so the class's source and import path would
+    resolve to Ray instead of the serve-app. `cortexgrid.serve.ingress` leaves
+    the class unwrapped."""
+    if any(klass.__module__.startswith("ray.serve") for klass in cls.__mro__):
+        raise ValueError(
+            f"{cls.__name__} is wrapped by ray.serve.ingress; decorate it with "
+            "cortexgrid.serve.ingress instead (from cortexgrid import serve)"
+        )
     entry_file = Path(inspect.getfile(cls)).resolve()
     serve_entry = Path(__file__).with_name("_serve_entry.py")
     desc = bundle(entry_file).merge(bundle(serve_entry))

{cortexgrid-0.2.86 → cortexgrid-0.2.87}/cortexgrid/model_storage.py

@@ -143,7 +143,8 @@ def save_model(
     the caller's concern. That directory boundary is the open-closed extension
     point - new model kinds need no change here.
 
-    `serve_app` is the Ray Serve ingress class that will front these weights.
+    `serve_app` is the `cortexgrid.serve.ingress` class that will front these
+    weights.
     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."""

cortexgrid-0.2.87/cortexgrid/serve.py

@@ -0,0 +1,43 @@
+"""Declare a serve-app's HTTP ingress without importing Ray.
+
+    from cortexgrid import serve
+
+    @serve.ingress(app)
+    class MyServeApp: ...
+
+Same shape as `ray.serve.ingress`, but the class is left exactly as written: the
+FastAPI app is only recorded on it, and `cortexgrid._serve_entry.build` applies
+Ray's ingress when it builds the Serve application on the cluster.
+
+Ray's decorator replaces the class with a wrapper subclass defined in
+ray/serve/api.py; older Ray (e.g. 2.9) leaves the wrapper's __module__ naming
+that module. Everything that locates a serve-app by its module - bundling its
+source, recording its import path - would then find Ray instead of the user's
+code. Deferring the wrap to the one place Serve needs it keeps the class
+locatable everywhere else (the laptop, Ray jobs, tests).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, TypeVar
+
+
+_T = TypeVar("_T", bound=type)
+
+_INGRESS_APP_ATTR = "__cortexgrid_ingress_app__"
+
+
+def ingress(app: Any) -> Callable[[_T], _T]:
+    """Mark a serve-app class as fronted by the ASGI `app` (e.g. a FastAPI
+    instance). Returns the class itself, unwrapped."""
+
+    def decorator(cls: _T) -> _T:
+        setattr(cls, _INGRESS_APP_ATTR, app)
+        return cls
+
+    return decorator
+
+
+def ingress_app(cls: type) -> Any | None:
+    """The app `cls` was marked with by `ingress`, or None if it was not."""
+    return getattr(cls, _INGRESS_APP_ATTR, None)

{cortexgrid-0.2.86 → cortexgrid-0.2.87}/docs/cortexgrid/README.md

@@ -127,9 +127,24 @@ s3_client = cortexgrid.get_s3_client()           # boto3 S3 client
 
 #### Model registry and serving
 
-Save a trained model's weights together with the serve-app that fronts it, then deploy it as a Ray Serve application:
+Save a trained model's weights together with the serve-app that fronts it, then deploy it as a Ray Serve application. A serve-app is a class fronted by a FastAPI app, marked with cortexgrid's `serve.ingress` (not Ray's):
 
 ```python
+from cortexgrid import serve
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@serve.ingress(app)
+class MyServeApp:
+    num_gpus = 1
+
+    def __init__(self, family: str, suffix: str, run_name: str) -> None:
+        self._weights_dir = cortexgrid.load_model(family, suffix, run_name)
+
+    @app.post("/complete")
+    async def complete(self, body: dict): ...
+
 saved = cortexgrid.save_model(weights_dir, MyServeApp, family="qwen", suffix="instruct")
 deployed = cortexgrid.deploy_model("qwen", "instruct", saved.run_name, wait=True)
 print(deployed.url)

{cortexgrid-0.2.86 → cortexgrid-0.2.87}/pyproject.toml

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