# Client APIs

The following reference provides detailed documentation for the synchronous and asynchronous clients of the {{platform_name}} Python SDK.

## Synchronous Client

Use `nemo_platform.NeMoPlatform` from regular Python code when you want blocking API calls.
The client reads the active CLI context by default, including the base URL,
workspace, and authentication settings configured by `nemo auth login`.

```python
from nemo_platform import NeMoPlatform

client = NeMoPlatform()

for workspace in client.workspaces.list().data:
    print(workspace.name)
```

### Constructor

```python
NeMoPlatform(
    *,
    workspace: str | None = None,
    base_url: str | httpx.URL | None = None,
    inference_base_url: str | httpx.URL | None = None,
    config_path: pathlib.Path | None = None,
    context_name: str | None = None,
    access_token: str | None = None,
    timeout: float | httpx.Timeout | None = not_given,
    max_retries: int = DEFAULT_MAX_RETRIES,
    default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
    http_client: httpx.Client | None = None,
)
```

| Parameter | Description |
| --- | --- |
| `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. |
| `base_url` | Base URL for the {{platform_name}} API. If omitted, the client reads it from the active CLI context. |
| `inference_base_url` | Optional override for inference gateway requests. Defaults to `base_url`. |
| `config_path` | Path to the CLI config file. Defaults to `~/.config/nmp/config.yaml`. |
| `context_name` | Named CLI context to read from the config file. |
| `access_token` | Explicit bearer token for automation. Token refresh is not performed for explicit tokens. |
| `timeout` | Request timeout for API calls. Pass a float in seconds, an `httpx.Timeout`, or `None`. |
| `max_retries` | Number of automatic retries for transient failures. |
| `default_headers` | Headers sent with every request. |
| `default_query` | Query parameters appended to every request. |
| `http_client` | Custom `httpx.Client`. When provided, config and auth bootstrap are skipped. |

### Connection Modes

| Mode | Example | Behavior |
| --- | --- | --- |
| CLI context | `NeMoPlatform()` | Reads the active CLI context and uses configured authentication with token refresh. |
| Named context | `NeMoPlatform(context_name="dev")` | Reads a specific CLI context instead of the active one. |
| Direct API | `NeMoPlatform(base_url="http://localhost:8080")` | Uses the given URL without reading config or injecting auth headers. |
| Explicit token | `NeMoPlatform(base_url=url, access_token=token)` | Uses the provided bearer token for API calls. |

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

```python
short_timeout_client = client.with_options(timeout=10.0)
```

## Asynchronous Client

Use `nemo_platform.AsyncNeMoPlatform` from `asyncio` applications. It exposes the same
resource tree as `NeMoPlatform`, but API methods are awaited.

```python
import asyncio

from nemo_platform import AsyncNeMoPlatform


async def main() -> None:
    client = AsyncNeMoPlatform()
    page = await client.workspaces.list()
    for workspace in page.data:
        print(workspace.name)


asyncio.run(main())
```

### Async client constructor

```python
AsyncNeMoPlatform(
    *,
    workspace: str | None = None,
    base_url: str | httpx.URL | None = None,
    inference_base_url: str | httpx.URL | None = None,
    config_path: pathlib.Path | None = None,
    context_name: str | None = None,
    access_token: str | None = None,
    timeout: float | httpx.Timeout | None = not_given,
    max_retries: int = DEFAULT_MAX_RETRIES,
    default_headers: Mapping[str, str] | None = None,
    default_query: Mapping[str, object] | None = None,
    http_client: httpx.AsyncClient | None = None,
)
```

`AsyncNeMoPlatform` accepts the same connection and authentication parameters as
`NeMoPlatform`. Pass a custom `httpx.AsyncClient` through `http_client` only when
you need to control the underlying transport directly.

```python
import os

from nemo_platform import AsyncNeMoPlatform

client = AsyncNeMoPlatform(
    base_url=os.environ["NMP_BASE_URL"],
    access_token=os.environ["NMP_ACCESS_TOKEN"],
    workspace="default",
)
```

### Errors

Client construction raises `RuntimeError` if configuration or authentication bootstrap fails.
Workspace-scoped methods raise `ValueError` when no workspace is provided on the client or
method call.

API calls raise typed exceptions from `nemo_platform`, including:

| Exception | Typical HTTP status |
| --- | --- |
| `BadRequestError` | `400` |
| `AuthenticationError` | `401` |
| `PermissionDeniedError` | `403` |
| `NotFoundError` | `404` |
| `ConflictError` | `409` |
| `UnprocessableEntityError` | `422` |
| `RateLimitError` | `429` |
| `InternalServerError` | `5xx` |

Catch `APIStatusError` for all non-success HTTP responses, or `NeMoPlatformError`
for SDK-level errors.

## Client Attributes

The {{platform_name}} clients provide access to API resources through the following attributes.
For endpoint details, see the [REST API Reference](../../api/index.md).

### Organization

- **workspaces**: Manage workspaces
- **projects**: Manage projects within a workspace

### Model Management

- **models**: Model entity CRUD
- **evaluation**: Benchmarks, benchmark jobs, metrics, and metric jobs
- **inference**: Deployments, deployment configs, providers, and OpenAI-compatible gateway

### Data & Synthesis

- **data_designer**: Synthetic data generation jobs
- **safe_synthesizer**: PII replacement and safe data synthesis jobs
- **files**: File upload and download

### Safety & Compliance

- **guardrail**: Guardrail configurations and checks
- **audit**: Model safety audit jobs and configs

### Platform

- **jobs**: Cross-service job management
- **entities**: Generic entity CRUD
- **secrets**: Secret management
- **iam**: Identity and access management
- **workspaces.members**: Workspace member and RBAC management

### Response Handling

- **with_raw_response**: Access raw HTTP response data
- **with_streaming_response**: Handle streaming responses
