"""Base contracts and common errors for AI text providers."""

from __future__ import annotations

from abc import ABC, abstractmethod
from typing import Any


class AIProviderError(RuntimeError):
    """Base error for provider operations."""


class AIProviderConfigError(AIProviderError):
    """Raised when provider configuration is missing or invalid."""


class AIProviderUnavailableError(AIProviderError):
    """Raised when a provider is temporarily unavailable."""


class AIProviderResponseError(AIProviderError):
    """Raised when provider response payload is invalid."""


class AIProvider(ABC):
    """Unified AI provider contract."""

    @abstractmethod
    def generate(self, prompt: str, context: dict[str, Any] | None = None) -> str:
        """Generate plain-text response from prompt and optional context."""

    @abstractmethod
    def health_check(self) -> bool:
        """Return provider availability state."""

    @abstractmethod
    def provider_name(self) -> str:
        """Return stable provider id."""
