feat: add CUDA-aware install helper

Document the generated CUDA dependency workflow and provide a shared installer path so users can select CPU, CUDA 12.8, or CUDA 13.0 with the required indexes and constraints.

Signed-off-by: Aaron Gonzales <aagonzales@nvidia.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: binaryaaron

CONTRIBUTING.md

@@ -487,6 +487,60 @@ All `make` targets check the entire project. Pre-commit scopes checks to staged
 | uv lock drift | `make lock-check` | not checked | on `pyproject.toml` changes |
 | DCO signoff | branch protection | not checked | commit-msg hook |
 
+## Dependency Updates
+
+Dependency updates have two generated surfaces:
+
+- CUDA/runtime extras: `cuda_deps.toml` is the source of truth. `pyproject.toml` is generated from it.
+- Security floors: `[tool.uv] constraint-dependencies` in `pyproject.toml` is the source of truth. `constraints.txt` is generated from it and published for downstream `pip` / `uv pip` installs.
+
+### CUDA and Accelerator Dependencies
+
+Edit `cuda_deps.toml` for changes to the CPU, CUDA 12.8, CUDA 13.0, PyTorch, FlashInfer, or NVIDIA package matrix. Do not hand-edit the generated `cpu`, `cu128`, `cu130`, `[tool.uv.sources]`, or `[[tool.uv.index]]` sections in `pyproject.toml`.
+
+After editing `cuda_deps.toml`, regenerate `pyproject.toml`:
+
+```bash
+uv run --script tools/gen_cuda_deps.py cuda_deps.toml --pyproject pyproject.toml
+uv lock
+```
+
+Then verify the generated sections are current:
+
+```bash
+uv run --script tools/gen_cuda_deps.py cuda_deps.toml --pyproject pyproject.toml --check
+uv run pytest tests/test_gen_cuda_deps.py
+make lock-check
+```
+
+When adding a new CUDA extra, update all user-facing install surfaces in the same PR:
+
+- `generated_extras` in `cuda_deps.toml`
+- `install_nss.sh`
+- `docs/user-guide/getting-started.md`
+- `README.md`
+
+Use dry runs to confirm the installer emits the expected command matrix:
+
+```bash
+DRY_RUN=1 CUDA=128 bash install_nss.sh
+DRY_RUN=1 CUDA=130 bash install_nss.sh
+DRY_RUN=1 CUDA=cpu bash install_nss.sh
+```
+
+### Security Floors and Constraints
+
+Dependabot CVE floors are applied with `tools/patch_dependabot.py`. The script bumps direct dependencies in `pyproject.toml`, adds transitive floors to `[tool.uv] constraint-dependencies`, writes the exported `constraints.txt`, and refreshes `uv.lock`.
+
+```bash
+export GITHUB_TOKEN="$(gh auth token)"
+uv run tools/patch_dependabot.py
+```
+
+The exported `constraints.txt` is intentionally not CUDA-version-specific. Runtime selection comes from the selected extra (`cpu`, `cu128`, `cu130`) and package indexes; security floors come from the shared constraints file.
+
+If you update `[tool.uv] constraint-dependencies` by hand, regenerate `constraints.txt` before opening a PR. The simplest supported path is to run `tools/patch_dependabot.py` with a cached `dependabot.json` or an active `GITHUB_TOKEN`, then review the resulting `pyproject.toml`, `constraints.txt`, and `uv.lock` diff.
+
 ## Documentation
 
 This project uses [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) for its documentation site, hosted at <https://nvidia-nemo.github.io/Safe-Synthesizer/>.
@@ -576,7 +630,29 @@ Before contributing, run `make format` and `make check`. See `AGENTS.md` for ful
 
 Releases are published to PyPI via the **Release NeMo Safe Synthesizer** GitHub Actions workflow. The workflow builds the wheel from a git tag, publishes to Test PyPI as a pre-flight check, publishes to the real PyPI, and creates a GitHub release.
 
-### 1. Create and push a tag
+### 1. Run dependency and install preflight
+
+Before tagging a release, verify generated dependency artifacts and install instructions are current:
+
+```bash
+uv run --script tools/gen_cuda_deps.py cuda_deps.toml --pyproject pyproject.toml --check
+uv run pytest tests/test_gen_cuda_deps.py
+make lock-check
+DRY_RUN=1 CUDA=128 bash install_nss.sh
+DRY_RUN=1 CUDA=130 bash install_nss.sh
+DRY_RUN=1 CUDA=cpu bash install_nss.sh
+```
+
+If Dependabot security floors changed since the last release, run:
+
+```bash
+export GITHUB_TOKEN="$(gh auth token)"
+uv run tools/patch_dependabot.py
+```
+
+Review `pyproject.toml`, `constraints.txt`, and `uv.lock` together. The release publishes the wheel to PyPI, but downstream installers also depend on the raw `constraints.txt` and `install_nss.sh` URLs from the release branch.
+
+### 2. Create and push a tag
 
 Release versions follow [PEP440](https://peps.python.org/pep-0440/) with major, minor, and patch release numbers.
 This project uses stable releases and release candidates only; prerelease versions append the suffix rcN (no dash, as specified by PEP440).
@@ -607,7 +683,7 @@ git tag v0.1.0rc1 <commit-sha>
 git push origin <tag>
 ```
 
-### 2. Monitor the workflow run
+### 3. Monitor the workflow run
 
 The [workflow](https://github.com/NVIDIA-NeMo/Safe-Synthesizer/actions/workflows/release.yml) to release is triggered automatically when a tag starting with `v` is pushed to GitHub.
 

README.md

@@ -16,17 +16,47 @@ Read detailed usage below, or jump to the documentation with [Getting Started](h
 
 ### Installation
 
+Choose one CUDA runtime extra. See the
+[installation guide](https://nvidia-nemo.github.io/Safe-Synthesizer/user-guide/getting-started/#install-the-package)
+for CPU and Docker installs.
+
+Installer script:
+
+```bash
+# CUDA 12.8 with the installer script:
+curl -fsSL https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/install_nss.sh | CUDA=128 bash
+
+# CUDA 13.0 with the installer script:
+curl -fsSL https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/install_nss.sh | CUDA=130 bash
+```
+
+Raw commands:
+
 ```bash
-# With uv (recommended):
+CONSTRAINTS_URL="https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt"
+
+# CUDA 12.8 with uv (recommended):
 uv pip install "nemo-safe-synthesizer[cu128,engine]" \
+  -c "$CONSTRAINTS_URL" \
   --index https://flashinfer.ai/whl/cu128 \
   --index https://download.pytorch.org/whl/cu128 \
+  --index https://pypi.nvidia.com \
+  --index-strategy unsafe-best-match
+
+# CUDA 13.0 with uv (requires NVIDIA Linux driver 580.65.06+):
+uv pip install "nemo-safe-synthesizer[cu130,engine]" \
+  -c "$CONSTRAINTS_URL" \
+  --index https://flashinfer.ai/whl/cu130 \
+  --index https://download.pytorch.org/whl/cu130 \
+  --index https://pypi.nvidia.com \
   --index-strategy unsafe-best-match
 
-# With pip:
+# CUDA 12.8 with pip:
 pip install "nemo-safe-synthesizer[cu128,engine]" \
+  -c "$CONSTRAINTS_URL" \
   --extra-index-url https://download.pytorch.org/whl/cu128 \
-  --extra-index-url https://flashinfer.ai/whl/cu128
+  --extra-index-url https://flashinfer.ai/whl/cu128 \
+  --extra-index-url https://pypi.nvidia.com
 ```
 
 Or install from source:
@@ -35,7 +65,9 @@ Or install from source:
 git clone https://github.com/NVIDIA-NeMo/Safe-Synthesizer.git
 cd Safe-Synthesizer
 make setup # installs the pinned mise version (if missing) + pinned tool versions from mise.lock
-make bootstrap-nss cuda
+uv sync --frozen --extra cu128 --extra engine --group dev
+# or, for CUDA 13.0:
+uv sync --frozen --extra cu130 --extra engine --group dev
 ```
 
 Development tools (`ruff`, `ty`, `yq`, `gh`, etc.) are managed via [mise](https://mise.jdx.dev/). Tool versions are declared in `.mise.toml` and locked in `mise.lock` (committed). mise also manages environment variables -- place project-local secrets or overrides in `.env` or `.env.local` (both git-ignored, auto-loaded by mise).

cuda_deps.toml

@@ -30,6 +30,17 @@ cuda_dependencies = [
 
 generated_extras = ["cpu", "cu128", "cu130"]
 
+# CUDA Python packaging context:
+# - Starting with CUDA Python 12.8, cuda-python is a metapackage that currently
+#   depends on cuda-bindings; the newer docs describe split components such as
+#   cuda.core, cuda.bindings, and cuda.pathfinder.
+# - CUDA 13.x optional Toolkit components are installed through the cuda-toolkit
+#   PyPI metapackage, and current NVIDIA package names are generally unsuffixed
+#   (for example, nvidia-cuda-nvrtc and nvidia-nvjitlink).
+# - Keep NVIDIA package routing per-library: nvidia-cublas is unsuffixed for both
+#   CUDA 12 and CUDA 13, while other CUDA 12 runtime packages may still need a
+#   -cu12 suffix and CUDA-specific PyTorch indexes.
+# - CUDA 13.x bindings require Linux driver 580.65.06 or newer.
 nvidia_cuda_libraries = [
   { name = "cublas", nvidia_package_suffix = "", index = "nvidia-pypi-public" },
   "cuda-cupti",

docs/user-guide/getting-started.md

@@ -26,35 +26,117 @@ does at each stage.
 
 ### Install the Package
 
-The CUDA and CPU extras depend on packages (PyTorch, FlashInfer) hosted on
-indexes outside PyPI. You must pass the extra index URLs shown below.
+Choose exactly one runtime extra: `cpu`, `cu128`, or `cu130`. Add `engine`
+when you want the CLI pipeline dependencies. Do not combine `cpu`, `cu128`,
+and `cu130`; they conflict by design.
+
+The CUDA and Linux CPU extras depend on packages hosted on indexes outside
+PyPI. You must pass the index URLs shown below for published-package installs.
+From a source checkout, `uv sync` reads the configured indexes from
+`pyproject.toml`.
+
+Published-package installs also use the exported
+[`constraints.txt`](https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt)
+security floor file. The same constraints file applies to all runtime extras;
+CUDA-specific package selection comes from the chosen extra and index URLs.
+
+#### Option 1: Installer Script
+
+The installer script is the shortest published-package path. It wraps the same
+extras, index URLs, and constraints file shown in the raw commands below.
+
+```bash
+# CUDA 12.8
+curl -fsSL https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/install_nss.sh | CUDA=128 bash
+
+# CUDA 13.0
+curl -fsSL https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/install_nss.sh | CUDA=130 bash
+
+# CPU-only development install
+curl -fsSL https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/install_nss.sh | CUDA=cpu bash
+```
+
+To inspect the script before running it:
+
+```bash
+curl -fsSLO https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/install_nss.sh
+CUDA=130 bash install_nss.sh
+```
+
+#### Option 2: Raw Commands
+
+Use the raw commands when you want to audit or customize every installer flag.
+
+!!! info "Why `--index-strategy unsafe-best-match`"
+    FlashInfer publishes wheels to flashinfer.ai, but `flashinfer-python`
+    can also appear on other package indexes at older versions. uv's default
+    `first-match` strategy stops at the first index that contains a package
+    name, so it can pick up the wrong version and fail to resolve.
+    `--index-strategy unsafe-best-match` tells uv to consider all indexes and
+    pick the best matching version.
 
 === "CUDA 12.8 (Linux with NVIDIA GPU)"
 
+    Use this for CUDA 12.8 environments.
+
     === "pip"
 
         ```bash
         pip install "nemo-safe-synthesizer[cu128,engine]" \
+          -c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt \
           --extra-index-url https://download.pytorch.org/whl/cu128 \
-          --extra-index-url https://flashinfer.ai/whl/cu128
+          --extra-index-url https://flashinfer.ai/whl/cu128 \
+          --extra-index-url https://pypi.nvidia.com
         ```
 
     === "uv"
 
         ```bash
         uv pip install "nemo-safe-synthesizer[cu128,engine]" \
+          -c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt \
           --index https://flashinfer.ai/whl/cu128 \
           --index https://download.pytorch.org/whl/cu128 \
+          --index https://pypi.nvidia.com \
           --index-strategy unsafe-best-match
         ```
 
-        !!! info "Why `--index-strategy unsafe-best-match`"
-            FlashInfer publishes wheels to flashinfer.ai, but `flashinfer-python`
-            also appears on the PyTorch index at older versions. uv's default
-            `first-match` strategy stops at the first index that contains a
-            package name, so it picks up the wrong version from the PyTorch
-            index and fails to resolve. `--index-strategy unsafe-best-match`
-            tells uv to consider all indexes and pick the best matching version.
+    === "source checkout"
+
+        ```bash
+        uv sync --frozen --extra cu128 --extra engine
+        ```
+
+=== "CUDA 13.0 (Linux with NVIDIA GPU)"
+
+    Use this for CUDA 13.0 environments. CUDA 13.x bindings require Linux
+    NVIDIA driver 580.65.06 or newer.
+
+    === "pip"
+
+        ```bash
+        pip install "nemo-safe-synthesizer[cu130,engine]" \
+          -c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt \
+          --extra-index-url https://download.pytorch.org/whl/cu130 \
+          --extra-index-url https://flashinfer.ai/whl/cu130 \
+          --extra-index-url https://pypi.nvidia.com
+        ```
+
+    === "uv"
+
+        ```bash
+        uv pip install "nemo-safe-synthesizer[cu130,engine]" \
+          -c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt \
+          --index https://flashinfer.ai/whl/cu130 \
+          --index https://download.pytorch.org/whl/cu130 \
+          --index https://pypi.nvidia.com \
+          --index-strategy unsafe-best-match
+        ```
+
+    === "source checkout"
+
+        ```bash
+        uv sync --frozen --extra cu130 --extra engine
+        ```
 
 === "CPU (macOS / Linux without GPU)"
 
@@ -66,26 +148,30 @@ indexes outside PyPI. You must pass the extra index URLs shown below.
     === "pip (macOS)"
 
         ```bash
-        pip install "nemo-safe-synthesizer[cpu,engine]"
+        pip install "nemo-safe-synthesizer[cpu,engine]" \
+          -c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt
         ```
 
     === "pip (Linux)"
 
         ```bash
         pip install "nemo-safe-synthesizer[cpu,engine]" \
+          -c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt \
           --extra-index-url https://download.pytorch.org/whl/cpu
         ```
 
     === "uv (macOS)"
 
         ```bash
-        uv pip install "nemo-safe-synthesizer[cpu,engine]"
+        uv pip install "nemo-safe-synthesizer[cpu,engine]" \
+          -c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt
         ```
 
     === "uv (Linux)"
 
         ```bash
         uv pip install "nemo-safe-synthesizer[cpu,engine]" \
+          -c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt \
           --index https://download.pytorch.org/whl/cpu
         ```
 
@@ -116,13 +202,15 @@ indexes outside PyPI. You must pass the extra index URLs shown below.
     === "pip"
 
         ```bash
-        pip install "nemo-safe-synthesizer"
+        pip install "nemo-safe-synthesizer" \
+          -c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt
         ```
 
     === "uv"
 
         ```bash
-        uv pip install "nemo-safe-synthesizer"
+        uv pip install "nemo-safe-synthesizer" \
+          -c https://raw.githubusercontent.com/NVIDIA-NeMo/Safe-Synthesizer/main/constraints.txt
         ```
 
     !!! note "Limited use"