"""LLM provider interface — the contract that all LLM plugins must implement.

Migrated from abc.ABC to typing.Protocol in Phase Mercury. The LLMProvider
Protocol is the canonical contract. BaseLLMProvider is kept as a convenience
base class with a default __init__ for plugins that want it.

Existing plugins (openai_llm, anthropic_llm) satisfy the LLMProvider Protocol
without changes because they already implement generate() and generate_with_tools().
"""

from __future__ import annotations

from vastian.bridges.protocols import LLMProvider  # re-export the Protocol
from vastian.config import Settings


class BaseLLMProvider:
    """Convenience base class for LLM providers.

    Provides a default __init__ that reads model config from Settings.
    Plugins may extend this for convenience, but it is NOT required --
    any class implementing generate() and generate_with_tools() satisfies
    the LLMProvider Protocol.
    """

    def __init__(self, settings: Settings) -> None:
        self.settings = settings
        self.default_model = settings.default_model
        self.fast_model = settings.fast_model

    async def generate(
        self,
        system_prompt: str,
        messages: list[dict[str, str]],
        model: str | None = None,
        temperature: float = 0.7,
        max_tokens: int = 4096,
    ) -> str:
        """Generate a response from the LLM."""
        raise NotImplementedError

    async def generate_with_tools(
        self,
        system_prompt: str,
        messages: list[dict[str, str]],
        tools: list[dict],
        model: str | None = None,
        temperature: float = 0.7,
    ) -> dict:
        """Generate a response that may include tool calls."""
        raise NotImplementedError


__all__ = ["LLMProvider", "BaseLLMProvider"]
