## Why PaddlePaddle has not published a Python 3.14 (`cp314`) wheel on PyPI (confirmed against PyPI project page and `PaddlePaddle/PaddleOCR#17370`, upstream tracking issue, no ETA). `perception/ocr.py::PaddleOCREngine` requires `paddlepaddle` at runtime to actually run inference, and `paddleocr>=3.0.0` is a hard dependency in `pyproject.toml`. Because the workspace pins `requires-python = ">=3.14"`, any host running this project on Python 3.14 can install `paddleocr` (pure-Python wheel) but can never install `paddlepaddle` — OCR will always fail with `RuntimeError: Engine 'paddle_static' is unavailable because dependency 'paddlepaddle' is not installed.` regardless of how the package is installed. This has already caused a production task failure (`assignment ec036... attempt 1 on device-8967d09f0d5f4cf49f7361a9f0dcb0ce: failed`). `docs/MACOS_IPHONE_SETUP.md` already anticipated this class of problem and explicitly told operators not to downgrade to Python 3.13 ad hoc — it requires this to be done as a reviewed, workspace-wide compatibility change first. This proposal is that change. ## What Changes - Lower the workspace's minimum/target Python version from `3.14` to `3.13` so `paddlepaddle` (and therefore working OCR) can actually be installed. **BREAKING**: any environment currently pinned to Python 3.14 must reinstall its toolchain with Python 3.13; `uv.lock` will be regenerated against the new interpreter and is not compatible with a 3.14-only environment. - Update `requires-python` in all four workspace `pyproject.toml` files (root, `apps/device-host-agent`, `apps/cloud-api`, `packages/cloud-platform`) from `>=3.14` to `>=3.13,<3.14`. - Update the Docker/CI base image from `astral-sh/uv:python3.14-bookworm-slim` to `astral-sh/uv:python3.13-bookworm-slim` in `Dockerfile` and `Jenkinsfile`. - Regenerate `uv.lock` against Python 3.13, which is expected to newly resolve a `paddlepaddle` wheel as installable (it is not added as a declared dependency by this change — see Non-Goals in design.md). - Audit the codebase for any Python-3.14-only syntax/stdlib usage that would break under 3.13, and fix or confirm none exists. - Update `docs/MACOS_IPHONE_SETUP.md` to remove/replace the now-obsolete "do not downgrade to 3.13 ad hoc" warning with guidance matching the new baseline. ## Capabilities ### New Capabilities - `python-runtime-baseline`: declares and enforces the workspace's supported Python interpreter version (3.13) consistently across all `pyproject.toml` files, `uv.lock`, the Docker image, and the CI pipeline. ### Modified Capabilities (none — no *existing* capability's observable requirements change; `perception-provider` and `host-agent-protocol` behavior are unaffected, only the Python interpreter version and dependency resolution change) ## Impact - **Affected files**: `pyproject.toml`, `apps/device-host-agent/pyproject.toml`, `apps/cloud-api/pyproject.toml`, `packages/cloud-platform/pyproject.toml`, `uv.lock`, `Dockerfile`, `Jenkinsfile`, `docs/MACOS_IPHONE_SETUP.md`. - **Affected systems**: local dev environments, CI (Jenkins), production Docker images/deployment — all must move to Python 3.13. - **Dependencies**: full `uv lock` re-resolution against 3.13; no dependency version pins in `pyproject.toml` are expected to need changes, but the lock will reflect whatever the resolver picks for 3.13. - **Out of scope**: actually declaring `paddlepaddle` as a project dependency (remains a manual per-host install, per prior decision) and hardening `perception/ocr.py::run_ocr()` to catch `RuntimeError` (previously declined by the user as a separate concern).