Skip to navigation

NVIDIA NeMo Fabric Python SDK

View as MarkdownOpen in Claude

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:

export NVIDIA_API_KEY=...

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.

import asyncio
from nemo_fabric import (
Fabric,
FabricConfig,
HarnessConfig,
InstructionConfig,
InstructionsConfig,
MetadataConfig,
ModelConfig,
RuntimeConfig,
)
config = FabricConfig(
metadata=MetadataConfig(name="review-agent"),
harness=HarnessConfig(adapter_id="nvidia.fabric.hermes"),
instructions=InstructionsConfig(
system=InstructionConfig(
content="Review code for concrete correctness risks.",
mode="replace",
)
),
runtime=RuntimeConfig(max_turns=8),
models={
"default": ModelConfig(
provider="nvidia",
model="nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
api_key_env="NVIDIA_API_KEY",
)
},
)
async def main() -> None:
fabric = Fabric()
result = await fabric.run(
config,
input="Review the workspace changes.",
)
print(result.status)
print(result.output.response)
asyncio.run(main())

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:

from nemo_fabric import inspect_adapter
from nemo_fabric_adapter_catalog import get_adapter_descriptor
inspection = inspect_adapter(config, get_adapter_descriptor(config.harness.adapter_id))
if inspection.issues:
raise ValueError("; ".join(f"{issue.field}: {issue.reason}" for issue in inspection.issues))
profile = inspection.capability_profile
print(profile.skills, profile.mcp, profile.atif)
# In the task environment, resolve its own executable descriptor.
result = await Fabric().run(
config,
input="Review the changes.",
expected_descriptor_sha256=profile.descriptor_sha256,
)

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:

inspection = inspect_adapter(config, descriptor)
if inspection.issues:
for issue in inspection.issues:
print(issue.adapter_id, issue.field, issue.reason)
else:
profile = inspection.capability_profile
# Continue admission using the capability flags and descriptor fingerprint.

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:

use nemo_fabric_core::{AdapterTargetDescriptor, inspect_adapter_config, load_adapter_descriptor};
let descriptor = load_adapter_descriptor(adapter_path)?;
let target: Option<AdapterTargetDescriptor> = None;
let inspection = inspect_adapter_config(config, &descriptor, target.as_ref(), true)?;

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