"""ASRProvider port — 语音转文字能力契约。"""

from typing import Protocol, runtime_checkable


class ASRTranscriptionError(Exception):
    """ASR 失败时抛出；`str(e)` 适合写入日志，面向客户端的文案由 pipeline 统一处理。"""


@runtime_checkable
class ASRProvider(Protocol):
    async def transcribe(self, audio: bytes, format: str = "m4a") -> str:
        """Transcribe audio bytes to text."""
        ...