"""Base interface for address suggestion providers."""

from abc import ABC, abstractmethod

from app.schemas.request import AddressSuggestRequest
from app.schemas.response import AddressSuggestion


class AddressSuggestionProvider(ABC):
    name: str

    @abstractmethod
    async def suggest(self, request: AddressSuggestRequest) -> list[AddressSuggestion]:
        """Fetch address suggestions for a validated internal request."""

        raise NotImplementedError


class AddressSuggestionClientError(RuntimeError):
    """Raised when an address suggestion adapter call fails."""


class AddressSuggestionRequestError(AddressSuggestionClientError):
    """Raised when a provider rejects an address suggestion request."""