Skip to content
Closed
Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
e8353bf
Document installing the nemo-relay CLI tool
dagardner-nv Jul 20, 2026
6d751ad
Fix docs url
dagardner-nv Jul 20, 2026
6319666
Refer to the nemo-relay CLI install doc for the adapters that need it…
dagardner-nv Jul 20, 2026
83096a2
Rename sections
dagardner-nv Jul 20, 2026
ef94f33
Guide the user towards the notebooks, add Google Colab link
dagardner-nv Jul 20, 2026
b6fa5d9
Guide the user to the SDK Guide and the other examples from the noteb…
dagardner-nv Jul 20, 2026
5801f92
Guide the user to the examples after the SDK doc
dagardner-nv Jul 20, 2026
0c8d708
Remove YAML specific references from the Code Concepts section
dagardner-nv Jul 20, 2026
c1e84a1
Always refer to Hermes Agent as Hermes Agent not just 'Hermes'
dagardner-nv Jul 20, 2026
a7b3840
The Codex adapter doesn't have SDK in the name
dagardner-nv Jul 20, 2026
6351c68
Formatting
dagardner-nv Jul 20, 2026
edc9588
Fix anchor tag
dagardner-nv Jul 20, 2026
e9e3576
Formatting
dagardner-nv Jul 20, 2026
f3d271e
Merge branch 'main' of github.com:NVIDIA/NeMo-Fabric into david-more-…
dagardner-nv Jul 20, 2026
1803817
NeMo Fabric, not Fabric
dagardner-nv Jul 21, 2026
d549136
Add a code rabbit check for the product name
dagardner-nv Jul 21, 2026
0158c68
NeMo Fabric not 'Fabric'
dagardner-nv Jul 21, 2026
83545f6
Clean-up
dagardner-nv Jul 21, 2026
3c9dd77
Product naming
dagardner-nv Jul 21, 2026
2db34ea
Product naming
dagardner-nv Jul 21, 2026
bcfc827
Slim down sentence about adapter packages
dagardner-nv Jul 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ just wheels
uv pip install --find-links dist nemo-fabric
```

Adapters are distributed as optional extras. For example, install the Hermes adapter with:
Adapters are distributed as optional extras. For example, install the Hermes Agent adapter with:

```bash
uv pip install --find-links dist "nemo-fabric[adapters-hermes]"
Expand Down Expand Up @@ -251,7 +251,7 @@ Examples:
```text
feat: add typed runtime diagnostics
fix: preserve adapter errors in run results
docs: clarify Hermes adapter installation
docs: clarify Hermes Agent adapter installation
test: cover concurrent Python runtime invocations
```

Expand Down
31 changes: 19 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,15 +106,15 @@ just build-all
just wheels
```

Install Fabric, Hermes Agent, and the Hermes adapter into an environment:
Install Fabric, Hermes Agent, and the Hermes Agent adapter into an environment:
Comment thread
dagardner-nv marked this conversation as resolved.
Resolved

```bash
# Use any Python 3.11-3.13 interpreter for Hermes.
# Use any Python 3.11-3.13 interpreter for Hermes Agent.
python3 -m venv .tmp/hermes-venv
.tmp/hermes-venv/bin/python -m pip install --find-links dist "nemo-fabric[hermes]"
```

If you are working from a local Hermes checkout, replace the final install line
If you are working from a local Hermes Agent checkout, replace the final install line
with:

```bash
Expand Down Expand Up @@ -144,6 +144,12 @@ under `examples/code_review_agent/artifacts/hermes/`. Its complete base
config and clone-based variants live in
`examples/code_review_agent/config.py`.

### Next Steps

- Follow the [Example Notebooks](examples/notebooks/README.md) for a guided tour of the Python SDK.
Comment thread
dagardner-nv marked this conversation as resolved.
Resolved
- Refer to the [Python SDK guide](docs/sdk/python.mdx): typed configuration, planning,
diagnostics, requests, multi-turn runtimes, parallelism, results, and errors.

## Claude Adapter

Build the local wheels and install Fabric with the independent Claude adapter:
Expand Down Expand Up @@ -175,15 +181,15 @@ authentication, and execution details.
config.block_tools("browser", "shell")
```

Hermes maps these names to disabled toolsets, Claude maps them to
`disallowed_tools`, Deep Agents enforces them with middleware, and adapters
without a native deny mechanism route the policy as unsupported.
The selected adapter interprets these names: Hermes Agent maps them to disabled
toolsets, Claude maps them to `disallowed_tools`, Deep Agents enforces them
with middleware, and adapters without a native deny mechanism route the
policy as unsupported.
- **Adapters:** harness-specific integrations selected by `harness.adapter_id`.
The Hermes adapter lives under `adapters/hermes/`; the Codex SDK
adapter lives under `adapters/codex/`; the
The Hermes Agent adapter lives under `adapters/hermes/`; the Codex adapter lives under `adapters/codex/`; the
[Claude adapter](adapters/claude/README.md)
lives under `adapters/claude/`; the LangChain Deep Agents adapter lives under
`adapters/deepagents/`. Harness-specific extensions belong under
`adapters/deepagents/`. Harness Agent-specific extensions belong under
`harness.settings` so the normalized contract can remain stable.
Comment thread
dagardner-nv marked this conversation as resolved.
Resolved
- **Artifacts:** normalized output, logs, patches, and telemetry references
returned through an `ArtifactManifest`.
Expand All @@ -200,6 +206,7 @@ the [Python SDK guide](docs/sdk/python.mdx). Exact signatures are in the

## More Workflows

- [Example Notebooks](examples/notebooks/README.md) provide a guided tour of the Python SDK.
- [Python SDK guide](docs/sdk/python.mdx): typed configuration, planning,
diagnostics, requests, multi-turn runtimes, parallelism, results, and errors.
- [Experimentation CLI](docs/experimentation/cli.mdx): presets, maintained
Expand All @@ -210,9 +217,9 @@ the [Python SDK guide](docs/sdk/python.mdx). Exact signatures are in the
selection and the end-to-end Fabric workflow.
- [Harbor examples](examples/harbor/README.md): validate the integration with a
deterministic, credential-free calculator smoke, optionally run the same
task with Hermes or Claude, and evaluate real coding tasks with SWE-Bench.
- Adapter guides: [Hermes](adapters/hermes/README.md),
[Codex SDK](adapters/codex/README.md), and
task with Hermes Agent or Claude, and evaluate real coding tasks with SWE-Bench.
- Adapter guides: [Hermes Agent](adapters/hermes/README.md),
[Codex](adapters/codex/README.md), and
[Deep Agents](adapters/deepagents/README.md).

## Tests
Expand Down
6 changes: 1 addition & 5 deletions adapters/claude/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,11 +58,7 @@ Refer to the [Claude adapter authentication guide](https://nvidia-nemo-fabric.do
for mode selection, required WIF variables, and the Relay boundary. Package
installation is verified by the adapter wheel and module-entrypoint tests.

Relay-enabled runs also require the external `nemo-relay` CLI. Fabric accepts
CLI versions `>=0.6.0,<0.7.0`. Install the CLI separately:

```bash
cargo install nemo-relay-cli
Relay-enabled runs also require the external `nemo-relay` CLI. Refer to the [NeMo Relay CLI](https://docs.nvidia.com/nemo/fabric/getting-started/install#nemo-relay-cli) install guide for instructions on installing the CLI tool.
Comment thread
dagardner-nv marked this conversation as resolved.
Resolved
```

The Python `nemo-relay` package does not install this executable. Refer to the
Expand Down
63 changes: 3 additions & 60 deletions adapters/codex/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,65 +122,8 @@ The adapter filters the inherited environment. It retains portable OS and
Codex state variables, the selected model's `api_key_env`, and explicit
`settings.env` values while clearing unrelated parent-process secrets.

## Relay Observability

Enable Relay through Fabric's normalized telemetry configuration. For each
Relay-enabled invocation, Fabric:

1. Resolves one external `nemo-relay` executable.
2. Generates invocation-scoped gateway and plugin configuration.
3. Starts and health-checks `nemo-relay --config ... --bind ...`.
4. Redirects the built-in OpenAI provider with request-scoped
`openai_base_url` and passes Relay hooks through the Codex SDK's `config`
argument.
5. Interrupts timed-out turns, closes the SDK runtime, and stops the gateway.

The SDK remains the Codex execution driver. Relay is a supervised sidecar and
hook forwarder; the adapter never invokes a `nemo-relay codex` wrapper. The
result reports the gateway config, URL, log, and collected Relay artifacts.

Fabric deliberately keeps Codex on its reserved built-in `openai` provider.
Defining Relay as a custom model-provider alias breaks the Python SDK's
ChatGPT-authenticated request path. Redirecting only `openai_base_url` preserves
the SDK's supported authentication and host metadata while allowing Relay to
capture Responses traffic. Fabric does not spoof the Codex CLI identity or fall
back to CLI execution. Relay routes and observes requests; it does not provide
OpenAI credentials or change the selected Codex authentication mode.

Relay-enabled Codex runs require `models.default.provider: openai`. The custom
`nvidia` provider is not supported with Relay because its configured NVIDIA
Responses base URL bypasses the built-in `openai_base_url` redirect. Run the
`nvidia` provider without Relay and supply its credential through `api_key_env`
(default: `NVIDIA_API_KEY`) and its endpoint through
`models.default.settings.base_url` or `NVIDIA_FRONTIER_BASE_URL`.

Relay-enabled runs require the external `nemo-relay` CLI in addition to the
Python package dependencies. Fabric accepts CLI versions `>=0.6.0,<0.7.0`.
Until the request-decoding fix is released, install the tested PR revision:
## Relay Integration

```bash
git clone https://github.com/NVIDIA/NeMo-Relay.git nemo-relay
git -C nemo-relay fetch origin pull/452/head
git -C nemo-relay checkout --detach 0b02e01ac10d7d678da28830feba0ebf6743a7c0
cargo install --locked --path nemo-relay/crates/cli
```
Relay-enabled runs also require the external `nemo-relay` CLI. Refer to the
[NeMo Relay CLI](https://docs.nvidia.com/nemo/fabric/getting-started/install#nemo-relay-cli) install guide for instructions on installing the CLI tool.
Comment thread
dagardner-nv marked this conversation as resolved.
Resolved

Removal of this temporary source installation is tracked in
[TODO.md](https://github.com/NVIDIA/NeMo-Fabric/blob/main/TODO.md#nemo-relay-06x-request-decoding-release).

The `nemo-relay` Python package does not install this executable. Refer to the
[NeMo Relay installation guide](https://docs.nvidia.com/nemo/relay/getting-started/installation)
for other supported installation methods.

Relay owns HTTP content decoding at the gateway boundary; Fabric does not
configure Codex request compression. The Relay `0.6.0-alpha.20260716` tag cannot
recover semantic fields from zstd-compressed SDK requests. Until a later `0.6.x`
release contains the fix, use the pinned
[NeMo Relay PR #452](https://github.com/NVIDIA/NeMo-Relay/pull/452) revision
above.

For Phoenix, native Codex OpenTelemetry targets the OTLP collector at
`http://localhost:4318/v1/traces` and provides low-level app-server spans.
Relay OpenInference provides the semantic chain, LLM, and tool hierarchy with
decoded prompt, response, and token attributes. Prefer Relay OpenInference for
agent-turn inspection.
16 changes: 8 additions & 8 deletions adapters/hermes/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,32 +9,32 @@ This adapter runs Hermes Agent through its Python SDK.

## Install

To install just the Hermes adapter by itself:
To install just the Hermes Agent adapter by itself:

```bash
pip install "nemo-fabric[adapters-hermes]"
```

To install just the Hermes adapter along with the NeMo Fabric Runtime:
To install just the Hermes Agent adapter along with the NeMo Fabric Runtime:

```bash
pip install "nemo-fabric[adapters-hermes, runtime]"
```

## What It Maps

The adapter receives a normalized payload from Fabric and materializes Hermes-native configuration for:
The adapter receives a normalized payload from Fabric and materializes a native Hermes Agent configuration for:

- model provider, model name, base URL, temperature, and token settings;
- workspace and terminal settings;
- Fabric skills as Hermes external skill directories;
- Fabric MCP servers as Hermes MCP server config;
- `tools.blocked` as Hermes disabled toolsets, unioned with
- Fabric skills as external skill directories for Hermes Agent;
- Fabric MCP servers as Hermes Agent MCP server config;
- `tools.blocked` as disabled toolsets for Hermes Agent, unioned with
`harness.settings.disabled_toolsets`;
- optional NeMo Relay telemetry plugin configuration.

`hermes_home` configures a base directory. The adapter creates a child under
`runtimes/<runtime_id>` so invocations in one Fabric runtime share Hermes state
`runtimes/<runtime_id>` so invocations in one Fabric runtime share Hermes Agent state
without sharing config or the session database with another runtime.

## Maintaining The Adapter
Expand All @@ -48,7 +48,7 @@ Keep `fabric-adapter.json` aligned with the Python implementation:
`runner.callable` names the equivalent reusable Python function.
- `requirements` powers `fabric doctor`; keep required env vars, binaries, or
packages current.
- `config.accepts` must match the Fabric sections this adapter maps into Hermes.
- `config.accepts` must match the Fabric sections this adapter maps into Hermes Agent.
- `telemetry.providers` declares provider-specific outputs and integration modes
the adapter can produce or forward.

Expand Down
8 changes: 4 additions & 4 deletions docs/about-nemo-fabric/overview.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ SPDX-License-Identifier: Apache-2.0 */}
NeMo Fabric is the harness-management layer that turns multiple agent runtimes
into one configurable, observable execution surface. Applications use the same
versioned config, lifecycle, result, artifact, and telemetry contracts whether
the selected harness is Hermes, Codex SDK, or a custom adapter.
the selected harness is Hermes Agent, Codex, or a custom adapter.

NeMo Fabric owns the seam between an application and its harness. It resolves
configuration, selects an adapter, drives the runtime lifecycle,
Expand Down Expand Up @@ -49,7 +49,7 @@ NeMo Fabric Rust core
|
| resolved adapter contract
v
Hermes | Codex SDK | custom harness
Hermes Agent | Codex | custom harness
|
v
RunResult + artifacts + events + telemetry references
Expand Down Expand Up @@ -115,8 +115,8 @@ asyncio.run(main())
```

Harness installation and credential requirements differ by adapter. The
[repository quick start](https://github.com/NVIDIA/NeMo-Fabric#quick-start-hermes)
contains the complete Hermes environment recipe.
[repository quick start](https://github.com/NVIDIA/NeMo-Fabric#quick-start-hermes-agent)
contains the complete Hermes Agent environment recipe.

Refer to the [Python SDK guide](/nemo/fabric/sdk/python-sdk) for planning,
diagnostics, typed requests, and multi-turn runtime examples.
Expand Down
41 changes: 40 additions & 1 deletion docs/getting-started/install.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ NeMo Fabric is separated into two distinct parts:
- Python version 3.11 - 3.14

NeMo Fabric supports Python versions 3.11-3.14, however some of the integrations and adapters may have
additional requirements. Specifically the Hermes adapter doesn't support Python 3.14 yet, and the Harbor
additional requirements. Specifically the Hermes Agent adapter doesn't support Python 3.14 yet, and the Harbor
integration requires Python 3.12 or later.

### Installing NeMo Fabric Runtime
Expand Down Expand Up @@ -51,6 +51,45 @@ For example, to install the Hermes Agent adapter:
pip install "nemo-fabric[adapters-hermes]"
```

### Install NeMo Relay

[NeMo Relay](https://docs.nvidia.com/nemo/relay) integration occurs in two
ways:

- [Python library](https://pypi.org/project/nemo-relay/)
- [NeMo Relay CLI](https://crates.io/crates/nemo-relay-cli)

The required integration depends on the agent harness chosen. Relay-enabled runs with
the Claude and Codex adapters require the [`nemo-relay` CLI](https://crates.io/crates/nemo-relay-cli).

#### NeMo Relay Python Library

The `relay` dependency extra installs a version of the NeMo Relay Python library known to be compatible with the
installed version of NeMo Fabric.

```bash
pip install "nemo-fabric[relay]"
```

#### NeMo Relay CLI

**Shell installation method (Linux and macOS):**

```bash
curl -fsSL https://raw.githubusercontent.com/NVIDIA/NeMo-Relay/main/install.sh | sh
```
Comment thread
dagardner-nv marked this conversation as resolved.
Resolved

**Windows PowerShell installation method:**

```powershell
irm https://raw.githubusercontent.com/NVIDIA/NeMo-Relay/main/install.ps1 | iex
```

**Cargo installation method (requires `cargo-binstall`):**

```bash
cargo binstall nemo-relay-cli
```

## Source Installation Method

Expand Down
2 changes: 1 addition & 1 deletion docs/integrations/codex.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: "Use the Codex Adapter"
description: "Configure capabilities, authentication, and telemetry for the NeMo Fabric Codex SDK adapter."
description: "Configure capabilities, authentication, and telemetry for the NeMo Fabric Codex adapter."
---
{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0 */}
Expand Down
2 changes: 1 addition & 1 deletion docs/integrations/harbor.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ selects and runs the agent harness.
One Harbor trial consumes one complete NeMo Fabric config. Compare harnesses or
capability variants by holding the Harbor task and verifier fixed and starting
a separate run with a different config or explicit Harbor skill/MCP input.
The checked-in Harbor workflow currently qualifies Hermes and Claude end to
The checked-in Harbor workflow currently qualifies Hermes Agent and Claude end to
end; other NeMo Fabric adapters are not yet presented as Harbor-qualified examples.

The repository example is the single source for installation, the local smoke,
Expand Down
7 changes: 5 additions & 2 deletions docs/sdk/python.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ relay_config.enable_relay(

The repository's
[code-review example](https://github.com/NVIDIA/NeMo-Fabric/tree/main/examples/code_review_agent)
uses this pattern for complete Hermes, Codex SDK, Deep Agents,
uses this pattern for complete Hermes Agent, Codex, Deep Agents,
environment, MCP, and telemetry variants.

If a config contains relative paths, pass a `base_dir` to `plan(...)`,
Expand Down Expand Up @@ -398,7 +398,7 @@ Use normalized NeMo Fabric fields for portable behavior: models, runtime,
environment, skills, MCP, telemetry, tools, artifacts, and request context.

Use `harness.settings` for adapter-owned configuration that the selected adapter
understands. Examples include Hermes-specific launch options, Codex SDK controls,
understands. Examples include Hermes Agent-specific launch options, Codex controls,
or adapter-specific launch paths.

Use `metadata` for caller-owned annotations that NeMo Fabric should preserve and echo
Expand Down Expand Up @@ -499,3 +499,6 @@ the request, start a replacement runtime, fail the job, or escalate to a user.
If a harness reports capacity pressure, an adapter should surface it as a
structured error or event such as busy, rate limited, capacity exceeded, or
backpressure. The consumer decides whether to wait, retry, scale out, or fail.

## Next Steps
- Review the examples in the GitHub repo [`examples/`](https://github.com/NVIDIA/NeMo-Fabric/tree/main/examples).
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
6 changes: 3 additions & 3 deletions examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ application-facing Python SDK contract:
- creating harness, environment, capability, and telemetry variants from deep
copies;
- resolving relative workspace and skill paths with `base_dir`;
- running maintained Hermes, Codex, Claude, and Deep Agents adapters through the Python SDK.
- running maintained Hermes Agent, Codex, Claude, and Deep Agents adapters through the Python SDK.

Start with:

Expand All @@ -48,8 +48,8 @@ skills, MCP servers, tool policy, and telemetry—into the final `FabricConfig`.
The walkthroughs include:

- a calculator walkthrough with a deterministic, credential-free integration
smoke test and optional LLM-backed Hermes and Claude runs; and
- a SWE-Bench workflow for running Hermes and Claude, comparing capability
smoke test and optional LLM-backed Hermes Agent and Claude runs; and
- a SWE-Bench workflow for running Hermes Agent and Claude, comparing capability
variations, inspecting Relay telemetry, and verifying real coding tasks.

Start with the shared setup and execution model in the
Expand Down
Loading