chore: add .python-version pin (#244)

## Summary

ran into weird bootstrapping issues with uv install python 3.13 due to
the recently relaxed versions. adding a pin here for now.

---------

Signed-off-by: aagonzales <aagonzales@nvidia.com>
Signed-off-by: Aaron Gonzales <aaron@aarongonzales.net>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: 3 people

.github/actions/setup-python-env/action.yml

@@ -21,9 +21,9 @@ inputs:
     required: false
     default: ""
   python-version:
-    description: "Python version to use"
+    description: "Python version to use (defaults to .python-version when empty)"
     required: false
-    default: "3.11"
+    default: ""
   fetch-depth:
     description: "Number of commits to fetch (0 for all history)"
     required: false
@@ -69,10 +69,17 @@ runs:
         enable-cache: true
 
     - name: Set up Python ${{ inputs.python-version }}
+      if: inputs.python-version != ''
       uses: actions/setup-python@v5
       with:
         python-version: ${{ inputs.python-version }}
 
+    - name: Set up Python from .python-version
+      if: inputs.python-version == ''
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: ".python-version"
+
     - name: Install tools
       if: inputs.bootstrap-tools == 'true'
       shell: bash

.github/workflows/README.md

@@ -7,18 +7,18 @@ This directory contains GitHub Actions workflows for CI/CD automation.
 
 ## Workflows Overview
 
-
-| Workflow                                           | Trigger                               | Description                                          |
-| -------------------------------------------------- | ------------------------------------- | ---------------------------------------------------- |
-| [ci-checks.yml](ci-checks.yml)                     | Push to `main`, PRs, manual           | Format, typecheck, and unit tests (CPU)              |
-| [gpu-tests.yml](gpu-tests.yml)                     | Push to `main`/`pull-request/*`, manual | GPU E2E tests (A100)                               |
-| [conventional-commit.yml](conventional-commit.yml) | PRs                                   | Validates PR titles follow conventional commit format |
-| [copyright-check.yml](copyright-check.yml)         | Push to `main`/`pull-request/*`        | Validates NVIDIA copyright headers on Python files   |
-| [docs.yml](docs.yml)                               | Push to `main` (docs paths)           | Builds and deploys documentation to GitHub Pages     |
-| [internal-release.yml](internal-release.yml)       | Tag push (`v[0-9]*`), manual dispatch | Builds and publishes wheel to Artifactory or PyPI    |
-| [release.yml](release.yml)                         | Manual dispatch                       | Builds and publishes package to PyPI (production)    |
-| [secrets-detector.yml](secrets-detector.yml)       | PRs                                   | Scans for accidentally committed secrets             |
-
+All workflows that use `.github/actions/setup-python-env` now default to the version in `../../.python-version`. Set the action input `python-version` only when a job intentionally needs an override.
+
+| Workflow                                           | Trigger                                  | Description                                           |
+| -------------------------------------------------- | ---------------------------------------- | ----------------------------------------------------- |
+| [ci-checks.yml](ci-checks.yml)                     | Push to `main`, PRs, manual              | Format, typecheck, and unit tests (CPU)               |
+| [gpu-tests.yml](gpu-tests.yml)                     | Push to `main`/`pull-request/*`, manual  | GPU E2E tests (A100)                                  |
+| [conventional-commit.yml](conventional-commit.yml) | PRs                                      | Validates PR titles follow conventional commit format |
+| [copyright-check.yml](copyright-check.yml)         | Push to `main`/`pull-request/*`          | Validates NVIDIA copyright headers on Python files    |
+| [docs.yml](docs.yml)                               | Push to `main` (docs paths)              | Builds and deploys documentation to GitHub Pages      |
+| [internal-release.yml](internal-release.yml)       | Tag push (`v[0-9]*`), manual dispatch    | Builds and publishes wheel to Artifactory or PyPI     |
+| [release.yml](release.yml)                         | Manual dispatch                          | Builds and publishes package to PyPI (production)     |
+| [secrets-detector.yml](secrets-detector.yml)       | PRs                                      | Scans for accidentally committed secrets              |
 
 ## Pull Request Testing (copy-pr-bot)
 
@@ -109,7 +109,7 @@ flowchart LR
 The `ci-checks.yml` workflow runs on every push to `main` and on pull requests. Every check step calls a `make` target so the Makefile is the single source of truth for how each check runs.
 
 | Job | `make` target | What it checks |
-|---|---|---|
+| --- | --- | --- |
 | Format | `format-check` | `ruff format --check` + `ruff check` + SPDX copyright headers |
 | Format (lock) | `lock-check` | `uv.lock` matches `pyproject.toml` |
 | Typecheck | `typecheck` | `ty check` (excludes per `pyproject.toml [tool.ty.src]`) |
@@ -204,6 +204,7 @@ The `internal-release.yml` workflow builds a wheel and publishes it to NVIDIA Ar
 **Tag push (automatic):** Pushing a `v[0-9]*` tag (e.g. `git tag v0.2.0 && git push --tags`) automatically builds and publishes to Artifactory. This is the primary release mechanism.
 
 **Manual dispatch:** Go to Actions > Internal Release and run with:
+
 - `release-ref`: Branch, tag, or commit SHA to build (defaults to `main`)
 - `publish-target`: `artifactory` (default) or `pypi`
 
@@ -258,10 +259,11 @@ this is placeholder information until we do a real release. will update then.
 1. Go to Actions > Release NeMo Safe Synthesizer
 2. Click Run workflow
 3. Fill in the required inputs:
-  - `release-ref`: Full SHA or tag of the commit to release
-  - `dry-run`: Set to `false` for production release (publishes to PyPI)
-  - `create-gh-release`: Whether to create a GitHub release
-  - `version-bump-branch`: Branch to push the version bump PR (usually `main`)
+
+- `release-ref`: Full SHA or tag of the commit to release
+- `dry-run`: Set to `false` for production release (publishes to PyPI)
+- `create-gh-release`: Whether to create a GitHub release
+- `version-bump-branch`: Branch to push the version bump PR (usually `main`)
 
 ### Release Process
 
@@ -293,28 +295,24 @@ The release workflow automatically bumps the PATCH version (or PRE_RELEASE for r
 
 The following secrets must be configured in GitHub repository settings:
 
-
-| Secret                   | Purpose                      |
-| ------------------------ | ---------------------------- |
-| `TWINE_USERNAME`         | PyPI username                |
-| `TWINE_PASSWORD`         | PyPI API token               |
-| `SLACK_WEBHOOK_ADMIN`    | Slack admin notifications    |
-| `SLACK_RELEASE_ENDPOINT` | Slack release notifications  |
-| `PAT`                    | GitHub Personal Access Token |
-| `SSH_KEY`                | GPG signing key              |
-| `SSH_PWD`                | GPG key passphrase           |
-| `BOT_KEY`                | GitHub App private key       |
-| `ARTIFACTORY_USERNAME`     | NVIDIA Artifactory username  |
-| `ARTIFACTORY_TOKEN`       | NVIDIA Artifactory API key   |
-| `ARTIFACTORY_INTERNAL_URL`| NVIDIA Artifactory repo URL  |
-
-
+| Secret                      | Purpose                      |
+| --------------------------- | ---------------------------- |
+| `TWINE_USERNAME`            | PyPI username                |
+| `TWINE_PASSWORD`            | PyPI API token               |
+| `SLACK_WEBHOOK_ADMIN`       | Slack admin notifications    |
+| `SLACK_RELEASE_ENDPOINT`    | Slack release notifications  |
+| `PAT`                       | GitHub Personal Access Token |
+| `SSH_KEY`                   | GPG signing key              |
+| `SSH_PWD`                   | GPG key passphrase           |
+| `BOT_KEY`                   | GitHub App private key       |
+| `ARTIFACTORY_USERNAME`      | NVIDIA Artifactory username  |
+| `ARTIFACTORY_TOKEN`         | NVIDIA Artifactory API key   |
+| `ARTIFACTORY_INTERNAL_URL`  | NVIDIA Artifactory repo URL  |
 
 | Variable | Purpose       |
 | -------- | ------------- |
 | `BOT_ID` | GitHub App ID |
 
-
 ## Reusable Workflows
 
 All compliance and release workflows reuse templates from [NVIDIA-NeMo/FW-CI-templates](https://github.com/NVIDIA-NeMo/FW-CI-templates) (pinned to `v0.66.6`):
@@ -326,9 +324,8 @@ All compliance and release workflows reuse templates from [NVIDIA-NeMo/FW-CI-tem
 
 ## Configuration Files
 
-
-| File                                              | Purpose                              |
-| ------------------------------------------------- | ------------------------------------ |
-| `config/.secrets.baseline`                        | False positives for secrets detector |
-| `../../.python-version`                           | Python version for uv packaging      |
-| `../../src/nemo_safe_synthesizer/package_info.py` | Version information                  |
+| File | Purpose |
+| --- | --- |
+| `config/.secrets.baseline` | False positives for secrets detector |
+| `../../.python-version` | Python version source for CI |
+| `../../src/nemo_safe_synthesizer/package_info.py` | Version information |

.github/workflows/ci-checks.yml

@@ -107,14 +107,10 @@ jobs:
         run: make typecheck
 
   unit-test:
-    name: Unit Tests - (Python ${{ matrix.python-version }})
+    name: Unit Tests
     needs: changes
     if: ${{ needs.changes.outputs.src == 'true' || needs.changes.outputs.test == 'true' || needs.changes.outputs.deps == 'true' || github.event_name == 'workflow_dispatch' }}
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.11"]
     steps:
       - name: checkout
         uses: actions/checkout@v6
@@ -125,7 +121,6 @@ jobs:
         id: setup
         uses: ./.github/actions/setup-python-env
         with:
-          python-version: ${{ matrix.python-version }}
           bootstrap-tools: "true"
 
       - name: Bootstrap
@@ -136,7 +131,6 @@ jobs:
 
       - name: Upload coverage report
         uses: actions/upload-artifact@v7
-        if: matrix.python-version == '3.11'
         with:
           name: coverage-report
           path: coverage.json

.github/workflows/docs.yml

@@ -48,7 +48,6 @@ jobs:
         with:
           fetch-depth: 0
           bootstrap-tools: "true"
-          python-version: "3.11"
 
       - name: Install docs dependencies
         run: make bootstrap-nss dev

.github/workflows/gpu-tests.yml

@@ -56,15 +56,11 @@ jobs:
         uses: ./.github/actions/detect-changes
 
   gpu-e2e-test:
-    name: GPU E2E Tests - (Python ${{ matrix.python-version }})
+    name: GPU E2E Tests
     needs: changes
     if: ${{ needs.changes.outputs.src == 'true' || needs.changes.outputs.test == 'true' || github.event_name == 'workflow_dispatch' }}
     timeout-minutes: 60
     runs-on: linux-amd64-gpu-a100-latest-1
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.11"]
     steps:
       - name: checkout
         uses: actions/checkout@v6
@@ -75,7 +71,6 @@ jobs:
         id: setup
         uses: ./.github/actions/setup-python-env
         with:
-          python-version: ${{ matrix.python-version }}
           bootstrap-tools: "true"
 
       - name: Run GPU E2E tests

.python-version

@@ -0,0 +1 @@
+3.11

CONTRIBUTING.md

@@ -24,7 +24,7 @@ Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
 
 ### Prerequisites
 
-- Python 3.11+
+- Python 3.11+ (project supports Python ≥3.11; `.python-version` currently pins 3.11 for bootstrapping at the repo root)
 - Git 2.34+ (minimum required for SSH commit signing)
 
 > Note: Other tools like [uv](https://docs.astral.sh/uv/), [ruff](https://docs.astral.sh/ruff/), [ty](https://github.com/astral-sh/ty), and [gh](https://cli.github.com/) are installed automatically by `make bootstrap-tools`.

README.md

@@ -6,7 +6,7 @@ This package makes synthetic data, safely.
 
 ### Prerequisites
 
-- Python 3.11+
+- Python 3.11+ (we pin a specific 3.11.x in `.python-version` for local/dev bootstrap; any supported 3.11+ interpreter is fine)
 - [uv](https://docs.astral.sh/uv/) - Python package manager (>=0.9.14, <0.10.0)
 - Git
 

docs/user-guide/getting-started.md

@@ -14,7 +14,7 @@ does at each stage.
 
 ### Prerequisites
 
-- Python 3.11+
+- Python 3.11+ (dev tooling currently pins 3.11 via `.python-version` in the repo root)
 - CUDA runtime 12.8
 - NVIDIA GPU (A100 or better) for training and generation