Add static type annotations to public APIs to improve correctness and tooling support

[plesqui]

The current codebase no use static type annotations. Introducing systematic type hints for public APIs will improve code correctness, readability, and developer tooling, while enabling lightweight static analysis (e.g., mypy, pyright) in the future if we choose to adopt it.

Type annotations are especially valuable for scientific and numerical code, where array shapes, dtypes, and expected units are often implicit and easy to misuse.

Why?

• Earlier error detection: Catch mismatches at development time instead of runtime.
• Clearer contracts: Function signatures explicitly state expected inputs and outputs.
• Better IDE support: Autocomplete, inline type hints, and refactoring tools work better.
• Scales with the codebase: Makes refactors and API evolution safer over time.
• Complements docstrings: Types define what, docstrings explain why.

Scope

• Add type annotations to:
  • Public functions
  • Public classes and class methods
  • Core data structures used in the public API
• Focus on function signatures first (parameters and return types).
• Internal/private helpers can be excluded initially.

Guidelines

• Use standard library types (list, dict, tuple, Optional, Union) and typing / typing_extensions where appropriate.
• Prefer numpy.typing (e.g., NDArray) for NumPy arrays.
• Be pragmatic: use Any where precise typing would be overly complex or unclear.
• Do not block development on full typing coverage.

Example

from typing import Optional
import numpy as np
from numpy.typing import NDArray

def compute_activity(
    image: NDArray[np.floating],
    mask: NDArray[np.bool_],
    voxel_volume: Optional[float] = None,
) -> float:
    ...