> ## Documentation Index
> Fetch the complete documentation index at: https://docs.generalrobotics.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CortexClient

> Client for interacting with Grid Cortex Ray Serve deployments

```python theme={null}
from grid_cortex_client import CortexClient
```

Client for interacting with Grid Cortex Ray Serve deployments.

## Constructor

```python theme={null}
CortexClient(api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: float = 30.0)
```

Initializes the CortexClient.

<ParamField body="api_key">
  API key. Uses GRID\_CORTEX\_API\_KEY env var if None.
</ParamField>

<ParamField body="base_url">
  Base URL of the Cortex API. If None, uses GRID\_CORTEX\_BASE\_URL env var or HTTPClient's default.
</ParamField>

<ParamField body="timeout" default="30.0">
  Default timeout for HTTP requests in seconds.
</ParamField>

## Methods

### `available_models()`

```python theme={null}
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`.

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

### `close()`

```python theme={null}
close()
```

Closes the underlying HTTP client.

### `get_info()`

```python theme={null}
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.

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

### `help()`

```python theme={null}
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`.

<ParamField body="model_id" required>
  Canonical model identifier (e.g., "zoedepth", "owlv2", "gsam2").
</ParamField>

**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.

```python theme={null}
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()`

```python theme={null}
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.

<ParamField body="model_id" required>
  The identifier of the model to run (use `available_models` to see all available options). Examples: "zoedepth", "owlv2", "gsam2".
</ParamField>

<ParamField body="timeout">
  Optional timeout in seconds for the HTTP request. If None, uses the client's default timeout.
</ParamField>

<ParamField body="debug" default="False">
  If True, enables detailed logging for this specific call to help troubleshoot issues.
</ParamField>

<ParamField body="raw_response" default="False">
  If True, returns the raw API response without postprocessing.
</ParamField>

<ParamField body="**kwargs">
  Model-specific input parameters. Each model's page in the **Cortex Models** docs section and `help` document its exact inputs.
</ParamField>

**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.

```python theme={null}
client = CortexClient()
output = client.run(ModelType.ZOEDEPTH, image_input="scene.jpg")
```

### `run_with_detections()`

```python theme={null}
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).


## Related topics

- [GRID Cortex Client](/models/cortex.md)
- [grid-cortex-client](/python-api/grid-cortex-client/overview.md)
- [CortexHubClient](/python-api/grid-cortex-client/cortexhubclient.md)
- [AsyncCortexClient](/python-api/grid-cortex-client/asynccortexclient.md)
- [CortexHubError](/python-api/grid-cortex-client/cortexhuberror.md)