grid-cortex-client 0.3.0__tar.gz

grid_cortex_client-0.3.0/.gitignore

@@ -0,0 +1,12 @@
+# Build artefacts
+build/
+dist/
+*.egg-info/
+.venv/
+__pycache__/
+*.pyc
+
+# Test
+.pytest_cache/
+.coverage
+htmlcov/

grid_cortex_client-0.3.0/CLAUDE.md

@@ -0,0 +1,109 @@
+# grid-cortex-client
+
+Python client for the Cortex ML inference API. Published to **public PyPI**.
+
+## Build & Test
+
+```bash
+uv run --package grid-cortex-client pytest
+```
+
+- Build tool: hatchling + hatch-vcs
+- Version: set via `BUILD_VERSION` env (auto-bumped on main from squash-commit type — see `knowledge/golden-rules/cortex/client-versioning.md`)
+- PyPI history: pre-PR-#44 versions up to `0.2.118` were published by the old pipeline; the new auto-pipeline starts at `0.3.0` and uses `cortex-client/v*` git tags as the version source of truth (first auto-publish lands via PR #45's `feat(cortex):` merge once its review feedback is addressed)
+
+## Key Details
+
+- Public API: `CortexClient`, `AsyncCortexClient`, `CortexHubClient`, `ModelType`, `registry`
+- `ModelType` enum is **auto-generated** by the `generate-enum` pre-commit hook — do not edit manually
+- One model handler file per Cortex model in `src/grid_cortex_client/models/`
+- Tests mirror model structure: `tests/test_<model>.py`. CI runs them against a live Ray Serve + CortexHub via `.ci/cortex/run_model_tests.py`.
+
+## Endpoints
+
+| Env | REST base | CortexHub WebSocket |
+|---|---|---|
+| Local | `http://localhost:8000/cortex` | `ws://localhost:8000/cortex/ws/ws` |
+| Stage | `https://cortex-stage.generalrobotics.dev/cortex` | `wss://cortex-stage.generalrobotics.dev/cortex/ws/ws` |
+| Prod | `https://cortex-prod.generalrobotics.dev/cortex` | `wss://cortex-prod.generalrobotics.dev/cortex/ws/ws` |
+
+Override via `GRID_CORTEX_BASE_URL` (REST) and `GRID_CORTEX_WS_URL` (WebSocket). Default is prod.
+
+## Publishing
+
+Client and server release on different cadences. Server deploys touch `cortex/services/ray-serve/**`; client publishes touch `cortex/packages/grid-cortex-client/**`. The two never piggyback — a server-only PR doesn't bump the client, so PyPI users only see versions when the client API actually changed.
+
+### Auto path (MINOR / PATCH)
+
+The squash-merge title's conventional-commit type drives the bump:
+
+| Subject prefix | Bump | Example |
+|---|---|---|
+| `feat:` (incl. `feat(scope):`) | MINOR | `feat(cortex-client): add ZoeDepth method` → `0.3.4 → 0.4.0` |
+| `fix:` / `perf:` | PATCH | `fix(cortex-client): retry transient 503s` → `0.3.4 → 0.3.5` |
+| `chore:` / `docs:` / `ci:` / `refactor:` / `test:` / `build:` / `style:` / `revert:` | none | no release fires |
+| `feat!:` / `fix!:` / `BREAKING CHANGE:` footer | none (manual) | see Manual MAJOR path below |
+
+Flow when a release-bumping client PR lands on main:
+
+1. `cortex-main.yaml` fires (path filter matches `cortex/packages/grid-cortex-client/**`)
+2. `resolve` parses the commit subject, computes the new version
+3. `build-wheel` builds with `BUILD_VERSION=<new>`, uploads as an artifact
+4. `validate-stage` + `validate-prod` install the wheel in fresh venvs, discover deployed models via `CortexClient.get_info()`, run the per-model integration tests against the live env
+5. `publish-client` (gated on **validate-prod green only** — stage is advisory) uploads to PyPI using `PYPI_API_TOKEN`
+6. `tag-client` creates and pushes `cortex-client/v<new>` after the wheel is on PyPI
+
+### Manual MAJOR path
+
+Auto-publish refuses to bump MAJOR. When you're ready:
+
+```bash
+gh release create cortex-client/v<X>.0.0 \
+  --target main \
+  --notes-file cortex/packages/grid-cortex-client/MIGRATION.md
+```
+
+The `release: published` event fires `release.yaml` → routes to `release-cortex-client` → `cortex-publish-client.yaml` builds from the tag and uploads. **Validate against deployed prod manually before cutting the release** — the manual path does not gate.
+
+### Implementation details
+
+- `pyproject.toml` declares `dynamic = ["version"]`; hatchling reads `BUILD_VERSION` from the workflow env.
+- Wheel is built once in `build-wheel`, then passed by artifact to `validate-{stage,prod}` and `publish-client` so all three use identical bits.
+- Tag creation happens only after a confirmed successful PyPI upload — `cortex-client/v*` means "this version is on PyPI." Recoverable if the tag-push step fails: `git tag cortex-client/v<x> <sha> && git push origin cortex-client/v<x>`.
+
+### Validate workflow shape (`.github/workflows/cortex-validate-client.yaml`)
+
+One job per env (no matrix). The job:
+
+1. Calls `CortexClient.get_info()` once via a Python heredoc that imports `CLIENT_HANDLER_OVERRIDES` + `SKIP_DEPLOYED` from `.ci/cortex/_client_overrides.py` (kept stdlib-only so the validate venv doesn't need pyyaml).
+2. Python writes a bash-sourceable `/tmp/discover.sh` with `DEPLOYED`, `SKIP_SET`, `OVERRIDES` — we do not parse JSON in bash because `cortex-aws-gpu` has no `jq`.
+3. Loops over `$DEPLOYED` sequentially. Per server name: SKIP entries short-circuit; missing test files become `NO-TEST` rows; remaining models run `pytest tests/test_<client>.py --tb=short`.
+4. `::group::pytest output (<client>)` block surfaces the full pytest log on FAIL so on-call doesn't have to reach the runner's `/tmp`.
+5. Exits 1 if discover python errors, if `DEPLOYED` is empty, or if `tested == 0` (the publish-gate invariant: validate must exercise at least one model before `publish-client` can run).
+
+Replaces the earlier discover+matrix shape, which fired N env-reviewer prompts per env without delivering real parallelism (single shared runner).
+
+### One-time repo setup
+
+1. **GitHub environment** `prod` — already used by `cortex-deploy.yaml`. Required reviewers on this environment also gate `cortex-publish-client`.
+2. **Repo secret `PYPI_API_TOKEN`** — project-scoped PyPI token for `grid-cortex-client`. Created on pypi.org → manage project → API tokens → create.
+3. **Repo secret `CORTEX_VALIDATE_API_KEY`** — an API key the workflow uses to talk to deployed stage/prod for the validate step. Must work on both envs (or, if scoped, use the prod-capable one — validate-prod is the gating call).
+
+### `MIN_SERVER_VERSION`
+
+`MIN_SERVER_VERSION` is a constant exported from this package; the client checks `/health` on construction and refuses to talk to a server older than its declared minimum. Bumping it = MAJOR client release. *Not yet implemented — tracked as a follow-up to the publish wiring.*
+
+## Consumed By
+
+- `nexus/packages/zenoh-dataflow` (imports grid_cortex_client)
+- `nexus/packages/grid-robot-api` (imports grid_cortex_client)
+- `cortex/services/ray-serve` (the service this client talks to — code-shared via `ModelType`)
+- External users via PyPI
+
+## Adding a New Model Handler
+
+1. Add handler in `src/grid_cortex_client/models/<model>.py` (copy `zoedepth.py`/`owlv2.py`/`pi05.py` as starting point)
+2. Add test in `tests/test_<model>.py` (copy the matching test_*.py)
+3. The `generate-enum` hook updates `ModelType` automatically
+
+The `/add-new-model` skill does all of the above end-to-end. See `.claude/skills/add-new-model/SKILL.md`.

grid_cortex_client-0.3.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: grid-cortex-client
+Version: 0.3.0
+Summary: Python client for Grid Cortex
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: msgpack-numpy>=0.4.0
+Requires-Dist: msgpack>=1.0.0
+Requires-Dist: numpy<2
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: requests>=2.20.0
+Requires-Dist: rerun-sdk==0.22.1
+Requires-Dist: websockets>=12.0
+Description-Content-Type: text/markdown
+
+# Grid Cortex Client
+
+[![PyPI version](https://img.shields.io/pypi/v/grid-cortex-client.svg)](https://pypi.org/project/grid-cortex-client/)
+[![Python](https://img.shields.io/pypi/pyversions/grid-cortex-client.svg)](https://pypi.org/project/grid-cortex-client/)
+
+Python client for [GRID Cortex](https://cortex.generalrobotics.dev).
+
+## Installation
+
+```bash
+pip install grid-cortex-client
+```
+
+## Quick Start
+
+```python
+from grid_cortex_client import CortexClient, ModelType
+
+client = CortexClient(api_key="your-api-key")
+
+# Monocular depth estimation
+depth_map = client.run(ModelType.ZOEDEPTH, image_input="path/to/image.jpg")
+```
+
+## Configuration
+
+Pass your API key and base URL directly, or set them as environment variables:
+
+```bash
+export GRID_CORTEX_API_KEY="your-api-key"
+export GRID_CORTEX_BASE_URL="https://cortex-prod.generalrobotics.dev/cortex"
+```
+
+```python
+# Explicit configuration
+client = CortexClient(api_key="your-key", base_url="https://...")
+
+# Or rely on environment variables
+client = CortexClient()
+```
+
+## Input Formats
+
+All image-based models accept multiple input types:
+
+- **File path:** `"path/to/image.jpg"`
+- **URL:** `"https://example.com/image.jpg"`
+- **PIL Image:** `Image.open("image.jpg")`
+- **NumPy array:** `np.ndarray` with shape `(H, W, 3)`
+
+## Async & Concurrent Inference
+
+The async client lets you call multiple models concurrently so total latency equals the **slowest** model, not the sum of all of them.
+
+### Concurrent multi-model example
+
+```python
+import asyncio
+import numpy as np
+from grid_cortex_client import AsyncCortexClient, ModelType
+
+async def run_perception_pipeline(image: np.ndarray):
+    """Run depth, detection, and segmentation concurrently on the same frame."""
+    async with AsyncCortexClient() as client:
+        depth, detections, mask = await asyncio.gather(
+            client.run(ModelType.ZOEDEPTH, image_input=image),
+            client.run(ModelType.OWLV2, image_input=image, prompt="bottle"),
+            client.run(ModelType.GSAM2, image_input=image, prompt="bottle"),
+        )
+    return depth, detections, mask
+
+depth, detections, mask = asyncio.run(
+    run_perception_pipeline(np.array(Image.open("scene.jpg")))
+)
+```
+
+### High-throughput streaming with pub/sub
+
+For continuous streams (e.g. camera feeds), the `CortexHubClient` uses WebSockets to overlap sending and receiving. While frame N's result is being returned, frame N+1 is already being processed server-side:
+
+```python
+import asyncio
+import numpy as np
+from grid_cortex_client import CortexHubClient, ModelType
+
+async def publisher(hub: CortexHubClient, frames: list[np.ndarray]):
+    """Send frames as fast as possible."""
+    for i, frame in enumerate(frames):
+        await hub.publish(ModelType.ZOEDEPTH, request_id=f"frame_{i}", image_input=frame)
+
+async def subscriber(hub: CortexHubClient, num_frames: int):
+    """Receive results as they arrive."""
+    count = 0
+    async for result in hub.subscribe():
+        if result.ok:
+            print(f"{result.request_id}: shape={result.data.shape}")
+        count += 1
+        if count >= num_frames:
+            break
+
+async def main():
+    frames = [np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)] * 100
+
+    async with CortexHubClient() as hub:
+        await asyncio.gather(
+            publisher(hub, frames),
+            subscriber(hub, len(frames)),
+        )
+
+asyncio.run(main())
+```
+
+## Documentation
+
+For model-specific usage examples, parameter references, and detailed guides, see the full documentation:
+
+**[docs.generalrobotics.dev/models/cortex](https://docs.generalrobotics.dev/models/cortex)**
+
+## Requirements
+
+- Python >= 3.8

grid_cortex_client-0.3.0/README.md

@@ -0,0 +1,121 @@
+# Grid Cortex Client
+
+[![PyPI version](https://img.shields.io/pypi/v/grid-cortex-client.svg)](https://pypi.org/project/grid-cortex-client/)
+[![Python](https://img.shields.io/pypi/pyversions/grid-cortex-client.svg)](https://pypi.org/project/grid-cortex-client/)
+
+Python client for [GRID Cortex](https://cortex.generalrobotics.dev).
+
+## Installation
+
+```bash
+pip install grid-cortex-client
+```
+
+## Quick Start
+
+```python
+from grid_cortex_client import CortexClient, ModelType
+
+client = CortexClient(api_key="your-api-key")
+
+# Monocular depth estimation
+depth_map = client.run(ModelType.ZOEDEPTH, image_input="path/to/image.jpg")
+```
+
+## Configuration
+
+Pass your API key and base URL directly, or set them as environment variables:
+
+```bash
+export GRID_CORTEX_API_KEY="your-api-key"
+export GRID_CORTEX_BASE_URL="https://cortex-prod.generalrobotics.dev/cortex"
+```
+
+```python
+# Explicit configuration
+client = CortexClient(api_key="your-key", base_url="https://...")
+
+# Or rely on environment variables
+client = CortexClient()
+```
+
+## Input Formats
+
+All image-based models accept multiple input types:
+
+- **File path:** `"path/to/image.jpg"`
+- **URL:** `"https://example.com/image.jpg"`
+- **PIL Image:** `Image.open("image.jpg")`
+- **NumPy array:** `np.ndarray` with shape `(H, W, 3)`
+
+## Async & Concurrent Inference
+
+The async client lets you call multiple models concurrently so total latency equals the **slowest** model, not the sum of all of them.
+
+### Concurrent multi-model example
+
+```python
+import asyncio
+import numpy as np
+from grid_cortex_client import AsyncCortexClient, ModelType
+
+async def run_perception_pipeline(image: np.ndarray):
+    """Run depth, detection, and segmentation concurrently on the same frame."""
+    async with AsyncCortexClient() as client:
+        depth, detections, mask = await asyncio.gather(
+            client.run(ModelType.ZOEDEPTH, image_input=image),
+            client.run(ModelType.OWLV2, image_input=image, prompt="bottle"),
+            client.run(ModelType.GSAM2, image_input=image, prompt="bottle"),
+        )
+    return depth, detections, mask
+
+depth, detections, mask = asyncio.run(
+    run_perception_pipeline(np.array(Image.open("scene.jpg")))
+)
+```
+
+### High-throughput streaming with pub/sub
+
+For continuous streams (e.g. camera feeds), the `CortexHubClient` uses WebSockets to overlap sending and receiving. While frame N's result is being returned, frame N+1 is already being processed server-side:
+
+```python
+import asyncio
+import numpy as np
+from grid_cortex_client import CortexHubClient, ModelType
+
+async def publisher(hub: CortexHubClient, frames: list[np.ndarray]):
+    """Send frames as fast as possible."""
+    for i, frame in enumerate(frames):
+        await hub.publish(ModelType.ZOEDEPTH, request_id=f"frame_{i}", image_input=frame)
+
+async def subscriber(hub: CortexHubClient, num_frames: int):
+    """Receive results as they arrive."""
+    count = 0
+    async for result in hub.subscribe():
+        if result.ok:
+            print(f"{result.request_id}: shape={result.data.shape}")
+        count += 1
+        if count >= num_frames:
+            break
+
+async def main():
+    frames = [np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)] * 100
+
+    async with CortexHubClient() as hub:
+        await asyncio.gather(
+            publisher(hub, frames),
+            subscriber(hub, len(frames)),
+        )
+
+asyncio.run(main())
+```
+
+## Documentation
+
+For model-specific usage examples, parameter references, and detailed guides, see the full documentation:
+
+**[docs.generalrobotics.dev/models/cortex](https://docs.generalrobotics.dev/models/cortex)**
+
+## Requirements
+
+- Python >= 3.8

grid_cortex_client-0.3.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "grid-cortex-client"
+dynamic = ["version"]
+description = "Python client for Grid Cortex"
+readme = "README.md"
+requires-python = ">=3.8"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "numpy<2",
+    "rerun-sdk==0.22.1",
+    "Pillow>=10.0.0",
+    "requests>=2.20.0",
+    "websockets>=12.0",
+    "msgpack>=1.0.0",
+    "msgpack-numpy>=0.4.0",
+]
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.uv]
+required-version = ">=0.7.20"
+exclude-newer = "7 days"
+
+[tool.hatch.version]
+source   = "env"
+variable = "BUILD_VERSION"
+
+[tool.hatch.version.raw-options]
+root = "../.."
+local_scheme = "no-local-version"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+    "integration: marks tests as integration tests",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+]

grid_cortex_client-0.3.0/src/grid_cortex_client/__init__.py

@@ -0,0 +1,30 @@
+"""Grid Cortex Python client.
+
+This package provides :class:`CortexClient` for high-level model inference.
+Use :class:`ModelType` enum to specify which model to run.
+"""
+
+import os
+
+# Public API first (ruff E402)
+from .model_type import ModelType  # re-export static enum
+from .tools.registry import registry  # shared model registry instance
+
+if os.environ.get("GRID_CORTEX_SKIP_PUBLIC_API") != "1":
+    from .cortex_client import AsyncCortexClient, CortexClient
+    from .cortex_hub_client import CortexHubClient, CortexHubError, HubResult
+
+# Configure the library logger to be silent by default **after** imports to satisfy E402.
+import logging
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "AsyncCortexClient",
+    "CortexClient",
+    "CortexHubClient",
+    "CortexHubError",
+    "HubResult",
+    "ModelType",
+    "registry",
+]