NVIDIA NeMo Fabric Python SDK
The Python SDK is the application-facing interface for NeMo Fabric. Use it to configure an agent harness, inspect the resolved plan, run one request or a multi-turn runtime, and collect normalized results, events, artifacts, and telemetry references.
The SDK is config-first. Applications should construct a Pydantic
FabricConfig from their own job, deployment, or evaluation config.
Examples, CI jobs, and applications construct the typed config directly and
can use ordinary Python functions to create variants.
Generated API reference pages remain the source of truth for exact signatures. This guide explains how the pieces are intended to fit together.
For installation and a package-backed example, start with the NeMo Fabric overview.
Start With One Run
This example uses an NVIDIA-hosted model. Export your NVIDIA API key before running it:
Construct a typed config, then pass it to Fabric.run(...). The SDK starts a
runtime, invokes it once, collects the result, and stops the runtime.
Omit instructions.system to preserve the harness’s native system instruction.
When present, InstructionConfig.mode defaults to replace. Use append only
with an adapter whose descriptor advertises that mode; planning rejects other
combinations before the runtime starts.
Use base_dir to resolve relative paths in an in-memory config. Before running
in a new environment, call plan(...) to inspect adapter selection and
doctor(...) to check runtime requirements.
The remaining examples reuse this config value.
Inspect Metadata On A Separate Host
Use inspect_adapter(config, descriptor) when the admission host cannot access
the task’s installed adapter. Supply canonical metadata from the matching
nemo-fabric-adapter-catalog release or an external adapter:
The returned AdapterInspection contains issues and a capability_profile.
The frozen AdapterCapabilityProfile reports declared skills and MCP support
and ATIF availability for the selected telemetry configuration. Inspection
validates descriptor values in memory with the same rules as startup,
without temporary descriptor files, executable adapter discovery, or harness SDK
imports. Host inspection requires nemo-fabric-runtime; the dependency-free
nemo-fabric-adapter-catalog is an optional metadata source. By default, unsupported configuration is returned in inspection.issues; check this list before accessing capability_profile or changing a deployment. diagnostics=True is the default. Pass diagnostics=False for exception-based rejection of incompatibilities. Malformed input raises FabricConfigError in both modes.
Passing None still runs the native metadata-free configuration checks, including the runtime.keep_state artifact requirement. It permits basic execution with false capability claims. Requested skills, MCP, or telemetry without metadata produce one combined issue at descriptor and no capability profile.
The optional expected_descriptor_sha256 argument on run() and
start_runtime() verifies the normalized descriptor in the actual execution
plan before startup. Catalog metadata never becomes an execution origin. A
fingerprint confirms descriptor correspondence, not installed software versions
or successful evidence production. ATIF requires a selected provider declaring
that output; Relay additionally requires one explicitly enabled observability
component with ATIF enabled. Unconfirmed ATIF requests, including ambiguous
duplicate components, fail admission.
For a registered workflow, also supply its canonical target metadata:
inspect_adapter(config, descriptor, target_descriptor=get_target_descriptor(config.workflow.target_id)).
Import get_target_descriptor from nemo_fabric_adapter_catalog. The fingerprint
then covers both normalized descriptors, including the target factory reference
and settings schema. Missing or mismatched target metadata fails admission.
Task execution still resolves its own installed target and verifies both
descriptors before starting the factory. Standalone fingerprints are unchanged.
Attached services require separate route-specific admission.
Structured Diagnostics
By default, inspection collects independent model, tool, and MCP incompatibilities. Call it before scheduling, installing dependencies, or changing a deployment when those actions require admission:
Each frozen AdapterCompatibilityIssue contains adapter_id, a NeMo Fabric configuration field such as models.default.temperature or tools.enabled,
and a reason that excludes configured values and credentials. Issues have a
deterministic order. A report with issues has capability_profile=None;
a successful report has an empty issue list and a populated profile.
Malformed configurations, descriptors, embedded schemas, and selector mismatches raise FabricConfigError with the original field and validation message. Descriptor validation details are preserved for catalog, file-loaded, and directly supplied metadata. A valid adapter that does not declare the supplied workflow target’s type returns a compatibility issue at workflow.target_id; mismatched target or adapter IDs remain input errors. The static runtime.keep_state artifact-directory requirement is shared with planning and raises the same field and reason. Harness and workflow settings, tool-definition schemas,
extensions, and telemetry retain first-error boundaries. Inspection and planning both require declared Relay ATIF output support and exactly one observability component when ATIF is requested. Inspection never
substitutes another descriptor. Select catalog metadata matching the intended
deployment release, then verify normalized descriptors in the task environment.
Success establishes compatibility with supplied metadata; it does not establish
image contents, credentials, network access, installed models, or runtime readiness.
Inspection API Migration
The Python return type changed from AdapterCapabilityProfile to
AdapterInspection. Change inspect_adapter(config, descriptor).mcp to
inspect_adapter(config, descriptor).capability_profile.mcp after checking result.issues. Compatibility failures return structured issues by default; malformed inputs raise FabricConfigError in both modes. Check issues and stop admission when it is nonempty. Callers that prefer exception-based rejection can explicitly pass diagnostics=False. Omitted arguments now select diagnostic behavior, so the default change is not backward-compatible. No transitional return types or deprecation period are provided.
Rust inspection now takes descriptor values instead of descriptor paths. File callers deserialize before inspection:
AdapterInspection and AdapterCompatibilityIssue are now public documented Rust types, marked #[non_exhaustive]. Rust callers explicitly pass true for structured compatibility issues, or false for exception-based rejection. Both modes reject malformed inputs. No file-based inspection wrapper is provided. doctor continues to diagnose resolved deployment plans.
SDK Subsections
Next Steps
- Review the examples in the GitHub repo
examples/.