> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/nemo/fabric/v0.7.0/sdk/python-sdk/llms.txt. # NVIDIA NeMo Fabric Python SDK > Use the NeMo Fabric Python SDK from applications, services, and evaluation harnesses. 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](/nemo/fabric/about-nemo-fabric/overview). ## Start With One Run This example uses an NVIDIA-hosted model. Export your NVIDIA API key before running it: ```bash 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. ```python 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: ```python 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: ```python 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: ```rust use nemo_fabric_core::{AdapterTargetDescriptor, inspect_adapter_config, load_adapter_descriptor}; let descriptor = load_adapter_descriptor(adapter_path)?; let target: Option = 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 * [Execution Model](/nemo/fabric/sdk/execution-model) - [Configure Agents](/nemo/fabric/sdk/configure-agents) - [Configure Skills](/nemo/fabric/integrations/harness-integrations/configure-skills) * [Requests and Runtimes](/nemo/fabric/sdk/requests-and-runtimes) - [Environments and Shared Services](/nemo/fabric/sdk/environments-and-shared-services) * [Streaming](/nemo/fabric/sdk/streaming) - [Results and Errors](/nemo/fabric/sdk/results-and-errors) * [Health Checks](/nemo/fabric/sdk/health-checks) - [Resource Usage and Stats](/nemo/fabric/sdk/resource-usage-and-stats) * [Software Execution Evidence](/nemo/fabric/sdk/software-execution-evidence) - [SDK Contract Boundaries](/nemo/fabric/sdk/contract-boundaries) ## Next Steps * Review the examples in the GitHub repo [`examples/`](https://github.com/NVIDIA/NeMo-Fabric/tree/v0.7.0/examples). ## Docs - [Execution Model](https://docs.nvidia.com/nemo/fabric/v0.7.0/sdk/execution-model.md): Understand SDK objects, runtime hosting, and the public API inventory. - [Configure Agents](https://docs.nvidia.com/nemo/fabric/v0.7.0/sdk/configure-agents.md): Configure agents with typed Python models and check harness compatibility. - [Configure Skills](https://docs.nvidia.com/nemo/fabric/v0.7.0/integrations/harness-integrations/configure-skills.md): Load skills from folders, choose bundled skills, and set how NVIDIA NeMo Fabric adapters handle skills that share a name. - [Requests and Runtimes](https://docs.nvidia.com/nemo/fabric/v0.7.0/sdk/requests-and-runtimes.md): Run requests, retain and resume state, and inspect recorded runtime status. - [Environments and Shared Services](https://docs.nvidia.com/nemo/fabric/v0.7.0/sdk/environments-and-shared-services.md): Manage environment and shared-service lifecycles from the Python SDK. - [Streaming](https://docs.nvidia.com/nemo/fabric/v0.7.0/sdk/streaming.md): Use native OpenAI streaming and NeMo Relay event streaming. - [Results and Errors](https://docs.nvidia.com/nemo/fabric/v0.7.0/sdk/results-and-errors.md): Read normalized results and events and handle SDK errors. - [Health Checks](https://docs.nvidia.com/nemo/fabric/v0.7.0/sdk/health-checks.md): Understand health scopes, levels, and the native evidence used by NVIDIA NeMo Fabric adapters. - [Resource Usage and Stats](https://docs.nvidia.com/nemo/fabric/v0.7.0/sdk/resource-usage-and-stats.md): Configure resource collection, understand measurements, and inspect agent execution results. - [Software Execution Evidence](https://docs.nvidia.com/nemo/fabric/v0.7.0/sdk/software-execution-evidence.md): Read software observations and understand evidence collection boundaries. - [SDK Contract Boundaries](https://docs.nvidia.com/nemo/fabric/v0.7.0/sdk/contract-boundaries.md): Understand schemas, versioning, extensibility, resilience, and backpressure.