transcription_provider.py 2.8 KB

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