module nemo_fabric.client

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

class Fabric

Primary Python entrypoint for NeMo Fabric.

Every 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 Runtime handle.

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_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 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_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 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.

This file was automatically generated via lazydocs.