"""LLM provider protocol and response types."""

from __future__ import annotations

from dataclasses import dataclass, field


@dataclass(frozen=True)
class LLMResponse:
    """Response from an LLM provider."""

    text: str
    model: str
    provider: str
    input_tokens: int = 0
    output_tokens: int = 0
    latency_ms: float = 0.0
    metadata: dict = field(default_factory=dict)


class LLMProvider:
    """Base protocol for LLM providers.

    All providers implement generate() and health_check().
    Subclasses override these methods to connect to specific backends.
    """

    name: str = "base"
    models: list[str] = []

    def generate(
        self,
        prompt: str,
        model: str | None = None,
        max_tokens: int = 1024,
        temperature: float = 0.7,
    ) -> LLMResponse:
        """Generate text from a prompt.

        Args:
            prompt: The input prompt.
            model: Model to use (defaults to provider's first model).
            max_tokens: Maximum tokens to generate.
            temperature: Sampling temperature.

        Returns:
            LLMResponse with generated text and metadata.
        """
        msg = f"{self.name} provider: generate() not implemented"
        raise NotImplementedError(msg)

    def health_check(self) -> dict:
        """Check if the provider is available.

        Returns:
            Dict with 'healthy' (bool), 'provider' (str), 'models' (list),
            and optional 'error' (str) if unhealthy.
        """
        return {
            "healthy": False,
            "provider": self.name,
            "models": self.models,
            "error": "not implemented",
        }

    def available_models(self) -> list[str]:
        """Return list of available models."""
        return list(self.models)
