provider_registry.py 8.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204
  1. """Shared engine behind the ``agent.*_registry`` provider registries.
  2. Every pluggable-backend registry has the same shape: a global name->provider map
  3. plus per-profile *scoped* maps (multiplexed gateways), a lock, registration with
  4. re-registration logging, and the snapshot/restore pair :mod:`hermes_cli.plugins`
  5. uses to unwind a plugin. Each ``*_registry`` module instantiates one
  6. :class:`ProviderRegistry` and re-exports its bound methods under the historical
  7. module-level names via :meth:`ProviderRegistry.export`, so ``patch("agent.x_registry.get_provider")``
  8. targets and the ``_providers`` / ``_scoped_providers`` / ``_lock`` test hooks are unchanged.
  9. """
  10. from __future__ import annotations
  11. import logging
  12. import threading
  13. from typing import Any, Callable, Dict, FrozenSet, Generic, List, Optional, TypeVar
  14. from hermes_constants import hermes_home_key, normalize_scope
  15. P = TypeVar("P")
  16. def lower_key(name: str) -> str:
  17. return name.strip().lower()
  18. class ProviderRegistry(Generic[P]):
  19. """Global + per-scope provider map with plugin snapshot/restore support.
  20. ``normalize`` is ``str.strip`` or ``lower_key`` (case-insensitive registries mirror
  21. how their dispatcher normalizes the configured name). ``builtin_names`` are reserved
  22. for in-tree implementations; a collision calls ``on_builtin_collision(key)`` and, if
  23. that returns, skips registration. ``logger`` is the owning module's so record names
  24. stay per-registry.
  25. """
  26. def __init__(
  27. self, *, label: str, provider_cls: type, logger: logging.Logger,
  28. normalize: Callable[[str], str] = str.strip, builtin_names: frozenset[str] = frozenset(),
  29. on_builtin_collision: Optional[Callable[[str], None]] = None,
  30. ) -> None:
  31. self.label = label
  32. self.provider_cls = provider_cls
  33. self.logger = logger
  34. self.normalize = normalize
  35. self.builtin_names = builtin_names
  36. self._on_builtin_collision = on_builtin_collision
  37. self._providers: dict[str, P] = {}
  38. self._scoped_providers: dict[str, dict[str, P]] = {}
  39. self._generation = 0
  40. self._scoped_generations: dict[str, int] = {}
  41. self._lock = threading.Lock()
  42. # "TTS provider" but "Registered browser provider": acronyms keep their case.
  43. self._log_label = label if label.isupper() else label[0].lower() + label[1:]
  44. def _target(self, scope: Optional[str], *, create: bool) -> dict[str, P]:
  45. scope = normalize_scope(scope)
  46. if scope is None:
  47. return self._providers
  48. if create:
  49. return self._scoped_providers.setdefault(scope, {})
  50. return self._scoped_providers.get(scope, {})
  51. def _bump(self, scope: Optional[str]) -> None:
  52. scope = normalize_scope(scope)
  53. if scope is None:
  54. self._generation += 1
  55. else:
  56. self._scoped_generations[scope] = self._scoped_generations.get(scope, 0) + 1
  57. def register(self, provider: P, *, scope: Optional[str] = None) -> None:
  58. """Register a provider; same-name re-registration overwrites (hot reload)."""
  59. if not isinstance(provider, self.provider_cls):
  60. article = "an" if self.provider_cls.__name__[0] in "AEIOU" else "a"
  61. raise TypeError(
  62. f"register_provider() expects {article} {self.provider_cls.__name__} "
  63. f"instance, got {type(provider).__name__}"
  64. )
  65. raw_name = provider.name
  66. if not isinstance(raw_name, str) or not raw_name.strip():
  67. raise ValueError(f"{self.label} provider .name must be a non-empty string")
  68. key = self.normalize(raw_name)
  69. if key in self.builtin_names:
  70. if self._on_builtin_collision is not None:
  71. self._on_builtin_collision(key)
  72. return
  73. with self._lock:
  74. target = self._target(scope, create=True)
  75. existing = target.get(key)
  76. target[key] = provider
  77. self._bump(scope)
  78. if existing is not None:
  79. self.logger.debug(
  80. f"{self.label} provider '%s' re-registered (was %r)", key, type(existing).__name__,
  81. )
  82. else:
  83. self.logger.debug(
  84. f"Registered {self._log_label} provider '%s' (%s)", key, type(provider).__name__,
  85. )
  86. def merged(self, scope: Optional[str] = None) -> dict[str, P]:
  87. """Global map overlaid with the active profile's scoped map (a copy)."""
  88. with self._lock:
  89. merged = dict(self._providers)
  90. merged.update(self._scoped_providers.get(hermes_home_key(scope), {}))
  91. return merged
  92. def list_providers(self, *, scope: Optional[str] = None) -> list[P]:
  93. """Return all registered providers, sorted by name."""
  94. return sorted(self.merged(scope).values(), key=lambda p: p.name)
  95. def get_provider(self, name: str, *, scope: Optional[str] = None) -> Optional[P]:
  96. """Return the provider registered under *name* (scoped first), or None."""
  97. if not isinstance(name, str):
  98. return None
  99. key = self.normalize(name)
  100. with self._lock:
  101. return (
  102. self._scoped_providers.get(hermes_home_key(scope), {}).get(key)
  103. or self._providers.get(key)
  104. )
  105. def registry_generation(self, *, scope: Optional[str] = None) -> tuple:
  106. """Cache fingerprint ``(global_generation, scoped_generation)``."""
  107. active_scope = hermes_home_key(scope)
  108. with self._lock:
  109. return self._generation, self._scoped_generations.get(active_scope, 0)
  110. def snapshot_registration(self, name: str, *, scope: Optional[str] = None) -> Optional[P]:
  111. """Exact-slot lookup (no global fallback) used to detect plugin ownership."""
  112. with self._lock:
  113. return self._target(scope, create=False).get(self.normalize(name))
  114. def restore_registration(
  115. self, name: str, current: P, previous: Optional[P], *, scope: Optional[str] = None
  116. ) -> bool:
  117. """Restore *previous* only when *current* is still installed under *name*."""
  118. key = self.normalize(name)
  119. scope = normalize_scope(scope)
  120. with self._lock:
  121. target = self._target(scope, create=True)
  122. if target.get(key) is not current:
  123. return False
  124. if previous is None:
  125. target.pop(key, None)
  126. else:
  127. target[key] = previous
  128. self._bump(scope)
  129. if scope is not None and not target:
  130. self._scoped_providers.pop(scope, None)
  131. return True
  132. def reset_for_tests(self) -> None:
  133. """Clear every registration. **Test-only.**"""
  134. with self._lock:
  135. self._providers.clear()
  136. self._scoped_providers.clear()
  137. self._scoped_generations.clear()
  138. self._generation += 1
  139. def export(self, namespace: dict[str, Any]) -> None:
  140. """Bind the historical module-level API (+ ``_providers``/``_scoped_providers``/
  141. ``_lock`` test hooks) into a ``*_registry`` module namespace."""
  142. namespace.update(
  143. _providers=self._providers, _scoped_providers=self._scoped_providers, _lock=self._lock,
  144. register_provider=self.register, list_providers=self.list_providers,
  145. get_provider=self.get_provider, snapshot_registration=self.snapshot_registration,
  146. restore_registration=self.restore_registration,
  147. registry_generation=self.registry_generation, _reset_for_tests=self.reset_for_tests,
  148. )
  149. def is_available_safe(
  150. provider: Any, logger: logging.Logger, fmt: str, *, level: int = logging.DEBUG, exc_info: bool = False,
  151. ) -> bool:
  152. """``bool(provider.is_available())`` that treats a raising provider as unavailable."""
  153. try:
  154. return bool(provider.is_available())
  155. except Exception as exc:
  156. logger.log(level, fmt, provider.name, exc, exc_info=exc_info)
  157. return False
  158. def configured_provider_name(section: str, logger: logging.Logger) -> Optional[str]:
  159. """Read ``<section>.provider`` from config.yaml, mapping the managed Nous
  160. selection to ``fal`` (the FAL plugin services it via the managed gateway)."""
  161. configured: Optional[str] = None
  162. try:
  163. from hermes_cli.config import load_config_readonly
  164. cfg = load_config_readonly()
  165. block = cfg.get(section) if isinstance(cfg, dict) else None
  166. raw = block.get("provider") if isinstance(block, dict) else None
  167. if isinstance(raw, str) and raw.strip():
  168. configured = raw.strip()
  169. except Exception as exc:
  170. logger.debug("Could not read %s.provider from config: %s", section, exc)
  171. if configured:
  172. try:
  173. from tools.tool_backend_helpers import NOUS_MANAGED_PROVIDER
  174. if configured.lower() == NOUS_MANAGED_PROVIDER:
  175. configured = "fal"
  176. except Exception: # pragma: no cover — helpers are in-repo
  177. pass
  178. return configured