> This page is for NeMo Fabric, version v0.7.0.
> For other versions, use one of these documentation indexes:
> - Latest (v0.7.0) (default): https://docs.nvidia.com/nemo/fabric/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/fabric/dev/llms.txt
> - v0.7.0: https://docs.nvidia.com/nemo/fabric/v0.7.0/llms.txt
> - v0.6.1: https://docs.nvidia.com/nemo/fabric/v0.6.1/llms.txt
> - v0.6.0: https://docs.nvidia.com/nemo/fabric/v0.6.0/llms.txt
> - v0.5.0: https://docs.nvidia.com/nemo/fabric/v0.5.0/llms.txt
> - v0.4.0: https://docs.nvidia.com/nemo/fabric/v0.4.0/llms.txt
> - v0.3.0: https://docs.nvidia.com/nemo/fabric/v0.3.0/llms.txt
> - v0.2.0: https://docs.nvidia.com/nemo/fabric/v0.2.0/llms.txt
> - v0.1.1: https://docs.nvidia.com/nemo/fabric/v0.1.1/llms.txt
> - v0.1.0: https://docs.nvidia.com/nemo/fabric/v0.1.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/fabric/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<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

* [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).