> This page is for NeMo Fabric, version v0.7.0.
> For other versions, use one of these documentation indexes:
> - Latest (v0.7.0) (default): https://docs.nvidia.com/nemo/fabric/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/fabric/dev/llms.txt
> - v0.7.0: https://docs.nvidia.com/nemo/fabric/v0.7.0/llms.txt
> - v0.6.1: https://docs.nvidia.com/nemo/fabric/v0.6.1/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.

# Client

> Resolve, plan, diagnose, and run agents with NVIDIA NeMo Fabric.

# <kbd>module</kbd> `nemo_fabric.client`

Native Python client for resolving and running NVIDIA NeMo Fabric agents.



---


## <kbd>class</kbd> `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.


### <kbd>method</kbd> `__init__`

```python
def __init__() -> None
```








---


### <kbd>method</kbd> `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:**

 - <b>`config`</b>:  Complete typed ``FabricConfig`` with caller-owned environment settings.
 - <b>`reference`</b>:  Provider-specific identity of the existing resource.
 - <b>`base_dir`</b>:  Base directory for resolving relative paths.



**Returns:**
 A verified, immutable ``EnvironmentHandle``.



**Raises:**

 - <b>`FabricConfigError`</b>:  If config, reference, or returned handle is invalid.
 - <b>`FabricNativeUnavailableError`</b>:  If the native extension is not installed.
 - <b>`FabricRuntimeError`</b>:  If environment verification or attachment fails.

---


### <kbd>method</kbd> `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:**

 - <b>`config`</b>:  Complete typed ``FabricConfig``.
 - <b>`reference`</b>:  Adapter-specific endpoint and credential references.  Do not include credential values.
 - <b>`base_dir`</b>:  Base directory for resolving relative paths.



**Returns:**
 An active caller-owned ``Service``. Use it as an asynchronous context manager to guarantee detach.



**Raises:**

 - <b>`FabricConfigError`</b>:  If the reference, plan, or adapter configuration  is invalid.
 - <b>`FabricNativeUnavailableError`</b>:  If the native extension is not  installed.
 - <b>`FabricRuntimeError`</b>:  If attachment or validation fails.

---


### <kbd>method</kbd> `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:**

 - <b>`environment`</b>:  Prepared or attached environment for server or runtime scope.
 - <b>`service`</b>:  Prepared or attached service handle for service scope.
 - <b>`request`</b>:  Typed scope, runtime or service target, highest level, and timeout.



**Returns:**
 An immutable ``CheckReport`` with ordered health observations.



**Raises:**

 - <b>`FabricConfigError`</b>:  If arguments or returned evidence are invalid.
 - <b>`FabricNativeUnavailableError`</b>:  If the native extension is missing.
 - <b>`FabricRuntimeError`</b>:  If transport fails before a report can be formed.

---


### <kbd>method</kbd> `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:**

 - <b>`config`</b>:  Complete typed ``FabricConfig``.
 - <b>`base_dir`</b>:  Base directory for resolving relative paths.



**Returns:**
 A ``DoctorReport`` with aggregate status and ordered checks.



**Raises:**

 - <b>`FabricConfigError`</b>:  If inputs or native diagnostic output are  invalid.
 - <b>`FabricNativeUnavailableError`</b>:  If the native extension is not  installed.

---


### <kbd>method</kbd> `invocation_result`

```python
async def invocation_result(
    *,
    agent_name: str,
    runtime_id: str,
    request_id: str,
    artifacts: str | os.PathLike[str] | None = None,
    environment: EnvironmentHandle | None = None,
) -> RunResult | None
```

Retrieve a saved invocation without executing or repeating work.

Supply the original request identifier. A null result means no completed result is available; it does not prove that work is running or safe to repeat. Local reads use the configured artifact root. OpenShell reads use the owning runtime server through ``fabric-agent-ctl result``. Files survive only while their artifact storage survives.

---


### <kbd>method</kbd> `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:**

 - <b>`config`</b>:  Complete typed ``FabricConfig``. Raw mappings are not  accepted.
 - <b>`base_dir`</b>:  Base directory for resolving relative paths.



**Returns:**
 A ``RunPlan`` containing the canonical config, path context, adapter, and declared runtime capabilities.



**Raises:**

 - <b>`FabricConfigError`</b>:  If the config or adapter resolution is invalid.
 - <b>`FabricNativeUnavailableError`</b>:  If the native extension is not  installed.

---


### <kbd>method</kbd> `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:**

 - <b>`config`</b>:  Complete typed ``FabricConfig`` describing the environment.
 - <b>`base_dir`</b>:  Base directory for resolving relative paths.



**Returns:**
 A typed, immutable ``EnvironmentHandle``.



**Raises:**

 - <b>`FabricConfigError`</b>:  If config resolution or the returned handle is invalid.
 - <b>`FabricNativeUnavailableError`</b>:  If the native extension is not installed.
 - <b>`FabricRuntimeError`</b>:  If environment preparation fails.

---


### <kbd>method</kbd> `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:**

 - <b>`config`</b>:  Complete typed ``FabricConfig``.
 - <b>`base_dir`</b>:  Base directory for resolving relative paths.



**Returns:**
 An active Fabric-owned ``Service``. Use it as an asynchronous context manager to guarantee shutdown.



**Raises:**

 - <b>`FabricConfigError`</b>:  If planning or adapter configuration is invalid.
 - <b>`FabricNativeUnavailableError`</b>:  If the native extension is not  installed.
 - <b>`FabricRuntimeError`</b>:  If service startup fails.

---


### <kbd>method</kbd> `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:**

 - <b>`environment`</b>:  Handle returned by ``prepare_environment()`` or  ``attach_environment()``.



**Raises:**

 - <b>`FabricConfigError`</b>:  If ``environment`` is not a typed handle.
 - <b>`FabricNativeUnavailableError`</b>:  If the native extension is not installed.
 - <b>`FabricRuntimeError`</b>:  If release or detach fails.

---


### <kbd>method</kbd> `run`

```python
async def run(
    config: FabricConfig,
    *,
    base_dir: str | os.PathLike[str] | None = None,
    input: Any = None,
    request: RunRequest | None = None,
    session_ref: SessionRef | 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. Unconfirmed cleanup raises an error with ``cleanup_runtime`` for an explicit stop retry in the same process.



**Args:**

 - <b>`config`</b>:  Complete typed ``FabricConfig``.
 - <b>`base_dir`</b>:  Base directory for resolving relative paths.
 - <b>`session_ref`</b>:  Native session to resume. Durable sessions  require retained storage and adapter support. Omission starts fresh.
 - <b>`input`</b>:  JSON-compatible invocation input.
 - <b>`request`</b>:  Complete validated ``RunRequest``.
 - <b>`expected_descriptor_sha256`</b>:  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:**

 - <b>`FabricConfigError`</b>:  If input and request are combined, request data is not  JSON-compatible, or config resolution fails.
 - <b>`FabricNativeUnavailableError`</b>:  If the native extension is not  installed.
 - <b>`FabricRuntimeError`</b>:  If the native runtime lifecycle fails before a  normalized result can be returned.

---


### <kbd>method</kbd> `runtime_status`

```python
async def runtime_status(
    *,
    runtime_id: str,
    agent_name: str,
    environment: EnvironmentHandle | None = None,
) -> RuntimeStatusReport
```

Read recorded runtime state and rediscover a safe handle by identifier.

Without an environment, read runtimes created by this ``Fabric`` instance and retain each ``Runtime`` until successful stop. Each client holds at most 128 runtime records, including pending starts. New starts evict the oldest stopped records first and fail with ``runtime_limit_reached`` if active, failed, and pending runtimes fill the limit. A stopped record has a null handle. A local environment also selects its exact identifier.

An OpenShell environment routes ``fabric-agent-ctl status`` to the owning server, including from a later client process. The returned handle belongs to that server's local environment. Records do not survive server restart. This operation never starts, invokes, stops, or probes a runtime. Recorded ``active`` state does not establish current harness health; use ``check()`` for a fresh observation.



**Args:**

 - <b>`runtime_id`</b>:  Runtime identifier returned by start.
 - <b>`agent_name`</b>:  Exact owning agent name.
 - <b>`environment`</b>:  Optional local selector or verified OpenShell binding.



**Returns:**
 An immutable ``RuntimeStatusReport`` with a discovery-only handle. Handle environment variables and arbitrary provider metadata are omitted.



**Raises:**

 - <b>`FabricConfigError`</b>:  If the target or returned report is invalid.
 - <b>`FabricStateError`</b>:  If the runtime or selected ownership is unavailable.
 - <b>`FabricNativeUnavailableError`</b>:  If remote routing needs a missing extension.
 - <b>`FabricRuntimeError`</b>:  If the status transport fails.

---


### <kbd>method</kbd> `start_runtime`

```python
async def start_runtime(
    config: FabricConfig,
    *,
    base_dir: str | os.PathLike[str] | None = None,
    overrides: Mapping[str, Any] | None = None,
    session_ref: SessionRef | 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:**

 - <b>`config`</b>:  Complete typed ``FabricConfig``.
 - <b>`base_dir`</b>:  Base directory for resolving relative paths.
 - <b>`session_ref`</b>:  Native session to resume. Durable sessions  require retained storage and adapter support. Omission starts fresh.
 - <b>`overrides`</b>:  JSON-compatible overrides applied to every invocation  in the runtime unless superseded by invocation overrides.
 - <b>`streaming`</b>:  Whether to enable collector-backed NeMo Relay ATOF  streaming for ``Runtime.invoke_stream()``.
 - <b>`launch_collector`</b>:  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``.
 - <b>`completion_wait_timeout`</b>:  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.
 - <b>`service`</b>:  Optional prepared or attached service. When supplied, the  runtime connects to that service instead of creating its own.
 - <b>`expected_descriptor_sha256`</b>:  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:**

 - <b>`FabricConfigError`</b>:  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.
 - <b>`FabricStateError`</b>:  If active, failed, and pending runtimes fill the  client's 128-record limit (``runtime_limit_reached``).
 - <b>`FabricNativeUnavailableError`</b>:  If the native extension is not  installed.
 - <b>`FabricRuntimeError`</b>:  If runtime startup fails.

---


### <kbd>method</kbd> `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,
    session_ref: SessionRef | 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:**

 - <b>`config`</b>:  Complete typed ``FabricConfig`` matching the environment.
 - <b>`environment`</b>:  Handle returned by ``prepare_environment()`` or  ``attach_environment()``.
 - <b>`base_dir`</b>:  Base directory for resolving relative paths.
 - <b>`session_ref`</b>:  Native session to resume. Durable sessions  require retained storage and adapter support. Omission starts fresh.
 - <b>`overrides`</b>:  JSON-compatible runtime-scoped invocation overrides.
 - <b>`streaming`</b>:  Whether to provision NeMo Relay ATOF streaming.



**Returns:**
 An active ``Runtime`` bound to ``environment``.



**Raises:**

 - <b>`FabricConfigError`</b>:  If inputs are invalid or the handle does not match the plan.
 - <b>`FabricStateError`</b>:  If active, failed, and pending runtimes fill the  client's 128-record limit (``runtime_limit_reached``).
 - <b>`FabricNativeUnavailableError`</b>:  If the native extension is not installed.
 - <b>`FabricRuntimeError`</b>:  If runtime startup fails.




---

_This file was automatically generated via [lazydocs](https://github.com/ml-tooling/lazydocs)._