feat: Python version-aware Docker image selection (#261)

* feat: Python version-aware Docker image selection

Auto-detect user's Python version at build/deploy time and select
the matching runtime image. Supports 3.10-3.12 (3.13+ not stable).

SDK changes:
- Add get_image_name() for versioned tag resolution (py3.11-latest)
- Add python_version field to ServerlessResource (in _hashed_fields)
- Wire LiveServerless/LiveLoadBalancer to use get_image_name()
- Add build-time validation with actionable error for unsupported versions
- Record python_version in flash_manifest.json
- Narrow pyproject.toml to >=3.10,<3.13

GPU images require Python 3.11+ (no PyTorch CUDA 12.8 image for 3.10).
CPU images support 3.10-3.12. Env var overrides (FLASH_GPU_IMAGE etc.)
bypass version logic entirely.

Tag format: runpod/flash:py3.11-latest (latest alias kept for py3.12)

* fix(review): address PR #261 feedback

- Move env-var override check before version validation in get_image_name
- Add regression tests for override bypassing unsupported versions
- Fix python_version field description (no auto-detection at field level)
- Fix build error message to recommend switching local Python
- Rename mismatched test (test_default_python_version_is_3_11)

* fix(review): add python_version to CPU subclass _input_only sets

Prevents python_version from leaking into GraphQL payloads for
CpuServerlessEndpoint and CpuLoadBalancerSlsResource.

* fix(review): address Henrik's review on PR #261

- Move Python version validation before `if requirements:` so no-dep
  projects are also checked (was silently skipped)
- Pass python_version to ManifestBuilder instead of reading sys.version_info
  at manifest build time
- Remove duplicate version check from install_dependencies (now done
  unconditionally in run_build)

* fix: pass python_version from manifest to resource constructors

create_resource_from_manifest now accepts python_version and includes
it in deployment_kwargs. All three call sites in deployment.py extract
python_version from the manifest and pass it through.

Fixes the bug where deploying from a 3.12 environment always selected
the default 3.11 image because python_version was never propagated.

* fix: auto-detect local Python version for live serverless image selection

LiveServerless used DEFAULT_PYTHON_VERSION (3.11) when python_version was
not set, causing cloudpickle serialization mismatches for users on other
Python versions. Now uses local_python_version() to detect the running
interpreter's version.

* fix: align tests with GPU_PYTHON_VERSIONS including 3.10

Tests were asserting GPU_PYTHON_VERSIONS == ("3.11", "3.12") but the
source has ("3.10", "3.11", "3.12"). Updated tests to match: GPU 3.10
is valid, not a raise.

* docs: document Python version constraints for deployed workers

GPU workers are pinned to Python 3.12 (torch/CUDA only installed for
3.12 in base image). CPU workers support 3.10-3.12. Build pipeline
handles wheel selection automatically.

* feat: pin GPU builds to Python 3.12 and auto-exclude base image packages

- Add BASE_IMAGE_PACKAGES (torch, numpy, triton) auto-excluded from
  build artifacts to avoid exceeding the 500 MB tarball limit
- Set target_python_version per resource in manifest (GPU=3.12 from
  base image, CPU=3.12 default) so pip downloads correct ABI wheels
- GPU LiveServerless/LiveLoadBalancer now use GPU_BASE_IMAGE_PYTHON_VERSION
  instead of local_python_version() for image selection
- create_tarball filters excluded packages at archive time instead of
  constraining pip resolution (avoids ResolutionImpossible errors)
- DEFAULT_PYTHON_VERSION changed from 3.11 to 3.12

* chore: bump status to Beta and update lockfile

* fix: restrict GPU_PYTHON_VERSIONS to 3.12 only

GPU base image only has torch/CUDA for 3.12, so GPU_PYTHON_VERSIONS
must reflect that. get_image_name now rejects 3.10/3.11 for GPU/LB
image types, preventing deployment of non-existent image tags.

* refactor: use DEFAULT_WORKERS_MIN/MAX constants in _normalize_workers

Replace hardcoded 0 and 1 in endpoint._normalize_workers() with the
named constants from core.resources.constants. Update tests to assert
against the constants instead of magic numbers.

* fix(review): address PR #261 feedback -- centralize python version validation

- Refactor ServerlessResource.validate_python_version to delegate to
  constants.validate_python_version instead of duplicating logic

* chore(ci): trim Python matrix to 3.10-3.12 matching requires-python

requires-python caps at <3.13, so 3.13/3.14 CI rows would fail on
pip install. Align CI matrix with supported range.

Author: deanq

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
+        python-version: ['3.10', '3.11', '3.12']
     timeout-minutes: 15
 
     steps:

README.md

@@ -155,6 +155,14 @@ Browse working examples: **[github.com/runpod/flash-examples](https://github.com
 - macOS or Linux (Windows support in development)
 - [Runpod account](https://runpod.io/console) with API key
 
+### Python version in deployed workers
+
+Your local Python version does not affect what runs in the cloud. `flash build` downloads wheels for the container's Python version automatically.
+
+- **GPU workers**: Python 3.12 only. The GPU base image ships multiple interpreters (3.9-3.14) for interactive pod use, but torch and CUDA libraries are installed only for 3.12. Using a different version would require reinstalling torch (~2GB) and matching all C-extension wheel ABIs.
+- **CPU workers**: Python 3.10, 3.11, or 3.12. Configurable via the `PYTHON_VERSION` build arg.
+- **Image tags**: `py{version}-{tag}` (e.g., `runpod/flash:py3.12-latest`).
+
 ## Contributing
 
 We welcome contributions! See [RELEASE_SYSTEM.md](RELEASE_SYSTEM.md) for development workflow.

pyproject.toml

@@ -8,12 +8,12 @@ authors = [
 readme = "README.md"
 license = { text = "MIT" }
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Programming Language :: Python :: 3",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
-requires-python = ">=3.10,<3.15"
+requires-python = ">=3.10,<3.13"
 
 dependencies = [
     "cloudpickle>=3.1.1",