"""Post-setup install hooks and installed-state predicates for `hermes tools` provider rows.""" from __future__ import annotations import os import shlex import shutil import sys from typing import Set from hermes_cli.cli_output import ( print_error as _print_error, print_info as _print_info, print_success as _print_success, print_warning as _print_warning) from hermes_cli.config import get_env_value from hermes_cli.tools_config_cua import _cua_driver_install_ready, install_cua_driver from tools.transcription_common import DEFAULT_LOCAL_MODEL, STT_MODEL_CATALOG _LOCAL_STT_MODEL_SUMMARY = ", ".join( f"{model} (default)" if model == DEFAULT_LOCAL_MODEL else model for model in STT_MODEL_CATALOG["local"] ) def _info_lines(*lines: str) -> None: """Print each line as a 4-space-indented info row.""" for line in lines: _print_info(f" {line}") def _ensure_browser_use_cli() -> None: """Confirm browser_exec's engine is runnable. It is browser-harness, a core dependency of Hermes's own venv, so there is nothing to download; a miss means the venv needs a re-sync.""" from tools.browser_use_cli import _find_cli if _find_cli() is not None: _print_success(" browser_exec ready (browser-harness, bundled with Hermes)") else: _print_warning(" browser-harness is missing from Hermes's Python environment") _print_info(" Re-sync it with: hermes update") def _post_setup_lightpanda() -> None: # browser_exec spawns ``lightpanda serve`` and attaches over CDP. No Chromium needed. _ensure_browser_use_cli() from tools.browser_lightpanda import LIGHTPANDA_INSTALL_HINT, find_lightpanda_binary lightpanda_bin = find_lightpanda_binary() if lightpanda_bin: _print_success(f" Lightpanda found: {lightpanda_bin}") else: _print_warning(" lightpanda binary not found on PATH, ~/.lightpanda or ~/.local/bin") _print_info(f" {LIGHTPANDA_INSTALL_HINT}") if os.name == "nt": _print_info(" Lightpanda has no native Windows build; run Hermes under WSL2.") def _post_setup_chromium() -> None: """Local Browser row: browser_exec launches pm's Chromium. Termux (system Chromium) and the Hermes Docker image (its baked build) own their payloads, so a miss there is a hint, never a download.""" import pm from hermes_cli.browser_runtime import BAKED_EXECUTABLE_FILE, chromium_executable, chromium_missing_hint from hermes_constants import is_termux _ensure_browser_use_cli() if chromium_executable() is None and not (is_termux() or BAKED_EXECUTABLE_FILE.exists()): try: pm.ensure("chromium", explicit=True) except (RuntimeError, OSError) as exc: # pm.InstallError, a download or worker failure _print_warning(f" Chromium install failed: {exc}") _info_lines("Retry with: hermes tools post-setup chromium") return found = chromium_executable() if found is None: _print_warning(f" {chromium_missing_hint()}") return _print_success(f" Chromium ready: {found}") # OS libraries are host-owned. Never download another package manager to install them. if sys.platform == "linux" and not is_termux(): _info_lines("Chromium also needs system libraries supplied by your distribution.") if shutil.which("apt-get") and _module_installed("playwright"): command = shlex.join([sys.executable, "-m", "playwright", "install-deps", "chromium"]) _info_lines(f"Install missing system libraries with: {command}") else: _info_lines("System dependency installation guide:", " https://playwright.dev/python/docs/browsers#install-system-dependencies") # The hook key is the UI provider identifier; extra names belong to pyproject.toml. def _python_hook(module, extra, label, installing, on_install=(), always=()) -> dict: return {"module": module, "extra": extra, "label": label, "installing": installing, "on_install": on_install, "always": always} _PYTHON_POST_SETUP_HOOKS: dict = { "faster_whisper": _python_hook( "faster_whisper", "stt-whisper", "faster-whisper", "Installing faster-whisper (model ~150MB downloads on first use)...", on_install=(f"Model sizes: {_LOCAL_STT_MODEL_SUMMARY}", "Change via stt.local.model in config.yaml")), "kittentts": _python_hook( "kittentts", "kittentts", "kittentts", "Installing kittentts (~25-80MB model, CPU-only)...", on_install=("Voices: Jasper, Bella, Luna, Bruno, Rosie, Hugo, Kiki, Leo", "Models: KittenML/kitten-tts-nano-0.8-int8 (25MB), micro (41MB), mini (80MB)")), "piper": _python_hook( "piper", "piper", "piper-tts", "Installing piper-tts (~14MB wheel, voices downloaded on first use)...", always=("Default voice: en_US-lessac-medium (downloaded on first TTS call)", "Full voice list: https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/VOICES.md", "Switch voices by setting tts.piper.voice in config.yaml")), "ddgs": _python_hook( "ddgs", "ddgs", "ddgs", "Installing ddgs (DuckDuckGo search package)...", always=("No API key required. DuckDuckGo enforces server-side rate limits.", "Pair with an extract provider if you also need web_extract."))} def _post_setup_python(spec: dict) -> None: """Enable one Python provider through the application dependency transaction.""" import pm label = spec["label"] _print_info(f" {spec['installing']}") try: pm.sync_venv([spec["extra"]], explicit=True) except (pm.InstallError, OSError, ValueError) as exc: _print_warning(f" {label} install failed: {exc}") _info_lines("Retry with: hermes tools") return _print_success(f" {label} dependencies ready. Restart Hermes to use them.") _info_lines(*spec["on_install"], *spec["always"]) def _post_setup_xai_grok() -> None: """Shared xAI credential bootstrap for any picker row that talks to xAI (TTS, STT, Video Gen, x_search …). Accepts a SuperGrok-tier OAuth token (preferred — billed to the existing subscription) or a raw XAI_API_KEY; the rows declare empty env_vars so the auth UX lives here.""" try: from hermes_cli.auth import get_xai_oauth_auth_status oauth_logged_in = bool(get_xai_oauth_auth_status().get("logged_in")) except Exception: oauth_logged_in = False if oauth_logged_in: _print_success(" xAI will use your xAI Grok OAuth (SuperGrok / Premium+) credentials") return if get_env_value("XAI_API_KEY"): _print_success(" xAI will use your existing XAI_API_KEY") return _print_info(" xAI needs credentials. Choose one:") try: from hermes_cli.setup import prompt_choice, prompt as _setup_prompt from hermes_cli.setup_tts import _run_xai_oauth_login_from_setup from hermes_cli.config import save_env_value except Exception as exc: _print_warning(f" Could not load setup helpers: {exc}") _info_lines("Run later: hermes auth add xai-oauth (or set XAI_API_KEY)") return idx = prompt_choice( " How do you want xAI to authenticate?", default=0, choices=["Sign in with xAI Grok OAuth (SuperGrok / Premium+) — browser login", "Paste an xAI API key (console.x.ai)", "Skip — configure later via `hermes auth add xai-oauth`"]) if idx == 0: if _run_xai_oauth_login_from_setup(): _print_success(" Logged in — xAI will use these OAuth credentials") else: _print_warning(" xAI Grok OAuth login did not complete. Run later: hermes auth add xai-oauth") elif idx == 1: api_key = _setup_prompt(" xAI API key", password=True) if api_key: save_env_value("XAI_API_KEY", api_key) _print_success(" XAI_API_KEY saved") else: _print_warning(" No API key provided. Run later: hermes auth add xai-oauth") else: _print_info(" xAI will remain inactive until credentials are configured.") def _codex_credentials_present() -> bool: """Cheap offline check for Codex/ChatGPT OAuth credentials (auth store + pool only).""" try: from hermes_cli.auth import get_codex_auth_status return bool(get_codex_auth_status().get("logged_in")) except Exception: return False def _post_setup_openai_codex() -> None: """Shared Codex/ChatGPT OAuth bootstrap for any picker row that talks to Codex without an API key (image gen today). The rows declare empty env_vars so the sign-in UX lives here. Saves tokens only — never rewrites ``model.provider``: the user picked an image backend, not a chat model (#102144).""" if _codex_credentials_present(): _print_success(" Image generation will use your existing Codex/ChatGPT OAuth credentials") return relogin = "hermes auth add openai-codex" _print_info(" OpenAI (Codex auth) needs credentials.") try: from hermes_cli.auth import _codex_device_code_login, _save_codex_tokens from hermes_cli.setup import is_noninteractive, prompt_choice except Exception as exc: _print_warning(f" Could not load setup helpers: {exc}") _info_lines(f"Run later: {relogin}") return if is_noninteractive(): # Dashboard/Desktop spawn this hook with stdin=DEVNULL: nobody can finish a device-code # login here, and the panel already shows the needs_auth pill. _info_lines(f"No terminal to sign in from. Run: {relogin}") return idx = prompt_choice( " How do you want to sign in?", default=0, choices=["Sign in with ChatGPT/Codex OAuth — browser login", f"Skip — configure later via `{relogin}`"]) if idx != 0: _print_info(" Codex image generation will remain inactive until you sign in.") return try: creds = _codex_device_code_login() _save_codex_tokens(creds["tokens"], creds.get("last_refresh"), set_active=False) except (Exception, KeyboardInterrupt) as exc: _print_warning(f" Codex sign-in did not complete: {exc}. Run later: {relogin}") return _print_success(" Logged in — image generation will use these Codex OAuth credentials") def _xai_credentials_ready() -> bool: from hermes_cli.tools_config import _xai_credentials_present # facade binding: tests patch it there return _xai_credentials_present() # Credential-bootstrap post_setup keys -> "credentials present" predicate. These rows have no install # side-effect; ``provider_readiness_status`` reports them ready/needs_auth from the auth store. _POST_SETUP_AUTH_READY: dict = { "xai_grok": _xai_credentials_ready, "openai_codex": _codex_credentials_present, } # post_setup key -> hook. Unknown keys are a silent no-op (callers validate against valid_post_setup_keys()). _POST_SETUP_HOOKS: dict = { "lightpanda": _post_setup_lightpanda, "chromium": _post_setup_chromium, # Cloud browser rows (plugins.browser.*): the vendor hosts Chromium; browser_exec attaches over CDP. "browserbase": lambda: _ensure_browser_use_cli(), "cua_driver": lambda: install_cua_driver(upgrade=False), "xai_grok": _post_setup_xai_grok, "openai_codex": _post_setup_openai_codex, **{key: (lambda spec=spec: _post_setup_python(spec)) for key, spec in _PYTHON_POST_SETUP_HOOKS.items()}, } def _run_post_setup(post_setup_key: str): """Run post-setup hooks for tools that need extra installation steps.""" _POST_SETUP_HOOKS.get(post_setup_key, lambda: None)() def valid_post_setup_keys() -> set[str]: """Return the set of post-setup keys declared by any visible provider (``TOOL_CATEGORIES`` plus plugin-registered providers). This is the allowlist ``post-setup`` and the dashboard endpoint validate against, so a caller cannot drive ``_run_post_setup`` with an arbitrary key.""" from hermes_cli.tools_config import ( TOOL_CATEGORIES, _plugin_browser_providers, _plugin_image_gen_providers, _plugin_video_gen_providers, _plugin_web_search_providers) keys: set[str] = set() for cat in TOOL_CATEGORIES.values(): keys.update(ps for prov in cat.get("providers", []) if (ps := prov.get("post_setup"))) for builder in (_plugin_web_search_providers, _plugin_image_gen_providers, _plugin_video_gen_providers, _plugin_browser_providers): try: keys.update(ps for prov in builder() if (ps := prov.get("post_setup"))) except Exception: # pragma: no cover — defensive; plugins optional continue return keys def run_post_setup_command(args) -> int: """``hermes tools post-setup `` — non-interactive runner the dashboard spawns so the GUI can drive backend setup without re-implementing install logic. Exit code: 0 ok, 2 unknown key.""" key = getattr(args, "post_setup_key", None) if not key: _print_error("Usage: hermes tools post-setup ") return 2 valid = valid_post_setup_keys() if key not in valid: _print_error(f"Unknown post-setup key: {key!r}. Valid keys: {', '.join(sorted(valid)) or '(none)'}") return 2 _print_info(f"Running post-setup hook: {key}") try: _run_post_setup(key) except Exception as exc: # pragma: no cover — defensive _print_error(f"Post-setup failed: {exc}") return 1 _print_success(f"Post-setup '{key}' complete") return 0 # post_setup_key -> predicate(): True when the install side-effect is already satisfied. Used by # `_toolset_needs_configuration_prompt` to force provider setup when a no-key provider still needs a # binary/dependency install (otherwise toggling the toolset on silently skips the hook). Only add an # entry when the post_setup is the ONLY install side-effect for a no-key provider and the check is # local, bounded, and import-light. _POST_SETUP_INSTALLED: dict = {"cua_driver": lambda: _cua_driver_install_ready()} def _post_setup_already_installed(post_setup_key: str) -> bool: """Return True when the post_setup install side-effect is satisfied (or no check is registered).""" predicate = _POST_SETUP_INSTALLED.get(post_setup_key) try: return predicate is None or bool(predicate()) except Exception: return True def _module_installed(module_name: str) -> bool: """Cheap importable-without-importing check (no heavy side effects).""" import importlib.util try: return importlib.util.find_spec(module_name) is not None except Exception: return False def _chromium_installed() -> bool: """Everything ``_run_post_setup("chromium")`` provides is present: browser-harness and a Chromium, so "Run setup" flips to installed only when re-running it would be a no-op.""" from hermes_cli.browser_runtime import chromium_executable return _browser_harness_installed() and chromium_executable() is not None def _browser_harness_installed() -> bool: """Installed-check for the ``browserbase`` hook: cloud providers host their own Chromium, so browser_exec's engine is the whole local contract.""" from tools.browser_use_cli import _find_cli return _find_cli() is not None def _lightpanda_installed() -> bool: """True when a lightpanda binary is on PATH or in a known install dir.""" try: from tools.browser_lightpanda import find_lightpanda_binary return find_lightpanda_binary() is not None except Exception: return False # post_setup_key -> predicate(): True when the install side-effect is satisfied. Used by # ``provider_readiness_status`` to mark a keyless post_setup row "ready" vs "needs_setup"; mirrors the # installed-checks the hooks perform. Credential bootstraps (``xai_grok``, ``openai_codex``) are absent — # they live in ``_POST_SETUP_AUTH_READY`` as auth checks. Late-bound lambdas so tests can monkeypatch the underlying predicates. _POST_SETUP_READY: dict = { **{key: (lambda m=spec["module"]: _module_installed(m)) for key, spec in _PYTHON_POST_SETUP_HOOKS.items()}, "chromium": lambda: _chromium_installed(), "browserbase": lambda: _browser_harness_installed(), "lightpanda": lambda: _lightpanda_installed(), "cua_driver": lambda: _cua_driver_install_ready()}