src/router/hooks.py

from typing import Protocol, Optional


class RouterHook(Protocol):
    """
    Interface for router observability.
    """

    def on_route_decision(
        self, *, route: str, provider: str, model: str, fallback: bool, reason: Optional[str] = None
    ) -> None:
        """Called whenever a routing decision is made."""
        ...


class NoOpHook:
    """Default no-op implementation of RouterHook."""

    def on_route_decision(self, *, route, provider, model, fallback, reason=None):
        pass