"""Transcription Provider ABC — pluggable speech-to-text backends. Providers register via :meth:`PluginContext.register_transcription_provider`; the one named by ``stt.provider`` services :func:`tools.transcription_tools.transcribe_audio` **when that name is not a built-in** (built-ins always win; ``HERMES_LOCAL_STT_COMMAND`` stays on the built-in ``local_command`` path). :meth:`TranscriptionProvider.transcribe` envelope: ``success`` bool, ``transcript`` str (empty on failure), ``provider`` str, ``error`` str (only when success=False). """ from __future__ import annotations import abc from typing import Any, Dict, Optional from agent.provider_base import CatalogProviderBase class TranscriptionProvider(CatalogProviderBase): """Abstract base class for a speech-to-text backend. Subclasses must implement :attr:`name` (rejected at registration if it collides with a built-in STT name) and :meth:`transcribe`. """ @abc.abstractmethod def transcribe( self, file_path: str, *, model: Optional[str] = None, language: Optional[str] = None, **extra: Any, ) -> dict[str, Any]: """Transcribe ``file_path`` (existence + size already validated) into the module envelope. Must NOT raise — convert exceptions to the error envelope. ``model`` None → :meth:`default_model`; ``language`` is an optional BCP-47 hint; ``extra`` may carry ``prompt`` (from ``stt.prompt`` or a ``pre_transcription`` hook) as a vocabulary hint; unknown keys must be ignored. """ @property def streaming_capable(self) -> bool: """True when :meth:`open_stream_session` can transcribe live 16 kHz mono s16le PCM (``stt.streaming``). Default False: only the file-based :meth:`transcribe` is used.""" return False def open_stream_session( self, *, language: Optional[str] = None, prompt: Optional[str] = None, ) -> TranscriptionStreamSession: """A single-use live session for one utterance (streaming-capable providers only).""" raise NotImplementedError(f"{self.name} does not support live streaming transcription") class TranscriptionStreamSession(abc.ABC): """Live audio -> transcript for one utterance. ``push_audio`` receives 16 kHz mono s16le PCM in any chunk size from one feeder thread; ``finalize`` flushes and returns the standard envelope (``success``/``transcript``/``provider``/``error``) and must not raise.""" @abc.abstractmethod def push_audio(self, chunk: bytes) -> None: """Feed one chunk of 16 kHz mono s16le PCM.""" @abc.abstractmethod def finalize(self) -> dict[str, Any]: """End the session and return the transcription envelope (blocks until final).""" def partial_transcript(self) -> str: """Latest non-final text, polled for live captions. Default: none.""" return ""