"""Provider interfaces and shared types for transcription adapters."""

from dataclasses import dataclass
from typing import Protocol


class ProviderError(RuntimeError):
    """Base error for provider failures."""


class ProviderAuthError(ProviderError):
    """Raised when provider authentication fails."""


class ProviderResponseError(ProviderError):
    """Raised when provider responses are malformed or unusable."""


@dataclass(frozen=True)
class TranscriptionResult:
    """Normalized output returned by any transcription provider."""

    text: str
    provider: str
    prompt_name: str
    model: str
    finish_reason: str | None = None
    usage_input_tokens: int | None = None
    usage_output_tokens: int | None = None
    usage_total_tokens: int | None = None


class TranscriptionProvider(Protocol):
    """Contract every transcription provider adapter must satisfy."""

    async def transcribe(self, *, prompt_text: str, image_bytes: bytes, mime_type: str) -> TranscriptionResult:
        """Transcribe the provided image according to the prompt text."""
        ...
