߲jHndZddlmZddlZddlZddlmZmZmZddl m Z d dZ Gdde Z dd lm Z y) ayWeb 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} ) annotationsN)AnyDictList) ProviderBasec ddlm}||}|tj|d}|xsdj S#t$rd}Y9wxYw)awConfig-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. r) get_env_valueN)hermes_cli.configr Exceptionosgetenvstrip)namer vals >/home/ubuntu/.hermes/hermes-agent/agent/web_search_provider.pyget_provider_envrsT3D! {iib! I2    s< A  A c`eZdZdZej d dZd dZd dZd dZ d d dZ d dZ y) WebSearchProviderzAbstract 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.cy)uTrue 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.Nselfs r is_availablezWebSearchProvider.is_available/scy)z0True if this provider implements :meth:`search`.Trrs rsupports_searchz!WebSearchProvider.supports_search4srcy)a`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.Frrs ris_keyless_availablez&WebSearchProvider.is_keyless_available8s rcy)uTrue if this provider implements :meth:`extract` (sync or ``async def`` — the dispatcher awaits coroutine functions).Frrs rsupports_extractz"WebSearchProvider.supports_extract?src2t|jd)z>Execute a web search. Callers gate on :meth:`supports_search`.z3 does not support search (override supports_search)NotImplementedErrorr)rquerylimits rsearchzWebSearchProvider.searchDs!yykL M  rc 2t|jd)a-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``).z5 does not support extract (override supports_extract)r#)rurlskwargss rextractzWebSearchProvider.extractJs "yykN O  rN)returnbool))r%strr&intr,zDict[str, Any])r)z List[str]r*rr,r) __name__ __module__ __qualname____doc__abcabstractmethodrrrr!r'r+rrrrr+s=m mm   rr)Optional)rr/r,r/)r4 __future__rr5r typingrrragent.provider_baserrrr7rrrr;s5 # "",&% % Xr