q792602257andClaude Opus 4.6
fa10cccf71
Change is complete (19/19 tasks) and its delta spec has been synced into a new main spec openspec/specs/python-runtime-baseline/spec.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
30 lines
3.6 KiB
Markdown
30 lines
3.6 KiB
Markdown
## 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).
|