> This page is for version 0.8.0. > For other versions, use one of these documentation indexes: > - Latest (default): https://docs.nvidia.com/nemo-helix/latest/llms.txt > - 0.8.0: https://docs.nvidia.com/nemo-helix/v0.8.0/llms.txt > - 0.7.1: https://docs.nvidia.com/nemo-helix/v0.7.1/llms.txt > - 0.7.0: https://docs.nvidia.com/nemo-helix/v0.7.0/llms.txt > - 0.6.0: https://docs.nvidia.com/nemo-helix/v0.6.0/llms.txt > - 0.5.1: https://docs.nvidia.com/nemo-helix/v0.5.1/llms.txt > - 0.5.0: https://docs.nvidia.com/nemo-helix/v0.5.0/llms.txt > - 0.4.0: https://docs.nvidia.com/nemo-helix/v0.4.0/llms.txt > - 0.3.0: https://docs.nvidia.com/nemo-helix/v0.3.0/llms.txt > - 0.2.0: https://docs.nvidia.com/nemo-helix/v0.2.0/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo-helix/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo-helix/_mcp/server. # Client APIs The following reference provides detailed documentation for the synchronous and asynchronous clients of the NeMo Helix Python SDK. ## Synchronous Client Use `NemoClient` from regular Python code when you want blocking API calls. The typed client talks directly to the NeMo Helix HTTP API. In most code, build it with `from_config()`, which reads the base URL, default workspace, and credentials from your current CLI context. To configure contexts, see [Connect with CLI Contexts](/documentation/reference/cli-reference/connect-to-deployments). ```python from nemo_helix_plugin.client.client import NemoClient client = NemoClient.from_config() for workspace in client.workspaces.list_workspaces().items(): print(workspace.name) ``` ### Constructor To connect without reading the CLI configuration, pass the connection settings directly: ```python from nemo_helix_plugin.client.client import NemoClient client = NemoClient( base_url="http://localhost:8080", workspace="default", ) ``` The `NemoClient` constructor accepts the following options. | Parameter | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `base_url` | Base URL of the NeMo Helix API (required). For example `http://localhost:8080`. | | `workspace` | Workspace name used by workspace-scoped routes. You can set it on the client or pass it to individual methods that accept a workspace argument. | | `auth` | A token provider, or a static bearer token string, used to authenticate requests. | | `default_headers` | Headers sent with every request. | | `timeout` | Request timeout for API calls. Pass a float in seconds, an `httpx.Timeout`, or `None`. | | `retry` | A `RetryPolicy` describing when and how many times to retry transient failures. | | `http_client` | Custom `httpx.Client`. When provided, the client shares that transport instead of building its own. | | `owns_http_client` | Whether the client owns (and closes) `http_client`. Defaults to `True` when `http_client` is not provided. | ### Connection Modes | Mode | Example | Behavior | | ------------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CLI context (recommended) | `NemoClient.from_config()` | Reads the active CLI context (base URL, workspace, auth) configured by `nemo setup` / `nemo auth login`. `NHX_*` environment variables such as `NHX_BASE_URL` and `NHX_ACCESS_TOKEN` override the saved values. | | Named context | `NemoClient.from_config(context="dev")` | Reads a specific CLI context instead of the active one. | | Explicit config path | `NemoClient.from_config(config_path="/path/to/config.yaml")` | Reads a specific CLI config file. | | Direct API | `NemoClient(base_url="http://localhost:8080")` | Uses the given URL, workspace, and any explicit auth without reading a config file. | Use `with_options(...)` to clone a client with request defaults changed: ```python short_timeout_client = client.with_options(timeout=10.0) ``` ## Asynchronous Client Use `AsyncNemoClient` from `asyncio` applications. It exposes the same resource tree as `NemoClient`, but API methods are awaited. ```python import asyncio from nemo_helix_plugin.client.client import AsyncNemoClient async def main() -> None: client = AsyncNemoClient.from_config() async for workspace in client.workspaces.list_workspaces().items(): print(workspace.name) asyncio.run(main()) ``` ### Async client constructor ```python from nemo_helix_plugin.client.client import AsyncNemoClient client = AsyncNemoClient( base_url="http://localhost:8080", workspace="default", ) ``` `AsyncNemoClient` accepts the same connection and authentication parameters as `NemoClient`, and `AsyncNemoClient.from_config()` accepts the same arguments as `NemoClient.from_config()`. Pass a custom `httpx.AsyncClient` through `http_client` only when you need to control the underlying transport directly. ### Errors API calls raise typed exceptions from `nemo_helix_plugin.client.errors`: | Exception | Typical HTTP status | | -------------------------- | ------------------- | | `BadRequestError` | `400` | | `AuthenticationError` | `401` | | `PermissionDeniedError` | `403` | | `NotFoundError` | `404` | | `ConflictError` | `409` | | `UnprocessableEntityError` | `422` | | `RateLimitError` | `429` | | `InternalServerError` | `5xx` | Catch `NemoHTTPError` for all non-success HTTP responses, or `NemoClientError` for SDK-level errors. Transport failures raise `NemoTransportError`. ## Client Attributes The NeMo Helix clients provide access to API resources through the following properties. Each returns a typed per-service client that shares the main client's transport. For endpoint details, see the [REST API Reference](/documentation/reference/api-reference). ### Organization * **workspaces**: Manage workspaces (via the entity store) * **projects**: Manage projects within a workspace * **iam**: Identity and access management * **auth**: Authentication * **access\_keys**: Access keys ### Model Management * **models**: Model entity CRUD * **inference**: Providers, deployments, deployment configs, and virtual models (`client.inference.providers`, `client.inference.deployments`, `client.inference.deployment_configs`, `client.inference.virtual_models`) * **evaluator**: Evaluations ### Data & Synthesis * **files**: Filesets and file upload/download * **data\_designer**: Synthetic data generation jobs * **intake**: Telemetry intake ### Safety & Compliance * **guardrail**: Guardrail configurations and checks * **garak**: Model safety audit jobs and configs * **agent\_hardener**: Agent hardening ### Platform * **jobs**: Cross-service job management * **agents**: Deployed agents * **secrets**: Secret management ### Plugin resources Plugin-owned resources are resolved from the `nemo.sdk` entry point and exposed as client attributes (for example `client.customization` for the Customizer plugin, or `client.agents` for the Agents plugin when provided by a plugin). Use them the same way as core resources. ### Response Handling Each method returns a typed response: * `NemoResponse` (`.data()` for the parsed entity, `.http_response` for the raw `httpx.Response`) * `NemoPaginatedResponse` (`.items()` and `.pages()` for paginated lists) * `NemoBinaryResponse` (`.read()` or `.stream()` for binary downloads) * `NemoStreamResponse` (`.stream()` for streaming responses)