Migration Strategy: Typing an Existing Codebase

How to take an untyped or partially typed Python codebase (an LLM service, a RAG repo, a research training package) to strict type checking without a big-bang rewrite, and how to modernise old typing syntax safely.

#Contents

• Principles
• Phase 0: baseline
• Phase 1: checker on, low strictness
• Phase 2: type the core data
• Phase 3: annotate outward from the leaves
• Phase 4: strict per package
• Phase 5: ship types
• Ordering heuristics
• Third-party libraries without types
• Modernising legacy syntax
• Raising the minimum Python version
• Automated annotation tools
• Annotating a function: worked example
• Team conventions
• Anti-patterns

#Principles

1. Ratchet, never big bang. Coverage and strictness only go up; CI blocks regressions, not legacy.
2. Types follow data. Typing the central data structures (messages, chunks, configs, requests) gives more value than annotating 200 helpers with dict[str, Any].
3. Boundaries first, then inward. Validate untyped input once (pydantic, isinstance), then everything behind the boundary can be precise.
4. Every error is either a bug or a missing type. Fix bugs; model the missing type. Suppress only with an error code and a reason.
5. The checker is part of the test suite. It runs on every PR with a pinned version.

#Phase 0: baseline

# coverage snapshot and the list of untyped functions
python annotation_audit.py src --target-version 3.10 --json > typing-baseline.json
python annotation_audit.py src --target-version 3.10 | tail -3

# how many checker errors at each level?
mypy src --ignore-missing-imports | tail -1
mypy src --strict --ignore-missing-imports | tail -1
pyright src --outputjson | python -c "import json,sys; print(json.load(sys.stdin)['summary'])"

Record: overall coverage %, number of errors in default mode, number in strict mode, the most common error codes (mypy ... | grep -o '\[[a-z-]*\]' | sort | uniq -c | sort -rn). This tells you whether you have a "missing annotations" problem or a "real bugs" problem.

#Phase 1: checker on, low strictness

Goal: CI runs a checker and is green, catching new bugs in existing code without demanding annotations.

[tool.mypy]
python_version = "3.10"
files = ["src"]
check_untyped_defs = true          # checks bodies of untyped functions too
warn_unused_ignores = true
warn_redundant_casts = true
no_implicit_optional = true         # default since mypy 0.990
ignore_missing_imports = false

[[tool.mypy.overrides]]
module = ["faiss.*", "some_untyped_sdk.*"]
ignore_missing_imports = true

Fix the errors that appear. In AI codebases, typical real bugs found here: missing await on client calls, None returned from a retrieval helper on empty results and then indexed, wrong argument order in embedding calls, string vs list confusion (stop="\n" vs stop=["\n"]), and dicts with typo'd keys.

If the error count is too large to fix at once: pyright/basedpyright baselines or mypy's per-module ignore_errors = true for the worst modules, each with a ticket to remove it. mypy has no built-in baseline; tools such as mypy-baseline can store and diff a baseline.

#Phase 2: type the core data

Find the dicts that flow everywhere and give them names:

Do this in a types.py / schemas.py module with no heavy imports so every module can import it without cycles.

#Phase 3: annotate outward from the leaves

Order of work inside a package:

1. Pure utilities (text cleaning, chunking, scoring, token counting): easy, high reuse.
2. Adapters around external services (LLM client, vector DB, object storage): define a Protocol for each and annotate the adapter; this is where Any from SDKs is contained.
3. Core domain services (retriever, agent loop, evaluator) that depend on 1 and 2.
4. Entry points (FastAPI routes, CLI commands, jobs).

For each module:

python annotation_audit.py src/app/chunking.py --target-version 3.10   # what is missing + suggestions
# annotate, then:
mypy src/app/chunking.py --strict
python annotation_audit.py src/app/chunking.py --min-coverage 100

Then add the module to the strict list (Phase 4) immediately, so it cannot regress.

#Phase 4: strict per package

strict = true is a global-only option in mypy configs: per-module overrides must list the individual flags. A practical per-module strict set for modules that are done:

[[tool.mypy.overrides]]
module = ["app.schemas", "app.chunking", "app.retrieval.*", "app.clients.*"]
disallow_untyped_defs = true
disallow_incomplete_defs = true
disallow_untyped_calls = true
disallow_untyped_decorators = true
disallow_any_generics = true
warn_return_any = true

Or invert it once most code is typed: global strict = true, plus an override that relaxes the remaining legacy modules. pyright: strict = ["src/app/schemas.py", "src/app/retrieval"].

CI gate that only ratchets up:

python annotation_audit.py src --min-coverage "$(cat .typing-coverage)"
# after improving coverage, bump the number in .typing-coverage in the same PR

#Phase 5: ship types

For libraries (internal SDKs, shared RAG components):

1. pyright --verifytypes yourpkg --ignoreexternal until the public API is complete.
2. Add an empty src/yourpkg/py.typed and make sure the build includes it.
3. Export public names explicitly (__all__ or from .x import Name as Name) so no_implicit_reexport users can import them.
4. Run python -m mypy.stubtest if you also ship .pyi stubs.
5. Note in the changelog that type changes are API changes: narrowing a parameter type or widening a return type breaks downstream type checks.

#Ordering heuristics

Leave for last: one-off scripts, notebooks, tests (annotate fixtures and helpers; test functions can stay -> None only).

#Third-party libraries without types

#Modernising legacy syntax

Do syntax modernisation as its own mechanical PR, separate from annotation work and behaviour changes, so review is trivial.

# report the rewrites for your minimum version
python annotation_audit.py src --target-version 3.10 --ignore missing-param,missing-return

# autofix with ruff (set target-version = "py310" in [tool.ruff])
ruff check src --select UP006,UP007,UP035,UP037,UP045 --fix
# 3.12+: PEP 695 generics and the type statement (some are unsafe fixes)
ruff check src --select UP040,UP046,UP047 --fix --unsafe-fixes

Safety rules for each rewrite:

After the rewrite: run the full test suite (runtime annotation consumers fail at import time, not in the checker), then the checker.

#Raising the minimum Python version

Typing improvements are a good reason to raise the floor. When moving from 3.9:

Update together: requires-python in pyproject.toml, [tool.mypy] python_version, [tool.pyright] pythonVersion, [tool.ruff] target-version, the CI matrix, and then run the modernisation pass.

#Automated annotation tools

#Annotating a function: worked example

Before:

def retrieve(query, store, embedder, k=5, filters=None, min_score=0.0):
    vec = embedder.embed([query])[0]
    hits = store.search(vec, k=k * 2, where=filters)
    good = [h for h in hits if h.score >= min_score]
    if not good:
        return None
    return good[:k]

Audit output (abridged):

L1    retrieve  [missing: query, store, embedder, k, filters, min_score, return]
         k              -> k: int = 5
         filters        -> filters: <T> | None = None
         min_score      -> min_score: float = 0.0
         return            (return value(s) not inferable from literals)

After, reasoning one parameter at a time:

from collections.abc import Mapping

def retrieve(
    query: str,
    store: VectorStore[Chunk],                       # Protocol: any backend works, fakes in tests
    embedder: Embedder,
    k: int = 5,
    filters: Mapping[str, str | int | float | bool] | None = None,   # read-only: Mapping
    min_score: float = 0.0,
) -> list[Hit[Chunk]]:                               # concrete return
    vec = embedder.embed([query])[0]
    hits = store.search(vec, k=k * 2, where=filters)
    return [h for h in hits if h.score >= min_score][:k]

The annotation exposed a design smell: returning None for "no results" forced every caller to handle None; an empty list is the natural empty value, so the return type became list[Hit[Chunk]] and the None branch disappeared.

#Team conventions

Write these down in CONTRIBUTING or the repo's AGENTS/CLAUDE file:

• Minimum Python version and therefore the allowed syntax (X | None, list[...], type statement or not).
• from __future__ import annotations: everywhere, nowhere, or only in non-pydantic modules. Pick one.
• Where shared types live (app/types.py), naming (ChatMessage, ToolSpec, *Config).
• When to use TypedDict vs dataclass vs pydantic (see ai-ml-typing.md).
• Any policy: allowed only in adapters around untyped libraries, with a comment.
• Suppression policy: # type: ignore[code] # reason, no bare ignores, warn_unused_ignores on.
• New code must be fully annotated; touched functions get annotated in the same PR.

#Anti-patterns