tts_tool_plugins.py 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132
  1. """Plugin-registered TTS providers for ``tools.tts_tool``: routes ``tts.provider: <name>`` values
  2. that are neither built-in nor ``type: command`` to a plugin :class:`agent.tts_provider.TTSProvider`.
  3. Discovery goes through ``hermes_cli.plugins._ensure_plugins_discovered`` (imported lazily so the
  4. tool module stays importable without the plugin machinery).
  5. """
  6. from __future__ import annotations
  7. import logging
  8. import math
  9. from typing import Any, Dict, Optional, Tuple
  10. from tools.tts_command_provider import (
  11. BUILTIN_TTS_PROVIDERS, DEFAULT_COMMAND_TTS_OUTPUT_FORMAT, _get_named_provider_config,
  12. _is_command_provider_config)
  13. from tools.tool_backend_helpers import NOUS_MANAGED_PROVIDER
  14. logger = logging.getLogger("tools.tts_tool")
  15. def _lookup_plugin_provider(key: str, *, discover: bool = True, retry: bool = False):
  16. """The registered ``TTSProvider`` named *key*, or None. ``discover`` runs plugin discovery first;
  17. ``retry`` re-discovers with ``force=True`` on a miss (a long-lived session may predate the
  18. plugin's install). Raises on registry/discovery failure — callers decide if fatal."""
  19. from agent.tts_registry import get_provider
  20. if discover:
  21. from hermes_cli.plugins import _ensure_plugins_discovered
  22. _ensure_plugins_discovered()
  23. plugin_provider = get_provider(key)
  24. if plugin_provider is None and retry:
  25. _ensure_plugins_discovered(force=True)
  26. plugin_provider = get_provider(key)
  27. return plugin_provider
  28. def _plugin_route_key(provider: str, tts_config: dict[str, Any]) -> Optional[str]:
  29. """Normalized *provider* when a plugin may service it, else None: built-in names never reach the
  30. registry and a same-named ``type: command`` provider wins (config is more local than a plugin)."""
  31. key = (provider or "").lower().strip()
  32. if not key or key in BUILTIN_TTS_PROVIDERS or key == NOUS_MANAGED_PROVIDER: # nous = the openai path
  33. return None
  34. if _is_command_provider_config(_get_named_provider_config(tts_config, key)):
  35. return None
  36. return key
  37. def _plugin_voice_kwargs(tts_config: dict[str, Any]) -> dict[str, Any]:
  38. """``voice`` / ``model`` / ``speed`` for a plugin call (None = provider default). Shared by
  39. ``synthesize`` and the streaming path so a streamed reply keeps the configured voice."""
  40. cfg = tts_config if isinstance(tts_config, dict) else {}
  41. voice, model, speed = cfg.get("voice"), cfg.get("model"), cfg.get("speed")
  42. return {"voice": voice if isinstance(voice, str) and voice else None,
  43. "model": model if isinstance(model, str) and model else None,
  44. "speed": float(speed) if isinstance(speed, (int, float)) else None}
  45. def _plugin_pcm_streaming_provider(provider: str, tts_config: dict[str, Any]) -> Optional[tuple[Any, int]]:
  46. """``(plugin, sample_rate)`` when the plugin servicing *provider* opted into raw-PCM streaming.
  47. Opt-in = ``streams_pcm`` truthy AND ``stream_sample_rate`` a finite number >= 1 Hz AND
  48. ``is_available()`` — read once per resolve, so per-profile state (key present, user opted out)
  49. belongs there. A bad rate is refused loudly: PCM played at a guessed rate garbles speech.
  50. """
  51. key = _plugin_route_key(provider, tts_config)
  52. if key is None:
  53. return None
  54. try:
  55. plugin = _lookup_plugin_provider(key)
  56. if plugin is None or not plugin.streams_pcm or not plugin.is_available():
  57. return None
  58. rate = plugin.stream_sample_rate
  59. except Exception: # third-party plugin code: a broken plugin falls back to per-sentence synthesis
  60. logger.debug("plugin TTS streaming lookup failed for '%s'", key, exc_info=True)
  61. return None
  62. if isinstance(rate, bool) or not isinstance(rate, (int, float)) or not math.isfinite(rate) or rate < 1:
  63. logger.warning("TTS provider '%s' sets streams_pcm without a valid stream_sample_rate (%r); "
  64. "using per-sentence synthesis instead", key, rate)
  65. return None
  66. return plugin, int(rate)
  67. def _dispatch_to_plugin_provider(text: str, output_path: str, provider: str, tts_config: dict[str, Any]) -> Optional[str]:
  68. """Route to a plugin-registered TTS provider; None means "fall through".
  69. Invariants re-checked here so a caller refactor can't break them: built-in names never reach
  70. the registry; a same-named ``type: command`` provider wins; only an exact registered name
  71. dispatches. Plugin exceptions propagate to ``text_to_speech_tool``'s error envelope.
  72. Resolution invariants enforced here (matches issue #30398):
  73. 1. The caller is responsible for the elif chain that handles ``edge``/``openai``/etc.; this function
  74. explicitly rejects those names defensively. 2. 3. Plugin dispatch fires only when ``provider`` matches a
  75. registered :class:`TTSProvider` whose ``name`` equals the configured value. Unknown names return None
  76. (caller falls through to Edge default). See #17843.
  77. """
  78. key = _plugin_route_key(provider, tts_config)
  79. if key is None:
  80. return None
  81. try:
  82. plugin_provider = _lookup_plugin_provider(key, retry=True)
  83. except Exception as exc:
  84. logger.debug("tts plugin dispatch skipped (discovery failed): %s", exc)
  85. return None
  86. if plugin_provider is None:
  87. return None
  88. fmt = (tts_config if isinstance(tts_config, dict) else {}).get(
  89. "output_format", DEFAULT_COMMAND_TTS_OUTPUT_FORMAT)
  90. logger.info("Generating speech with plugin TTS provider '%s'...", key)
  91. written = plugin_provider.synthesize(
  92. text, output_path, format=str(fmt).lower() if fmt else "mp3", **_plugin_voice_kwargs(tts_config))
  93. return written if isinstance(written, str) and written else output_path
  94. def _plugin_provider_is_voice_compatible(provider: str) -> bool:
  95. """True when the registered plugin provider opts into voice-bubble delivery (any failure -> False)."""
  96. key = (provider or "").lower().strip()
  97. if not key or key in BUILTIN_TTS_PROVIDERS:
  98. return False
  99. try:
  100. plugin_provider = _lookup_plugin_provider(key, discover=False)
  101. return plugin_provider is not None and bool(plugin_provider.voice_compatible)
  102. except Exception as exc:
  103. logger.debug("tts plugin voice_compatible check failed for '%s': %s", key, exc)
  104. return False
  105. def _plugin_provider_is_available(provider: str) -> bool:
  106. """``check_fn`` leg for plugin names: discovered provider reports ``is_available()``; any failure is False."""
  107. try:
  108. plugin = _lookup_plugin_provider(provider)
  109. return bool(plugin and plugin.is_available())
  110. except Exception:
  111. return False