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.

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:

from nemo_helix_plugin.client.client import NemoClient
client = NemoClient(
    base_url="http://localhost:8080",
    workspace="default",
)

The NemoClient constructor accepts the following options.

Connection Modes

Use with_options(...) to clone a client with request defaults changed:

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.

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

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:

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.

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 entities, model providers, deployment configs, and deployments (client.models.create_provider, client.models.create_deployment_config, client.models.create_deployment, …)
• evaluator: Evaluations

Virtual models and the inference gateway have typed clients without a shortcut property. Build them from the main client:

from nemo_helix_plugin.client.client import NemoClient
from nemo_helix_plugin.inference_gateway.client import InferenceGatewayClient
from nemo_helix_plugin.virtual_models.client import VirtualModelsClient
client = NemoClient.from_config()
virtual_models = VirtualModelsClient.from_client(client)
gateway = InferenceGatewayClient.from_client(client)

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)