"""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 summarize_weekly(self, payload: MarketPayload, week_sessions: list) -> tuple[Report, str]:
        """Weekly recap over a payload whose quotes carry week-over-week changes."""
        ...

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

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