Python: run single-version tools on demand

.github/actions/python-setup/action.yml

@@ -47,4 +47,17 @@ runs:
       - name: Install the project
         shell: bash
         run: |
-          cd python && uv sync --all-packages --all-extras --all-groups --prerelease=if-necessary
+          cd python
+          sync_args=(
+            --all-packages
+            --all-extras
+            --all-groups
+            --no-group tool-runtime
+            --no-group tool-hooks
+            --no-group tool-markdown
+            --prerelease=if-necessary
+          )
+          if [[ -z "${{ inputs.exclude-packages }}" ]]; then
+            sync_args+=(--frozen)
+          fi
+          uv sync "${sync_args[@]}"

.github/dependabot.yml

@@ -63,19 +63,23 @@ updates:
   - package-ecosystem: "pip"
     directories:
       - "python/"
+      - "python/tooling/"
       - "python/packages/lab/"
     schedule:
       interval: "weekly"
       day: "thursday"
     groups:
       basics:
         patterns:
-          - "uv"
           - "ruff"
           - "prek"
           - "poethepoet"
           - "tomli"
           - "rich"
+          - "packaging"
+          - "pygments"
+          - "griffe"
+          - "opentelemetry-sdk"
       pytest:
         patterns:
           - "pytest*"
@@ -89,6 +93,10 @@ updates:
           - "pyrefly"
           - "ty"
           - "zuban"
+    # Root uv upgrades must update required-version, workflow pins, and the
+    # pre-commit revision together. Lab retains its independent uv updater.
+    ignore:
+      - dependency-name: "uv"
     labels:
       - "python"
       - "dependencies"
@@ -101,27 +109,26 @@ updates:
       interval: "weekly"
       day: "thursday"
     groups:
+      # Single-version tools in python/tooling/requirements-*.txt are handled
+      # by the pip updater above. This entry covers pyproject.toml and uv.lock.
       basics:
         patterns:
-          - "uv"
-          - "ruff"
           - "prek"
           - "poethepoet"
           - "tomli"
           - "rich"
+          - "packaging"
+          - "pygments"
+          - "opentelemetry-sdk"
       pytest:
         patterns:
           - "pytest*"
       flit:
         patterns:
           - "flit*"
-      python-type-checkers:
-        patterns:
-          - "mypy"
-          - "pyright"
-          - "pyrefly"
-          - "ty"
-          - "zuban"
+    # Avoid partial root uv bumps; coordinated uv upgrades are manual.
+    ignore:
+      - dependency-name: "uv"
     labels:
       - "python"
       - "dependencies"

.github/workflows/github-automation-tests.yml

@@ -13,6 +13,7 @@ on:
       - ".github/workflows/issue-plan.md"
       - ".github/workflows/issue-plan.lock.yml"
       - "python/pyproject.toml"
+      - "python/tooling/requirements-api-compatibility.txt"
       - "python/uv.lock"
   push:
     branches:
@@ -28,6 +29,7 @@ on:
       - ".github/workflows/issue-plan.md"
       - ".github/workflows/issue-plan.lock.yml"
       - "python/pyproject.toml"
+      - "python/tooling/requirements-api-compatibility.txt"
       - "python/uv.lock"
 
 permissions:
@@ -49,7 +51,7 @@ jobs:
 
       - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
-          version: "0.12.9"
+          version: "0.12.23"
 
       - name: Run JavaScript tests
         run: node --test .github/tests/*.js
@@ -63,17 +65,16 @@ jobs:
           UV_NO_CONFIG: "1"
         run: |
           griffe_requirement="$(
-            python3 - "$GITHUB_WORKSPACE/python/pyproject.toml" <<'PY'
+            python3 - "$GITHUB_WORKSPACE/python/tooling/requirements-api-compatibility.txt" <<'PY'
           import sys
-          import tomllib
 
-          with open(sys.argv[1], "rb") as pyproject_file:
-              dev_dependencies = tomllib.load(pyproject_file)["dependency-groups"]["dev"]
           requirements = [
-              dependency for dependency in dev_dependencies if dependency.startswith("griffe")
+              line.strip()
+              for line in open(sys.argv[1], encoding="utf-8")
+              if line.strip() and not line.lstrip().startswith("#")
           ]
           if len(requirements) != 1:
-              raise SystemExit("Expected exactly one Griffe development dependency")
+              raise SystemExit("Expected exactly one Griffe tool requirement")
           print(requirements[0])
           PY
           )"

.github/workflows/python-api-compatibility.yml

@@ -34,7 +34,7 @@ jobs:
         uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           enable-cache: false
-          version: "0.12.9"
+          version: "0.12.23"
 
       - name: Compare public API with the PR base
         working-directory: ${{ runner.temp }}
@@ -97,11 +97,16 @@ jobs:
 
           git -C "$GITHUB_WORKSPACE" show "$BASE_SHA:.github/scripts/check_python_api_compatibility.py" \
             > "$RUNNER_TEMP/check_python_api_compatibility.py"
-          git -C "$GITHUB_WORKSPACE" show "$BASE_SHA:python/pyproject.toml" \
-            > "$RUNNER_TEMP/python-pyproject.toml"
-
-          griffe_requirement="$(
-            python3 - "$RUNNER_TEMP/python-pyproject.toml" <<'PY'
+          if git -C "$GITHUB_WORKSPACE" cat-file -e \
+            "$BASE_SHA:python/tooling/requirements-api-compatibility.txt" 2>/dev/null; then
+            git -C "$GITHUB_WORKSPACE" show \
+              "$BASE_SHA:python/tooling/requirements-api-compatibility.txt" \
+              > "$RUNNER_TEMP/python-api-compatibility-requirements.txt"
+          else
+            git -C "$GITHUB_WORKSPACE" show "$BASE_SHA:python/pyproject.toml" \
+              > "$RUNNER_TEMP/python-base-pyproject.toml"
+            python3 - "$RUNNER_TEMP/python-base-pyproject.toml" \
+              > "$RUNNER_TEMP/python-api-compatibility-requirements.txt" <<'PY'
           import sys
           import tomllib
 
@@ -114,6 +119,21 @@ jobs:
               raise SystemExit("Expected exactly one Griffe development dependency")
           print(requirements[0])
           PY
+          fi
+
+          griffe_requirement="$(
+            python3 - "$RUNNER_TEMP/python-api-compatibility-requirements.txt" <<'PY'
+          import sys
+
+          requirements = [
+              line.strip()
+              for line in open(sys.argv[1], encoding="utf-8")
+              if line.strip() and not line.lstrip().startswith("#")
+          ]
+          if len(requirements) != 1:
+              raise SystemExit("Expected exactly one Griffe tool requirement")
+          print(requirements[0])
+          PY
           )"
 
           args=(

.github/workflows/python-code-quality.yml

@@ -140,4 +140,4 @@ jobs:
         env:
           UV_CACHE_DIR: /tmp/.uv-cache
       - name: Run tests/samples type checkers (mypy, pyrefly, ty)
-        run: uv run python scripts/workspace_poe_tasks.py ci-test-typing
+        run: uv run --locked --group tool-runtime python -m scripts.workspace_poe_tasks ci-test-typing

.github/workflows/python-dependency-maintenance.yml

@@ -43,18 +43,18 @@ jobs:
           echo "DEPENDENCY_RELEASE_CUTOFF=${cutoff}" >> "$GITHUB_ENV"
           echo "Using dependency release cutoff: ${cutoff}"
 
-      - name: Repin dev dependency declarations
+      - name: Repin development and tool dependency declarations
         run: uv run poe upgrade-dev-dependency-pins
         working-directory: ./python
 
-      - name: Refresh lockfile after dev pin updates
+      - name: Refresh lockfile after dependency pin updates
         run: uv lock
         working-directory: ./python
 
-      - name: Save dev dependency changes
+      - name: Save development and tool dependency changes
         run: |
           DEV_PATCH="${RUNNER_TEMP}/python-dev-dependency-updates.patch"
-          git diff -- python/pyproject.toml "python/packages/*/pyproject.toml" python/uv.lock > "${DEV_PATCH}"
+          git diff -- python/pyproject.toml "python/packages/*/pyproject.toml" "python/tooling/requirements-*.txt" python/uv.lock > "${DEV_PATCH}"
           if [ -s "${DEV_PATCH}" ]; then
             echo "has_dev_changes=true" >> "$GITHUB_OUTPUT"
           else
@@ -117,7 +117,7 @@ jobs:
             const bodyLines = [
               "Automated dependency bounds test mode failed before dependency upper-bound validation could run.",
               "",
-              "The weekly dependency maintenance workflow kept only dev dependency updates for the generated PR, if any, and skipped dependency range updates for this run.",
+              "The weekly dependency maintenance workflow kept only development and tool dependency updates for the generated PR, if any, and skipped dependency range updates for this run.",
               "",
             ]
 
@@ -271,13 +271,13 @@ jobs:
               core.info(`Created issue: ${title}`)
             }
 
-      - name: Keep only dev updates when range validation fails
+      - name: Keep only development and tool updates when range validation fails
         if: steps.validate_bounds_test.outcome != 'success' || steps.validate_ranges.outcome != 'success'
         env:
           DEV_PATCH: ${{ steps.dev_changes.outputs.patch }}
           HAS_DEV_CHANGES: ${{ steps.dev_changes.outputs.has_dev_changes }}
         run: |
-          git restore python/pyproject.toml python/packages/*/pyproject.toml python/uv.lock
+          git restore python/pyproject.toml python/packages/*/pyproject.toml python/tooling/requirements-*.txt python/uv.lock
           if [ "${HAS_DEV_CHANGES}" = "true" ]; then
             git apply "${DEV_PATCH}"
           fi
@@ -308,7 +308,7 @@ jobs:
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git checkout -B "${BRANCH}"
 
-          git add python/pyproject.toml python/packages/*/pyproject.toml python/uv.lock
+          git add python/pyproject.toml python/packages/*/pyproject.toml python/tooling/requirements-*.txt python/uv.lock
           if git diff --cached --quiet; then
             echo "has_changes=false" >> "$GITHUB_OUTPUT"
             echo "No dependency updates to commit."

.github/workflows/python-lab-tests.yml

@@ -78,10 +78,10 @@ jobs:
         run: uv run pytest -m "resource_intensive and not integration" --junitxml=test-results-resource-intensive.xml
 
       - name: Run lab lint
-        run: uv run poe lint
+        run: uv run poe syntax-check
 
       - name: Run lab format check
-        run: uv run poe fmt --check
+        run: uv run poe syntax-format --check
 
       - name: Run lab type checking
         run: uv run poe pyright

.github/workflows/python-openai-dependency-bounds.yml

@@ -13,6 +13,7 @@ on:
       - "python/scripts/dependencies/**"
       - "python/samples/04-hosting/container/hyperlight_codeact/call_server.py"
       - "python/shared_tasks.toml"
+      - "python/tooling/requirements-typing.txt"
 
 permissions:
   contents: read
@@ -60,5 +61,5 @@ jobs:
         run: |
           uv run --no-sync python -c "import openai; print(f'OpenAI SDK {openai.__version__}')"
           uv run --no-sync python -m pytest -m "not integration" --cov=${{ matrix.module }} --cov-report=term-missing:skip-covered tests
-          uv run --no-sync pyright
+          uv run --no-sync --with-requirements ../../tooling/requirements-typing.txt pyright
         working-directory: ./python/packages/${{ matrix.package }}

CONTRIBUTING.md

@@ -148,9 +148,9 @@ Only APIs from packages marked `released` in `python/PACKAGE_STATUS.md` are chec
 Prerelease packages and APIs marked with `@experimental` or `@release_candidate`—including
 members of a staged class—are excluded. Package state and feature-stage markers are read
 from the base commit, so changing either in the same pull request cannot suppress a
-compatibility finding. The Griffe version is pinned with the other Python development
-dependencies in `python/pyproject.toml`; the workflow reads that pin from the trusted base
-commit. Instance-attribute initializer values are excluded because Griffe derives them from
+compatibility finding. The Griffe version is pinned in
+`python/tooling/requirements-api-compatibility.txt`; the workflow reads that pin from the
+trusted base commit. Instance-attribute initializer values are excluded because Griffe derives them from
 constructor control flow and can report implementation-only assignment changes; other
 Griffe-detected attribute value changes remain checked.
 

python/.github/skills/agent-framework-py-release/SKILL.md

@@ -45,7 +45,8 @@ If the user states target versions or a date explicitly, use exactly what they s
 - **Follow `python-package-management` for package lifecycle and versioning rules** — do not duplicate those
   rules in this release workflow.
 - **No `Co-Authored-By` trailer** on any commit.
-- **Use `uv run`** for all Python/poe commands (`uv run poe ...`, `uv run pytest ...`).
+- **Use `uv run`** for cross-version Python/Poe commands and add the relevant
+  `tooling/requirements-*.txt` bundle only for single-version tools.
 - **Never rename an existing CHANGELOG section header** during a new release cut. Only INSERT a new section above existing ones.
 - **Footer reference links are part of the CHANGELOG edit**, not optional.
 

python/.github/skills/python-code-quality/SKILL.md

@@ -55,6 +55,11 @@ uv run poe pyright -S
 uv run poe markdown-code-lint
 ```
 
+Poe and the pytest toolchain stay in the cross-version development
+environment. Ruff and the type checkers use pinned
+`tooling/requirements-*.txt` files; prek is selected from the `tool-hooks`
+dependency group only when needed.
+
 ## Pre-commit Hooks (prek)
 
 Prek hooks run automatically on commit. They stay lightweight and only check
@@ -65,10 +70,10 @@ changed files.
 uv run poe prek-install
 
 # Run all hooks manually
-uv run prek run -a
+uv run --group tool-hooks prek run -a
 
 # Run on last commit
-uv run prek run --last-commit
+uv run --group tool-hooks prek run --last-commit
 ```
 
 They run changed-package syntax formatting/checking, markdown code lint only

python/.github/skills/python-package-management/SKILL.md

@@ -51,7 +51,7 @@ uv run poe venv --python 3.12
 # Intentionally upgrade a specific dependency to reduce lockfile conflicts
 uv lock --upgrade-package <dependency-name> && uv run poe install
 
-# Refresh exact development dependency-group pins, lockfile, and validation in one run
+# Refresh exact development and on-demand tool pins, lockfiles, and validation
 uv run poe upgrade-dev-dependencies
 
 # Release cuts: refresh uv.lock and probe changed packages at both bound extremes.
@@ -96,11 +96,21 @@ uv run poe test
   project task can drive repo-wide upper-bound automation by using `--package "*"` and omitting `--dependency`.
 - Prefer targeted lock updates with `uv lock --upgrade-package <dependency-name>` to reduce `uv.lock` merge conflicts.
 - Use `add-dependency-and-validate-bounds` for package-scoped dependency additions plus bound validation in one command.
-- Keep shared tooling and source/type-check support in the root or package `dev` group. Put package-specific test
-  fixtures in a `test` group, and use a feature-named group for local-only executable dependencies that cannot be
-  expressed in published runtime metadata.
-- Use `upgrade-dev-dependencies` for repo-wide development dependency refreshes; it repins exact dependencies
-  across development groups, refreshes `uv.lock`, and reruns `check`, `typing`, and `test`.
+- Keep the test framework and Poe in the root `dev` group across Python
+  versions. Put script-only libraries in `tool-runtime`. Put tools used by
+  only one Python version in a named `tool-*` group or pinned
+  `tooling/requirements-*.txt` file, and add the smallest relevant group or
+  bundle to each command. Keep source/type-check support that is part of a
+  package's import surface in a package dependency group. Put package-specific
+  test fixtures in a `test` group.
+- Use `upgrade-dev-dependencies` for repo-wide development and tool dependency
+  refreshes; it repins exact dependencies across development groups and
+  `tooling/requirements-*.txt`, refreshes `uv.lock`, and reruns `check` and
+  `typing`.
+- Upgrade the root uv version manually as one coordinated change across the
+  `dev` requirement, `[tool.uv].required-version`, setup workflows, and the
+  uv pre-commit revision. Automated dependency updates intentionally ignore
+  the root uv pin.
 - Run Lab dependency and validation commands from `packages/lab`; root workspace tasks deliberately do not
   discover or update the Lab project.
 

python/.pre-commit-config.yaml

@@ -51,7 +51,7 @@ repos:
     hooks:
       - id: poe-check
         name: Run checks through Poe
-        entry: uv run python scripts/workspace_poe_tasks.py prek-check
+        entry: uv run --locked --group tool-runtime --group tool-markdown python -m scripts.workspace_poe_tasks prek-check
         language: system
   - repo: https://github.com/PyCQA/bandit
     rev: 1.9.4
@@ -62,7 +62,7 @@ repos:
         additional_dependencies: ["bandit[toml]"]
   - repo: https://github.com/astral-sh/uv-pre-commit
     # uv version.
-    rev: 0.11.6
+    rev: 0.12.23
     hooks:
       # Update the uv lockfile
       - id: uv-lock