feat: Python 3.14 migration — dependency upgrade and compatibility testing

[kvithayathil]

Summary

Spike confirmed Python 3.14 adoption requires upgrading 6+ native dependencies that lack cp314 wheels at their current pinned versions. This issue tracks the actual migration work.

Spike Findings

Package	Pinned	Target (latest w/ cp314)	Breaking?
watchfiles	1.0.5	1.1.1	PyO3 0.24→0.25, unlikely
numpy	2.2.4	2.4.4	Major minor bump, check changelog
scipy	1.15.2	1.17.1	Minor bump, low risk
rapidfuzz	3.13.0	3.14.5	Patch-level, safe
scikit-learn	1.6.1	1.8.0	Minor bump, check deprecations
pymupdf	1.25.5	1.27.2.2	Minor bump, check API changes

Already have cp314 wheels at current versions: pydantic-core, pillow

Tasks

Phase 1: Prep

• Pin requires-python = ">=3.12,<3.14" in pyproject.toml (prevents accidental 3.14 adoption before ready)
• Update .python-version to 3.13.9 (explicit, not just 3.13)
• Update devcontainer to match

Phase 2: Dependency Upgrades (on a feature branch with 3.14)

• uv lock --upgrade-package numpy --upgrade-package scipy --upgrade-package watchfiles --upgrade-package rapidfuzz --upgrade-package scikit-learn --upgrade-package pymupdf
• Review changelogs for numpy 2.2→2.4, scikit-learn 1.6→1.8, pymupdf 1.25→1.27
• Run full test suite on Python 3.13 after upgrades (regression check)
• Run full test suite on Python 3.14 (compatibility check)

Phase 3: Adopt 3.14

• Update requires-python = ">=3.13,<3.15" in pyproject.toml
• Update .python-version to 3.14
• Update devcontainer Python feature to 3.14
• Run uv sync --python 3.14 — verify all deps install from wheels (no source builds)
• Run full test suite (1335+ tests)
• Run basedpyright type check
• Run ruff check && ruff format --check

Phase 4: CI

• Update CI matrix to test on 3.13 + 3.14
• Verify devcontainer builds and tests pass

Acceptance Criteria

• All 1335+ tests pass on Python 3.14.4
• basedpyright clean
• ruff check clean
• CI passes on both 3.13 and 3.14
• No source builds required (all deps have cp314 wheels)

Risks

• numpy 2.4 may have breaking API changes vs 2.2 (check migration guide)
• scikit-learn 1.8 may deprecate models/features we use
• pymupdf API changes between 1.25→1.27 need review
• Free-threading (PEP 703) is opt-in in 3.14 — not in scope for this issue

References

• Python 3.14 release notes
• numpy 2.4 migration