"""
adapters/base/llm.py
Abstract base class for all LLM adapters.
"""
from abc import ABC, abstractmethod


class LLMAdapter(ABC):
    """
    Contract that every LLM provider adapter must fulfil.

    Capability strings
    ------------------
    "reasoning-heavy"  — tasks requiring deep chain-of-thought (e.g. T1, T2)
    "capable"          — general-purpose capable model (e.g. T3, T4)
    "fast-cheap"       — high-volume, low-latency tasks (e.g. T5 quick checks)
    """

    @abstractmethod
    def complete(self, prompt: str, capability: str, context: dict) -> str:
        """
        Send a prompt to the model and return the text response.

        Parameters
        ----------
        prompt      : The full prompt string (system + user combined or just user).
        capability  : One of "reasoning-heavy" | "capable" | "fast-cheap".
        context     : Arbitrary key/value bag passed to the adapter (e.g. system
                      prompt override, temperature, max_tokens).

        Returns
        -------
        The model's text completion as a plain string.
        """
        ...

    @abstractmethod
    def resolve_model(self, capability: str) -> str:
        """
        Map a capability string to the concrete model identifier for this provider.

        Parameters
        ----------
        capability : One of "reasoning-heavy" | "capable" | "fast-cheap".

        Returns
        -------
        Model identifier string (e.g. "claude-opus-4-6", "gpt-4o").
        """
        ...