PL jXdZddlmZddlZddlmZmZmZGddejZ dS)u Web Search Provider ABC ======================= Defines the pluggable-backend interface for web search and content extraction. Providers register instances via ``PluginContext.register_web_search_provider()``; the active one (selected via ``web.search_backend`` / ``web.extract_backend`` / ``web.backend`` in ``config.yaml``) services every ``web_search`` / ``web_extract`` tool call. Providers live in ``/plugins/web//`` (built-in, auto-loaded as ``kind: backend``) or ``~/.hermes/plugins/web//`` (user, opt-in via ``plugins.enabled``). This ABC is the SINGLE plugin-facing surface for web providers — every provider in the tree (brave-free, ddgs, searxng, exa, parallel, tavily, firecrawl) implements it. The legacy in-tree ``tools.web_providers.base`` ABCs were deleted in PR #25182 along with the per-vendor inline helpers in ``tools/web_tools.py``; the response-shape contract documented below is preserved bit-for-bit so the tool wrapper does not have to translate. Response shape (preserved from the legacy contract): Search results:: { "success": True, "data": { "web": [ {"title": str, "url": str, "description": str, "position": int}, ... ] } } Extract results:: { "success": True, "data": [ {"url": str, "title": str, "content": str, "raw_content": str, "metadata": dict}, ... ] } On failure (either capability):: {"success": False, "error": str} ) annotationsN)AnyDictListceZdZdZeejddZeddZejddZ ddZ dd Z dd Z dddZ ddZddZd dZdS)!WebSearchProvideruAbstract base class for a web search/extract/crawl backend. Subclasses must implement :meth:`is_available` and at least one of :meth:`search` / :meth:`extract` / :meth:`crawl`. The :meth:`supports_search` / :meth:`supports_extract` / :meth:`supports_crawl` capability flags let the registry route each tool call to the right provider, and let multi-capability providers (Firecrawl, Tavily, Exa, …) advertise multiple capabilities from a single class. returnstrcdS)a*Stable short identifier used in ``web.search_backend`` / ``web.extract_backend`` / ``web.backend`` config keys. Lowercase, no spaces; hyphens permitted to preserve existing user-visible names. Examples: ``brave-free``, ``ddgs``, ``searxng``, ``firecrawl``. Nselfs =/home/kuhnn/.hermes/hermes-agent/agent/web_search_provider.pynamezWebSearchProvider.nameJc|jS)zEHuman-readable label shown in ``hermes tools``. Defaults to ``name``.)rr s r display_namezWebSearchProvider.display_nameUs yrboolcdS)uReturn True when this provider can service calls. Typically a cheap check (env var present, optional Python dep importable, instance URL set). Must NOT make network calls — this runs at tool-registration time and on every ``hermes tools`` paint. Nr r s r is_availablezWebSearchProvider.is_availableZrrcdS)z7Return True if this provider implements :meth:`search`.Tr r s rsupports_searchz!WebSearchProvider.supports_searchcstrcdS)uReturn True if this provider implements :meth:`extract`. Both sync and async :meth:`extract` implementations are valid — the dispatcher detects coroutine functions via :func:`inspect.iscoroutinefunction` and awaits as needed. Sync implementations that perform blocking I/O (HTTP, SDK calls) should ideally wrap in :func:`asyncio.to_thread` at the call site; small providers can keep their sync shape and let the dispatcher handle threading. Fr r s rsupports_extractz"WebSearchProvider.supports_extractgs urcdS)uReturn True if this provider implements :meth:`crawl`. Crawl differs from extract in that the agent provides a *seed URL* and the provider walks linked pages on its own — useful for documentation sites where the agent doesn't know all relevant URLs upfront. Tavily is the only built-in backend that natively crawls today; Firecrawl provides a similar capability that we don't currently surface as a tool. Providers that don't crawl should leave this as False; the dispatcher in :func:`tools.web_tools.web_crawl_tool` will fall back to its auxiliary-model summarization path. Fr r s rsupports_crawlz WebSearchProvider.supports_crawlts urquerylimitintDict[str, Any]c0t|jd)zExecute a web search. Override when :meth:`supports_search` returns True. The default raises NotImplementedError; callers should gate on :meth:`supports_search` before calling. z3 does not support search (override supports_search)NotImplementedErrorr)rrr s rsearchzWebSearchProvider.searchs$"y M M M   rurls List[str]kwargsrc 0t|jd)u$Extract content from one or more URLs. Override when :meth:`supports_extract` returns True. The default raises NotImplementedError; callers should gate on :meth:`supports_extract` before calling. Return shape: a list of result dicts matching what the legacy :func:`tools.web_tools.web_extract_tool` post-processing pipeline expects:: [ { "url": str, "title": str, "content": str, "raw_content": str, "metadata": dict, # optional "error": str, # optional, only on per-URL failure }, ... ] Implementations MAY be ``async def`` — the dispatcher detects coroutines via :func:`inspect.iscoroutinefunction` and awaits. ``kwargs`` may carry forward-compat fields (``format``, ``include_raw``, ``max_chars``) — implementations should ignore unknown keys. z5 does not support extract (override supports_extract)r$)rr'r)s rextractzWebSearchProvider.extracts$:"y O O O   rurlc 0t|jd)uaCrawl a seed URL and return results. Override when :meth:`supports_crawl` returns True. The default raises NotImplementedError; callers should gate on :meth:`supports_crawl` before calling. Return shape: ``{"results": [{"url": str, "title": str, "content": str, ...}, ...]}`` matching what :func:`tools.web_tools.web_crawl_tool` post-processing expects. Implementations MAY be ``async def``. ``kwargs`` may carry forward-compat fields (e.g. ``max_depth``, ``include_domains``) — implementations should ignore unknown keys. z1 does not support crawl (override supports_crawl)r$)rr,r)s rcrawlzWebSearchProvider.crawls$ "y K K K   rc|jddgdS)uReturn provider metadata for the ``hermes tools`` picker. Used by ``hermes_cli/tools_config.py`` to inject this provider as a row in the Web Search / Web Extract picker. Shape:: { "name": "Brave Search (Free)", "badge": "free", "tag": "No paid tier needed — uses Brave's free API.", "env_vars": [ {"key": "BRAVE_SEARCH_API_KEY", "prompt": "Brave Search API key", "url": "https://brave.com/search/api/"}, ], } Default: minimal entry derived from ``display_name``. Override to expose API key prompts, badges, and instance URL fields. )rbadgetagenv_vars)rr s rget_setup_schemaz"WebSearchProvider.get_setup_schemas"*%    rN)r r )r r)r)rr r r!r r")r'r(r)rr r)r,r r)rr r)r r")__name__ __module__ __qualname____doc__propertyabcabstractmethodrrrrrrr&r+r.r4r rrrr?s"   X X                   B    (      rr) r8 __future__rr:typingrrrABCrr rrr?s11f#""""" """"""""""^ ^ ^ ^ ^ ^ ^ ^ ^ ^ r