agentic-mobile-control/openspec/changes/downgrade-python-3-13-paddleocr/proposal.md

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).