chore: bump python default to 3.13

.github/workflows/ci-checks.yml

@@ -163,14 +163,14 @@ jobs:
 
       - name: Upload coverage report
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
-        if: matrix.python-version == '3.11'
+        if: matrix.python-version == '3.13'
         with:
           name: coverage-report
           path: coverage.json
           retention-days: 30
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@e79a6962e0d4c0c17b229090214935d2e33f8354 # v6
-        if: matrix.python-version == '3.11'
+        if: matrix.python-version == '3.13'
         with:
           files: coverage.json
           token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/gpu-tests.yml

@@ -87,6 +87,10 @@ jobs:
       }}
     timeout-minutes: 30
     runs-on: linux-amd64-gpu-a100-latest-1
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.13"]
     steps:
       - name: checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
@@ -96,6 +100,8 @@ jobs:
 
       - name: Setup GPU test environment
         uses: ./.github/actions/setup-gpu-test-env
+        with:
+          python-version: ${{ matrix.python-version }}
 
       - name: Run GPU smoke tests - train only
         timeout-minutes: 10

.python-version

@@ -1 +1 @@
-3.11
+3.13

CONTRIBUTING.md

@@ -27,7 +27,7 @@ Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
 
 ### Prerequisites
 
-- Python 3.11–3.13 (project supports Python 3.11, 3.12, and 3.13; `.python-version` currently pins 3.11 for bootstrapping at the repo root. Python 3.14+ is not supported — see [Troubleshooting](docs/user-guide/troubleshooting.md#python-314-is-not-supported))
+- Python 3.11–3.13 (project supports Python 3.11, 3.12, and 3.13; `.python-version` pins 3.13 for bootstrapping at the repo root. Python 3.14+ is not supported — see [Troubleshooting](docs/user-guide/troubleshooting.md#python-314-is-not-supported))
 - 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 setup` (via [mise](https://mise.jdx.dev/)). Tool versions are declared in `.mise.toml` and locked in `mise.lock` (committed), ensuring reproducible toolchains across developer systems and CI. These should not interfere with locally installed tools.
@@ -544,6 +544,10 @@ Before submitting a PR:
 
 For detailed style guidelines covering Python, markdown, Dockerfiles, shell scripts, testing, and docstrings, see [STYLE_GUIDE.md](STYLE_GUIDE.md).
 
+### Python Version Compatibility
+
+Although the default development/runtime interpreter is Python 3.13, source code must remain Python 3.11 syntax-compatible until the NMP platform moves its base Python version to 3.12. Do not use Python 3.12-only syntax such as PEP 695 `type` statements or bracketed generic class/function parameters in shared package code yet.
+
 ### Formatting, Linting, and Type Checking
 
 Use mise tasks instead of running `ruff` or `ty` directly. The tasks use pinned tool versions from `.mise.[toml|lock]` (installed via `make setup`) and check all tracked files.

README.md

@@ -9,7 +9,7 @@ Read detailed usage below, or jump to the documentation with [Getting Started](h
 
 ### Prerequisites
 
-- Python 3.11–3.13 (we pin a specific 3.11.x in `.python-version` for local/dev bootstrap; any 3.11, 3.12, or 3.13 interpreter works. Python 3.14+ is NOT supported because ray, a transitive dependency of vLLM, does not yet publish `cp314` wheels)
+- Python 3.11–3.13 (`.python-version` pins 3.13 for local/dev bootstrap; any 3.11, 3.12, or 3.13 interpreter works. Python 3.14+ is NOT supported because vLLM currently declares `<3.14` support while upstream resolves Python 3.14 wheel compatibility across its dependency stack)
 - [uv](https://docs.astral.sh/uv/) (recommended) or pip -- Python package manager
 - NVIDIA GPU (A100 or larger) for training and generation
 - Linux only -- macOS, Windows, and Apple Silicon are not supported for training or generation. A CPU-only install is available for development and configuration validation.

STYLE_GUIDE.md

@@ -116,7 +116,9 @@ How to write clear, testable Python -- independent of which library primitives y
 
 ### Type hints
 
-The codebase targets Python 3.11–3.13 and uses native typing syntax throughout. Expect 3.11 as the minimum for the foreseeable future; the upper bound tracks dependency availability (currently ray/vLLM lack `cp314` wheels).
+The codebase targets Python 3.11–3.13 and uses native typing syntax throughout. Expect 3.11 as the minimum for the foreseeable future; the upper bound tracks dependency availability (currently vLLM declares `<3.14` support while its dependency stack gains full `cp314` wheel coverage).
+
+Even though `.python-version` pins Python 3.13 for local development and CI defaults, shared package code must stay Python 3.11 syntax-compatible until the NMP platform moves its base Python version to 3.12. Do not use Python 3.12-only syntax yet, including PEP 695 `type` statements or bracketed generic class/function parameters. Prefer `TypeAlias`, `TypeVar`, and `typing_extensions` backports when newer typing features are useful before the minimum runtime moves.
 
 ```python
 from typing import Self, Sequence

containers/Dockerfile.cuda

@@ -63,7 +63,7 @@ ARG UBUNTU_VERSION=22.04
 # Use "runtime" when all deps ship pre-built wheels (current state).
 # Switch to "devel" if a future dependency requires CUDA compilation.
 ARG CUDA_IMAGE_TYPE=runtime
-ARG PYTHON_VERSION=3.11.13
+ARG PYTHON_VERSION=3.13.13
 
 # CUDA compute capabilities to compile for (used with CUDA_IMAGE_TYPE=devel).
 # Recommended values per architecture:

containers/Dockerfile.test_ci

@@ -1,6 +1,6 @@
-FROM python:3.11.13-slim AS setup
+FROM python:3.13.13-slim AS setup
 
-ARG PYTHON_VERSION=3.11.13
+ARG PYTHON_VERSION=3.13.13
 
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \

containers/README.md

@@ -10,7 +10,7 @@ Dockerfiles for running and testing Safe-Synthesizer in containers.
 | File | Base | Purpose |
 |------|------|---------|
 | `Dockerfile.cuda` | `nvidia/cuda:12.8.1-runtime-ubuntu22.04` | GPU runtime and dev images for training, generation, and evaluation |
-| `Dockerfile.test_ci` | `python:3.11.13-slim` | CPU-only test image (`mise run test:ci-container`) |
+| `Dockerfile.test_ci` | `python:3.13-slim` | CPU-only test image (`mise run test:ci-container`) |
 | `entrypoint.sh` | -- | Wrapper entrypoint for the runtime image (mount/GPU checks) |
 
 ## CUDA Image
@@ -83,7 +83,7 @@ Key flags:
 | `CUDA_VERSION` | `12.8.1` | CUDA toolkit version in the base image tag |
 | `UBUNTU_VERSION` | `22.04` | Ubuntu version in the base image tag |
 | `CUDA_IMAGE_TYPE` | `runtime` | Base image variant (`runtime` or `devel`) |
-| `PYTHON_VERSION` | `3.11.13` | Python version installed via `uv python install` to `/opt/python` |
+| `PYTHON_VERSION` | `3.13` | Python version installed via `uv python install` to `/opt/python` |
 | `UV_VERSION` | `0.9.30` | uv version for the deps stage (matches `.mise.toml` pin) |
 | `TARGETARCH` | _(set by BuildKit)_ | Target architecture (`amd64` or `arm64`) |
 | `CUDA_ARCH_FLAGS` | `80;86;90;90a` | CUDA SM capabilities for `nvcc` (override for arm64: `90;90a;120;120a`) |

docs/developer-guide/docker.md

@@ -24,7 +24,7 @@ flowchart TD
 
     subgraph stages [Build Stages]
         tools["tools\nInstalls mise + all dev tools\n(.mise.toml is single source of truth)"]
-        deps["deps\nInstalls Python 3.11 via uv\nuv sync cu129+engine"]
+        deps["deps\nInstalls Python 3.13 via uv\nuv sync cu129+engine"]
         runtime["runtime\nCopies venv + Python\nNon-root appuser\ntini + entrypoint.sh"]
         dev["dev\nExtends runtime\nCopies mise tree from tools\nRoot user"]
     end
@@ -101,7 +101,7 @@ command).
 | `CUDA_VERSION` | `12.8.1` | CUDA toolkit version in the base image tag |
 | `UBUNTU_VERSION` | `22.04` | Ubuntu version in the base image tag |
 | `CUDA_IMAGE_TYPE` | `runtime` | Base image variant for the deps stage. Change to `devel` if a dependency requires CUDA headers for compilation |
-| `PYTHON_VERSION` | `3.11.13` | Python version installed via `uv python install` |
+| `PYTHON_VERSION` | `3.13` | Python version installed via `uv python install` |
 | `TARGETARCH` | _(set by BuildKit)_ | Target architecture (`amd64` or `arm64`). Automatically populated by `docker buildx build --platform` |
 | `CUDA_ARCH_FLAGS` | `80;86;90;90a` | CUDA SM capabilities for `nvcc`. Override for arm64: `90;90a;120;120a` |
 
@@ -262,7 +262,7 @@ To reduce size:
 
 | Aspect | `Dockerfile.cuda` | `Dockerfile.test_ci` |
 |--------|-------------------|----------------------|
-| Base | `nvidia/cuda:12.9.1-runtime-ubuntu22.04` | `python:3.11-slim` |
+| Base | `nvidia/cuda:12.9.1-runtime-ubuntu22.04` | `python:3.13-slim` |
 | Extras | `cu129` + `engine` | `cpu` + `engine` |
 | GPU | Required | Not needed |
 | Stages | `tools` / `deps` / `runtime` / `dev` | `setup` / `install-deps` |