On a small service it's tempting to skip type hints — "it's just a few endpoints." In practice, that's exactly where they pay off fastest.
Pydantic as the boundary
Every request and response in this project's backend is a Pydantic model. That means malformed input is rejected before it reaches business logic, and the response schema is documented automatically in Swagger — no separate API docs to keep in sync.
class ChatRequest(BaseModel):
message: str
conversation_id: str | None = None
Where mypy earns its keep
Full type hints let a type checker catch an entire class of mistakes — passing a
str where an AsyncSession was expected, forgetting to await a coroutine —
before the code ever runs. On a service with SSE streaming and async database
calls, that class of mistake is exactly the kind that's easy to miss in a manual
review.
The overhead of writing the hints is real, but it's paid once. The bugs it prevents are the kind that show up in production, at 2am, in a service nobody has looked at in a month.