GRID Docs | General Robotics

from grid_cortex_client import CortexClient

Client for interacting with Grid Cortex Ray Serve deployments.

Constructor

CortexClient(api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: float = 30.0)

Initializes the CortexClient.

API key. Uses GRID_CORTEX_API_KEY env var if None.

Base URL of the Cortex API. If None, uses GRID_CORTEX_BASE_URL env var or HTTPClient’s default.

default:"30.0"

Default timeout for HTTP requests in seconds.

Methods

`available_models()`

available_models() -> list[str]

Return all registered model identifiers. This method provides a complete list of all available models that can be used with the CortexClient. Essential for LLM agents to discover what models are available before attempting to use them. Returns: A sorted list of model identifiers (e.g., [“gsam2”, “owlv2”, “zoedepth”]). These strings can be used directly with run and help.

client = CortexClient()
models = client.available_models()
print(models)  # ['gsam2', 'owlv2', 'zoedepth']
client.run(models[0], image_input=img)  # Use first available model

`close()`

close()

Closes the underlying HTTP client.

`get_info()`

get_info() -> Dict[str, Any]

Get Grid-Cortex server version and deployed models status. Fetches real-time information about the Cortex deployment including version and current model replica counts. Returns: Dictionary containing:

version (str): Grid-Cortex version (e.g., “v0.2.49”)
models (list): List of deployed models with:
- name (str): Model identifier
- status (str): Deployment status (“RUNNING”, etc.)
- route (str): HTTP route prefix
- replicas (int): Number of running replicas

Raises: CortexAPIError: If the API returns an error. CortexNetworkError: If network communication fails.

client = CortexClient()
info = client.get_info()
print(info["version"])
print(f"ZoeDepth has {info['models'][0]['replicas']} replicas")

`help()`

help(model_id: str) -> str

Return comprehensive documentation for a model. This method provides complete API documentation for any registered model, including usage examples, parameter descriptions, return types, and error conditions. Essential for LLM agents to understand how to interact with specific models before calling run.

required

Canonical model identifier (e.g., “zoedepth”, “owlv2”, “gsam2”).

Returns: A formatted string containing:

Class-level docstring with usage examples and parameter descriptions
Preprocess method documentation (input parameters and validation)
Postprocess method documentation (output format and data types)

Raises: NotImplementedError: If model_id is not registered or not found.

client = CortexClient()
docs = client.help("zoedepth")
print(docs)  # Shows complete zoedepth documentation
# For LLM agents: discover model capabilities
models = client.available_models()
for model in models:
    print(f"=== {model} ===")
    print(client.help(model))

`run()`

run(model_id: Union[str, ModelType], timeout: Optional[float] = None, debug: bool = False, raw_response: bool = False, **kwargs: Any) -> Any

Execute inference using a specified model with given inputs. This is the primary method for running AI model inference. It automatically handles model discovery, input preprocessing, API communication, and output postprocessing. Essential for LLM agents to perform actual model inference after discovering available models and understanding their requirements.

required

The identifier of the model to run (use available_models to see all available options). Examples: “zoedepth”, “owlv2”, “gsam2”.

Optional timeout in seconds for the HTTP request. If None, uses the client’s default timeout.

default:"False"

If True, enables detailed logging for this specific call to help troubleshoot issues.

default:"False"

If True, returns the raw API response without postprocessing.

Model-specific input parameters. Each model’s page in the Cortex Models docs section and help document its exact inputs.

Returns: The model’s postprocessed output; the concrete type is model-specific. Per-model inputs, output types, and worked examples live on the model pages in the Cortex Models docs section — generated from each model wrapper’s docstring, the canonical source — and via help. Raises: NotImplementedError: If model_id is not found in available models. CortexAPIError: If the API returns an error response. CortexNetworkError: If network communication fails. ValueError: If input validation or processing fails.

client = CortexClient()
output = client.run(ModelType.ZOEDEPTH, image_input="scene.jpg")

`run_with_detections()`

run_with_detections(model_id: Union[str, ModelType], timeout: Optional[float] = None, **kwargs: Any) -> Dict[str, Any]

Like run, but returns per-instance detections (currently SAM3 text/box prompts).

​Constructor

​Methods

​available_models()

​close()

​get_info()

​help()

​run()

​run_with_detections()