tools_config_post_setup.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357
  1. """Post-setup install hooks and installed-state predicates for `hermes tools` provider rows."""
  2. from __future__ import annotations
  3. import os
  4. import shlex
  5. import shutil
  6. import sys
  7. from typing import Set
  8. from hermes_cli.cli_output import (
  9. print_error as _print_error, print_info as _print_info, print_success as _print_success,
  10. print_warning as _print_warning)
  11. from hermes_cli.config import get_env_value
  12. from hermes_cli.tools_config_cua import _cua_driver_install_ready, install_cua_driver
  13. from tools.transcription_common import DEFAULT_LOCAL_MODEL, STT_MODEL_CATALOG
  14. _LOCAL_STT_MODEL_SUMMARY = ", ".join(
  15. f"{model} (default)" if model == DEFAULT_LOCAL_MODEL else model for model in STT_MODEL_CATALOG["local"]
  16. )
  17. def _info_lines(*lines: str) -> None:
  18. """Print each line as a 4-space-indented info row."""
  19. for line in lines:
  20. _print_info(f" {line}")
  21. def _ensure_browser_use_cli() -> None:
  22. """Confirm browser_exec's engine is runnable. It is browser-harness, a core dependency of
  23. Hermes's own venv, so there is nothing to download; a miss means the venv needs a re-sync."""
  24. from tools.browser_use_cli import _find_cli
  25. if _find_cli() is not None:
  26. _print_success(" browser_exec ready (browser-harness, bundled with Hermes)")
  27. else:
  28. _print_warning(" browser-harness is missing from Hermes's Python environment")
  29. _print_info(" Re-sync it with: hermes update")
  30. def _post_setup_lightpanda() -> None:
  31. # browser_exec spawns ``lightpanda serve`` and attaches over CDP. No Chromium needed.
  32. _ensure_browser_use_cli()
  33. from tools.browser_lightpanda import LIGHTPANDA_INSTALL_HINT, find_lightpanda_binary
  34. lightpanda_bin = find_lightpanda_binary()
  35. if lightpanda_bin:
  36. _print_success(f" Lightpanda found: {lightpanda_bin}")
  37. else:
  38. _print_warning(" lightpanda binary not found on PATH, ~/.lightpanda or ~/.local/bin")
  39. _print_info(f" {LIGHTPANDA_INSTALL_HINT}")
  40. if os.name == "nt":
  41. _print_info(" Lightpanda has no native Windows build; run Hermes under WSL2.")
  42. def _post_setup_chromium() -> None:
  43. """Local Browser row: browser_exec launches pm's Chromium. Termux (system Chromium) and the Hermes
  44. Docker image (its baked build) own their payloads, so a miss there is a hint, never a download."""
  45. import pm
  46. from hermes_cli.browser_runtime import BAKED_EXECUTABLE_FILE, chromium_executable, chromium_missing_hint
  47. from hermes_constants import is_termux
  48. _ensure_browser_use_cli()
  49. if chromium_executable() is None and not (is_termux() or BAKED_EXECUTABLE_FILE.exists()):
  50. try:
  51. pm.ensure("chromium", explicit=True)
  52. except (RuntimeError, OSError) as exc: # pm.InstallError, a download or worker failure
  53. _print_warning(f" Chromium install failed: {exc}")
  54. _info_lines("Retry with: hermes tools post-setup chromium")
  55. return
  56. found = chromium_executable()
  57. if found is None:
  58. _print_warning(f" {chromium_missing_hint()}")
  59. return
  60. _print_success(f" Chromium ready: {found}")
  61. # OS libraries are host-owned. Never download another package manager to install them.
  62. if sys.platform == "linux" and not is_termux():
  63. _info_lines("Chromium also needs system libraries supplied by your distribution.")
  64. if shutil.which("apt-get") and _module_installed("playwright"):
  65. command = shlex.join([sys.executable, "-m", "playwright", "install-deps", "chromium"])
  66. _info_lines(f"Install missing system libraries with: {command}")
  67. else:
  68. _info_lines("System dependency installation guide:",
  69. " https://playwright.dev/python/docs/browsers#install-system-dependencies")
  70. # The hook key is the UI provider identifier; extra names belong to pyproject.toml.
  71. def _python_hook(module, extra, label, installing, on_install=(), always=()) -> dict:
  72. return {"module": module, "extra": extra, "label": label, "installing": installing,
  73. "on_install": on_install, "always": always}
  74. _PYTHON_POST_SETUP_HOOKS: dict = {
  75. "faster_whisper": _python_hook(
  76. "faster_whisper", "stt-whisper", "faster-whisper", "Installing faster-whisper (model ~150MB downloads on first use)...",
  77. on_install=(f"Model sizes: {_LOCAL_STT_MODEL_SUMMARY}",
  78. "Change via stt.local.model in config.yaml")),
  79. "kittentts": _python_hook(
  80. "kittentts", "kittentts", "kittentts", "Installing kittentts (~25-80MB model, CPU-only)...",
  81. on_install=("Voices: Jasper, Bella, Luna, Bruno, Rosie, Hugo, Kiki, Leo",
  82. "Models: KittenML/kitten-tts-nano-0.8-int8 (25MB), micro (41MB), mini (80MB)")),
  83. "piper": _python_hook(
  84. "piper", "piper", "piper-tts", "Installing piper-tts (~14MB wheel, voices downloaded on first use)...",
  85. always=("Default voice: en_US-lessac-medium (downloaded on first TTS call)",
  86. "Full voice list: https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/VOICES.md",
  87. "Switch voices by setting tts.piper.voice in config.yaml")),
  88. "ddgs": _python_hook(
  89. "ddgs", "ddgs", "ddgs", "Installing ddgs (DuckDuckGo search package)...",
  90. always=("No API key required. DuckDuckGo enforces server-side rate limits.",
  91. "Pair with an extract provider if you also need web_extract."))}
  92. def _post_setup_python(spec: dict) -> None:
  93. """Enable one Python provider through the application dependency transaction."""
  94. import pm
  95. label = spec["label"]
  96. _print_info(f" {spec['installing']}")
  97. try:
  98. pm.sync_venv([spec["extra"]], explicit=True)
  99. except (pm.InstallError, OSError, ValueError) as exc:
  100. _print_warning(f" {label} install failed: {exc}")
  101. _info_lines("Retry with: hermes tools")
  102. return
  103. _print_success(f" {label} dependencies ready. Restart Hermes to use them.")
  104. _info_lines(*spec["on_install"], *spec["always"])
  105. def _post_setup_xai_grok() -> None:
  106. """Shared xAI credential bootstrap for any picker row that talks to xAI (TTS, STT, Video Gen, x_search
  107. …). Accepts a SuperGrok-tier OAuth token (preferred — billed to the existing subscription) or a raw
  108. XAI_API_KEY; the rows declare empty env_vars so the auth UX lives here."""
  109. try:
  110. from hermes_cli.auth import get_xai_oauth_auth_status
  111. oauth_logged_in = bool(get_xai_oauth_auth_status().get("logged_in"))
  112. except Exception:
  113. oauth_logged_in = False
  114. if oauth_logged_in:
  115. _print_success(" xAI will use your xAI Grok OAuth (SuperGrok / Premium+) credentials")
  116. return
  117. if get_env_value("XAI_API_KEY"):
  118. _print_success(" xAI will use your existing XAI_API_KEY")
  119. return
  120. _print_info(" xAI needs credentials. Choose one:")
  121. try:
  122. from hermes_cli.setup import prompt_choice, prompt as _setup_prompt
  123. from hermes_cli.setup_tts import _run_xai_oauth_login_from_setup
  124. from hermes_cli.config import save_env_value
  125. except Exception as exc:
  126. _print_warning(f" Could not load setup helpers: {exc}")
  127. _info_lines("Run later: hermes auth add xai-oauth (or set XAI_API_KEY)")
  128. return
  129. idx = prompt_choice(
  130. " How do you want xAI to authenticate?", default=0,
  131. choices=["Sign in with xAI Grok OAuth (SuperGrok / Premium+) — browser login",
  132. "Paste an xAI API key (console.x.ai)",
  133. "Skip — configure later via `hermes auth add xai-oauth`"])
  134. if idx == 0:
  135. if _run_xai_oauth_login_from_setup():
  136. _print_success(" Logged in — xAI will use these OAuth credentials")
  137. else:
  138. _print_warning(" xAI Grok OAuth login did not complete. Run later: hermes auth add xai-oauth")
  139. elif idx == 1:
  140. api_key = _setup_prompt(" xAI API key", password=True)
  141. if api_key:
  142. save_env_value("XAI_API_KEY", api_key)
  143. _print_success(" XAI_API_KEY saved")
  144. else:
  145. _print_warning(" No API key provided. Run later: hermes auth add xai-oauth")
  146. else:
  147. _print_info(" xAI will remain inactive until credentials are configured.")
  148. def _codex_credentials_present() -> bool:
  149. """Cheap offline check for Codex/ChatGPT OAuth credentials (auth store + pool only)."""
  150. try:
  151. from hermes_cli.auth import get_codex_auth_status
  152. return bool(get_codex_auth_status().get("logged_in"))
  153. except Exception:
  154. return False
  155. def _post_setup_openai_codex() -> None:
  156. """Shared Codex/ChatGPT OAuth bootstrap for any picker row that talks to Codex without an API key
  157. (image gen today). The rows declare empty env_vars so the sign-in UX lives here. Saves tokens only —
  158. never rewrites ``model.provider``: the user picked an image backend, not a chat model (#102144)."""
  159. if _codex_credentials_present():
  160. _print_success(" Image generation will use your existing Codex/ChatGPT OAuth credentials")
  161. return
  162. relogin = "hermes auth add openai-codex"
  163. _print_info(" OpenAI (Codex auth) needs credentials.")
  164. try:
  165. from hermes_cli.auth import _codex_device_code_login, _save_codex_tokens
  166. from hermes_cli.setup import is_noninteractive, prompt_choice
  167. except Exception as exc:
  168. _print_warning(f" Could not load setup helpers: {exc}")
  169. _info_lines(f"Run later: {relogin}")
  170. return
  171. if is_noninteractive():
  172. # Dashboard/Desktop spawn this hook with stdin=DEVNULL: nobody can finish a device-code
  173. # login here, and the panel already shows the needs_auth pill.
  174. _info_lines(f"No terminal to sign in from. Run: {relogin}")
  175. return
  176. idx = prompt_choice(
  177. " How do you want to sign in?", default=0,
  178. choices=["Sign in with ChatGPT/Codex OAuth — browser login",
  179. f"Skip — configure later via `{relogin}`"])
  180. if idx != 0:
  181. _print_info(" Codex image generation will remain inactive until you sign in.")
  182. return
  183. try:
  184. creds = _codex_device_code_login()
  185. _save_codex_tokens(creds["tokens"], creds.get("last_refresh"), set_active=False)
  186. except (Exception, KeyboardInterrupt) as exc:
  187. _print_warning(f" Codex sign-in did not complete: {exc}. Run later: {relogin}")
  188. return
  189. _print_success(" Logged in — image generation will use these Codex OAuth credentials")
  190. def _xai_credentials_ready() -> bool:
  191. from hermes_cli.tools_config import _xai_credentials_present # facade binding: tests patch it there
  192. return _xai_credentials_present()
  193. # Credential-bootstrap post_setup keys -> "credentials present" predicate. These rows have no install
  194. # side-effect; ``provider_readiness_status`` reports them ready/needs_auth from the auth store.
  195. _POST_SETUP_AUTH_READY: dict = {
  196. "xai_grok": _xai_credentials_ready,
  197. "openai_codex": _codex_credentials_present,
  198. }
  199. # post_setup key -> hook. Unknown keys are a silent no-op (callers validate against valid_post_setup_keys()).
  200. _POST_SETUP_HOOKS: dict = {
  201. "lightpanda": _post_setup_lightpanda,
  202. "chromium": _post_setup_chromium,
  203. # Cloud browser rows (plugins.browser.*): the vendor hosts Chromium; browser_exec attaches over CDP.
  204. "browserbase": lambda: _ensure_browser_use_cli(),
  205. "cua_driver": lambda: install_cua_driver(upgrade=False),
  206. "xai_grok": _post_setup_xai_grok,
  207. "openai_codex": _post_setup_openai_codex,
  208. **{key: (lambda spec=spec: _post_setup_python(spec)) for key, spec in _PYTHON_POST_SETUP_HOOKS.items()},
  209. }
  210. def _run_post_setup(post_setup_key: str):
  211. """Run post-setup hooks for tools that need extra installation steps."""
  212. _POST_SETUP_HOOKS.get(post_setup_key, lambda: None)()
  213. def valid_post_setup_keys() -> set[str]:
  214. """Return the set of post-setup keys declared by any visible provider (``TOOL_CATEGORIES`` plus
  215. plugin-registered providers). This is the allowlist ``post-setup`` and the dashboard endpoint
  216. validate against, so a caller cannot drive ``_run_post_setup`` with an arbitrary key."""
  217. from hermes_cli.tools_config import (
  218. TOOL_CATEGORIES, _plugin_browser_providers, _plugin_image_gen_providers,
  219. _plugin_video_gen_providers, _plugin_web_search_providers)
  220. keys: set[str] = set()
  221. for cat in TOOL_CATEGORIES.values():
  222. keys.update(ps for prov in cat.get("providers", []) if (ps := prov.get("post_setup")))
  223. for builder in (_plugin_web_search_providers, _plugin_image_gen_providers,
  224. _plugin_video_gen_providers, _plugin_browser_providers):
  225. try:
  226. keys.update(ps for prov in builder() if (ps := prov.get("post_setup")))
  227. except Exception: # pragma: no cover — defensive; plugins optional
  228. continue
  229. return keys
  230. def run_post_setup_command(args) -> int:
  231. """``hermes tools post-setup <key>`` — non-interactive runner the dashboard spawns so the GUI can drive
  232. backend setup without re-implementing install logic. Exit code: 0 ok, 2 unknown key."""
  233. key = getattr(args, "post_setup_key", None)
  234. if not key:
  235. _print_error("Usage: hermes tools post-setup <key>")
  236. return 2
  237. valid = valid_post_setup_keys()
  238. if key not in valid:
  239. _print_error(f"Unknown post-setup key: {key!r}. Valid keys: {', '.join(sorted(valid)) or '(none)'}")
  240. return 2
  241. _print_info(f"Running post-setup hook: {key}")
  242. try:
  243. _run_post_setup(key)
  244. except Exception as exc: # pragma: no cover — defensive
  245. _print_error(f"Post-setup failed: {exc}")
  246. return 1
  247. _print_success(f"Post-setup '{key}' complete")
  248. return 0
  249. # post_setup_key -> predicate(): True when the install side-effect is already satisfied. Used by
  250. # `_toolset_needs_configuration_prompt` to force provider setup when a no-key provider still needs a
  251. # binary/dependency install (otherwise toggling the toolset on silently skips the hook). Only add an
  252. # entry when the post_setup is the ONLY install side-effect for a no-key provider and the check is
  253. # local, bounded, and import-light.
  254. _POST_SETUP_INSTALLED: dict = {"cua_driver": lambda: _cua_driver_install_ready()}
  255. def _post_setup_already_installed(post_setup_key: str) -> bool:
  256. """Return True when the post_setup install side-effect is satisfied (or no check is registered)."""
  257. predicate = _POST_SETUP_INSTALLED.get(post_setup_key)
  258. try:
  259. return predicate is None or bool(predicate())
  260. except Exception:
  261. return True
  262. def _module_installed(module_name: str) -> bool:
  263. """Cheap importable-without-importing check (no heavy side effects)."""
  264. import importlib.util
  265. try:
  266. return importlib.util.find_spec(module_name) is not None
  267. except Exception:
  268. return False
  269. def _chromium_installed() -> bool:
  270. """Everything ``_run_post_setup("chromium")`` provides is present: browser-harness and a Chromium, so
  271. "Run setup" flips to installed only when re-running it would be a no-op."""
  272. from hermes_cli.browser_runtime import chromium_executable
  273. return _browser_harness_installed() and chromium_executable() is not None
  274. def _browser_harness_installed() -> bool:
  275. """Installed-check for the ``browserbase`` hook: cloud providers host their own Chromium, so
  276. browser_exec's engine is the whole local contract."""
  277. from tools.browser_use_cli import _find_cli
  278. return _find_cli() is not None
  279. def _lightpanda_installed() -> bool:
  280. """True when a lightpanda binary is on PATH or in a known install dir."""
  281. try:
  282. from tools.browser_lightpanda import find_lightpanda_binary
  283. return find_lightpanda_binary() is not None
  284. except Exception:
  285. return False
  286. # post_setup_key -> predicate(): True when the install side-effect is satisfied. Used by
  287. # ``provider_readiness_status`` to mark a keyless post_setup row "ready" vs "needs_setup"; mirrors the
  288. # installed-checks the hooks perform. Credential bootstraps (``xai_grok``, ``openai_codex``) are absent —
  289. # they live in ``_POST_SETUP_AUTH_READY`` as auth checks. Late-bound lambdas so tests can monkeypatch the underlying predicates.
  290. _POST_SETUP_READY: dict = {
  291. **{key: (lambda m=spec["module"]: _module_installed(m)) for key, spec in _PYTHON_POST_SETUP_HOOKS.items()},
  292. "chromium": lambda: _chromium_installed(),
  293. "browserbase": lambda: _browser_harness_installed(),
  294. "lightpanda": lambda: _lightpanda_installed(),
  295. "cua_driver": lambda: _cua_driver_install_ready()}