H-6664: Introduce Python monorepo infrastructure and formalize python repo-chores

.config/mise/config.toml

@@ -16,7 +16,7 @@ node        = { version = "22.21.1", postinstall = "corepack enable" }
 
 # Helper to install tools
 cargo-binstall = "1.19.1"
-uv             = "0.11.18"
+uv             = "0.11.28"
 
 # Tools to compile the project
 'cargo:wasm-opt'  = "0.116.1"

.config/mise/tasks/fix/python.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+#MISE description="Fix Python: sync lockfile, apply ruff autofixes and formatting"
+set -euo pipefail
+
+mise exec uv -- uv sync
+mise exec uv -- uv run --frozen ruff check --fix .
+mise exec uv -- uv run --frozen ruff format .

.config/mise/tasks/lint/python.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+#MISE description="Lint Python: lock stability, workspace sync, ruff format + lint, ty type checks, tach architecture checks"
+set -uo pipefail
+
+FAILED=0
+
+run() {
+    echo "$ $*"
+    mise exec uv -- "$@" || FAILED=1
+}
+
+# `--locked` doubles as the uv.lock stability check: it fails if the lockfile
+# is out of sync with the workspace manifests.
+run uv sync --locked
+# Boundaries: explicit workspace membership, uniform requires-python, shared
+# tool pins, and generated package.json turbo wiring.
+run uv run --frozen repo-chores sync --check
+# Dependency rules: fully bounded version ranges, registry-only sources.
+run uv run --frozen repo-chores lint
+run uv run --frozen ruff format --check .
+run uv run --frozen ruff check .
+run uv run --frozen ty check
+run uv run --frozen tach check
+run uv run --frozen tach check-external
+
+exit "$FAILED"

.config/mise/tasks/sync/python.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+#MISE description="Synchronize Python workspace membership, version bounds, and generated package.json wiring"
+set -euo pipefail
+
+# Unfrozen on purpose: this is a fix task, so a stale uv.lock is expected
+# input. `uv run` refreshes the lock and environment before running the tool.
+mise exec uv -- uv run repo-chores sync
+# Membership or dependency fixes change the workspace graph; refresh the lock
+# and environment again so the result is immediately usable.
+mise exec uv -- uv lock
+mise exec uv -- uv sync

.dockerignore

@@ -136,6 +136,7 @@ blocks/**/.env
 **/pip-delete-this-directory.txt
 **/.mypy_cache
 **/.pytest_cache
+**/.ruff_cache
 **/.hypothesis
 **/wheels
 

.github/actions/prune-repository/action.yml

@@ -12,12 +12,15 @@ runs:
       shell: bash
       env:
         SCOPE: ${{ inputs.scope }}
-      run: python3 ${{ github.action_path }}/prune.py "$SCOPE"
+      # Executed directly: pruning happens before any dependencies are
+      # installed, so the script relies on the stdlib alone. `repo-chores
+      # prune` wraps the same logic for use inside the workspace environment.
+      run: python3 libs/@local/repo-chores/python/repo_chores/prune.py "$SCOPE"
 
     - name: Copy required files
       shell: bash
       run: |
-        cp -R Cargo.toml Cargo.lock rust-toolchain.toml oxfmt.config.ts infra/ out/
+        cp -R Cargo.toml Cargo.lock rust-toolchain.toml oxfmt.config.ts pyproject.toml uv.lock infra/ out/
 
         # Globs are fun, especially in Bash. Covers all dot-files except `.`, `..`, and `.git`.
         shopt -s extglob

.github/workflows/lint.yml

@@ -97,6 +97,10 @@ jobs:
             | jq '[.tasks[] | select(.task == "lint:clippy" and .command != "<NONEXISTENT>")] != []' || echo 'false')
           echo "clippy=$CLIPPY" | tee -a $GITHUB_OUTPUT
 
+          RUFF=$(turbo run lint:ruff --filter '${{ matrix.name }}' --dry-run=json \
+            | jq '[.tasks[] | select(.task == "lint:ruff" and .command != "<NONEXISTENT>")] != []' || echo 'false')
+          echo "ruff=$RUFF" | tee -a $GITHUB_OUTPUT
+
           HAS_RUST=$([[ -f "${{ matrix.path }}/Cargo.toml" || ${{ matrix.path }} = "apps/hash-graph" ]] && echo 'true' || echo 'false')
           echo "has-rust=$HAS_RUST" | tee -a $GITHUB_OUTPUT
 
@@ -129,6 +133,10 @@ jobs:
         if: always() && steps.lints.outputs.tsc == 'true'
         run: turbo run lint:tsc --filter "${{ matrix.name }}"
 
+      - name: Run ruff
+        if: always() && steps.lints.outputs.ruff == 'true'
+        run: turbo run lint:ruff --filter "${{ matrix.name }}"
+
       - name: Run rustfmt
         if: always() && steps.lints.outputs.has-rust == 'true'
         working-directory: ${{ matrix.path }}
@@ -282,6 +290,20 @@ jobs:
             exit 1
           fi
 
+      - name: Run yarn lint:python
+        if: ${{ success() || failure() }}
+        run: |
+          if ! yarn lint:python; then
+            echo ''
+            echo ''
+            echo 'ℹ️ ℹ️ ℹ️'
+            echo 'Python checks failed (uv.lock stability, ruff, ty, or tach).'
+            echo 'Try running `yarn fix:python` locally to apply autofixes;'
+            echo 'ty and tach findings need to be fixed by hand.'
+            echo 'ℹ️ ℹ️ ℹ️'
+            exit 1
+          fi
+
       - name: Validate Claude Code skills
         if: ${{ success() || failure() }}
         run: |

.gitignore

@@ -123,6 +123,7 @@ blocks/**/.env
 **/pip-delete-this-directory.txt
 **/.mypy_cache
 **/.pytest_cache
+**/.ruff_cache
 **/.hypothesis
 **/wheels
 

.lefthook.yml

@@ -31,6 +31,11 @@ pre-commit:
       glob: "*.rs"
       run: rustfmt {staged_files} || true
       stage_fixed: true
+    python:
+      tags: [backend, style]
+      glob: "*.py"
+      run: uv run --frozen ruff check --fix {staged_files} && uv run --frozen ruff format {staged_files} || true
+      stage_fixed: true
     toml:
       tags: [backend, style]
       glob: "*.toml"

AGENTS.md

@@ -61,9 +61,11 @@ The HASH repository is organized into several key directories:
 - TypeScript type check: `yarn lint:tsc`
 - ESLint: `yarn lint:eslint`
 - Formatting check: `yarn lint:format`
+- Python (ruff, ty, tach, dependency bounds, uv.lock stability, workspace sync): `mise run lint:python`
 
 - Fix ESLint issues: `yarn fix:eslint`
 - Fix formatting: `yarn fix:format`
+- Fix Python (ruff autofixes + formatting, lock refresh): `mise run fix:python`
 
 ### For Specific Packages
 
@@ -77,6 +79,10 @@ turbo run <command> --filter '<package-name>'
 cargo nextest run --package <package-name>
 cargo test --package <package-name> --doc  # For doc tests
 cargo clippy --all-features --package <package-name>
+
+# For Python packages (from the package directory)
+uv run --frozen pytest tests
+uv run --frozen ruff check .
 ```
 
 For Rust packages, you can add features as needed with `--all-features`, specific features like `--features=foo,bar`, or use `cargo-hack` with `--feature-powerset` for comprehensive feature testing.
@@ -91,6 +97,16 @@ mise run sync:turborepo    # sync package.json identity + deps from Cargo.toml m
 
 `sync:turborepo` only manages that generated wiring — the `scripts` section is hand-maintained and is used by CI and Turborepo (e.g. `test:unit`, `lint:clippy`, `doc:dependency-diagram`), so add or edit scripts by hand. The task wraps the `repo-chores` CLI; the equivalent direct invocation is `cargo run --package hash-repo-chores --bin repo-chores-cli -- sync-turborepo`. A related task, `mise run fix:package-json`, sorts `package.json` keys consistently.
 
+### Monorepo wiring for Python packages
+
+Python packages form a single uv workspace rooted at the repository's `pyproject.toml` (shared lockfile, virtual environment, and ruff/ty/tach configuration; Python version bound `>=3.14,<3.15`). After **adding, removing, or renaming a Python package**, or changing its workspace dependencies, re-sync the generated wiring:
+
+```bash
+mise run sync:python    # membership, requires-python, dev pins, package.json wiring, uv.lock
+```
+
+The task wraps the Python `repo-chores` CLI (`libs/@local/repo-chores/python`; direct invocation: `uv run repo-chores sync`). Unlike the Rust wiring, the managed `package.json` includes baseline `scripts` (`lint:ruff`, `fix:ruff`, and `test:unit` when a `tests/` directory exists) — ruff and pytest are requirements, not opt-ins. Extra scripts and other keys are preserved. CI runs `repo-chores sync --check` and fails on any drift, including `pyproject.toml` files that are not workspace members. Import boundaries for new packages are declared in a `tach.domain.toml` next to the package's code; global tach settings live under `[tool.tach]` in the root `pyproject.toml`.
+
 ## Documentation Maintenance
 
 ### Petrinaut user-facing docs

README.md

@@ -209,6 +209,39 @@ This repository's contents is divided across several primary sections:
 
 </details>
 
+<details>
+  <summary> &nbsp; Python tooling</summary>
+
+### Python tooling
+
+Python packages are managed as a single [uv](https://docs.astral.sh/uv/) workspace rooted at [`pyproject.toml`](/pyproject.toml), pinned to Python 3.14 (uv downloads the interpreter automatically; `mise install` provides uv itself). All packages share one lockfile (`uv.lock`), one virtual environment (`.venv`), and the workspace-level tool configuration:
+
+- **[ruff](https://docs.astral.sh/ruff/)** — linting (`ALL` rules + preview, with curated exceptions) and formatting
+- **[ty](https://docs.astral.sh/ty/)** — type checking
+- **[tach](https://docs.gauge.sh/)** — import-boundary and layering checks, configured under `[tool.tach]` in the root `pyproject.toml`
+- **pytest** — tests, run per-package through turbo (`test:unit`)
+
+Common commands:
+
+```sh
+uv sync                    # create/refresh .venv from uv.lock
+mise run lint:python       # everything CI runs: lock stability, sync --check, dependency lint, ruff, ty, tach
+mise run fix:python        # apply ruff autofixes + formatting, refresh the lock
+mise run sync:python       # regenerate the boring parts (see below)
+```
+
+To add a new Python package, create a directory with a `pyproject.toml` (any location; `libs/` or `tools/` are conventional) and run `mise run sync:python`. The sync command — implemented by [`libs/@local/repo-chores/python`](/libs/@local/repo-chores/python), the Python sibling of the Rust `sync-turborepo` tooling — generates and enforces:
+
+- explicit membership in the root `[tool.uv.workspace]` (no globs; CI fails on unlisted packages),
+- a uniform `requires-python` bound across every member (the Python 3.14 boundary),
+- shared ruff/pytest pins in each member's dev group,
+- each member's `package.json` turbo wiring (`@python/<name>` with managed `lint:ruff`/`fix:ruff`/`test:unit` scripts and `workspace:*` dependencies mirroring `[tool.uv.sources]`),
+- coverage by the root `package.json` yarn workspace globs, plus the managed ruff `src` and pytest `testpaths` arrays.
+
+Module boundaries for new packages are declared in a `tach.domain.toml` next to the package's code (layer assignments; see [`libs/@local/repo-chores/python/repo_chores/tach.domain.toml`](/libs/@local/repo-chores/python/repo_chores/tach.domain.toml)). CI prunes per-package jobs with `turbo prune` (via `repo-chores prune`), which keeps the pruned tree a valid uv workspace by copying the manifests of pruned-out members.
+
+</details>
+
 <details>
   <summary> &nbsp; Environment variables</summary>
 

apps/petrinaut-opt/openapi/openapi.json

@@ -14,6 +14,7 @@
         "title": "HTTPValidationError",
         "type": "object"
       },
+      "JsonValue": {},
       "Phase": {
         "enum": [
           "idle",
@@ -143,7 +144,9 @@
           "content": {
             "application/json": {
               "schema": {
-                "additionalProperties": true,
+                "additionalProperties": {
+                  "$ref": "#/components/schemas/JsonValue"
+                },
                 "title": "Optimization Manifest",
                 "type": "object"
               }
@@ -201,7 +204,9 @@
           "content": {
             "application/json": {
               "schema": {
-                "additionalProperties": true,
+                "additionalProperties": {
+                  "$ref": "#/components/schemas/JsonValue"
+                },
                 "title": "Optimization Manifest",
                 "type": "object"
               }

apps/petrinaut-opt/package.json

@@ -1,14 +1,16 @@
 {
-  "name": "@apps/petrinaut-opt",
+  "name": "@python/petrinaut-optimization",
   "version": "0.0.0-private",
   "private": true,
   "description": "Scenario-parameter optimization for Petrinaut using Optuna",
   "license": "(MIT OR Apache-2.0)",
   "scripts": {
     "codegen": "uv run python -m scripts.generate_openapi",
+    "fix:ruff": "uv run --frozen ruff check --fix . && uv run --frozen ruff format .",
     "install:deps": "uv sync",
+    "lint:ruff": "uv run --frozen ruff check . && uv run --frozen ruff format --check .",
     "start": "uv run uvicorn src.optimization_api:app",
     "start:dev": "uv run uvicorn src.optimization_api:app --reload",
-    "test:unit": "uv run pytest && yarn codegen && git diff --exit-code -- openapi/openapi.json"
+    "test:unit": "uv run --frozen pytest tests"
   }
 }

apps/petrinaut-opt/pyproject.toml

@@ -3,22 +3,24 @@ name = "petrinaut-optimization"
 version = "0.1.0"
 description = "Scenario-parameter optimization for Petrinaut using Optuna"
 readme = "README.md"
-requires-python = ">=3.10.20"
+requires-python = ">=3.14,<3.15"
 dependencies = [
     "fastapi>=0.128.8",
     "opentelemetry-exporter-otlp-proto-grpc>=1.44.0",
     "opentelemetry-exporter-otlp-proto-http>=1.44.0",
     "opentelemetry-instrumentation-fastapi>=0.65b0",
     "opentelemetry-sdk>=1.44.0",
     "optuna>=3.6",
+    "pydantic>=2.13.4,<3.0.0",
     "python-dotenv>=1.0.0",
     "uvicorn[standard]>=0.39.0",
 ]
 
 [dependency-groups]
 dev = [
-    "httpx>=0.28",
-    "pytest>=8.3",
+    "httpx2>=2.7.0,<3",
+    "pytest>=9.1.1,<10",
+    "ruff>=0.15.21,<0.16",
 ]
 
 [tool.pytest.ini_options]

apps/petrinaut-opt/scripts/generate_openapi.py

@@ -1,13 +1,10 @@
 """Write the FastAPI OpenAPI schema used by TypeScript code generation."""
 
-from __future__ import annotations
-
 import json
 from pathlib import Path
 
 from src.optimization_api import app
 
-
 output_path = Path(__file__).resolve().parents[1] / "openapi" / "openapi.json"
 output_path.parent.mkdir(parents=True, exist_ok=True)
 output_path.write_text(