transcription_common.py 6.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132
  1. """Constants, result envelopes and tiny config readers shared by every STT module."""
  2. from __future__ import annotations
  3. import logging
  4. import os
  5. import subprocess
  6. from typing import Any, Dict
  7. from tools.tts_command_provider import _get_provider_section as _get_stt_section
  8. # Log-record parity with the origin module.
  9. logger = logging.getLogger("tools.transcription_tools")
  10. DEFAULT_PROVIDER = "local"
  11. DEFAULT_LOCAL_MODEL = "base"
  12. DEFAULT_LOCAL_STT_LANGUAGE = "en"
  13. DEFAULT_STT_MODEL = os.getenv("STT_OPENAI_MODEL", "whisper-1")
  14. DEFAULT_GROQ_STT_MODEL = os.getenv("STT_GROQ_MODEL", "whisper-large-v3-turbo")
  15. DEFAULT_MISTRAL_STT_MODEL = os.getenv("STT_MISTRAL_MODEL", "voxtral-mini-latest")
  16. DEFAULT_ELEVENLABS_STT_MODEL = os.getenv("STT_ELEVENLABS_MODEL", "scribe_v2")
  17. # Seconds for one STT HTTP request; shared by the OpenAI-SDK path and the QQ adapter so a
  18. # self-hosted model's cold start is not cut off at the old fixed 30s (#112939).
  19. DEFAULT_STT_TIMEOUT = 60.0
  20. # /v1/stt's server default moved from grok-voice-transcribe-1.0 to 2.0 between Sep 17 and
  21. # Sep 21 2026 and 1.0 is slated for retirement; naming the model keeps the wire deterministic
  22. # and lets STT_XAI_MODEL / stt.xai.model pin 1.0 for a rollback.
  23. XAI_STT_MODEL_ENV = "STT_XAI_MODEL"
  24. LEGACY_XAI_STT_MODEL = "grok-stt"
  25. LOCAL_STT_COMMAND_ENV = "HERMES_LOCAL_STT_COMMAND"
  26. LOCAL_STT_LANGUAGE_ENV = "HERMES_LOCAL_STT_LANGUAGE"
  27. COMMON_LOCAL_BIN_DIRS = ("/opt/homebrew/bin", "/usr/local/bin")
  28. GROQ_BASE_URL = os.getenv("GROQ_BASE_URL", "https://api.groq.com/openai/v1")
  29. OPENAI_BASE_URL = os.getenv("STT_OPENAI_BASE_URL", "https://api.openai.com/v1")
  30. XAI_STT_BASE_URL = os.getenv("XAI_STT_BASE_URL", "https://api.x.ai/v1")
  31. ELEVENLABS_STT_BASE_URL = os.getenv("ELEVENLABS_STT_BASE_URL", "https://api.elevenlabs.io/v1")
  32. # DeepInfra STT base URL is resolved via hermes_cli.models.deepinfra_base_url (shared).
  33. SUPPORTED_FORMATS = {".mp3", ".mp4", ".mpeg", ".mpga", ".m4a", ".wav", ".webm", ".ogg", ".oga", ".opus", ".aac", ".flac", ".caf"}
  34. LOCAL_NATIVE_AUDIO_FORMATS = {".wav", ".aiff", ".aif"}
  35. MAX_FILE_SIZE = 25 * 1024 * 1024 # 25 MB
  36. # Per-provider model catalogs keyed by ``stt.<provider>`` section, default first. This one table
  37. # feeds the `hermes tools` picker, the dashboard selects and the auto-correction sets below.
  38. # DeepInfra has no static list: its picker reads the live catalog.
  39. STT_MODEL_CATALOG = {
  40. "local": ["base", "tiny", "small", "medium", "large-v3", "turbo"],
  41. "groq": ["whisper-large-v3-turbo", "whisper-large-v3"],
  42. "openai": ["whisper-1", "gpt-4o-mini-transcribe", "gpt-4o-transcribe", "gpt-transcribe"],
  43. "mistral": ["voxtral-mini-latest", "voxtral-mini-2602"],
  44. "xai": ["grok-voice-transcribe-2.0", "grok-voice-transcribe-1.0"],
  45. "elevenlabs": ["scribe_v2", "scribe_v1"]}
  46. # ElevenLabs historically uses ``model_id`` instead of ``model``.
  47. STT_MODEL_CONFIG_KEY = {"elevenlabs": "model_id"}
  48. # Known model sets for auto-correction. Groq shut distil-whisper-large-v3-en down on
  49. # 2025-08-23 (console.groq.com/docs/deprecations); a config still naming it is remapped.
  50. OPENAI_MODELS = frozenset(STT_MODEL_CATALOG["openai"])
  51. GROQ_MODELS = frozenset(STT_MODEL_CATALOG["groq"])
  52. RETIRED_GROQ_MODELS = frozenset({"distil-whisper-large-v3-en"})
  53. # Providers with native handlers. Kept in sync with ``agent.transcription_registry._BUILTIN_NAMES``
  54. # (a regression test fails on drift); plugins may not register under these names and the
  55. # dispatcher short-circuits them before command/plugin lookup.
  56. # The plugin hook from issue #30398-style follow-up rejects plugins registering under any of these names;
  57. # the dispatcher in ``transcribe_audio`` short-circuits them defensively as well.
  58. BUILTIN_STT_PROVIDERS = frozenset({
  59. "local", "local_command", "groq", "openai", "mistral", "xai", "elevenlabs", "deepinfra"})
  60. # Built-in providers that upload audio to a remote API.
  61. CLOUD_STT_PROVIDERS = frozenset(BUILTIN_STT_PROVIDERS - {"local", "local_command"})
  62. def _error_result(error: str, **extra: Any) -> dict[str, Any]:
  63. """Standard failure envelope shared by every provider and validator."""
  64. return {"success": False, "transcript": "", "error": error, **extra}
  65. class STTResponseError(ValueError):
  66. """A provider answered with a structured object carrying no transcript text.
  67. Raised by ``_extract_transcript_text`` when an SDK object or JSON body reports an
  68. ``error`` (or neither ``text`` nor ``error``) instead of a usable transcript. The
  69. message is the provider's own, so the STT failure paths surface it verbatim rather
  70. than stringifying the response object into its repr (#78098)."""
  71. def normalize_xai_stt_model(model: Any) -> str:
  72. """Return a valid xAI STT model: blank or Hermes' old ``grok-stt`` alias -> ``STT_XAI_MODEL`` (read
  73. per call, so a profile's env applies), else the catalog default."""
  74. value = str(model or "").strip()
  75. if not value or value == LEGACY_XAI_STT_MODEL:
  76. return os.getenv(XAI_STT_MODEL_ENV, "").strip() or STT_MODEL_CATALOG["xai"][0]
  77. return value
  78. def _ok_result(transcript: str, provider: str) -> dict[str, Any]:
  79. return {"success": True, "transcript": transcript, "provider": provider}
  80. def _lazy_ensure_quietly(extra: str) -> None:
  81. """Best-effort ``pm.ensure_import(extra)``; failures are swallowed.
  82. Installs are gated by ``security.allow_lazy_installs`` inside pm."""
  83. try:
  84. import pm
  85. pm.ensure_import(extra)
  86. except Exception:
  87. pass
  88. def _process_error_detail(exc: subprocess.CalledProcessError) -> str:
  89. """stderr > stdout > str(exc) for a failed helper binary."""
  90. for output in (exc.stderr, exc.stdout):
  91. if isinstance(output, bytes):
  92. detail = output.decode("utf-8", errors="replace").strip()
  93. else:
  94. detail = str(output or "").strip()
  95. if detail:
  96. return detail
  97. return str(exc)
  98. def _log_prompt_unsupported(label: str) -> None:
  99. logger.debug("%s does not support transcription prompts — proceeding without the prompt.", label)
  100. def _config_number(cfg: dict[str, Any], key: str, default, cast=float):
  101. """Read ``cfg[key]`` through *cast*, falling back to *default* on bad values."""
  102. try:
  103. return cast(cfg.get(key, default))
  104. except (TypeError, ValueError):
  105. return default