tts_tool_lifecycle.py 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232
  1. """Local-engine lifecycle for ``tools.tts_tool``: warm-up / release leases.
  2. Local engines load lazily on first synthesis (dead air on the first spoken reply) and then stay
  3. resident. Every surface that flips speech output on holds a *lease* here (warming the configured
  4. engine); when the last lease is released the local model caches are dropped after a keep-warm
  5. window (``tts.keep_warm_seconds``), so one surface's "off" can't unload a model another surface
  6. still needs and a wake-word loop that re-acquires within the window reuses the loaded model.
  7. Cloud providers have nothing resident; warming only ensures the SDK imports. Origin seams (``_load_tts_config``, ``_get_provider``) are
  8. resolved through :func:`_origin` per call.
  9. """
  10. from __future__ import annotations
  11. import logging
  12. import threading
  13. import time
  14. from typing import Any, Callable, Dict, List, Optional
  15. from agent.memory_provider import ctx_bound
  16. from tools import tts_command_provider
  17. from tools.tts_command_provider import (
  18. BUILTIN_TTS_PROVIDERS, _get_command_tts_timeout, _get_named_provider_config,
  19. _is_command_provider_config, command_env_passthrough as _command_provider_env_passthrough,
  20. render_command_template as _render_command_tts_template)
  21. from tools.tts_tool_delivery import _origin
  22. from tools.tts_tool_local import (
  23. _LOCAL_TTS_MODEL_CACHES, _load_kittentts_model_for_config, _load_piper_voice_for_config)
  24. from tools.tts_tool_plugins import _lookup_plugin_provider
  25. logger = logging.getLogger("tools.tts_tool")
  26. _tts_lease_lock = threading.Lock()
  27. _tts_leases: set = set()
  28. # Pending keep-warm unload; the generation lets a timer that already woke up see it was superseded.
  29. _DEFAULT_KEEP_WARM_SECONDS = 60.0
  30. _make_keep_warm_timer = threading.Timer # test seam
  31. _keep_warm_timer: Optional[threading.Timer] = None
  32. _keep_warm_generation = 0
  33. def _local_tts_warmers() -> dict[str, Callable[[dict[str, Any]], Any]]:
  34. """Provider name → loader populating that engine's cache slot (same key synthesis uses)."""
  35. return {
  36. "piper": lambda cfg: _load_piper_voice_for_config(cfg)[0],
  37. "kittentts": lambda cfg: _load_kittentts_model_for_config(cfg)[0]}
  38. # pm extra for providers whose SDK installs on first use.
  39. _LAZY_SDK_FEATURES = {"edge": "edge-tts", "elevenlabs": "tts-premium", "mistral": "mistral"}
  40. def _signal_user_tts_provider(name: str, tts_config: dict[str, Any], hook: str) -> Optional[str]:
  41. """Forward a lease ``hook`` (``"warm"``/``"release"``) to a user-declared provider; returns the action.
  42. Command providers run their optional ``<hook>_command`` (same template/env/timeout rules as
  43. ``command``) on a background thread so a toggle never waits on a model server; plugins get
  44. :meth:`TTSProvider.warm`/``release``. Best-effort: failures are logged at debug."""
  45. if not name or name in BUILTIN_TTS_PROVIDERS:
  46. return None
  47. cfg = _get_named_provider_config(tts_config, name)
  48. try:
  49. if _is_command_provider_config(cfg):
  50. template = str(cfg.get(f"{hook}_command") or "").strip()
  51. if not template:
  52. return None
  53. command = _render_command_tts_template(template, {
  54. "voice": str(cfg.get("voice", "")),
  55. "model": str(cfg.get("model", "")),
  56. "speed": str(cfg.get("speed", tts_config.get("speed", "")))})
  57. def _run() -> None:
  58. try:
  59. tts_command_provider.run_command_provider(
  60. command, _get_command_tts_timeout(cfg),
  61. env_passthrough=_command_provider_env_passthrough(cfg))
  62. except Exception as exc:
  63. logger.debug("[TTS] %s_command for %s failed: %s", hook, name, exc)
  64. # ctx_bound: env_passthrough resolves through the caller's profile secret scope.
  65. threading.Thread(target=ctx_bound(_run), name=f"tts-{hook}-{name}", daemon=True).start()
  66. return hook
  67. plugin_provider = _lookup_plugin_provider(name)
  68. if plugin_provider is None:
  69. return None
  70. getattr(plugin_provider, hook)()
  71. return hook
  72. except Exception as exc:
  73. logger.debug("[TTS] %s hook for %s failed: %s", hook, name, exc)
  74. return "error"
  75. def warm_tts_provider(tts_config: Optional[dict[str, Any]] = None, provider: Optional[str] = None) -> dict[str, Any]:
  76. """Pre-load the configured TTS provider so the next synthesis starts hot (blocking; never raises).
  77. Local engines fill the same LRU slot synthesis reads (including first-use download); lazily
  78. installed cloud SDKs are made importable; user-declared providers get their warm hook;
  79. everything else is ``action: "noop"``. The result carries ``warmed`` / ``action`` / ``error``."""
  80. if tts_config is None:
  81. tts_config = _origin()._load_tts_config()
  82. name = (provider or _origin()._get_provider(tts_config) or "").lower().strip()
  83. result: dict[str, Any] = {"provider": name, "warmed": False, "action": "noop"}
  84. warmer = _local_tts_warmers().get(name)
  85. if warmer is not None:
  86. cache = _LOCAL_TTS_MODEL_CACHES.get(name, {})
  87. before, started = len(cache), time.monotonic()
  88. try:
  89. warmer(tts_config)
  90. except Exception as exc: # engine missing, download failed, bad voice…
  91. logger.warning("[TTS] warm-up for %s failed: %s", name, exc)
  92. result.update(action="error", error=str(exc))
  93. return result
  94. result.update(
  95. warmed=True, action="loaded" if len(cache) > before else "cached",
  96. elapsed_ms=int((time.monotonic() - started) * 1000))
  97. logger.info("[TTS] warm-up %s: %s in %dms", name, result["action"], result["elapsed_ms"])
  98. return result
  99. signalled = _signal_user_tts_provider(name, tts_config, "warm")
  100. if signalled is not None:
  101. ok = signalled != "error"
  102. result.update(warmed=ok, action="warmed" if ok else "error")
  103. return result
  104. feature = _LAZY_SDK_FEATURES.get(name)
  105. if feature is not None:
  106. try:
  107. import pm
  108. if pm.available(feature):
  109. result.update(warmed=True, action="cached")
  110. else:
  111. pm.ensure_import(feature)
  112. result.update(warmed=True, action="installed")
  113. except Exception as exc:
  114. logger.debug("[TTS] SDK warm-up for %s skipped: %s", name, exc)
  115. result.update(action="error", error=str(exc))
  116. return result
  117. def release_tts_provider(provider: Optional[str] = None) -> dict[str, Any]:
  118. """Drop resident local models -> ``{"released": <count>}``. With ``provider`` only that engine's
  119. cache is cleared; otherwise every cache is, and the configured user provider is signalled."""
  120. name = (provider or "").lower().strip()
  121. if not name:
  122. tts_config = _origin()._load_tts_config()
  123. _signal_user_tts_provider(_origin()._get_provider(tts_config), tts_config, "release")
  124. released = 0
  125. for cache_name, cache in _LOCAL_TTS_MODEL_CACHES.items():
  126. if not name or cache_name == name:
  127. released += len(cache)
  128. cache.clear()
  129. if released:
  130. logger.info("[TTS] released %d resident local model(s)", released)
  131. return {"released": released}
  132. def _keep_warm_seconds() -> float:
  133. """``tts.keep_warm_seconds``, read per call so each profile's config applies; ``0`` = unload now."""
  134. raw = _origin()._load_tts_config().get("keep_warm_seconds", _DEFAULT_KEEP_WARM_SECONDS)
  135. try:
  136. return max(0.0, float(raw))
  137. except (TypeError, ValueError):
  138. return _DEFAULT_KEEP_WARM_SECONDS
  139. def _cancel_keep_warm_locked() -> None:
  140. global _keep_warm_timer, _keep_warm_generation
  141. _keep_warm_generation += 1
  142. if _keep_warm_timer is not None:
  143. _keep_warm_timer.cancel()
  144. _keep_warm_timer = None
  145. def _schedule_release_locked() -> int:
  146. """No holders left: (re)start the keep-warm window, or unload inline when it is 0.
  147. Returns the count released inline."""
  148. global _keep_warm_timer
  149. _cancel_keep_warm_locked()
  150. delay = _keep_warm_seconds()
  151. if delay <= 0:
  152. return release_tts_provider()["released"]
  153. # ctx_bound: the unload reads config/secrets under the releasing caller's profile scope.
  154. timer = _make_keep_warm_timer(
  155. delay, ctx_bound(_release_after_keep_warm), args=(_keep_warm_generation,))
  156. timer.daemon = True
  157. _keep_warm_timer = timer
  158. timer.start()
  159. return 0
  160. def _release_after_keep_warm(generation: int) -> None:
  161. global _keep_warm_timer
  162. with _tts_lease_lock:
  163. if generation != _keep_warm_generation or _tts_leases:
  164. return
  165. _keep_warm_timer = None
  166. release_tts_provider()
  167. def acquire_tts_lease(lease: str, tts_config: Optional[dict[str, Any]] = None) -> dict[str, Any]:
  168. """Register ``lease`` (e.g. ``"desktop:read-aloud"``) and warm the provider. Re-acquiring is
  169. idempotent but still re-warms (cheap on a cache hit; heals a cache cleared elsewhere). An
  170. acquire inside the keep-warm window cancels the pending unload."""
  171. with _tts_lease_lock:
  172. _cancel_keep_warm_locked()
  173. _tts_leases.add(lease)
  174. holders = len(_tts_leases)
  175. result = warm_tts_provider(tts_config)
  176. with _tts_lease_lock:
  177. # Every holder released while the load ran: the window starts now that the model is resident.
  178. if not _tts_leases:
  179. _schedule_release_locked()
  180. return {**result, "leases": holders}
  181. def release_tts_lease(lease: str) -> dict[str, Any]:
  182. """Drop ``lease``; the last one out unloads resident local models once the keep-warm window
  183. passes with no new acquire. A never-acquired lease is a no-op (still reports the holder count)
  184. so surfaces can call this unconditionally. ``released`` counts models unloaded inline."""
  185. with _tts_lease_lock:
  186. held = lease in _tts_leases
  187. _tts_leases.discard(lease)
  188. holders = len(_tts_leases)
  189. released = _schedule_release_locked() if held and holders == 0 else 0
  190. return {"leases": holders, "released": released}
  191. def tts_lease_holders() -> list[str]:
  192. """Snapshot of live lease names (diagnostics / tests)."""
  193. with _tts_lease_lock:
  194. return sorted(_tts_leases)
  195. def _reset_tts_leases_for_tests() -> None:
  196. with _tts_lease_lock:
  197. _cancel_keep_warm_locked()
  198. _tts_leases.clear()