Grid Cortex Client
Python client for GRID Cortex.
Installation
pip install grid-cortex-client
Quick Start
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:
export GRID_CORTEX_API_KEY="your-api-key"
export GRID_CORTEX_BASE_URL="https://cortex-prod.generalrobotics.dev/cortex"
# Explicit configuration
client = CortexClient(api_key="your-key", base_url="https://...")
# Or rely on environment variables
client = CortexClient()
Input Formats
RGB and stereo model inputs 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.ndarraywith shape(H, W, 3) - GRID Image:
grid_types.Image
For RGB and stereo models, encoded JPEG and PNG GRID Images are forwarded without decoding or re-encoding. Other GRID Image inputs follow the model's existing conversion path; PI05 still resizes its images to 224×224 before sending them. Numerical depth and segmentation inputs retain their existing NumPy/NPY contract.
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
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:
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
Requirements
- Python >= 3.8
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file grid_cortex_client-1.0.8-py3-none-any.whl.
File metadata
- Download URL: grid_cortex_client-1.0.8-py3-none-any.whl
- Upload date:
- Size: 74.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
408d38c78d41964feef39bf03441a0ca2f6c4721d311db28e647449df041d07d
|
|
| MD5 |
58e17097062dbd0c997a0f7ece616861
|
|
| BLAKE2b-256 |
3b4dcc5c0bc5506a6de8a27a3c22c96097640a4366fcba795512e0e66e71abc3
|
