Add Python type hints throughout and enable mypy-based static analysis in CI

[soumendrak]

Current state: The openodia codebase (~25 Python source files) has almost no type hints. Parameters and return values are documented via docstrings but not annotated. For example:

# _understandData.py — currently:
def remove_stopwords(self, text, get_str=False):
    """..."""
    tokens = self.word_tokenizer(text)
    ...

# What it could be:
def remove_stopwords(
    self,
    text: str,
    get_str: bool = False,
    stopwords: Container[str] | None = None,
) -> list[str] | str:
    """..."""

Why this matters:

1. IDE autocompletion — users of the library get no inline type hints in VSCode/PyCharm
2. Catch bugs early — a surprising number of edge cases (e.g., None vs empty string, wrong return type) would be caught by mypy
3. API clarity — type annotations serve as executable documentation; they make the public API contract explicit
4. Onboarding — new contributors can understand function signatures without reading the full implementation

Suggested approach:

1. Phase 1 — Core types (quick wins):

   • Add from __future__ import annotations to every source file (enables PEP 604 union syntax on 3.10+)
   • Annotate all public functions in __init__.py, _letters.py, _translate.py, _summarization.py, _understandData.py
   • Add typed Dict/List return types for all public APIs

2. Phase 2 — Internal modules:

   • numbers/ — all 6 submodules
   • stats/ — FreqDist, collocations, cooccurrence, ngrams
   • segment/ — sentences, abbreviations
   • stopwords/ — Stopwords class
   • text/ — normalize, clean, CleanOptions
   • cache/ — configure, stats, clear
   • corpus/ — dictionary

3. Phase 3 — CI integration:

   • Add mypy to the dev dependencies in pyproject.toml
   • Create a mypy.ini or pyproject.toml config:

     [tool.mypy]
     python_version = "3.10"
     strict = false  # start relaxed, tighten per-module
     warn_return_any = true
     warn_unused_configs = true

   • Add a mypy step to the existing Quality job in .github/workflows/release.yml
   • Consider using --strict gradually via per-file # mypy: ... comments

4. Phase 4 — Strict mode for public API:

   • Enable --strict for the public-facing modules (__init__.py and files directly imported by it)
   • Add a scripts/check_types.sh that runs mypy with increasing strictness over time

Estimated effort: 2–4 hours for a contributor familiar with Python typing.

Resources:

• Python typing docs: https://docs.python.org/3/library/typing.html
• mypy cheatsheet: https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html