tool_backend_helpers.py 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305
  1. """Shared helpers for tool backend selection."""
  2. from __future__ import annotations
  3. import logging
  4. import os
  5. from pathlib import Path
  6. from typing import Any, Dict, Optional
  7. from utils import is_truthy_value
  8. logger = logging.getLogger(__name__)
  9. _DEFAULT_BROWSER_PROVIDER = "local"
  10. _DEFAULT_MODAL_MODE = "auto"
  11. _VALID_MODAL_MODES = {"auto", "direct", "managed"}
  12. def managed_nous_tools_enabled(*, force_fresh: bool = False) -> bool:
  13. """Coarse gate: entitled to the Nous Tool Gateway (paid Portal access OR a live free
  14. pool). Fails closed on unknown/error — never blocks startup. Callers narrow per category
  15. via ``tool_gateway_entitled_for``; ``force_fresh`` is for flows needing a just-bought grant."""
  16. try:
  17. from hermes_cli.nous_account import get_nous_portal_account_info
  18. # Branched call, not ``force_fresh=force_fresh``: tests stub the reader with zero-arg lambdas.
  19. account_info = (get_nous_portal_account_info(force_fresh=True) if force_fresh
  20. else get_nous_portal_account_info())
  21. return bool(account_info.logged_in) and account_info.tool_gateway_entitled
  22. except Exception:
  23. return False
  24. def nous_tool_gateway_unavailable_message(capability: str = "the Nous Tool Gateway", *,
  25. force_fresh: bool = False) -> str:
  26. """Return account-aware guidance for an unavailable Nous Tool Gateway path."""
  27. try:
  28. from hermes_cli.nous_account import (
  29. format_nous_portal_entitlement_message, get_nous_portal_account_info)
  30. message = format_nous_portal_entitlement_message(
  31. get_nous_portal_account_info(force_fresh=force_fresh), capability=capability,
  32. in_chat=True)
  33. if message:
  34. return message
  35. except Exception:
  36. pass
  37. return (f"{capability} is unavailable. Run `hermes model` to refresh your "
  38. "Nous Portal login and billing status.")
  39. def normalize_browser_cloud_provider(value: object | None) -> str:
  40. """Return a normalized browser provider key."""
  41. provider = str(value or _DEFAULT_BROWSER_PROVIDER).strip().lower()
  42. return provider or _DEFAULT_BROWSER_PROVIDER
  43. def coerce_modal_mode(value: object | None) -> str:
  44. """Return the requested modal mode when valid, else the default."""
  45. mode = str(value or _DEFAULT_MODAL_MODE).strip().lower()
  46. return mode if mode in _VALID_MODAL_MODES else _DEFAULT_MODAL_MODE
  47. normalize_modal_mode = coerce_modal_mode
  48. def has_direct_modal_credentials() -> bool:
  49. """Return True when direct Modal credentials/config are available. The token pair is a
  50. profile credential: read it through the secret scope so the default profile's Modal
  51. account never selects the direct backend for a multiplexed secondary."""
  52. if _scoped_credential("MODAL_TOKEN_ID") and _scoped_credential("MODAL_TOKEN_SECRET"):
  53. return True
  54. try:
  55. return (Path.home() / ".modal.toml").exists()
  56. except OSError: # includes PermissionError on Path.home()
  57. return False
  58. def resolve_modal_backend_state(modal_mode: object | None, *, has_direct: bool,
  59. managed_ready: bool,
  60. managed_enabled: bool | None = None) -> dict[str, Any]:
  61. """Resolve direct vs managed Modal backend: ``direct``/``managed`` are exclusive; ``auto``
  62. prefers managed when available, else direct."""
  63. requested_mode = coerce_modal_mode(modal_mode)
  64. if managed_enabled is None:
  65. managed_enabled = managed_nous_tools_enabled()
  66. managed_ok = managed_enabled and managed_ready
  67. exclusive = {"managed": "managed" if managed_ok else None,
  68. "direct": "direct" if has_direct else None}
  69. selected_backend = exclusive.get(
  70. requested_mode, "managed" if managed_ok else "direct" if has_direct else None)
  71. return {"requested_mode": requested_mode, "mode": requested_mode, "has_direct": has_direct,
  72. "managed_ready": managed_ready,
  73. "managed_mode_blocked": requested_mode == "managed" and not managed_enabled,
  74. "selected_backend": selected_backend}
  75. def _scoped_credential(name: str) -> str:
  76. """Read a credential env var under the active profile secret scope; raw env fallback only
  77. if ``agent.secret_scope`` cannot import (a packaging edge must never lose the key)."""
  78. try:
  79. from agent.secret_scope import get_secret
  80. return (get_secret(name, "") or "").strip()
  81. except Exception: # pragma: no cover — secret_scope is in-repo
  82. return (os.getenv(name, "") or "").strip()
  83. def _dotenv_value(env_var: str) -> str:
  84. """``.env`` value via ``hermes_cli.config.get_env_value`` (``""`` when unavailable)."""
  85. try:
  86. from hermes_cli.config import get_env_value
  87. return str(get_env_value(env_var) or "").strip()
  88. except Exception: # pragma: no cover — config is in-repo
  89. return ""
  90. def _env_source_suppressed(provider_id: str, env_var: str) -> bool:
  91. """``hermes auth remove <provider>`` records ``env:<VAR>`` in ``suppressed_sources`` and promises
  92. the variable is ignored until ``hermes auth add``; a value still living in a long-running
  93. gateway's process environment (inherited across update restarts) must honor that too."""
  94. if not provider_id:
  95. return False
  96. try:
  97. from hermes_cli.auth import is_source_suppressed
  98. return is_source_suppressed(provider_id, f"env:{env_var}")
  99. except Exception: # pragma: no cover — auth store unreadable: keep prior behavior
  100. return False
  101. def resolve_provider_secret(env_var: str, provider_id: str, config_value: str = "",
  102. env_getter=None) -> str:
  103. """Resolve a voice-provider API key (single owner for STT/TTS lookup). Order: explicit
  104. ``config_value`` -> profile secret scope / env -> ``.env`` via ``env_getter`` (or
  105. ``hermes_cli.config.get_env_value``) -> credential pool for ``provider_id``. Under an
  106. active multiplex turn the profile scope is authoritative: a miss returns ``""`` rather
  107. than borrowing another profile's env or pool. Never raises. The env/.env tier is skipped
  108. entirely while ``env:<env_var>`` is suppressed for ``provider_id`` (#116155).
  109. Resolution order (fixes #68003 — keys added via ``hermes auth add <provider>`` were invisible to the
  110. voice tools, which only consulted env/.env):
  111. """
  112. key = str(config_value or "").strip()
  113. if key:
  114. return key
  115. env_suppressed = _env_source_suppressed(provider_id, env_var)
  116. if not env_suppressed and (key := _scoped_credential(env_var)):
  117. return key
  118. try:
  119. from agent.secret_scope import is_multiplex_active
  120. if is_multiplex_active():
  121. return ""
  122. except Exception: # pragma: no cover — secret_scope is in-repo
  123. pass
  124. if not env_suppressed:
  125. key = str(env_getter(env_var) or "").strip() if env_getter else _dotenv_value(env_var)
  126. if key or not provider_id:
  127. return key
  128. try:
  129. from agent.credential_pool import load_pool
  130. # config.yaml ``providers.<name>`` entries are pooled under ``custom:<name>``.
  131. for pool_key in (provider_id, f"custom:{provider_id}"):
  132. pool = load_pool(pool_key)
  133. entry = pool.peek() if pool is not None and pool.has_credentials() else None
  134. key = str(getattr(entry, "runtime_api_key", "") or getattr(entry, "access_token", "")
  135. or "").strip()
  136. if key:
  137. return key
  138. except Exception as exc:
  139. logger.debug("Could not read %s credential pool for %s: %s", provider_id, env_var, exc)
  140. return ""
  141. def resolve_openai_audio_api_key() -> str:
  142. """Prefer VOICE_TOOLS_OPENAI_KEY, else OPENAI_API_KEY (scope-aware, pool fallback for the
  143. latter). Must go through the secret scope: a raw ``os.environ`` read could bill another
  144. profile's account under multiplex.
  145. Outside a multiplexed turn, ``OPENAI_API_KEY`` additionally falls back to the credential pool (``hermes
  146. auth add openai-api``) via ``resolve_provider_secret`` — same #68003 fix as the other voice providers.
  147. The dedicated voice-tools override remains env/scope-only.
  148. """
  149. return (resolve_provider_secret("VOICE_TOOLS_OPENAI_KEY", "")
  150. or resolve_provider_secret("OPENAI_API_KEY", "openai-api"))
  151. def prefers_gateway(config_section: str) -> bool:
  152. """True when ``<section>.use_gateway`` is set in config.yaml. Never raises."""
  153. try:
  154. from hermes_cli.config import load_config
  155. section = (load_config() or {}).get(config_section)
  156. return isinstance(section, dict) and is_truthy_value(section.get("use_gateway"))
  157. except Exception:
  158. return False
  159. # Provider value the managed "Nous Subscription" picker rows write for every category;
  160. # any other name = that vendor direct; no key = legacy autodetect.
  161. NOUS_MANAGED_PROVIDER = "nous"
  162. # Per-capability keys that also count as "this category has been configured".
  163. _EXTRA_SELECTION_KEYS = {"web": ("search_backend", "extract_backend")}
  164. _DEFAULT_NAME_KEYS = ("provider", "backend", "cloud_provider")
  165. # Key(s) carrying each category's provider selection: one entry per `hermes tools` / Tool Gateway
  166. # category read_selection() serves. A leftover ``browser.backend`` (the pre-v52 driver choice) is
  167. # not the cloud provider — excluded.
  168. _SELECTION_NAME_KEYS = {
  169. "browser": ("cloud_provider",), "web": ("backend",),
  170. **dict.fromkeys(("image_gen", "video_gen", "tts", "stt"), _DEFAULT_NAME_KEYS),
  171. }
  172. def selection_config_keys() -> frozenset[str]:
  173. """Dotted config keys read_selection()/selection_exists() honour, from their own tables.
  174. DEFAULT_CONFIG leaves them unseeded on purpose (a stored key is the user's explicit pick), so
  175. the config-key validator asks here instead of walking the defaults."""
  176. return frozenset(
  177. f"{section}.{key}"
  178. for section, name_keys in _SELECTION_NAME_KEYS.items()
  179. for key in ("use_gateway", *name_keys, *_EXTRA_SELECTION_KEYS.get(section, ())))
  180. def _raw_section(section: str) -> dict[str, Any] | None:
  181. """The RAW (unmerged) config.yaml mapping for ``section``, or None."""
  182. try:
  183. from hermes_cli.config import read_raw_config_readonly
  184. cfg = read_raw_config_readonly() or {}
  185. raw = cfg.get(section) if isinstance(cfg, dict) else None
  186. return raw if isinstance(raw, dict) else None
  187. except Exception:
  188. return None
  189. def read_selection(section: str) -> str | None:
  190. """THE single runtime read of the persisted `hermes tools` selection: ``"nous"`` (managed
  191. gateway row), a vendor name (direct, own credentials), or ``None`` (never configured ->
  192. legacy autodetect allowed). Reads the RAW config.yaml so key presence means "actually
  193. written", not "schema default"; a raw ``local`` is therefore a real user selection.
  194. Legacy shim: ``use_gateway: true`` was only ever written by the managed row, so it maps
  195. to ``"nous"`` regardless of the name key. Never raises."""
  196. raw = _raw_section(section)
  197. if raw is None:
  198. return None
  199. if is_truthy_value(raw.get("use_gateway")):
  200. return NOUS_MANAGED_PROVIDER
  201. for key in _SELECTION_NAME_KEYS.get(section, _DEFAULT_NAME_KEYS):
  202. text = str(raw.get(key)).strip().lower() if raw.get(key) is not None else ""
  203. if text:
  204. return text
  205. # use_gateway: false with no name key is not a usable selection shape;
  206. # per-capability web keys still count as configured via selection_exists().
  207. return None
  208. def read_web_capability_selection(capability: Optional[str] = None) -> str | None:
  209. """Stored selection that decides ONE web capability (``"search"`` / ``"extract"``):
  210. ``web.<capability>_backend`` when set (``"nous"`` = managed gateway, a vendor name =
  211. that vendor direct), else the shared :func:`read_selection`. Lets search and extract
  212. each choose between the user's own key and the Nous Tool Gateway."""
  213. if capability:
  214. raw = _raw_section("web") or {}
  215. pin = str(raw.get(f"{capability}_backend") or "").strip().lower()
  216. if pin:
  217. return pin
  218. return read_selection("web")
  219. def selection_exists(section: str) -> bool:
  220. """True when ANY selection signal was ever written for the section (wider than
  221. read_selection: per-capability web keys count too)."""
  222. if read_selection(section) is not None:
  223. return True
  224. extra = _EXTRA_SELECTION_KEYS.get(section, ())
  225. raw = _raw_section(section) if extra else None
  226. return raw is not None and any(str(raw.get(key) or "").strip() for key in extra)
  227. # Backends that once shipped in-tree but were removed; a config still pointing at one would
  228. # otherwise fail silently at the FIRST tool call with a generic "no registered provider has that
  229. # name". Used by the startup config check and selection_error(); add removals here, never as
  230. # one-off string checks: "web": {"<name>": "the <Name> backend was removed in vX (...)"}
  231. REMOVED_BACKENDS: dict[str, dict[str, str]] = {}
  232. # Backends that once shipped in-tree but were removed. A config that still points at one otherwise fails
  233. # silently at the FIRST tool call with a generic "no registered provider has that name" — no migration, no
  234. # startup notice (reported after the Tavily removal in #99199). Both the startup config check
  235. # (hermes_cli.config.validate_config_structure) and selection_error() consult this map so the user learns
  236. # what actually happened and what to do. Declared data, one policy — add future removals here, never as
  237. # one-off string checks at call sites.
  238. # Currently empty: the Tavily removal (#99199) that introduced this registry was reverted by the #99731
  239. # restore. Future backend removals add an entry here, e.g. "web": {"<name>": "the <Name> backend was removed
  240. # in vX.Y.Z (...)"},
  241. def removed_backend_note(section: str, name: str) -> Optional[str]:
  242. """Explanation for a backend that used to ship in-tree, or None. ``name`` tolerates the
  243. quoted form callers pass to selection_error()."""
  244. return REMOVED_BACKENDS.get(section, {}).get((name or "").strip().strip("'\"").lower())
  245. def selection_error(section: str, selection_name: str, failure: str) -> str:
  246. """The uniform honest-error contract for a selected-but-broken provider."""
  247. failure = removed_backend_note(section, selection_name) or failure
  248. return (f"{section} is configured to use {selection_name} (set via hermes "
  249. f"tools), but {failure}. Run 'hermes tools' to change it.")
  250. def fal_key_is_configured() -> bool:
  251. """True when FAL_KEY is set (scope/env, else ``.env`` for CLI paths that run before dotenv
  252. loads) to a non-whitespace value, so tool-side and CLI setup-time checks agree."""
  253. return bool(_scoped_credential("FAL_KEY") or _dotenv_value("FAL_KEY"))