Improve type annotations and checking

[DevilsAutumn]

Improve Type Annotations and Static Type Checking

Problem

The codebase currently has several areas where type hints could be improved to enhance code quality, IDE support, and catch potential bugs at development time. The current type hints are basic and could be more specific.

Areas Needing Improvement

1. Return Types

   • Many functions return Dict[str, Any] or List[Any] which could be more specific
   • Return types like Callable should use typing.Callable with proper parameter and return type annotations

2. Missing Type Parameters

   • Generic types like List, Dict, Optional, etc. should use square bracket notation (e.g., List[str] instead of just list)

3. Model Adapters

   • The ModelAdapter base class and its implementations could benefit from more specific type hints
   • Return types for methods like generate() could be more precise

4. Configuration

   • Configuration dictionaries could be replaced with proper TypedDict or dataclasses
   • Environment variable parsing could be more type-safe

5. Async Functions

   • Async functions should use typing.Awaitable where appropriate
   • Return types should properly reflect async nature (e.g., -> Awaitable[Dict[str, Any]])

Proposed Changes

1. Add a py.typed file to mark the package as type-checked
2. Add mypy or pyright configuration
3. Add type stubs for third-party libraries if needed
4. Convert configuration dictionaries to dataclasses or TypedDict
5. Add proper return type annotations to all public APIs
6. Add type checking to CI/CD pipeline

Example Improvements

# Before
def get_model_adapter(model_name: str, config=None):
    # ...

# After
from typing import Dict, Optional, Type, TypeVar, Union
from typing_extensions import Protocol

T = TypeVar('T', bound=ModelAdapter)

class ModelConfig(Protocol):
    api_key: Optional[str]
    timeout: int
    # Other common config options

def get_model_adapter(
    model_name: str, 
    config: Optional[Dict[str, Any]] = None
) -> ModelAdapter:
    # ...

Resources:

• https://google.github.io/styleguide/pyguide.html#3192-typing-imports
• https://mypy.readthedocs.io/en/stable/cheat_sheet_py3.html
• https://typing-extensions.readthedocs.io/en/latest/#
• https://dropbox.tech/application/our-journey-to-type-checking-4-million-lines-of-python
• https://realpython.com/python-type-checking/

[yanurag-dev]

@DevilsAutumn Assign this to me. I'll take it up.