nemo-fabric-integrate

Files (8)

• BENCHMARK.md
• SKILL.md
• evals.json · evals/
• config-mapping.md · references/
• results-and-errors.md · references/
• sdk-api-inventory.md · references/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# Integrate NVIDIA NeMo Fabric Through The Python SDK

Use this skill when a consumer codebase — an application, service, evaluation
harness, or platform — needs to run agent harnesses through NeMo Fabric's typed
Python SDK. The consumer owns its own configuration object and translates it
into an in-memory `FabricConfig`; NeMo Fabric owns adapter selection, the runtime
lifecycle, and normalized results.

## Integration Boundary

Use the public, in-memory contract. These rules keep a consumer integration
supported and upgrade-safe:

- Import only from the public `nemo_fabric` package. Never import `_native` or
  any adapter-internal module.
- Build configuration as a typed `FabricConfig` in memory and pass it directly to
  NeMo Fabric. Create every deployment or evaluation variant with ordinary Python
  functions and `model_copy(deep=True)`. A platform integration can serialize
  the typed config inside a private transient run specification when it crosses
  a process boundary; that transport is not a public authoring format.
- Let NeMo Fabric own harness control. Do not reimplement start, invoke, or stop
  logic, and do not manage adapter threads, sessions, or processes directly.
- Treat `runtime_id`, `invocation_id`, and `request_id` as opaque correlation
  strings, not parsable or reusable state.

Refer to [config-mapping.md](references/config-mapping.md) for how to translate a
consumer config object into `FabricConfig`, and for the full list of mechanics
that stay hidden behind this boundary.

## Install And Set Up The Environment

The consumer or its execution environment owns installation; NeMo Fabric validates
runtime assumptions but never installs harnesses or credentials at run time.

- Choose supported Python interpreters for the runtime, Harbor, and adapter
  environments from the
  [installation guide](https://github.com/NVIDIA/NeMo-Fabric/blob/main/docs/getting-started/install.mdx).
- Install the runtime with `uv pip install nemo-fabric` (add the `harbor` extra
  for the Harbor integration).
- Select the harness adapter through `HarnessConfig.adapter_id`. To install the
  NeMo Fabric runtime, adapter, and supported harness in one environment, use
  `nemo-fabric[claude]`, `nemo-fabric[codex]`,
  or `nemo-fabric[deepagents]`.
- Install Hermes Agent separately from the Fabric adapter. Follow the
  [Hermes integration guide](https://github.com/NVIDIA/NeMo-Fabric/blob/main/docs/integrations/harness/hermes.mdx)
  for the current compatible interpreter, source checkout, Relay dependencies,
  and adapter installation. The `nemo-fabric[hermes-agent]` extra does not
  install Hermes Agent.
- In a separate adapter environment, install
  `nemo-fabric-adapters-<adapter>[harness]`. This installs the adapter and
  supported harness dependencies without the NeMo Fabric runtime. Use `full`
  instead when that adapter package provides package-installable optional
  integrations.
- Point the runtime to a separate adapter environment with `ADAPTER_PYTHON`.
  Use matching NeMo Fabric release versions for the runtime and adapter package
  unless a different pairing has been explicitly validated.
- If the adapter environment already manages a compatible harness, install the
  bare `nemo-fabric-adapters-<adapter>` distribution. Bare adapter
  distributions contain only adapter-owned runtime dependencies.
- LangChain Deep Agents and Hermes adapter packages provide `relay` and include
  the NeMo Relay Python package in `full`. Claude and Codex do not provide
  `relay`; their `harness` and `full` extras install the supported `nemo-relay`
  CLI alongside the harness SDK.
- Provide model credentials through environment variables named by the config
  (`ModelConfig.api_key_env`), never as literals in code.
- Forward other existing variables with `EnvironmentConfig.env_names`; only names are stored in configuration and run plans. `EnvironmentConfig.env` supplies literal values and does not expand `$NAME` references. Neither field loads a `.env` file.
- Keep named environment values unchanged while a runtime or service is active. NeMo Fabric rejects changed or unset values before invocation; restart the runtime and any associated service after changing them. With Harbor, deliver values into the task environment through Harbor's managed environment first.
- Confirm the native extension is importable; SDK calls raise
  `FabricNativeUnavailableError` when it is missing.
- For descriptor inspection without harness SDKs, install the separate `nemo-fabric-adapter-catalog` package and call `nemo_fabric_adapter_catalog.get_adapter_descriptor(adapter_id)` or `get_target_descriptor(target_id)`. Refer to the [catalog guide](https://github.com/NVIDIA/NeMo-Fabric/blob/main/sdk/python/nemo-fabric-adapter-catalog/README.md). Catalog resources do not register execution runners; unknown IDs raise `KeyError`. Validate against the task environment's descriptor before relying on a snapshot claim. Catalog source versions and fingerprints are not runtime-observed provenance.

## Build The Typed Config From Consumer Config

Map the consumer's application, job, or deployment object into a `FabricConfig`
with the public models and helper methods:

```python
from nemo_fabric import (
    FabricConfig,
    HarnessConfig,
    InstructionConfig,
    InstructionsConfig,
    MetadataConfig,
    ModelConfig,
    RuntimeConfig,
    ToolsConfig,
)


def to_tools_config(job) -> ToolsConfig | None:
    enabled = job.enabled_tools
    blocked = list(job.blocked_tools)
    if enabled is None and not blocked:
        return None
    return ToolsConfig(
        enabled=None if enabled is None else list(enabled),
        blocked=blocked,
    )


def to_fabric_config(job) -> FabricConfig:
    config = FabricConfig(
        metadata=MetadataConfig(name=job.name),
        harness=HarnessConfig(adapter_id=job.adapter_id, resolution="preinstalled"),
        models={
            "default": ModelConfig(
                provider=job.provider,
                model=job.model,
                api_key_env=job.api_key_env,
                base_url=job.base_url,
            )
        },
        instructions=(
            InstructionsConfig(
                system=InstructionConfig(
                    content=job.system_instruction,
                    mode=job.system_instruction_mode,
                ),
            )

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills