nSj-ldZddlmZddlZddlZddlmZmZmZm Z d dZ Gd d ej Z 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)AnyDictListOptionalnamestrreturncd} ddlm}||}n#t$rd}YnwxYw|tj|d}|pdS)u:Config-aware env lookup for web providers. Resolves *name* via :func:`hermes_cli.config.get_env_value` (checks ``os.environ`` first, then ``~/.hermes/.env``) so credentials set through Hermes' config layer are visible even when they were never exported into the process environment — gateway sessions, delegate children, and subprocess agent runs (issue #40190). Falls back to a bare ``os.getenv`` when the config module is unavailable (stripped installs, early import contexts). Returns the stripped value, or ``""`` when unset. Nr) get_env_value)hermes_cli.configr Exceptionosgetenvstrip)rvalr s ;/home/ice/.hermes/hermes-agent/agent/web_search_provider.pyget_provider_envr;sC333333mD!!  {ib!! I2    s  %%ceZdZdZeejddZeddZejddZ ddZ dd Z dddZ ddZ ddZdS)WebSearchProvideruAbstract base class for a web search/extract backend. Subclasses must implement :meth:`is_available` and at least one of :meth:`search` / :meth:`extract`. The :meth:`supports_search` / :meth:`supports_extract` 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. r r cdS)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 rrzWebSearchProvider.namedc|jS)zEHuman-readable label shown in ``hermes tools``. Defaults to ``name``.)rrs r display_namezWebSearchProvider.display_nameos 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. Nrrs r is_availablezWebSearchProvider.is_availabletrrcdS)z7Return True if this provider implements :meth:`search`.Trrs rsupports_searchz!WebSearchProvider.supports_search}strcdS)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. Frrs rsupports_extractz"WebSearchProvider.supports_extracts 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)rr(r)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-)rr0r2s rextractzWebSearchProvider.extracts$:"y O O O   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. r )rbadgetagenv_vars)rrs rget_setup_schemaz"WebSearchProvider.get_setup_schemas"*%    rN)r r )r r )r')r(r r)r*r r+)r0r1r2rr r)r r+)__name__ __module__ __qualname____doc__propertyabcabstractmethodrrr"r$r&r/r4r9rrrrrYs   X X                   B      rr)rr r r ) r= __future__rr?rtypingrrrrrABCrrrrrDs11f#""""" ,,,,,,,,,,,,