GRID Docs | General Robotics

from grid_cortex_client import AsyncCortexClient

Async client for interacting with Grid Cortex Ray Serve deployments.

Constructor

Signature

AsyncCortexClient(
    api_key: Optional[str] = None,
    base_url: Optional[str] = None,
    timeout: float = 30.0,
    *,
    observer: Optional[RuntimeObserver] = None,
)

Initialize the AsyncCortexClient.

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.

default:"30.0"

Default timeout for HTTP requests in seconds.

Optional caller-owned observer for run events. The client does not close it.

Methods

`available_models()`

Signature

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()`

Signature

close()

Closes the underlying async HTTP client.

`get_info()`

Signature

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 and models information. Raises: CortexAPIError: If the API returns an error. CortexNetworkError: If network communication fails.

`help()`

Signature

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()`

Signature

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

Execute inference using a specified model (async version).

required

The identifier of the model to run.

Optional timeout in seconds for the HTTP request.

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. CortexAPIError: If the API returns an error. CortexNetworkError: If network communication fails. ValueError: If input validation or processing fails.

​Constructor

​Methods

​available_models()

​close()

​get_info()

​help()

​run()

Constructor

Methods

`available_models()`

`close()`

`get_info()`

`help()`

`run()`