> This page is for NeMo Fabric, version Latest (v0.6.0) (default).
> For other versions, use one of these documentation indexes:
> - Latest (v0.6.0) (default): https://docs.nvidia.com/nemo/fabric/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/fabric/dev/llms.txt
> - v0.6.0: https://docs.nvidia.com/nemo/fabric/v0.6.0/llms.txt
> - v0.5.0: https://docs.nvidia.com/nemo/fabric/v0.5.0/llms.txt
> - v0.4.0: https://docs.nvidia.com/nemo/fabric/v0.4.0/llms.txt
> - v0.3.0: https://docs.nvidia.com/nemo/fabric/v0.3.0/llms.txt
> - v0.2.0: https://docs.nvidia.com/nemo/fabric/v0.2.0/llms.txt
> - v0.1.1: https://docs.nvidia.com/nemo/fabric/v0.1.1/llms.txt
> - v0.1.0: https://docs.nvidia.com/nemo/fabric/v0.1.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/fabric/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/fabric/_mcp/server.
# Client
> Resolve, plan, diagnose, and run agents with NVIDIA NeMo Fabric.
# module `nemo_fabric.client`
Native Python client for resolving and running NVIDIA NeMo Fabric agents.
---
## class `Fabric`
Primary Python entrypoint for NeMo Fabric.
Every config-dependent lifecycle method accepts a complete, typed ``FabricConfig`` plus an optional ``base_dir`` used to resolve relative paths. Compose variants in Python before calling the SDK. The ``doctor()``, ``plan()``, and ``run()`` results are typed, read-only mapping models. ``start_runtime()`` returns an active local ``Runtime`` handle. Explicit environment users call either ``prepare_environment()`` or ``attach_environment()``, then ``start_runtime_in()`` and ``release_environment()`` separately.
Software capture is deferred until enabled initialization so configuration can disable all lookups. A new Fabric instance refreshes the SDK snapshot. Embedded guest servers label their own SDK observations ``guest_sdk``.
``Fabric`` uses the native Rust extension. SDK calls raise ``FabricNativeUnavailableError`` when the native extension is not installed.
See the Getting Started overview for runnable single-invocation, typed-config, and multi-turn examples.
### method `__init__`
```python
def __init__() -> None
```
---
### method `attach_environment`
```python
async def attach_environment(
config: FabricConfig,
reference: EnvironmentReference,
*,
base_dir: str | os.PathLike[str] | None = None,
) -> EnvironmentHandle
```
Verify and attach to an existing caller-owned environment.
Attachment does not create the provider resource and does not grant Fabric deletion authority. Attachment is available only when the selected provider implements it. The returned handle can be passed to ``start_runtime_in()`` and later to ``release_environment()`` to detach.
**Args:**
- `config`: Complete typed ``FabricConfig`` with caller-owned environment settings.
- `reference`: Provider-specific identity of the existing resource.
- `base_dir`: Base directory for resolving relative paths.
**Returns:**
A verified, immutable ``EnvironmentHandle``.
**Raises:**
- `FabricConfigError`: If config, reference, or returned handle is invalid.
- `FabricNativeUnavailableError`: If the native extension is not installed.
- `FabricRuntimeError`: If environment verification or attachment fails.
---
### method `attach_service`
```python
async def attach_service(
config: FabricConfig,
reference: ServiceReference,
*,
base_dir: str | os.PathLike[str] | None = None,
) -> Service
```
Validate and attach to a caller-owned long-lived service.
The adapter validates the reference against the normalized configuration and writes any resolved credentials only to private, process-local connection material. Releasing the returned service detaches NeMo Fabric without stopping the caller-owned service.
**Args:**
- `config`: Complete typed ``FabricConfig``.
- `reference`: Adapter-specific endpoint and credential references. Do not include credential values.
- `base_dir`: Base directory for resolving relative paths.
**Returns:**
An active caller-owned ``Service``. Use it as an asynchronous context manager to guarantee detach.
**Raises:**
- `FabricConfigError`: If the reference, plan, or adapter configuration is invalid.
- `FabricNativeUnavailableError`: If the native extension is not installed.
- `FabricRuntimeError`: If attachment or validation fails.
---
### method `check`
```python
async def check(
*,
request: CheckRequest,
environment: EnvironmentHandle | None = None,
service: ServiceHandle | None = None,
) -> CheckReport
```
Check server, runtime, or service health.
OpenShell checks execute ``fabric-agent-ctl check`` inside the selected sandbox. Runtime checks then use the local SDK and an independent adapter health channel. Local server checks return unsupported. The request's single deadline covers routing, all levels, and decoding. Timeouts return ``unknown`` with reason ``probe_timeout``. Service checks use the selected process-local ``ServiceHandle``.
**Args:**
- `environment`: Prepared or attached environment for server or runtime scope.
- `service`: Prepared or attached service handle for service scope.
- `request`: Typed scope, runtime or service target, highest level, and timeout.
**Returns:**
An immutable ``CheckReport`` with ordered health observations.
**Raises:**
- `FabricConfigError`: If arguments or returned evidence are invalid.
- `FabricNativeUnavailableError`: If the native extension is missing.
- `FabricRuntimeError`: If transport fails before a report can be formed.
---
### method `doctor`
```python
async def doctor(
config: FabricConfig,
*,
base_dir: str | os.PathLike[str] | None = None,
) -> DoctorReport
```
Diagnose a planned agent without starting its runtime.
Doctor checks the resolved adapter, capability mappings, and declared environment requirements using the native NeMo Fabric core.
**Args:**
- `config`: Complete typed ``FabricConfig``.
- `base_dir`: Base directory for resolving relative paths.
**Returns:**
A ``DoctorReport`` with aggregate status and ordered checks.
**Raises:**
- `FabricConfigError`: If inputs or native diagnostic output are invalid.
- `FabricNativeUnavailableError`: If the native extension is not installed.
---
### method `plan`
```python
def plan(
config: FabricConfig,
*,
base_dir: str | os.PathLike[str] | None = None,
) -> RunPlan
```
Resolve a complete typed configuration into an immutable execution plan.
Planning resolves the selected adapter and reports optional runtime capabilities such as streaming, updates, and cancellation. Planning does not start the runtime.
**Args:**
- `config`: Complete typed ``FabricConfig``. Raw mappings are not accepted.
- `base_dir`: Base directory for resolving relative paths.
**Returns:**
A ``RunPlan`` containing the canonical config, path context, adapter, and declared runtime capabilities.
**Raises:**
- `FabricConfigError`: If the config or adapter resolution is invalid.
- `FabricNativeUnavailableError`: If the native extension is not installed.
---
### method `prepare_environment`
```python
async def prepare_environment(
config: FabricConfig,
*,
base_dir: str | os.PathLike[str] | None = None,
) -> EnvironmentHandle
```
Prepare an execution environment.
The returned local handle is independent of any runtime session. The caller owns the lifecycle decision and must eventually pass it to ``release_environment()``. Non-local providers must add their own preparation support before they can be used here.
**Args:**
- `config`: Complete typed ``FabricConfig`` describing the environment.
- `base_dir`: Base directory for resolving relative paths.
**Returns:**
A typed, immutable ``EnvironmentHandle``.
**Raises:**
- `FabricConfigError`: If config resolution or the returned handle is invalid.
- `FabricNativeUnavailableError`: If the native extension is not installed.
- `FabricRuntimeError`: If environment preparation fails.
---
### method `prepare_service`
```python
async def prepare_service(
config: FabricConfig,
*,
base_dir: str | os.PathLike[str] | None = None,
) -> Service
```
Create and supervise a Fabric-owned long-lived service.
The selected adapter maps the normalized configuration into its service configuration. The returned handle is process-local and can be shared by multiple runtimes created from the same resolved plan.
**Args:**
- `config`: Complete typed ``FabricConfig``.
- `base_dir`: Base directory for resolving relative paths.
**Returns:**
An active Fabric-owned ``Service``. Use it as an asynchronous context manager to guarantee shutdown.
**Raises:**
- `FabricConfigError`: If planning or adapter configuration is invalid.
- `FabricNativeUnavailableError`: If the native extension is not installed.
- `FabricRuntimeError`: If service startup fails.
---
### method `release_environment`
```python
async def release_environment(environment: EnvironmentHandle) -> None
```
Release or detach a prepared environment through its provider.
Local and externally owned environments detach without deletion. Provider-managed, Fabric-owned environments may be deleted according to their normalized ownership contract.
**Args:**
- `environment`: Handle returned by ``prepare_environment()`` or ``attach_environment()``.
**Raises:**
- `FabricConfigError`: If ``environment`` is not a typed handle.
- `FabricNativeUnavailableError`: If the native extension is not installed.
- `FabricRuntimeError`: If release or detach fails.
---
### method `run`
```python
async def run(
config: FabricConfig,
*,
base_dir: str | os.PathLike[str] | None = None,
input: Any = None,
request: RunRequest | None = None,
expected_descriptor_sha256: str | None = None,
) -> RunResult
```
Execute one complete start, invoke, and stop lifecycle.
``input`` and ``request`` are mutually exclusive. Omitting both produces an empty text input. Use ``RunRequest`` when the invocation needs a caller-owned request ID, context, or overrides. NeMo Fabric attempts to stop a started runtime even when invocation fails.
**Args:**
- `config`: Complete typed ``FabricConfig``.
- `base_dir`: Base directory for resolving relative paths.
- `input`: JSON-compatible invocation input.
- `request`: Complete validated ``RunRequest``.
- `expected_descriptor_sha256`: Optional host-inspection fingerprint. Reject descriptor drift before starting the runtime.
**Returns:**
The normalized ``RunResult``, including output, artifacts, telemetry references, lifecycle events, and structured error data.
**Raises:**
- `FabricConfigError`: If input and request are combined, request data is not JSON-compatible, or config resolution fails.
- `FabricNativeUnavailableError`: If the native extension is not installed.
- `FabricRuntimeError`: If the native runtime lifecycle fails before a normalized result can be returned.
---
### method `start_runtime`
```python
async def start_runtime(
config: FabricConfig,
*,
base_dir: str | os.PathLike[str] | None = None,
overrides: Mapping[str, Any] | None = None,
streaming: bool = False,
launch_collector: bool | None = None,
completion_wait_timeout: float = 1.0,
service: Service | None = None,
expected_descriptor_sha256: str | None = None,
) -> Runtime
```
Start a stateful runtime for one or more ordered invocations.
Each call starts a new logical runtime. Runtime-scoped overrides are recursively merged below invocation-scoped overrides. With NVIDIA NeMo Relay enabled, ``streaming=True`` uses collector-backed streaming. By default, streaming starts an embedded collector. Set ``launch_collector=False`` to use an externally managed collector. Pi requires the embedded collector because its ATOF records do not carry NeMo Fabric request IDs.
**Args:**
- `config`: Complete typed ``FabricConfig``.
- `base_dir`: Base directory for resolving relative paths.
- `overrides`: JSON-compatible overrides applied to every invocation in the runtime unless superseded by invocation overrides.
- `streaming`: Whether to enable collector-backed NeMo Relay ATOF streaming for ``Runtime.invoke_stream()``.
- `launch_collector`: Whether to launch an embedded collector. ``None`` defaults to ``True`` when streaming is enabled. ``False`` uses an externally managed collector. Pi does not support ``False``. This argument cannot be set unless ``streaming=True``.
- `completion_wait_timeout`: Maximum seconds the embedded collector waits for a Pi ``agent_settled`` marker after invocation. Increase this value when Relay delivery can be delayed. This value is ignored unless Pi streaming uses the embedded collector.
- `service`: Optional prepared or attached service. When supplied, the runtime connects to that service instead of creating its own.
- `expected_descriptor_sha256`: Optional descriptor fingerprint from host inspection. Matching metadata does not qualify an attached service's deployment-owned skills or MCP configuration.
**Returns:**
An active ``Runtime``. Use it as an asynchronous context manager to guarantee runtime shutdown.
**Raises:**
- `FabricConfigError`: If inputs or overrides are invalid, streaming is requested without NeMo Relay enabled, ``launch_collector`` is set without streaming, Pi is configured with an external collector, or an external collector has no sink.
- `FabricNativeUnavailableError`: If the native extension is not installed.
- `FabricRuntimeError`: If runtime startup fails.
---
### method `start_runtime_in`
```python
async def start_runtime_in(
config: FabricConfig,
environment: EnvironmentHandle,
*,
base_dir: str | os.PathLike[str] | None = None,
overrides: Mapping[str, Any] | None = None,
streaming: bool = False,
) -> Runtime
```
Start one stateful runtime in an explicitly prepared or attached environment.
Starting or stopping the runtime does not release ``environment``. Runtime and reuse limits depend on the provider. Release the environment separately after stopping the runtime and collecting results. Runtime startup is supported by local environments and the OpenShell command bridge. OpenShell invocation is buffered and supports multiple runtime IDs per sandbox.
**Args:**
- `config`: Complete typed ``FabricConfig`` matching the environment.
- `environment`: Handle returned by ``prepare_environment()`` or ``attach_environment()``.
- `base_dir`: Base directory for resolving relative paths.
- `overrides`: JSON-compatible runtime-scoped invocation overrides.
- `streaming`: Whether to provision NeMo Relay ATOF streaming.
**Returns:**
An active ``Runtime`` bound to ``environment``.
**Raises:**
- `FabricConfigError`: If inputs are invalid or the handle does not match the plan.
- `FabricNativeUnavailableError`: If the native extension is not installed.
- `FabricRuntimeError`: If runtime startup fails.
---
_This file was automatically generated via [lazydocs](https://github.com/ml-tooling/lazydocs)._