uv and Build System

Package management with uv, extras for CPU/CUDA, hatch build, and dynamic versioning.

Bootstrap Commands

# Full dev environment (tools + Python + CPU deps)
mise run setup && mise run bootstrap-nss cpu

# Pick a variant:
mise run bootstrap-nss dev       # dev tools only (no engine/torch)
mise run bootstrap-nss cpu       # + engine + CPU PyTorch
mise run bootstrap-nss cu129     # + engine + CUDA 12.9 PyTorch
mise run bootstrap-nss cuda      # alias for cu129
mise run bootstrap-nss engine    # + engine (no torch)

# Slurm: force Python, caches, and the project venv onto Lustre
LUSTRE_DIR="/path/to/container-visible/project/directory" \
  MISE_IGNORED_CONFIG_PATHS="$HOME/.config/mise/config.toml" \
  MISE_LOCKED=1 mise run bootstrap-nss-slurm cu129

Under the hood: uv sync --frozen --extra <extra> [--extra engine] --group dev

bootstrap-nss-slurm requires LUSTRE_DIR, installs the pinned Python under that directory, recreates .venv if its interpreter is not container-visible, then runs the same frozen profile sync as bootstrap-nss.

Extras and Conflicts

cpu and cu129 conflict -- you must pick one, never both. Enforced in [tool.uv] conflicts.

Index Management

PyTorch wheels come from dedicated indexes, not PyPI:

All indexes are explicit = true (only used when a package is mapped to them in [tool.uv.sources]).

Adding Dependencies

# Add to base dependencies
uv add <package>

# Add to a dependency group
uv add --group dev <package>
uv add --group test <package>

# Change CPU or CUDA runtime extras
# Edit cuda_deps.toml, regenerate pyproject.toml, then lock.
uv run --frozen tools/gen_cuda_deps.py cuda_deps.toml --pyproject pyproject.toml
mise run lock:update

After any change: mise run lock:update to regenerate uv.lock. Pre-commit verifies the lock is up to date. The generated CPU/CUDA sections of pyproject.toml must not be edited directly; mise run check:lock verifies that they match cudadeps.toml. The generator owns the complete [tool.uv.sources] and [[tool.uv.index]] sections, so add every source or index there through cudadeps.toml.

Dependency Groups

Running Tools

Always use uv run to ensure the correct environment:

uv run pytest ...
uv run --frozen pytest ...     # Don't update lock
uv run --group docs mkdocs serve
uv run --frozen --no-project --group docs mkdocs build

Build and Version

# Build wheel (version from git tag via uv-dynamic-versioning)
mise run build-wheel     # or: uv build --wheel

# Publish to NVIDIA Artifactory
mise run publish:internal

Version source: uv-dynamic-versioning reads git tags (PEP 440 style). Fallback 0.0.0 for shallow clones.

Build backend: hatchling with wheel target packages = ["src/nemosafesynthesizer"].

Key pyproject.toml Sections

Vendor Package

[tool.vendor-package] configures vendoring Safe-Synthesizer into the NMP SDK:

• Target: beta.safe_synthesizer
• Includes specific paths from src/ and tests/
• Used by the prek tool during NMP sync

Conventions

1. Never use pip -- always uv
2. Use --frozen in CI and Make targets to prevent lock updates
3. Use uv run to run tools (pytest, mkdocs, etc.)
4. uv version is pinned in .mise.toml.
5. Edit non-generated pyproject.toml sections directly (e.g. dependency groups); CPU/CUDA extras go through cuda_deps.toml instead, then mise run lock:update
6. Use uv add for base/group deps