Skip to content

docs: correct Hermes split-environment setup #238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rapids-bot merged 1 commit into from
Aug 15, 2026
Merged

docs: correct Hermes split-environment setup #238

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
12 changes: 7 additions & 5 deletions .agents/skills/contribute-adapter/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,12 +31,14 @@ Follow these repository-specific requirements after applying the public skill:
`README.md`, `<name>.fabric-adapter.json`, language-native package and lock
files, a source entry point, and focused tests.
2. Give each Python leaf adapter a small base installation, a `harness` extra
for supported target packages, and a `full` extra for package-installable
integrations. Add a `relay` extra only when the adapter imports NVIDIA NeMo
Relay Python APIs.
for package-installable target packages, and a `full` extra for
package-installable integrations. The Hermes adapter is the sole source-only
exception and omits `harness`. Add a `relay` extra only when the adapter
imports NVIDIA NeMo Relay Python APIs.
3. Add one canonical root extra that delegates to the matching leaf adapter
and its `harness` extra. Keep `nemo-fabric-runtime` an exact-version,
unconditional root dependency.
and its `harness` extra. The Hermes root extra delegates to the bare adapter
because users install Hermes Agent separately from source. Keep
`nemo-fabric-runtime` an exact-version, unconditional root dependency.
4. Add the package to the root adapter-test dependency group,
`[tool.uv.sources]`, `python_projects` in `justfile`, applicable catalogs,
and CI enumerations. Ship its descriptor under
Expand Down
14 changes: 9 additions & 5 deletions .agents/skills/maintain-packaging/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,12 +44,16 @@ commitment.

- Keep `nemo-fabric` as a metapackage that unconditionally installs the
exact-version `nemo-fabric-runtime` distribution. Its harness extras delegate
to version-matched leaf adapter `harness` extras. Do not add adapter-only
to version-matched leaf adapter `harness` extras. Hermes Agent is the sole
exception: its root extra delegates to the bare adapter because Hermes Agent
0.20 and later is not installable from PyPI. Do not add other adapter-only
aliases.
- Keep leaf adapters adapter-only by default. Every leaf provides `harness` and
`full`; provide `relay` only when the adapter imports the NeMo Relay Python
package. For adapters that launch the Relay CLI, both `harness` and `full`
install the version-matched `nemo-relay-cli-bin` package and remain equivalent.
- Keep leaf adapters adapter-only by default. Every leaf provides `full`, and
every package-installable harness provides `harness`. The Hermes adapter omits
`harness` because users install Hermes Agent separately from source. Provide
`relay` only when the adapter imports the NeMo Relay Python package. For
adapters that launch the Relay CLI, both `harness` and `full` install the
version-matched `nemo-relay-cli-bin` package and remain equivalent.
- First prefer the standard library, an existing dependency, or a small local
implementation when it keeps the behavior clear and maintainable.
- When multiple dependencies satisfy the technical requirement, prefer the
Expand Down
32 changes: 19 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -181,28 +181,34 @@ Create an environment for the NeMo Fabric runtime:
```bash
python -m venv .venv-fabric
source .venv-fabric/bin/activate
python -m pip install "nemo-fabric==0.2.0"
```

Install Hermes Agent by following its
[installation guide](https://hermes-agent.nousresearch.com/docs/installation).
Then install the Hermes adapter into the Hermes-managed Python environment:

```bash
pip install "nemo-fabric[hermes-agent]"==0.2.0
if [ -z "${ADAPTER_PYTHON:-}" ]; then
if [ -x "$HOME/.hermes/hermes-agent/venv/bin/python" ]; then
ADAPTER_PYTHON="$HOME/.hermes/hermes-agent/venv/bin/python"
else
ADAPTER_PYTHON="/usr/local/lib/hermes-agent/venv/bin/python"
fi
fi
if [ ! -x "$ADAPTER_PYTHON" ]; then
echo "Hermes Agent Python is not executable: $ADAPTER_PYTHON" >&2
exit 1
fi
export ADAPTER_PYTHON
"$ADAPTER_PYTHON" -m pip install "nemo-fabric-adapters-hermes==0.2.0"
```

The adapter package keeps this environment independent from the `nemo-fabric`
distribution and does not install Hermes Agent. Use matching NeMo Fabric
release versions for the runtime and adapter package unless a different
pairing has been explicitly validated.

Run NeMo Fabric from its environment and set `ADAPTER_PYTHON` to the interpreter
that contains the adapter and harness:

```bash
source .venv-fabric/bin/activate
export ADAPTER_PYTHON="${HERMES_HOME:-$HOME/.hermes}/hermes-agent/venv/bin/python"
```
The adapter package keeps the Hermes environment independent from the
`nemo-fabric` runtime distribution and does not install Hermes Agent. Keep the
NeMo Fabric environment active and `ADAPTER_PYTHON` set when running NeMo
Fabric. Use matching NeMo Fabric release versions for the runtime and adapter
package unless a different pairing has been explicitly validated.

For package options and platform-specific instructions, refer to the
[installation guide](docs/getting-started/install.mdx).
Expand Down
18 changes: 8 additions & 10 deletions examples/notebooks/01_quickstart.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,6 +92,7 @@
"import os\n",
"import sys\n",
"\n",
"os.environ[\"FABRIC_PYTHON\"] = sys.executable\n",
"os.environ[\"HERMES_PYTHON\"] = os.environ.get(\"ADAPTER_PYTHON\", sys.executable)"
]
},
Expand All @@ -103,20 +104,17 @@
"outputs": [],
"source": [
"%%bash\n",
"pip show -q \"nemo-fabric\"\n",
"NEMO_FABRIC_CHECK=$?\n",
"set -euo pipefail\n",
"\n",
"pip show -q \"nemo-fabric-adapters-hermes\"\n",
"ADAPTERS_HERMES_CHECK=$?\n",
"NEMO_FABRIC_VERSION=\"0.2.0\"\n",
"\n",
"if [ \"$NEMO_FABRIC_CHECK\" -ne 0 ] || \\\n",
" [ \"$ADAPTERS_HERMES_CHECK\" -ne 0 ]; then\n",
" pip install nemo-fabric nemo-fabric-adapters-hermes\n",
"else\n",
" echo \"NeMo Fabric and the Hermes adapter are already installed\"\n",
"if [ \"$(\"$FABRIC_PYTHON\" -c 'from importlib.metadata import version; print(version(\"nemo-fabric\"))' 2>/dev/null || true)\" != \"$NEMO_FABRIC_VERSION\" ]; then\n",
" \"$FABRIC_PYTHON\" -m pip install \"nemo-fabric==$NEMO_FABRIC_VERSION\"\n",
"fi\n",
"if [ \"$(\"$HERMES_PYTHON\" -c 'from importlib.metadata import version; print(version(\"nemo-fabric-adapters-hermes\"))' 2>/dev/null || true)\" != \"$NEMO_FABRIC_VERSION\" ]; then\n",
" \"$HERMES_PYTHON\" -m pip install \"nemo-fabric-adapters-hermes==$NEMO_FABRIC_VERSION\"\n",
"fi\n",
"\n",
"set -euo pipefail\n",
"# f80f453ae0679347e38abc917c7f94f717bf96c5 aligns with Hermes Agent v0.20.1.\n",
"HERMES_COMMIT=\"f80f453ae0679347e38abc917c7f94f717bf96c5\"\n",
"REPO_ROOT=\"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\"\n",
Expand Down
52 changes: 6 additions & 46 deletions examples/notebooks/02_variations.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,7 @@
"import os\n",
"import sys\n",
"\n",
"os.environ[\"FABRIC_PYTHON\"] = sys.executable\n",
"os.environ[\"HERMES_PYTHON\"] = os.environ.get(\"ADAPTER_PYTHON\", sys.executable)"
]
},
Expand All @@ -92,56 +93,15 @@
"outputs": [],
"source": [
"%%bash\n",
"pip show -q \"nemo-fabric\"\n",
"NEMO_FABRIC_CHECK=$?\n",
"\n",
"pip show -q \"nemo-fabric-adapters-claude\"\n",
"ADAPTERS_CLAUDE_CHECK=$?\n",
"\n",
"pip show -q \"claude-agent-sdk\"\n",
"CLAUDE_AGENT_SDK_CHECK=$?\n",
"\n",
"pip show -q \"nemo-fabric-adapters-codex\"\n",
"ADAPTERS_CODEX_CHECK=$?\n",
"\n",
"pip show -q \"openai-codex\"\n",
"OPENAI_CODEX_CHECK=$?\n",
"\n",
"pip show -q \"nemo-fabric-adapters-deepagents\"\n",
"ADAPTERS_DEEPAGENTS_CHECK=$?\n",
"\n",
"pip show -q \"deepagents\"\n",
"DEEPAGENTS_CHECK=$?\n",
"\n",
"pip show -q \"langchain\"\n",
"LANGCHAIN_CHECK=$?\n",
"\n",
"pip show -q \"langgraph\"\n",
"LANGGRAPH_CHECK=$?\n",
"\n",
"pip show -q \"nemo-fabric-adapters-hermes\"\n",
"ADAPTERS_HERMES_CHECK=$?\n",
"set -euo pipefail\n",
"\n",
"pip show -q \"nemo-relay\"\n",
"NEMO_RELAY_CHECK=$?\n",
"NEMO_FABRIC_VERSION=\"0.2.0\"\n",
"\"$FABRIC_PYTHON\" -m pip install \"nemo-fabric[claude,codex,deepagents,relay]==$NEMO_FABRIC_VERSION\"\n",
"\n",
"if [ \"$NEMO_FABRIC_CHECK\" -ne 0 ] || \\\n",
" [ \"$ADAPTERS_CLAUDE_CHECK\" -ne 0 ] || \\\n",
" [ \"$CLAUDE_AGENT_SDK_CHECK\" -ne 0 ] || \\\n",
" [ \"$ADAPTERS_CODEX_CHECK\" -ne 0 ] || \\\n",
" [ \"$OPENAI_CODEX_CHECK\" -ne 0 ] || \\\n",
" [ \"$ADAPTERS_DEEPAGENTS_CHECK\" -ne 0 ] || \\\n",
" [ \"$DEEPAGENTS_CHECK\" -ne 0 ] || \\\n",
" [ \"$LANGCHAIN_CHECK\" -ne 0 ] || \\\n",
" [ \"$LANGGRAPH_CHECK\" -ne 0 ] || \\\n",
" [ \"$ADAPTERS_HERMES_CHECK\" -ne 0 ] || \\\n",
" [ \"$NEMO_RELAY_CHECK\" -ne 0 ]; then\n",
" pip install \"nemo-fabric[claude,codex,deepagents,relay]\" nemo-fabric-adapters-hermes\n",
"else\n",
" echo \"All package-installable dependencies are already installed\"\n",
"if [ \"$(\"$HERMES_PYTHON\" -c 'from importlib.metadata import version; print(version(\"nemo-fabric-adapters-hermes\"))' 2>/dev/null || true)\" != \"$NEMO_FABRIC_VERSION\" ]; then\n",
" \"$HERMES_PYTHON\" -m pip install \"nemo-fabric-adapters-hermes==$NEMO_FABRIC_VERSION\"\n",
"fi\n",
"\n",
"set -euo pipefail\n",
"# f80f453ae0679347e38abc917c7f94f717bf96c5 aligns with Hermes Agent v0.20.1.\n",
"HERMES_COMMIT=\"f80f453ae0679347e38abc917c7f94f717bf96c5\"\n",
"REPO_ROOT=\"$(git rev-parse --show-toplevel 2>/dev/null || pwd)\"\n",
Expand Down
Loading