agentic-mobile-control/openspec/specs/python-runtime-baseline/spec.md

Purpose

Define the supported Python interpreter version range for the project workspace, container images, and CI pipeline, ensuring all environments converge on a single Python baseline.

Requirements

Requirement: Workspace-wide supported Python version

The system SHALL declare a single, consistent supported Python interpreter version range across the uv workspace root and every workspace member (apps/device-host-agent, apps/cloud-api, packages/cloud-platform), such that the range admits Python 3.13 and excludes Python 3.14, so that paddlepaddle (which has no Python 3.14 wheel available on PyPI) can be installed in every environment that follows the project's documented setup.

Scenario: Workspace resolves and syncs on Python 3.13

• WHEN an operator runs uv python install 3.13 followed by uv sync --locked --all-packages in the repository root
• THEN the sync succeeds and provisions a .venv using a Python 3.13 interpreter, with uv.lock resolved against that interpreter

Scenario: A Python 3.14 interpreter is rejected

• WHEN uv attempts to resolve or sync the workspace against a Python 3.14 interpreter
• THEN uv reports the interpreter as incompatible with the declared requires-python range, rather than silently proceeding

Requirement: Container and CI images match the declared Python baseline

The system SHALL build its Docker image and Jenkins CI pipeline using a base image whose Python version matches the workspace's declared requires-python range, so that containerized and CI environments never diverge from what local development targets.

Scenario: Docker image build uses the supported Python version

• WHEN the project's Dockerfile is built
• THEN the resulting image's base image is astral-sh/uv:python3.13-bookworm-slim

Scenario: CI pipeline uses the supported Python version

• WHEN the Jenkins pipeline defined in Jenkinsfile executes
• THEN it runs inside the astral-sh/uv:python3.13-bookworm-slim image