From f0a04ce7b79b53ce2eeb5e65f4568db9d20de1f5 Mon Sep 17 00:00:00 2001 From: Ajay Thorve Date: Fri, 14 Aug 2026 16:39:45 -0700 Subject: [PATCH] docs: correct Hermes split-environment setup Signed-off-by: Ajay Thorve --- .agents/skills/contribute-adapter/SKILL.md | 12 ++--- .agents/skills/maintain-packaging/SKILL.md | 14 +++--- README.md | 32 +++++++------ examples/notebooks/01_quickstart.ipynb | 18 ++++---- examples/notebooks/02_variations.ipynb | 52 +++------------------- 5 files changed, 49 insertions(+), 79 deletions(-) diff --git a/.agents/skills/contribute-adapter/SKILL.md b/.agents/skills/contribute-adapter/SKILL.md index 327acc622..28b059c05 100644 --- a/.agents/skills/contribute-adapter/SKILL.md +++ b/.agents/skills/contribute-adapter/SKILL.md @@ -31,12 +31,14 @@ Follow these repository-specific requirements after applying the public skill: `README.md`, `.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 diff --git a/.agents/skills/maintain-packaging/SKILL.md b/.agents/skills/maintain-packaging/SKILL.md index 08ca2fe2a..51aa73ebf 100644 --- a/.agents/skills/maintain-packaging/SKILL.md +++ b/.agents/skills/maintain-packaging/SKILL.md @@ -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 diff --git a/README.md b/README.md index ffb349aa8..c8b3275e3 100644 --- a/README.md +++ b/README.md @@ -181,6 +181,7 @@ 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 @@ -188,21 +189,26 @@ Install Hermes Agent by following its 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). diff --git a/examples/notebooks/01_quickstart.ipynb b/examples/notebooks/01_quickstart.ipynb index 60d50b34d..c0e8c4bbb 100644 --- a/examples/notebooks/01_quickstart.ipynb +++ b/examples/notebooks/01_quickstart.ipynb @@ -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)" ] }, @@ -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", diff --git a/examples/notebooks/02_variations.ipynb b/examples/notebooks/02_variations.ipynb index 5b282c61a..40f37f400 100644 --- a/examples/notebooks/02_variations.ipynb +++ b/examples/notebooks/02_variations.ipynb @@ -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)" ] }, @@ -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",