feat(doctor): make doctor diagnostic for venv drift

[feRpicoral]

Why

Every time uv sync runs (directly or via uv run's auto-sync), the GPU-coupled installs from constraints/serve.txt and constraints/eval.txt get silently unwound — and the next make rehearse fails several seconds deep into a vLLM import with a confusing transformers/huggingface-hub error.

This burned ~20 minutes during the post-merge validation pass alone. make doctor catches it in one second instead.

What it checks

8 checks against the active venv:

• Python version is 3.12.x
• constraints/serve.txt packages installed at compatible versions (vllm + transformers)
• transformers ↔ huggingface-hub invariant (transformers 4.x needs huggingface-hub <1.0)
• vllm executable on PATH
• constraints/eval.txt packages (lm-eval + transformers pin)
• lm-eval executable on PATH

Each fail prints an actionable fix command, e.g.:

✗ serve: transformers   5.8.1 does not satisfy <5.0,>=4.45
     ↳ fix: uv pip install -c constraints/serve.txt "transformers"

Usage

make doctor               # full check (serve + eval)
make doctor               # exit 0 on green, 1 on any failure
python -m scripts.doctor --no-eval   # serve-only environments (production image)

Implementation

• scripts/doctor.py — pure Python (no shelling out), uses packaging.requirements to parse the constraint files so the diagnostic stays in lockstep with what uv would install.
• tests/test_doctor.py — 17 tests covering each check type, the constraint-file parser, version mismatches, missing executables, the transformers/huggingface-hub invariant, and the CLI exit codes.
• Makefile — make doctor target.
• pyproject.toml — declare packaging as a direct dep (it was already transitive but the import is direct).

Tests

127 total (17 new), 87% coverage, lint+format+mypy clean.

Test plan

• CI green
• make doctor exits 0 on a healthy venv
• make doctor flags missing/mispinned packages with a working fix command