Client
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__
method attach_environment
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 typedFabricConfigwith 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
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 typedFabricConfig.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
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
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 typedFabricConfig.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 invocation_result
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.
method plan
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 typedFabricConfig. 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
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 typedFabricConfigdescribing 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
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 typedFabricConfig.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
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 byprepare_environment()orattach_environment().
Raises:
FabricConfigError: Ifenvironmentis not a typed handle.FabricNativeUnavailableError: If the native extension is not installed.FabricRuntimeError: If release or detach fails.
method run
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:
config: Complete typedFabricConfig.base_dir: Base directory for resolving relative paths.session_ref: Native session to resume. Durable sessions require retained storage and adapter support. Omission starts fresh.input: JSON-compatible invocation input.request: Complete validatedRunRequest.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 runtime_status
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:
runtime_id: Runtime identifier returned by start.agent_name: Exact owning agent name.environment: 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:
FabricConfigError: If the target or returned report is invalid.FabricStateError: If the runtime or selected ownership is unavailable.FabricNativeUnavailableError: If remote routing needs a missing extension.FabricRuntimeError: If the status transport fails.
method start_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 typedFabricConfig.base_dir: Base directory for resolving relative paths.session_ref: Native session to resume. Durable sessions require retained storage and adapter support. Omission starts fresh.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 forRuntime.invoke_stream().launch_collector: Whether to launch an embedded collector.Nonedefaults toTruewhen streaming is enabled.Falseuses an externally managed collector. Pi does not supportFalse. This argument cannot be set unlessstreaming=True.completion_wait_timeout: Maximum seconds the embedded collector waits for a Piagent_settledmarker 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_collectoris set without streaming, Pi is configured with an external collector, or an external collector has no sink.FabricStateError: If active, failed, and pending runtimes fill the client’s 128-record limit (runtime_limit_reached).FabricNativeUnavailableError: If the native extension is not installed.FabricRuntimeError: If runtime startup fails.
method start_runtime_in
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 typedFabricConfigmatching the environment.environment: Handle returned byprepare_environment()orattach_environment().base_dir: Base directory for resolving relative paths.session_ref: Native session to resume. Durable sessions require retained storage and adapter support. Omission starts fresh.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.FabricStateError: If active, failed, and pending runtimes fill the client’s 128-record limit (runtime_limit_reached).FabricNativeUnavailableError: If the native extension is not installed.FabricRuntimeError: If runtime startup fails.
This file was automatically generated via lazydocs.