python-type-hints-annotator

Annotate Python so a type checker can prove things about it: precise parameter and return types, modern syntax for the project's minimum Python version, abstract inputs and concrete outputs, no silent Any, and zero new checker errors. Then fix whatever mypy or pyright reports with the smallest correct change, never with a blanket # type: ignore. scripts/annotation_audit.py measures coverage, finds unannotated functions, infers easy types and rewrites legacy typing syntax; you supply the types that need understanding of the code: protocols, generics, TypedDicts for LLM payloads, overloads and array shapes.

#Trigger Conditions

Activate this skill when the user:

• Says "add type hints", "annotate this", "type this module", "make mypy/pyright happy", "get to strict"
• Pastes a mypy or pyright error (Incompatible types in assignment, Item "None" of "X | None" has no attribute, reportOptionalMemberAccess, Missing type parameters for generic type, Function is missing a return type annotation)
• Wants to modernise typing: List/Dict/Optional/Union to list/dict/X | None, TypeVar to PEP 695, TypeAlias to type
• Types LLM / RAG / agent code: chat message dicts, tool schemas, streaming responses, async clients, retry decorators, callbacks, embeddings, vector stores, model configs
• Types numeric code: numpy arrays and dtypes, torch tensors, shape annotations with jaxtyping
• Sets up mypy/pyright config, a CI gate, py.typed, stubs, or plans incremental adoption on a large untyped codebase

#Workflow

1. SCOPE     -> minimum Python version? checker (mypy / pyright / both)? library (public API) or app?
2. AUDIT     -> python scripts/annotation_audit.py <file|dir> --target-version 3.X
3. MODERNISE -> apply legacy-* rewrites and fix the import lines it prints
4. ANNOTATE  -> public API first: params abstract (Iterable, Mapping), returns concrete (list, dict)
5. MODEL     -> TypedDict / dataclass / pydantic for structured data, Protocol for collaborators,
                generics where a type flows from input to output, overload where it depends on a value
6. CHECK     -> run mypy / pyright; fix errors by narrowing, not by casting or ignoring
7. GATE      -> --min-coverage N in CI; tighten checker strictness module by module

#Core Rules

1. Annotate every public function fully (all params and the return), including -> None. An unannotated def is skipped by mypy's default mode: its body is not checked at all.
2. Use the syntax the minimum supported Python allows (see table below). Libraries supporting 3.9 can still write X | None inside annotations with from __future__ import annotations, but never in runtime expressions (aliases, cast, isinstance, pydantic fields, FastAPI params).
3. Accept abstract, return concrete. Parameters take Iterable[str], Sequence[float], Mapping[str, object]; returns give list[str], dict[str, float]. Callers get maximum freedom in, maximum information out.
4. No implicit Optional. def f(stop: list[str] = None) is an error in mypy and pyright. Write stop: list[str] | None = None and never use a mutable default.
5. Any is an escape hatch, not a type. Prefer object (accept anything, use nothing), a TypeVar (pass through), a TypedDict/Protocol (known shape), or a recursive JSON alias. Each remaining Any gets a comment saying why.
6. Narrow instead of cast. if x is None: raise, isinstance, match, TypeIs functions and assert_never keep the checker honest; cast() and # type: ignore[code] are last resorts and always carry the error code.
7. Model data, don't annotate dict[str, Any]. LLM messages, tool calls, configs and API payloads get a TypedDict (static shape for dicts you pass to SDKs), a dataclass (internal objects) or a pydantic model (validation at a trust boundary).
8. Generics when types flow through. If the output type depends on the input type (first(items), Cache[T], retry(fn)), use a type parameter; ParamSpec for decorators so wrapped signatures survive.
9. Don't over-annotate locals. Annotate variables only where inference fails: empty containers (hits: list[Doc] = []), None initialisers, and class attributes.
10. Typing must not change runtime behaviour. Imports used only in annotations go under if TYPE_CHECKING:; never import torch just to annotate a helper module that otherwise doesn't need it.

#Syntax by Python Version

Anything newer than the target comes from typing_extensions (a tiny, ubiquitous dependency). Full per-version detail: typing-cheatsheet.md.

#Before and After

# Before: untyped, mutable default, Optional implicit, any-shaped dicts
def call_llm(messages, tools=None, temperature=0.2, stop=[]):
    ...

# After (3.10+)
from collections.abc import Sequence
from typing import Literal, NotRequired, TypedDict

class ChatMessage(TypedDict):
    role: Literal["system", "user", "assistant", "tool"]
    content: str
    tool_call_id: NotRequired[str]

class ToolSpec(TypedDict):
    name: str
    description: str
    parameters: dict[str, object]           # JSON Schema

def call_llm(
    messages: Sequence[ChatMessage],
    tools: Sequence[ToolSpec] | None = None,
    temperature: float = 0.2,
    stop: Sequence[str] | None = None,
) -> str:
    ...

#Choosing the Right Type

#Fixing Checker Errors (most common)

A longer catalogue with pyright rule names and fixes is in type-checker-setup.md.

#Narrowing Patterns

from typing import Literal, assert_never        # assert_never: 3.11+, else typing_extensions

def require(value: str | None, name: str) -> str:
    if value is None:
        raise ValueError(f"{name} is required")
    return value                                 # narrowed to str

def cost_per_token(provider: Literal["openai", "anthropic", "local"]) -> float:
    match provider:
        case "openai":
            return 2.5e-6
        case "anthropic":
            return 3e-6
        case "local":
            return 0.0
        case _:
            assert_never(provider)               # checker errors if a new provider is unhandled

User-defined narrowing: TypeGuard[T] (3.10) narrows only the positive branch to exactly T; TypeIs[T] (3.13) narrows both branches and intersects with the input type. Prefer TypeIs for "is this X?" predicates. See advanced-typing.md.

#Protocols over Base Classes

from collections.abc import Sequence
from typing import Protocol

class Embedder(Protocol):
    def embed(self, texts: Sequence[str]) -> list[list[float]]: ...

class VectorStore[T](                            # 3.12 syntax; Protocol[T] before
    Protocol
):
    def upsert(self, ids: Sequence[str], vectors: Sequence[list[float]], payloads: Sequence[T]) -> None: ...
    def query(self, vector: list[float], k: int = 5) -> list[tuple[T, float]]: ...

def index(docs: Sequence[str], embedder: Embedder, store: VectorStore[str]) -> None:
    store.upsert([str(i) for i in range(len(docs))], embedder.embed(docs), docs)

Any class with matching methods satisfies the protocol: no inheritance, so OpenAI, local and fake test embedders all fit. Add @runtime_checkable only if you need isinstance (it checks method names, not signatures).

#Decorators that Keep Signatures

import asyncio
import functools
from collections.abc import Awaitable, Callable

def retry[**P, R](attempts: int = 3) -> Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[R]]]:
    def deco(fn: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
        @functools.wraps(fn)
        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
            for i in range(attempts - 1):
                try:
                    return await fn(*args, **kwargs)
                except TimeoutError:
                    await asyncio.sleep(2 ** i)
            return await fn(*args, **kwargs)
        return wrapper
    return deco

Before 3.12: P = ParamSpec("P"), R = TypeVar("R") at module level, same body.

#AI-Engineering Typing Quick Reference

Full worked examples (OpenAI/Anthropic-style messages, tool schemas, pydantic vs TypedDict trade-offs, generic repositories, typed settings, training loops): ai-ml-typing.md.

#Imports, Cycles and Heavy Dependencies

from __future__ import annotations              # annotations become strings: no runtime cost, no cycles

from typing import TYPE_CHECKING

if TYPE_CHECKING:                                # never executed; checkers still see it
    import torch
    from .store import VectorStore

def to_device(batch: torch.Tensor, store: VectorStore[str]) -> torch.Tensor: ...

Caveat: libraries that evaluate annotations at runtime (pydantic, FastAPI, typer, dataclasses with get_type_hints, SQLAlchemy Mapped[...]) need the names importable at runtime; keep their imports real, and on 3.9 keep Optional[X] in those classes even with the future import.

#Gradual Adoption

1. Run the audit to get a baseline: annotation_audit.py src/ --json > typing-baseline.json.
2. Turn on the checker in non-strict mode with check_untyped_defs = true; fix real bugs first.
3. Make new and touched modules strict via per-module overrides; annotate leaf utilities, then core domain types (messages, configs), then services.
4. Gate CI on coverage that only goes up (--min-coverage), and on mypy --strict for opted-in packages.
5. Ship py.typed once the public API is annotated.

Step-by-step plan, config snippets and how to handle untyped third-party libraries: migration-strategy.md.

#Output Format

When annotating or fixing types, return:

1. Summary: target Python version, checker, coverage before → after (from the audit script).
2. Annotated code: the full rewritten functions or module, with any new TypedDict / Protocol / alias definitions placed above their first use and imports fixed.
3. Decisions: one line each for non-obvious choices (why Sequence not list, why an overload, where Any remains and why).
4. Checker errors fixed: the original message, the cause, the fix.
5. Follow-ups: config changes (strictness flags, overrides), stubs to install, py.typed.

Never leave a bare # type: ignore; if one is unavoidable, use # type: ignore[code] # reason.

#Scripts

Audit coverage, missing annotations and legacy syntax (stdlib only, never imports the analysed code):

python scripts/annotation_audit.py src/llm_client.py                       # report for one file
python scripts/annotation_audit.py src/ --target-version 3.12              # 3.12 rewrites: type, PEP 695
python scripts/annotation_audit.py src/ --min-coverage 85                  # CI gate: exit 1 if overall < 85%
python scripts/annotation_audit.py app.py --strict --json                  # exit 1 on any finding, JSON output
python scripts/annotation_audit.py app.py --ignore any-usage,missing-return
cat module.py | python scripts/annotation_audit.py -

It reports per-function missing parameter and return annotations with suggested types (from literal defaults; from return of literals, f-strings, comparisons, annotated parameters, self → Self, cls() → Self; generators → Iterator[...]; always-raising → NoReturn), coverage for params, returns and overall (self/cls excluded), and rule-tagged issues with the exact rewrite: legacy-generic, legacy-optional, legacy-union, legacy-abc, legacy-import (the replacement import lines), legacy-backport (typing_extensions names already in typing), legacy-alias and legacy-typevar (3.12+), any-usage, mutable-default, implicit-optional, default-mismatch. It knows that from __future__ import annotations (or target 3.14) makes X | None safe in annotations but not in runtime expressions or pydantic fields, and quotes forward references when needed. Exit codes: 0 ok, 1 with --strict findings or a failed --min-coverage gate, 2 for usage or syntax errors. Inferred types are suggestions: confirm them against the code, then run the real checker.

#Additional Resources