agentic-mobile-control/openspec/changes/archive/2026-07-14-downgrade-python-3-13-paddleocr/tasks.md

1. Update Python version pins

• 1.1 Update requires-python in root pyproject.toml from >=3.14 to >=3.13,<3.14
• 1.2 Update requires-python in apps/device-host-agent/pyproject.toml to >=3.13,<3.14
• 1.3 Update requires-python in apps/cloud-api/pyproject.toml to >=3.13,<3.14
• 1.4 Update requires-python in packages/cloud-platform/pyproject.toml to >=3.13,<3.14

2. Update container/CI base images

• 2.1 Update Dockerfile:26 base image from astral-sh/uv:python3.14-bookworm-slim to astral-sh/uv:python3.13-bookworm-slim
• 2.2 Update Jenkinsfile:58 image reference from astral-sh/uv:python3.14-bookworm-slim to astral-sh/uv:python3.13-bookworm-slim
• 2.3 Grep the repo for any other python3.14/3.14 references tied to the toolchain (excluding this change's own openspec/changes/ artifacts and historical openspec/changes/archive/ records) and update or confirm each is out of scope

3. Regenerate the lockfile and provision the environment

• 3.1 uv python install 3.13
• 3.2 uv lock to regenerate uv.lock against Python 3.13; confirm the resolution completes without conflict errors
• 3.3 uv sync --locked --all-packages to provision a fresh .venv; confirm it uses the 3.13 interpreter (uv run --package device-agent-runtime python --version)
• 3.4 Confirm paddlepaddle is now installable against the regenerated lock/environment (uv pip install paddlepaddle succeeds and python -c "import paddle" works) — manual, not added to pyproject.toml/uv.lock, per design.md Non-Goals

4. Verify no Python-3.14-only usage breaks under 3.13

• 4.1 Run the full non-integration suite against the 3.13 environment: uv run --all-packages pytest -m "not integration"; fix any failures caused by the interpreter downgrade (none expected per design.md D4) — 543 passed. Note: collection was initially blocked by pre-existing Python-2-style except X, Y: syntax errors (7 occurrences across runtime/task.py, packages/cloud-platform/cloud/sql_repository.py, packages/cloud-platform/cloud/internal_api/api.py), introduced by commit 22d37ca9 (2026-07-13) unrelated to this change's scope. Fixed as a drive-by (parenthesized the tuples) per user direction, since they blocked verification on any Python version.
• 4.2 Run uv run --all-packages python -m compileall . (or equivalent) across the workspace to catch any syntax-level incompatibility beyond what pytest collection would exercise — clean, no errors (scoped to project source dirs, excluding .venv)
• 4.3 Ruff check/format on any files touched by this change — uvx ruff check all checks passed; uvx ruff format --check 3 files already formatted (ruff isn't a project dependency, run ephemerally via uvx)

5. Update documentation

• 5.1 Update docs/MACOS_IPHONE_SETUP.md §4.2 to reflect the Python 3.13 baseline and remove/replace the now-obsolete "do not downgrade to 3.13 ad hoc" warning (lines ~156-158) with guidance that 3.13 is now the supported version
• 5.2 Sweep docs/MACOS_IPHONE_SETUP.md and any other docs for stray 3.14 references introduced when the project originally targeted 3.14, and correct them to 3.13 — only remaining 3.14 mentions are the intentional upper-bound pin and the paddlepaddle-wheel-availability explanation

6. Final validation

• 6.1 git diff --check (no whitespace errors) across all changed files — clean
• 6.2 openspec validate downgrade-python-3-13-paddleocr --strict — valid
• 6.3 Confirm all four pyproject.toml files and Dockerfile/Jenkinsfile agree on the same Python version, and uv.lock is committed alongside them — all agree on 3.13