`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`

def __init__() -> None

`method` `attach_environment`

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`

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`

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`

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`

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`

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`

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`

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`

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`

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`

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.

module nemo_fabric.client

class Fabric

method __init__

method attach_environment

method attach_service

method check

method doctor

method plan

method prepare_environment

method prepare_service

method release_environment

method run

method start_runtime

method start_runtime_in

`module` `nemo_fabric.client`

`class` `Fabric`

`method` `init`

`method` `attach_environment`

`method` `attach_service`

`method` `check`

`method` `doctor`

`method` `plan`

`method` `prepare_environment`

`method` `prepare_service`

`method` `release_environment`

`method` `run`

`method` `start_runtime`

`method` `start_runtime_in`