"""Web Search Provider ABC. The single plugin-facing surface every web provider (brave-free, ddgs, searxng, exa, parallel, tavily, keenable, firecrawl) implements; registered via ``PluginContext.register_web_search_provider()`` and selected by ``web.search_backend`` / ``web.extract_backend`` / ``web.backend``. Response shapes (legacy contract, the tool wrapper does not translate):: search: {"success": True, "data": {"web": [{"title", "url", "description", "position"}, ...]}} extract: {"success": True, "data": [{"url", "title", "content", "raw_content", "metadata"}, ...]} failure: {"success": False, "error": str} """ from __future__ import annotations import abc import os from typing import Any, Dict, List from agent.provider_base import ProviderBase def get_provider_env(name: str) -> str: """Config-aware env lookup (``os.environ`` first, then ``~/.hermes/.env``) so credentials set through the config layer are visible in gateway sessions / delegate children / subprocess runs. Stripped value, or ``""`` when unset. Falls back to a bare ``os.getenv`` when the config module is unavailable (stripped installs, early import contexts). See #40190. Never when a profile secret scope is bound: a scoped miss means the served profile has no key, and ``os.environ`` holds the LAUNCH profile's — a routed profile without an Exa/Parallel key must be refused, not search on another profile's key. """ try: from hermes_cli.config import get_env_value val = get_env_value(name) except Exception as exc: try: from agent.secret_scope import UnscopedSecretError except ImportError: UnscopedSecretError = () # type: ignore[assignment,misc] if isinstance(exc, UnscopedSecretError): raise val = None scope_bound, multiplex_active = _secret_scope_state() if val is None and multiplex_active and not scope_bound: from agent.secret_scope import UnscopedSecretError raise UnscopedSecretError(name, f"get_provider_env({name!r}) called with no active profile scope") if val is None and not scope_bound: val = os.getenv(name, "") return (val or "").strip() def _secret_scope_state() -> tuple[bool, bool]: try: from agent.secret_scope import current_secret_scope, is_multiplex_active except Exception: return False, False return current_secret_scope() is not None, is_multiplex_active() class WebSearchProvider(ProviderBase): """Abstract base class for a web search/extract backend: implement :meth:`is_available` and at least one of :meth:`search` / :meth:`extract`; the ``supports_*`` flags route each capability.""" @abc.abstractmethod def is_available(self) -> bool: """True when this provider can service calls. Cheap check only (env var, importable dep, instance URL) — NO network; runs at tool registration and on every ``hermes tools`` paint.""" def supports_search(self) -> bool: """True if this provider implements :meth:`search`.""" return True def is_keyless_available(self) -> bool: """True when this provider can serve calls WITHOUT credentials (public anonymous free tiers such as Exa / Parallel MCP); used only when NO provider is configured or keyed. Must never make :meth:`is_available` True, or the legacy preference walk would route keyed users onto a higher-priority backend's free tier. Cheap, no network.""" return False def supports_extract(self) -> bool: """True if this provider implements :meth:`extract` (sync or ``async def`` — the dispatcher awaits coroutine functions).""" return False def search(self, query: str, limit: int = 5) -> dict[str, Any]: """Execute a web search. Callers gate on :meth:`supports_search`.""" raise NotImplementedError( f"{self.name} does not support search (override supports_search)" ) def extract(self, urls: list[str], **kwargs: Any) -> Any: """Extract content from URLs (callers gate on :meth:`supports_extract`); may be ``async def``. Returns ``[{"url", "title", "content", "raw_content", "metadata"?, "error"?}, ...]`` (``error`` only on per-URL failure). Ignore unknown ``kwargs`` (``format``, ``include_raw``, ``max_chars``).""" raise NotImplementedError( f"{self.name} does not support extract (override supports_extract)" )