"""LLM provider interface. Implementations must be side-effect free apart from the HTTP call."""

from __future__ import annotations

from typing import Protocol

from us2kr.models import MarketPayload, Report, Verification, VerificationIssue


class LLMError(RuntimeError):
    """Raised when every configured model failed to produce a valid Report."""


class LLMProvider(Protocol):
    def summarize(self, payload: MarketPayload) -> tuple[Report, str]:
        """Return (validated Report, model id that produced it). Raise LLMError on total failure."""
        ...

    def verify(self, payload: MarketPayload, report: Report) -> tuple[Verification, str]:
        """Fact-check `report` against the payload. Raise LLMError on total failure."""
        ...

    def revise(
        self, payload: MarketPayload, report: Report, issues: list[VerificationIssue]
    ) -> tuple[Report, str]:
        """Return a corrected Report addressing `issues`. Raise LLMError on total failure."""
        ...