"""STT provider contracts — swap implementations without changing the flow."""

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any


class VoiceProviderError(Exception):
    """Raised when a voice provider fails or receives invalid input."""

    def __init__(self, message: str, *, code: str = "voice_error") -> None:
        self.code = code
        super().__init__(message)


@dataclass
class STTResult:
    text: str
    provider: str
    stub: bool = False
    language: str | None = None
    confidence: float | None = None
    segments: list[dict[str, Any]] = field(default_factory=list)
    message: str = "OK"


class STTProvider(ABC):
    name: str = "stt"

    @abstractmethod
    async def transcribe(
        self,
        *,
        audio_bytes: bytes,
        language: str = "en",
        mime_type: str = "audio/wav",
        options: dict[str, Any] | None = None,
    ) -> STTResult:
        ...
