ci(python-sdk): enforce mypy with module-by-module allowlist ratchet (#971)

[7vignesh]

Summary

Adopts the mypy half of #620 as phase 1 of #971. The ruff half shipped in #812, but the mypy half was never wired up: sdk/python/mypy.ini existed and nothing ran it. This adds a required mypy step to the Python SDK CI with a module-by-module allowlist, so the gate can be turned on immediately (zero behavior change) and the allowlist shrunk module by module.

Closes #971 (phase 1). Refs #620.

Type of change

• Bug fix
• New feature
• Refactor / cleanup
• Docs only
• Tests only
• CI / tooling
• Breaking change

What changed

• Pin mypy==1.18.2 in the dev extras (pyproject.toml) and regenerate uv.lock.
• Add a per-module ignore_errors = True allowlist to mypy.ini for the 34 modules that currently have type errors (217 errors total), with a header comment describing the ratchet and how to shrink it.
• Add a Type check (mypy) step to .github/workflows/sdk-python.yml running mypy --config-file mypy.ini agentfield/.

No # type: ignore sprinkles were added, and no agentfield/ source was modified.

Validation contract (from #971)

• CI fails if a non-allowlisted module gains a new mypy error. Verified: injecting a type error into a clean module (agent_cli.py) makes mypy exit 1.
• Removing a module from the allowlist while it still has errors fails CI. Verified: removing agentfield.types re-surfaces its errors (exit 1).
• pip install .[dev] provides the pinned mypy version used in CI.

Test plan

• cd sdk/python && mypy --config-file mypy.ini agentfield/ -> Success: no issues found in 79 source files (exit 0)
• cd sdk/python && ruff check . -> All checks passed!
• cd sdk/python && uv lock --check -> clean after regenerating uv.lock
• python -c "import agentfield" -> imports OK
• Ratchet invariants verified (see Validation contract above)

Test coverage

• I ran tests for the surface(s) I changed locally.
• No production code changed; this is CI/tooling only, so coverage is unaffected.
• The coverage gate check is green in CI before requesting review.

Checklist

• I have read CONTRIBUTING.md (if present) and docs/DEVELOPMENT.md.
• Commits are signed and follow conventional-commits style. (conventional-commits: yes; commit signing not configured in my environment)
• I have linked any related issues.

Related issues / PRs

Closes #971 (phase 1). Refs #620, #812.

Notes for reviewers

• The mypy step runs in the existing lint-and-test matrix (Python 3.10-3.13). mypy.ini pins python_version = 3.10, so results are identical across matrix rows; running it in every row is redundant but harmless. Happy to move it to a single dedicated job if you prefer.
• Phase 2 (cleaning the async-heavy modules first, per the issue's suggested order) is intentionally out of scope for this PR to keep it a pure, reviewable wiring change.

[github-actions]

Performance

SDK	Memory	Δ	Latency	Δ	Tests	Status
Python	9.0 KB	-	0.31 µs	-11%	✓	✓

✓ No regressions detected

[github-actions]

📊 Coverage gate

Thresholds from .coverage-gate.toml: per-surface ≥ 84%, aggregate ≥ 85%, max per-surface regression ≤ 1.0 pp, max aggregate regression ≤ 0.50 pp.

Surface	Current	Baseline	Δ
control-plane	87.90%	87.40%	↑ +0.50 pp	🟡
sdk-go	93.20%	92.00%	↑ +1.20 pp	🟢
sdk-python	94.72%	93.73%	↑ +0.99 pp	🟢
sdk-typescript	91.76%	90.42%	↑ +1.34 pp	🟢
web-ui	84.77%	84.79%	↓ -0.02 pp	🟡
aggregate	85.92%	85.75%	↑ +0.17 pp	🟡

✅ Gate passed

No surface regressed past the allowed threshold and the aggregate stayed above the floor.

[github-actions]

📐 Patch coverage gate

Threshold: 80% on lines this PR touches vs origin/main (from .coverage-gate.toml:thresholds.min_patch).

Surface	Touched lines	Patch coverage	Status
control-plane	0	—	➖ no changes
sdk-go	0	—	➖ no changes
sdk-python	0	—	➖ no changes
sdk-typescript	0	—	➖ no changes
web-ui	0	—	➖ no changes

✅ Patch gate passed

Every surface whose lines were touched by this PR has patch coverage at or above the threshold.

[santoshkumarradha]

The ratchet structure makes sense, but the checked-in environment cannot currently run the new gate.

[7vignesh]

Fixed in e57eaf7. You're right - the gate wasn't reproducible.

Reproduced exactly: after uv sync --python 3.13 --extra dev, the locked requests 2.33.1 ships no stubs, so mypy failed with [import-untyped] in multimodal.py and agent_field_handler.py. CI was green only because pip install .[dev] pulled a newer requests that bundles its own stubs.

Went with your first suggestion: pinned types-requests==2.33.0.20260906 in the dev extras and regenerated uv.lock. I chose the stub package over allowlisting those two modules because it keeps them type-clean (allowlisting would suppress all their errors, not just the requests import), and over switching CI to uv sync because the stub pin fixes both paths without restructuring the workflow.

Verified mypy Success: no issues found against both the locked requests 2.33.1 and a newer pip-resolved requests; ruff check clean; uv lock --check clean.

[santoshkumarradha]

Thanks for fixing the reproducible typing environment. I rechecked the updated head with Python 3.13: the locked dev sync, full mypy gate, Ruff, and diff check all pass. The new allowlist entry matches the module added on current main, so this is ready from review.

[AbirAbbas]

Ran the workflow's exact steps on the merge with main in three environments: fresh pip 3.10, fresh pip 3.13, and the locked uv sync --python 3.13 --extra dev env Santosh used. ruff 0.15.22, mypy --config-file mypy.ini agentfield/ (80 files, clean) and run_pytest.sh pass in all of them, uv lock --check is clean, and the types-requests pin installs on 3.10/3.11/3.12/3.13. The gate is real: a type error injected into an unlisted module fails CI, one in a listed dirty module is suppressed, which is the ratchet contract. All 35 listed modules exist on main. Good to merge.