14. Pydantic Type Safety Strategy

Architecture Decision Record: 14. Pydantic Type Safety Strategy

14. Pydantic Type Safety Strategy

Date: 2025-10-13

Status

Accepted

Category

Core Architecture

Context

Python’s dynamic typing creates runtime errors that could be caught at development time:

• Invalid data passed to functions
• Missing required fields
• Type mismatches
• No IDE autocomplete

Production systems need:

• Runtime validation of untrusted input
• Type-safe API contracts
• Self-documenting code
• IDE support (autocomplete, type checking)

Decision

Use Pydantic BaseModel for all data structures requiring validation.

Implementation

from pydantic import BaseModel, Field, field_validator

class SessionData(BaseModel):
    session_id: str = Field(..., min_length=32)
    user_id: str = Field(...)
    roles: List[str] = Field(default_factory=list)
    created_at: str
    expires_at: str

    @field_validator('session_id')
    @classmethod
    def validate_session_id(cls, v: str) -> str:
        if len(v) < 32:
            raise ValueError('Session ID must be at least 32 characters')
        return v

Consequences

Positive Consequences

• Runtime Validation: Automatic validation of all fields
• Type Safety: mypy catches type errors
• IDE Support: Full autocomplete and type hints
• Self-Documenting: Field descriptions in schema
• JSON Serialization: Built-in model_dump_json()

Negative Consequences

• Performance: Validation overhead (~10-50µs per model)
• Boilerplate: More code than plain dicts
• Learning Curve: Pydantic-specific patterns

Alternatives Considered

1. dataclasses: No validation, just structure
2. TypedDict: No runtime validation
3. Plain dicts: No type safety

Usage Across Codebase

• Session Management: SessionData model (src/mcp_server_langgraph/auth/session.py:30)
• Authentication: UserData, AuthResponse models (src/mcp_server_langgraph/auth/user_provider.py:26)
• Configuration: Settings, FeatureFlags (src/mcp_server_langgraph/core/config.py)
• Compliance: All GDPR, SOC 2, HIPAA models

References

• Dependency: pyproject.toml:44 - pydantic>=2.5.3
• Related ADRs: ADR-0005