"""Base adapter interface for LLM endpoints."""

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any


@dataclass
class AdapterResponse:
    """Response from an LLM adapter call."""

    text: str
    tokens_in: int
    tokens_out: int
    latency_ms: float
    model: str = ""
    raw: dict[str, Any] = field(default_factory=dict)


class BaseAdapter(ABC):
    """Abstract base class for LLM endpoint adapters.

    All adapters must implement complete(), list_models(), and test_connection().
    """

    @abstractmethod
    async def complete(
        self, prompt: str, model: str, params: dict[str, Any]
    ) -> AdapterResponse:
        """Send a completion request to the LLM endpoint.

        Args:
            prompt: The user prompt text.
            model: Model identifier (e.g. "gpt-4", "llama3").
            params: Additional parameters (temperature, max_tokens, etc.).

        Returns:
            AdapterResponse with the generated text and usage metadata.
        """

    @abstractmethod
    async def list_models(self) -> list[str]:
        """Return available model identifiers from the endpoint."""

    @abstractmethod
    async def test_connection(self) -> bool:
        """Test whether the endpoint is reachable and authenticated.

        Returns:
            True if connection is healthy, False otherwise.
        """