sj%?DUdZddlmZddlZddlZddlmZmZmZddl m Z ddl m Z ej eZiZded<iZd ed <ejZdd d-dZdd d.dZdd d/dZdd d/dZdd d0dZd1dZd Zd!Zd2d#Zd3d&Zd4d'Zd5dd(d6d)Z d7d*Z!d7d+Z"d8d,Z#dS)9u. 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`` (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``) 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)WebSearchProvider)hermes_home_keyzDict[str, WebSearchProvider] _providersz'Dict[str, Dict[str, WebSearchProvider]]_scoped_providers)scopeproviderrr Optional[str]returnNonect|ts$tdt|j|j}t|t r|std|}t5|tnt |i}| |}|||<dddn #1swxYwY|0td|t|jdStd|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_lockr r setdefaultgetloggerdebug)r r raw_namertargetexistings =/home/agent/.hermes/hermes-agent/agent/web_search_registry.pyregister_providerr"2s h 1 2 2  ->>* - -   }H h $ $JHNN,<,<JHIII >>  D   $}2C2N2NuVX2Y2Y::d##t                 6 $x..)      / $x..)     s?CC#&C#List[WebSearchProvider]cFt5tt}|t|p t it|}dddn #1swxYwYt|dS)z0Return all registered providers, sorted by name.Nc|jSN)r)ps r!z list_providers..Xsqv)key) rdictr updater rrlistvaluessorted)r mergeditemss r!list_providersr2Rs &&j!! '++E,F_5F5FKKLLLV]]__%%&&&&&&&&&&&&&&& %-- . . ..sA2BB  B rrOptional[WebSearchProvider]cFt|tsdSt5|}t|p t i|pt|cdddS#1swxYwYdS)z5Return the provider registered under *name*, or None.N)rrrrr rrr )rr r*s r! get_providerr5[s dC t eejjll $$U%?o.?.?DDHHMMdQ[Q_Q_`cQdQdeeeeeeeeeeeeeeeeeesA*BBBct5|tnt|i}||cdddS#1swxYwYdSr&)rr r rr)rr rs r!snapshot_registrationr7ds (($}2C2G2Gr2R2Rzz$**,,''((((((((((((((((((sA A  A$'A$currentpreviousboolcx|}t5|tnt|i}|||ur ddddS|||dn|||<||st|ddddn #1swxYwYdS)zERestore a plugin registration only when *current* is still installed.NFT)rrr r rrpop)rr8r9r r*rs r!restore_registrationr=ls **,,C  / /$}2C2N2NuVX2Y2Y ::c??' ) ) / / / / / / / /   JJsD ! ! ! !"F3K  V   ! !% . . . / / / / / / / / / / / / / / / 4s=B/&=B//B36B3pathc 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_config_readonlyNzCould not read config %s: %s.) hermes_cli.configr@rr+rrr Exceptionrrjoin)r>r@cfgcursegmentexcs r!_read_config_keyrIs J::::::""$$ # #Gc4(( tt'''""CC c3   CIIKK 99;;  JJJ 3SXXd^^SIIIIIIIIJ 4s,BAB C/CC) firecrawlparalleltavilyexasearxngz brave-freeddgs)rMrKrLrJkeenabletuplec ddlmm}|tzt fdt tDS#t $r%}td|Yd}~nd}~wwxYwtS)aReturn the keyless walk order for resolution. Delegates the entry-vendor choice to the ring cursor in :mod:`plugins.web.keyless_mcp` (round-robin per request, seeded by the per-process random session id) so resolution and dispatch agree on which vendor a fresh install starts at. The remaining vendors follow in ring order as fallbacks for registration gaps. r) _KEYLESS_RING _ring_cursorc3NK|]}|ztzV dSr&)len).0irSstarts r! z&_keyless_preference..sM   519M(:(:: ;      r)z"keyless ring order unavailable: %sN) plugins.web.keyless_mcprSrTrVrQrangerCrr_KEYLESS_PREFERENCE)rTrHrSrYs @@r!_keyless_preferencer^s @GGGGGGGGs=111     3}--..       @@@ 93????????@ sAA BA>>B configured capabilityc t5tt}|tt idddn #1swxYwYdfd dd |r^||}| |r|S|td|ntd | fd | D}t|d kr|d StD]3}||}||r |r|cS4trtD]q}||}| |s% |r|cS?#t$r&}td ||Yd}~jd}~wwxYwdS)uResolve the active provider for a capability ("search" | "extract"). 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'rrr:cdkr!t|Sdkr!t|SdS)NsearchextractF)r:supports_searchsupports_extract)r'r`s r!_capablez_resolve.._capablesR  ! !))++,, ,  " "**,,-- -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)r: is_availablerCrrr)r'rHs r!_is_available_safez$_resolve.._is_available_safesd (()) )    LL? M M M55555 s # A!AAzz_resolve..sJ 8A;;--a00 r)rz,provider %s.is_keyless_available() raised %s)r'rrr:)rr+r r,r rrrrr.rV_LEGACY_PREFERENCE_keyless_tier_enabledr^is_keyless_availablerC) r_r`snapshotr eligiblelegacyrrHrgrjs ` @@r!_resolverus< FF ##)--o.?.?DDEEEFFFFFFFFFFFFFFF << ++  HHX$6$6 O   LLN     LLUJ   ??$$H 8}}{$<<''  "" !""8,, !OOO '))  D||D))Hxx'9'9 0022$#OOO$    BD#  4s*AA&&A*-A*F-- G7GGc ddlm}|dpi}t|ddS#t$r&}t d|Yd}~dSd}~wwxYw)zBRead ``web.keyless_fallback`` from config.yaml (default: enabled).r) load_configwebkeyless_fallbackTz'keyless_fallback config read failed: %sN)rBrwrr:rCrr)rwweb_cfgrHs r!rprp<s111111+--##E**0bGKK 2D99:::  >DDDtttttsAA A:A55A:r`c dd}|s'|dvr#td|dptdd}|sd S||} d d lm}|}|jD]s\}}t |t r|d s0|jr8|j d krD| ddd}|||kr|cStn2#t$r%} t d| Yd } ~ nd } ~ wwxYwd S)uReturn the plugin key of a *disabled* bundled web plugin that would have provided the configured backend, or None. When a user sets ``web.extract_backend: firecrawl`` (or the search equivalent) but also lists ``web-firecrawl`` in ``plugins.disabled``, the provider never registers and the dispatcher would otherwise emit a misleading "No web extract provider configured. Set web.extract_backend to ..." error — even though the backend IS configured correctly. The real fix is to re-enable the plugin. This helper detects that case so the dispatcher can point the user at the actual cause (issue #40190 follow-up: pi314's disabled-plugin symptom). Pass ``capability`` ("search" | "extract") to resolve the configured name straight from ``config.yaml`` (``web._backend`` → ``web.backend``). This is more reliable than the resolved backend the dispatcher fell back to, since a disabled provider fails the ``_is_backend_available`` gate and the dispatcher silently drops to the shared default. An explicit ``configured`` name still wins when given. Matching is by convention: bundled web plugins live under the ``web/`` key with the provider ``name`` differing only in hyphen/underscore (``brave-free`` provider ⇄ ``web/brave_free`` key, ``firecrawl`` ⇄ ``web/firecrawl``). We normalize both sides before comparing so every bundled provider is covered without hardcoding a per-vendor table. srrcv|ddS)N-_)rlowerreplace)r}s r!_normz'_disabled_web_plugin_for.._normds*wwyy  ((c222r))rcrdrx_backendbackendNr)get_plugin_managerzweb/zdisabled via config/rnz%disabled-web-plugin lookup failed: %s)r}rrr)rIhermes_cli.pluginsr_pluginsr1rr startswithenablederrorsplitrCrr) r_r`rwantrpmr*loadedvendorrHs r!_disabled_web_plugin_forrHs83333  *(=== Uz$;$;$; < < 2y11  t 5  DC999999   ! !;,,..  KCc3'' s~~f/E/E ~ |444YYsA&&q)FuV}}$$ %  CCC rrr )rrQ)r_r r`rrr3)rr:r&)r_r r`r rr )rr3)rr)$__doc__ __future__rlogging threadingtypingrrragent.web_search_providerrhermes_constantsr getLoggerrrr __annotations__r Lockrr"r2r5r7r=rIror]r^rurprrrrrlr)r!rsP@#"""""''''''''''777777,,,,,,  8 $ $,. ----=????? NR      @.2//////7;eeeeee*.(((((( 60$,iiiiX    8^b888888v33334444""""""r)