fix(cli): make uv tool install the front door for nemo-platform

.github/actions/build-nemo-platform-wheel/action.yaml

@@ -43,9 +43,9 @@ inputs:
     required: false
     default: "19700101000000"
   python-version:
-    description: Python version for setup-uv.
+    description: Python version for setup-uv. Must be within the wheel's supported range.
     required: false
-    default: "3.11"
+    default: "3.12"
   source-root:
     description: >
       Path to the checked-out repository. release-bundle.yaml uses `source`;

.github/wheel-constraints/nemo-platform-plugin.txt

@@ -3,22 +3,22 @@
 # reproducibility; deep transitives resolve normally and cannot self-conflict.
 # Regenerate with: script/compile-wheel-constraints.sh <dir-with-built-wheels>
 #
-anthropic==0.118.0
+anthropic==0.122.0
 anyio==4.14.2
 distro==1.9.0
 docker==7.2.0
-fastapi==0.139.2
-fsspec==2026.6.0
+fastapi==0.141.1
+fsspec==2026.7.0
 httpx==0.28.1
 jsonschema==4.26.0
 lark==1.3.1
-ngcsdk==4.21.0
+ngcsdk==4.34.10
 nvidia-ml-py==13.610.43
-openai==2.47.0
-prompt-toolkit==3.0.52
+openai==3.0.0
+prompt-toolkit==3.0.53
 psutil==7.2.2
-pydantic-settings==2.14.2
 pydantic==2.13.4
+pydantic-settings==2.15.0
 pyyaml==6.0.3
 requests==2.34.2
 rich==15.0.0

.github/wheel-constraints/nemo-platform-services.txt

@@ -7,8 +7,8 @@ aioboto3==15.5.0
 aiofiles==25.1.0
 aiohttp==3.14.3
 aiosqlite==0.22.1
-alembic==1.18.5
-anthropic==0.118.0
+alembic==1.19.1
+anthropic==0.122.0
 anyio==4.14.2
 asyncpg==0.31.0
 base58==2.1.1
@@ -21,40 +21,46 @@ datasets==4.3.0
 distro==1.9.0
 docker==7.2.0
 duckdb==1.5.5
-fastapi==0.139.2
-fastmcp==3.4.4
+fastapi==0.141.1
+fastmcp==3.4.7
 fsspec==2025.9.0
-greenlet==3.5.4
+greenlet==3.5.5
 gunicorn==26.0.0
 httpx==0.28.1
-huggingface-hub==1.24.0
+huggingface-hub==1.27.0
 hvac==2.4.0
 jinja2==3.1.6
 jsonpath-ng==1.8.0
 jsonschema==4.26.0
 kubernetes==36.0.3
+langchain==1.3.15
 langchain-aws==1.1.0
 langchain-community==0.3.31
-langchain-core==1.5.0
+langchain-core==1.5.4
 langchain-nvidia-ai-endpoints==1.4.3
-langchain-openai==1.4.0
-langchain==1.3.14
+langchain-openai==1.5.0
 lark==1.3.1
+matplotlib==3.11.1
 nemo-anonymizer==0.3.3
 nemo-fabric==0.1.1
+nemo-fabric-adapters-hermes==0.1.1
+nemoguardrails==0.23.0
 nemo-relay==0.6.0
 nemo-safe-synthesizer==0.1.7
-nemoguardrails==0.23.0
-ngcsdk==4.21.0
+ngcsdk==4.34.10
+numpy==2.5.2
 nvidia-ml-py==13.610.43
-nvidia-nat-config-optimizer==1.8.0
-nvidia-nat-core==1.8.0
-nvidia-nat-langchain==1.8.0
-openai==2.47.0
+nvidia-nat-atif==1.9.0a20260811
+nvidia-nat-config-optimizer==1.9.0a20260811
+nvidia-nat-core==1.9.0a20260811
+nvidia-nat-eval==1.9.0a20260811
+nvidia-nat-langchain==1.9.0a20260811
+nvidia-nat-opentelemetry==1.9.0a20260811
+openai==2.54.0
 opentelemetry-distro==0.64b0
+opentelemetry-exporter-otlp==1.43.0
 opentelemetry-exporter-otlp-proto-grpc==1.43.0
 opentelemetry-exporter-otlp-proto-http==1.43.0
-opentelemetry-exporter-otlp==1.43.0
 opentelemetry-exporter-prometheus==0.64b0
 opentelemetry-instrumentation-fastapi==0.64b0
 opentelemetry-instrumentation-httpx==0.64b0
@@ -64,15 +70,16 @@ opentelemetry-instrumentation-system-metrics==0.64b0
 opentelemetry-processor-baggage==0.65b0
 opentelemetry-proto==1.43.0
 opentelemetry-sdk==1.43.0
+optuna==4.4.0
 pandas==2.3.3
-prometheus-client==0.25.0
-prometheus-fastapi-instrumentator==8.0.2
-prompt-toolkit==3.0.52
+prometheus-client==0.26.0
+prometheus-fastapi-instrumentator==8.1.0
+prompt-toolkit==3.0.53
 psutil==7.2.2
 psycopg2-binary==2.9.12
 pyarrow==24.0.0
-pydantic-settings==2.14.2
 pydantic==2.13.4
+pydantic-settings==2.15.0
 pyjwt==2.13.0
 pyleak==0.2.0
 python-multipart==0.0.32
@@ -83,7 +90,7 @@ rich==14.3.4
 rouge-score==0.1.2
 sacrebleu==2.6.0
 sniffio==1.3.1
-sqlalchemy==2.0.51
+sqlalchemy==2.0.52
 sqlmodel==0.0.39
 streaming-form-data==2.1.0
 structlog==26.1.0
@@ -92,7 +99,7 @@ typer==0.25.1
 types-aioboto3==15.5.0
 typing-extensions==4.16.0
 urllib3==2.7.0
-uvicorn==0.51.0
+uvicorn==0.52.3
 wasmtime==47.0.1
 xdg-base-dirs==6.0.2
 yara-python==4.5.1

.github/workflows/ci.yaml

@@ -1303,7 +1303,7 @@ jobs:
   # Test each wheel: install from the artifact and run basic CLI /
   # import checks.
   wheel-test:
-    name: ${{ matrix.package }} wheel build + test (py${{ matrix.python-version }})
+    name: ${{ matrix.package }} wheel build + test (py${{ matrix.python-version }}, ${{ matrix.install-method }})
     needs: [wheel-build]
     runs-on: ubuntu-latest
     timeout-minutes: 15
@@ -1314,6 +1314,13 @@ jobs:
       matrix:
         package: [nemo-platform, nemo-platform-plugin]
         python-version: ["3.12", "3.13"]
+        # `uv tool install` is the documented front door for the CLI; `venv`
+        # covers installs into an environment the user owns. The plugin is a
+        # library with no CLI entry point, so it only gets the venv leg.
+        install-method: [venv, tool]
+        exclude:
+          - package: nemo-platform-plugin
+            install-method: tool
     steps:
       - name: Checkout code
         uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
@@ -1337,9 +1344,11 @@ jobs:
         shell: bash
         env:
           PYTHON_VERSION: ${{ matrix.python-version }}
+          INSTALL_METHOD: ${{ matrix.install-method }}
           NMP_DATA_DIR: ${{ runner.temp }}/nemo-data
           NMP_AUTH_ENABLED: "false"
           _TYPER_FORCE_DISABLE_TERMINAL: "1"
+          UV_TOOL_BIN_DIR: ${{ runner.temp }}/wheelcheck/tool-bin
         run: |
           set -euo pipefail
           shopt -s nullglob
@@ -1351,14 +1360,25 @@ jobs:
           WHEEL="${wheels[0]}"
           # Supply-chain: partial-pin the wheel's direct external deps to a committed constraints
           # file. Regenerate with script/compile-wheel-constraints.sh.
-          VENV="${RUNNER_TEMP}/wheelcheck/.venv"
-          uv venv "${VENV}" --python "${PYTHON_VERSION}"
-          uv pip install --python "${VENV}/bin/python" \
-            --constraint "${GITHUB_WORKSPACE}/.github/wheel-constraints/nemo-platform-services.txt" \
-            "${WHEEL}[services]"
+          CONSTRAINTS="${GITHUB_WORKSPACE}/.github/wheel-constraints/nemo-platform-services.txt"
+          # --no-config: this step runs inside the checkout, so uv would otherwise apply the
+          # repo's [tool.uv] override-dependencies and resolve a dependency set no user can get.
+          if [[ "${INSTALL_METHOD}" == "tool" ]]; then
+            uv tool install --no-config --python "${PYTHON_VERSION}" \
+              --constraints "${CONSTRAINTS}" \
+              "${WHEEL}[services]"
+            BIN_DIR="${UV_TOOL_BIN_DIR}"
+          else
+            VENV="${RUNNER_TEMP}/wheelcheck/.venv"
+            uv venv "${VENV}" --python "${PYTHON_VERSION}"
+            uv pip install --no-config --python "${VENV}/bin/python" \
+              --constraint "${CONSTRAINTS}" \
+              "${WHEEL}[services]"
+            BIN_DIR="${VENV}/bin"
+          fi
           cd "${RUNNER_TEMP}/wheelcheck"
           unset PYTHONPATH VIRTUAL_ENV
-          export PATH="${VENV}/bin:${PATH}"
+          export PATH="${BIN_DIR}:${PATH}"
           bash "${GITHUB_WORKSPACE}/script/test-nemo-cli.sh"
 
       - name: Install + test nemo-platform-plugin
@@ -1379,7 +1399,7 @@ jobs:
           # (see the nemo-platform CLI step above).
           cd "${RUNNER_TEMP}/wheelcheck"
           uv venv .venv --python "${PYTHON_VERSION}"
-          uv pip install --python .venv/bin/python \
+          uv pip install --no-config --python .venv/bin/python \
             --constraint "${GITHUB_WORKSPACE}/.github/wheel-constraints/nemo-platform-plugin.txt" \
             "${WHEEL}"
           unset PYTHONPATH VIRTUAL_ENV

README.md

@@ -20,13 +20,13 @@ Quick install from PyPI:
 ```bash
 curl -LsSf https://astral.sh/uv/0.9.30/install.sh | sh
 export PATH="$HOME/.local/bin:$PATH"
-uv venv --python 3.13
-source .venv/bin/activate
-uv pip install nemo-platform
+uv tool install "nemo-platform[all]"
 
 nemo setup
 ```
 
+`uv tool install` gives you a global `nemo` command in its own isolated environment, with nothing to activate. The `all` extra adds the platform services, so `nemo services run` works; without it you get the SDK and CLI only. To import the SDK from your own code, `uv pip install "nemo-platform[all]"` into a virtual environment instead.
+
 Source checkout for development:
 
 ```bash

SETUP.md

@@ -86,7 +86,9 @@ is unavailable, start Docker and retry—do not proceed to `rm -rf`.
 
 ## Bootstrap and start
 
-The README documents the streamlined path. Prefer this over the manual steps below whenever the task fits — it covers prerequisites install, service startup, provider registration, default/fast model selection, and demo agent deployment in one shot:
+This section is the **source checkout** path: use it to work on NeMo Platform itself, on a local plugin, or on Studio assets. To only *use* the platform, install the published wheel instead — `uv tool install "nemo-platform[all]"` needs no checkout and no toolchain, then continue at `nemo setup`.
+
+The steps below cover prerequisites install, service startup, provider registration, default/fast model selection, and demo agent deployment in one shot. Prefer them over the manual sections further down whenever the task fits:
 
 Before running `make bootstrap`, install Flox from the [Flox installation guide](https://flox.dev/docs/install-flox/install). Flox is the recommended source-development toolchain and does not need to be activated first. Contributors using a preinstalled host toolchain instead need the versions printed by `make toolchain-versions` and a C compiler; they must use `make TOOLCHAIN=system bootstrap`.
 

docs/cli/index.mdx

@@ -28,25 +28,37 @@ If you previously installed the `nemo-microservices` package, uninstall it first
 pip uninstall nemo-microservices
 ```
 
-### Install in a Virtual Environment
+### Install
 
-Install the PyPI `nemo-platform` wrapper package in a Python 3.12-3.13 virtual environment. If you are working from a source checkout, run `make bootstrap` from the repository root instead; the generated SDK package under `sdk/python/nemo-platform/pyproject.toml` does not define the wrapper extras.
+Install the PyPI `nemo-platform` wrapper package. From a source checkout, run `make bootstrap` from the repository root instead; the generated SDK package under `sdk/python/nemo-platform/pyproject.toml` does not define the wrapper extras.
+
+<Tabs>
+
+<Tab title="uv tool (recommended)">
+
+One command, `nemo` available everywhere, nothing to activate.
 
 ```bash
-pip install "nemo-platform[all]"
+uv tool install "nemo-platform[all]"
 ```
 
-Or with uv:
+</Tab>
+
+<Tab title="Virtual environment">
+
+Use when you also import the SDK from your own code. `nemo` works only while the environment is active.
 
 ```bash
+uv venv
+source .venv/bin/activate
 uv pip install "nemo-platform[all]"
 ```
 
-<Warning>
+Plain `pip install "nemo-platform[all]"` works in an environment you manage yourself.
 
-When installed in a virtual environment, the `nemo` command is only available when the environment is activated.
+</Tab>
 
-</Warning>
+</Tabs>
 
 ### Verify Installation
 

docs/cli/troubleshooting.mdx

@@ -23,6 +23,25 @@ Activate the virtual environment where you installed the package:
 source /path/to/venv/bin/activate
 ```
 
+## Installation Issues
+
+### Install Fails Building a Dependency
+
+**Symptoms:**
+- `uv tool install "nemo-platform[all]"` fails while building a dependency, often on a missing C header such as `omp.h`
+
+**Cause:**
+
+NeMo Platform supports Python 3.12 and 3.13, but uv [picks the interpreter itself](https://docs.astral.sh/uv/concepts/tools/#python-versions), so an install can land on Python 3.14.
+
+**Solution:**
+
+Name a supported interpreter. uv downloads one if you do not have it:
+
+```bash
+uv tool install --python 3.13 "nemo-platform[all]"
+```
+
 ## Connection Issues
 
 ### Unable to Connect to Server

docs/get-started/setup.mdx

@@ -12,7 +12,7 @@ Install NeMo Platform and start working with AI agents.
 - Python 3.12-3.13
 - An API key from one of: [NVIDIA Build](https://build.nvidia.com), [OpenAI](https://platform.openai.com/api-keys), [Anthropic](https://console.anthropic.com/settings/keys), [Google Gemini](https://aistudio.google.com/apikey), or a local [Ollama](https://ollama.com) instance (no key needed)
 - 16 GB available disk space and 8 GB RAM
-- For the PyPI install: `pip` in a Python environment
+- For the PyPI install: [uv](https://docs.astral.sh/uv/) `>=0.9.14`, or `pip` in a Python environment
 - For the source checkout install: [Git](https://git-scm.com/), GNU Make, a C compiler, and [Flox](https://flox.dev/docs/install-flox/install) (recommended). A system-toolchain alternative is documented below.
 
 ## Install
@@ -21,21 +21,37 @@ Choose the install path that matches what you want to do.
 
 ### Install from PyPI
 
-Use the [PyPI package](https://pypi.org/project/nemo-platform/) for the quickest local install. The `all` extra includes the SDK, CLI, platform services, and default first-party plugins:
+Use the [PyPI package](https://pypi.org/project/nemo-platform/) for the quickest local install. The `all` extra includes the SDK, CLI, platform services, and default first-party plugins; drop it for the SDK and CLI alone.
+
+<Tabs>
+
+<Tab title="uv tool (recommended)">
+
+One command, `nemo` available everywhere, nothing to activate.
 
 ```bash
-python -m venv .venv
-source .venv/bin/activate
-pip install "nemo-platform[all]"
+uv tool install "nemo-platform[all]"
 ```
 
-For SDK and CLI usage only, install the base package:
+</Tab>
+
+<Tab title="Virtual environment">
+
+Use when you also import the SDK from your own code. `nemo` works only while the environment is active.
 
 ```bash
-pip install nemo-platform
+uv venv
+source .venv/bin/activate
+uv pip install "nemo-platform[all]"
 ```
 
-After installing `nemo-platform[all]` from PyPI, continue with `nemo setup`.
+Plain `pip install "nemo-platform[all]"` works in an environment you manage yourself.
+
+</Tab>
+
+</Tabs>
+
+Continue with `nemo setup`.
 
 ### Install from source