Gradually introduce mypy type checking

[subindevs]

Follow-up to #42.

Issue #42 set up ruff (lint + format) with pre-commit and CI, but mypy was dropped from that issue's scope due to the size of the gap between the codebase and a clean mypy run.

Current state

With a starting config of:

[tool.mypy]
python_version = "3.10"
disallow_untyped_defs = true
ignore_missing_imports = true
explicit_package_bases = true
mypy_path = "."

mypy . reports 3002 errors across 225 of 299 source files. Breakdown by error code:

Code	Count	Notes
no-untyped-def	1928	missing type annotations — dominant category
assignment	401	often implicit-Optional defaults (def f(x: str = None))
union-attr	267	.attr access on X | None
attr-defined	238	some may be real bugs worth investigating
var-annotated	48
arg-type	40
return-value	28
index, operator, misc, dict-item, etc.	~36

Note: explicit_package_bases = true + mypy_path = "." is required to resolve scripts/projection_explorer.py (imported as both scripts.projection_explorer and projection_explorer — no __init__.py in scripts/).

Proposed approach: incremental adoption

Fixing ~3000 errors in one pass isn't practical. Instead:

1. Add the [tool.mypy] config above, but without disallow_untyped_defs initially (cuts ~1928 errors).
2. Add [[tool.mypy.overrides]] blocks with ignore_errors = true for the modules/packages that still fail, enumerated explicitly (e.g. gently.harness.bridge, benchmarks.*, etc.) — captured as a checklist below.
3. Wire mypy . into CI (.github/workflows/lint.yml) and the mypy pre-commit hook — it passes immediately because failing modules are excluded.
4. New modules and PRs touching excluded modules are expected to clean up that module's overrides entry and remove it from the ignore list as part of the change.
5. Periodically (or via follow-up issues per subsystem), pick off modules from the ignore list — gently/harness/bridge.py alone accounts for ~25 errors and is a good first target given it's a single large file.

Tasks

• Add lenient [tool.mypy] config (drop disallow_untyped_defs, keep ignore_missing_imports, explicit_package_bases, mypy_path)
• Enumerate currently-failing modules and add [[tool.mypy.overrides]] with ignore_errors = true
• Re-add mypy to .pre-commit-config.yaml and .github/workflows/lint.yml
• Re-add mypy to the dev dependency group in pyproject.toml
• Update CONTRIBUTING.md to document the incremental-typing policy
• (Stretch) Fix gently/harness/bridge.py (~25 errors, mostly implicit-Optional and missing return types) as a first incremental cleanup

Acceptance Criteria

• mypy . passes in CI and pre-commit (via the override list)
• The policy for adding new code / shrinking the ignore list is documented in CONTRIBUTING.md

[pskeshu]

Follow-up: mypy . result depends on whether project deps are installed

While reviewing #48 I hit a discrepancy worth tracking here for the next phase.

mypy . reports different results depending on the environment:

• CI + pre-commit (pip install mypy only, no project deps — relying on ignore_missing_imports = true): ✅ Success: no issues found in 300 source files
• uv run mypy . (project deps installed — i.e. what a contributor gets after uv sync, as CONTRIBUTING.md instructs): ⚠️ 78 errors in 11 files

Why: the override list in pyproject.toml was effectively calibrated against the deps-less run. With the real third-party packages installed (anthropic, numpy, …), mypy resolves their actual types instead of falling back to Any, and surfaces genuine mismatches. None of the 11 affected modules are in the override list, and two of them are Phase-3-"cleared" tool modules:

48  gently/hardware/dispim/claude_client.py   (anthropic SDK content-block unions)
10  gently/app/tools/focus_tools.py           (Phase-3 cleared)
 6  scripts/watch_devices.py
 3  gently/ui/web/server.py
 3  gently/ui/web/plots.py
 2  scripts/watch_position.py
 2  gently/harness/state.py
 1  scripts/recreate_session_videos.py
 1  gently/ui/web/embryo_marker.py
 1  gently/app/tools/calibration_tools.py      (Phase-3 cleared)
 1  gently/analysis/focus.py

Most are pre-existing (anthropic content-block unions, ndarray→scalar assignments) rather than anything #48 introduced — they're simply invisible to the deps-less run.

Options for the next phase:

1. Install the project (deps) in CI before mypy . so the type checker sees real stubs and catches these — then fix or exempt the 11 modules. This makes mypy meaningfully stronger.
2. Keep the deps-less invocation as the contract and document it explicitly (so uv run mypy . divergence is expected), accepting that third-party-typed bugs won't be caught.

Recommend (1) as the eventual target. Flagging so the override-list shrink in the next phase is measured against the deps-installed run, not the deps-less one.

[subindevs]

Closing — original scope complete; continuation tracked in #49

The checklist here is fully implemented and merged via #48 (Phases 1–3):

• ✅ Lenient [tool.mypy] config (dropped disallow_untyped_defs; kept ignore_missing_imports, explicit_package_bases, mypy_path)
• ✅ Failing modules enumerated under [[tool.mypy.overrides]] with ignore_errors = true
• ✅ mypy . wired into CI (.github/workflows/lint.yml) and pre-commit (mirrors-mypy), pinned to 2.1.0 across CI/pre-commit/dev
• ✅ Incremental-typing policy documented in CONTRIBUTING.md
• ✅ Stretch: gently/harness/bridge.py cleaned up and removed from the ignore list

The gradual override-list shrink continues in #49 (Phase 4 — 369 errors / 79 files remaining when overrides are stripped, down from 3002 / 225). The deps-installed-CI follow-up from the comment above has also been carried over to #49 so it isn't lost.

Closing as completed.