PL j&UdZddlmZddlZddlZddlmZmZmZddl m Z ej e Z iZded<ejZdd ZddZd dZd!dZdZd"dZd#dZd#dZd#dZd$dZdS)%u[ Web Search Provider Registry ============================ Central map of registered web providers. Populated by plugins at import-time via :meth:`PluginContext.register_web_search_provider`; consumed by the ``web_search`` and ``web_extract`` tool wrappers in :mod:`tools.web_tools` to dispatch each call to the active backend. Active selection ---------------- The active provider is chosen by configuration with this precedence: 1. ``web.search_backend`` / ``web.extract_backend`` / ``web.crawl_backend`` (per-capability override). 2. ``web.backend`` (shared fallback). 3. If exactly one capability-eligible provider is registered AND available, use it. 4. Legacy preference order — ``firecrawl`` → ``parallel`` → ``tavily`` → ``exa`` → ``searxng`` → ``brave-free`` → ``ddgs`` — filtered by availability. Matches the historic ``tools.web_tools._get_backend()`` candidate order so installs that never set a config key keep landing on the same provider they did before the plugin migration. 5. Otherwise ``None`` — the tool surfaces a helpful error pointing at ``hermes tools``. The capability filter (``supports_search`` / ``supports_extract`` / ``supports_crawl``) is applied at every step so a search-only provider (``brave-free``) configured as ``web.extract_backend`` correctly falls through to an extract-capable backend. ) annotationsN)DictListOptional)WebSearchProviderzDict[str, WebSearchProvider] _providersproviderrreturnNonec<t|ts$tdt|j|j}t|t r|stdt5t |}|t|<dddn #1swxYwY|0t d|t|jdSt d|t|jdS)uRegister a web search/extract provider. Re-registration (same ``name``) overwrites the previous entry and logs a debug message — makes hot-reload scenarios (tests, dev loops) behave predictably. z>register_provider() expects a WebSearchProvider instance, got z-Web provider .name must be a non-empty stringNz(Web provider '%s' re-registered (was %r)z!Registered web provider '%s' (%s)) isinstancer TypeErrortype__name__namestrstrip ValueError_lockrgetloggerdebug)r rexistings =/home/kuhnn/.hermes/hermes-agent/agent/web_search_registry.pyregister_providerr0sa h 1 2 2  ->>* - -    =D dC J JHIII $$>>$''# 4$$$$$$$$$$$$$$$ 6 $x..)      / $x..)     s%B11B58B5List[WebSearchProvider]ct5tt}dddn #1swxYwYt |dS)z0Return all registered providers, sorted by name.Nc|jS)Nr)ps rz list_providers..Rsqv)key)rlistrvaluessorted)itemss rlist_providersr(Ns **Z&&(())*************** %-- . . ..s ';??rrOptional[WebSearchProvider]ct|tsdSt5t|cdddS#1swxYwYdS)z5Return the provider registered under *name*, or None.N)r rrrrrrs r get_providerr+Us dC t ,,~~djjll++,,,,,,,,,,,,,,,,,,s,AAApath Optional[str]c ddlm}|}|}|D]/}t|tsdS||}0t|t r(|r|SnF#t$r9}t dd ||Yd}~nd}~wwxYwdS)zGResolve a dotted config key from ``config.yaml``. Returns None on miss.r) load_configNzCould not read config %s: %s.) hermes_cli.configr/r dictrrr Exceptionrrjoin)r,r/cfgcursegmentexcs r_read_config_keyr9bs J111111kmm # #Gc4(( tt'''""CC c3   CIIKK 99;;  JJJ 3SXXd^^SIIIIIIIIJ 4s,BAB C/CC) firecrawlparalleltavilyexasearxngz brave-freeddgs configured capabilityc4t5tt}dddn #1swxYwYd fd d d|r^||}| |r|S|td|ntd |fd |D}t|d kr|d StD]3}||}||r|r|cS4dS)u%Resolve the active provider for a capability ("search" | "extract" | "crawl"). Resolution rules (in order): 1. **Explicit config wins, ignoring availability.** If ``web.{capability}_backend`` or ``web.backend`` names a registered provider that supports *capability*, return it even if its :meth:`is_available` returns False — the dispatcher will surface a precise "X_API_KEY is not set" error to the user instead of silently routing somewhere else. Matches legacy :func:`tools.web_tools._get_backend` behavior for configured names. 2. **Single-provider shortcut.** When only one registered provider supports *capability* AND ``is_available()`` reports True, return it. 3. **Legacy preference walk, filtered by availability.** Walk the :data:`_LEGACY_PREFERENCE` order (firecrawl → parallel → tavily → exa → searxng → brave-free → ddgs) looking for a provider whose ``supports_()`` is True AND whose ``is_available()`` is True. Matches the historic ``tools.web_tools._get_backend()`` candidate order so users with credentials but no explicit config key keep landing on the same provider as pre-migration. This is the path that fires when no config key is set — pick the highest-priority backend the user actually has credentials for. Returns None when no provider is configured AND no available provider matches the legacy preference; the dispatcher then returns a "set up a provider" error to the user. Nr rr boolcdkr!t|Sdkr!t|Sdkr!t|SdS)NsearchextractcrawlF)rCsupports_searchsupports_extractsupports_crawl)r rAs r_capablez_resolve.._capablesw  ! !))++,, ,  " "**,,-- -  ((**++ +ur"c t|S#t$r,}td|j|Yd}~dSd}~wwxYw)zDWrap ``is_available()`` so a buggy provider doesn't kill resolution.z$provider %s.is_available() raised %sNF)rC is_availabler3rrr)r r8s r_is_available_safez$_resolve.._is_available_safesd (()) )    LL? M M M55555 s # A!AAzz_resolve..sJ 8A;;--a00 r"r)r rr rC) rr2rrrrr%len_LEGACY_PREFERENCE)r@rAsnapshotr eligiblelegacyrKrNs ` @@r_resolverYs< $$ ##$$$$$$$$$$$$$$$ << ++  HHX$6$6 O   LLN     LLUJ   ??$$H 8}}{$<<''  "" !""8,, !OOO 4s ,00cdtddptdd}t|dS)zResolve the currently-active web search provider. Reads ``web.search_backend`` (preferred) or ``web.backend`` (shared fallback) from config.yaml; falls back per the module docstring. websearch_backendbackendrErAr9rYexplicits rget_active_search_providerrbs8  '788^rusm@#"""""''''''''''777777  8 $ $,. ----     <////,,,,0XXXXv33334444 2 2 2 2r"