Add type hints to public API functions

Feature Request

Summary

Adding type hints to public API functions would significantly improve developer experience and enable better tooling support.

Motivation

• IDEs can provide better autocomplete and inline documentation
• Static type checkers like mypy can catch bugs before runtime
• New contributors can understand the expected inputs/outputs faster
• Type hints serve as machine-checked documentation

Proposed Change

Add type annotations to all public functions:

# Before:
def process(data, config=None):
    ...

# After:
from typing import Optional, Dict, Any

def process(data: Dict[str, Any], config: Optional[Dict] = None) -> bool:
    ...

Additional Context

This is a non-breaking change and can be done incrementally, starting with the most-used public functions.

Start by inventorying the public Python functions and checking whether the repository already has typing or mypy conventions. Define a bounded first group of the most-used public APIs, then add annotations for their inputs and outputs. Use mypy to verify the result; the issue does not name specific files or tests.