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

from dataclasses import dataclass
from typing import Protocol
from uuid import UUID

from ..models import Transcript


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

    def to_transcript(self, job_id: UUID, *, revision: int = 0) -> Transcript:
        """Convert a TranscriptionResult to a Transcript model instance."""
        return Transcript(
            job_id=job_id,
            revision=revision,
            provider=self.provider,
            prompt_name=self.prompt_name,
            model=self.model,
            text=self.text,
        )


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."""
        ...
