"""
Abstract base class for Speech-to-Text providers.

Every provider must implement `transcribe(audio_url, callid)` and return an
`STTResult`.  New providers (Deepgram, Whisper, …) just subclass BaseSTT and
register in the factory.
"""
from __future__ import annotations

import logging
from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any, Dict, List

logger = logging.getLogger(__name__)


@dataclass
class STTResult:
    """Normalised transcription output shared across all STT providers."""

    transcript: str
    speaker_segments: List[Dict[str, Any]] = field(default_factory=list)
    duration: float = 0.0
    provider: str = ""

    def to_dict(self) -> Dict[str, Any]:
        return {
            "transcript": self.transcript,
            "speaker_segments": self.speaker_segments,
            "duration": self.duration,
            "provider": self.provider,
        }


class BaseSTT(ABC):
    """Abstract speech-to-text provider."""

    @property
    @abstractmethod
    def provider_name(self) -> str:
        """Short identifier used in `stt_provider` DB column."""

    @abstractmethod
    def transcribe(self, audio_url: str, callid: str) -> STTResult:
        """Download audio from *audio_url* and return an STTResult.

        Raises `RuntimeError` on unrecoverable failure so the caller can mark
        the call as failed without swallowing the reason.
        """