$*jh<dZddlmZddlZddlZddlZddlZddlZddlm Z m Z m Z ddl Z ddl mZejeZdZdZdZd Zed eZd Zd Zd1dZd2dZd3dZd3dZd2dZeZeZd1dZ d4d5dZ!d6dZ"d7d!Z#d8d#Z$d9d&Z%d:d*Z&d;d.Z'Gd/d0eZ(dS)@zISearch powered by the free Parallel Web Search MCP (https://parallel.ai).returnstrcFtdtjjS)uSMint a fresh Parallel ``session_id`` for a single tool call. Per-call rather than process-global: one process serves many unrelated chats in the gateway/batch runners, and a shared id would pool their searches into one Parallel session. The prefix is deliberately generic (no hermes attribution — telemetry policy). -)_MCP_CLIENT_NAMEuuiduuid4hexB/home/ubuntu/.hermes/hermes-agent/plugins/web/parallel/provider.py_new_session_idrLs! 3 3!1 3 33rNonec ddlm}|dddS#t$rYdSt$r!}tt |d}~wwxYw)aMTrigger lazy install of the parallel SDK if it isn't present. Mirrors the lazy-deps pattern used by the legacy implementation. Swallows benign ImportError from the lazy_deps helper itself; if the SDK is genuinely missing the subsequent ``from parallel import ...`` raises ImportError that the caller can handle. r)ensurezsearch.parallelF)promptN)tools.lazy_depsr ImportError Exceptionr ) _lazy_ensureexcs r_ensure_parallel_sdk_installedr]s$:::::: &u555555      $$$#c((###$s A AA  Arcddlm}t|dd}||Stjd}|st dt ddlm}||}||_ |S)zLazy-load + cache the sync Parallel client. Cache lives on :mod:`tools.web_tools` (as ``_parallel_client``) so unit tests that reset that name between cases keep working. rN_parallel_clientPARALLEL_API_KEYVPARALLEL_API_KEY environment variable not set. Get your API key at https://parallel.ai)Parallelapi_key) tools.web_tools web_toolsgetattrosgetenv ValueErrorrparallelr#r )_wtcachedr%r#clients r_get_sync_clientr0os "!!!!! S,d 3 3F  i*++G   6   #$$$!!!!!! Xg & & &F!C Mrcddlm}t|dd}||Stjd}|st dt ddlm}||}||_ |S)z}Lazy-load + cache the async Parallel client. Cache lives on :mod:`tools.web_tools` (as ``_async_parallel_client``). rN_async_parallel_clientr!r") AsyncParallelr$) r&r'r(r)r*r+rr,r3r2)r-r.r%r3r/s r_get_async_clientr4s "!!!!! S2D 9 9F  i*++G   6   #$$$&&&&&& ]7 + + +F!'C Mrc.ddlm}d|_d|_dS)zDrop both cached clients so tests can re-instantiate cleanly. Clears the canonical slots on :mod:`tools.web_tools` (where :func:`_get_sync_client` / :func:`_get_async_client` read/write them). rN)r&r'r r2)r-s r_reset_clients_for_testsr6s, "!!!!!C!%Crctjdd}|dks|dvrdSdS)uReturn the validated v1 search mode (default "advanced"). V1 collapses the three Beta modes into two. We accept the v1 values directly and map the legacy Beta values for back-compat with anyone who still sets ``PARALLEL_SEARCH_MODE=fast|one-shot|agentic``: - ``fast`` / ``one-shot`` → ``basic`` (lower latency) - ``agentic`` → ``advanced`` (higher quality, the v1 default) PARALLEL_SEARCH_MODEadvancedbasic>one-shotfast)r)r*lowerstrip)modes r_resolve_search_moder@sL 9+Z 8 8 > > @ @ F F H HD w$"666w :r session_id str | Noner%protocol_versionDict[str, str]cLddtd}|r||d<|r||d<|rd||d<|S)uHeaders for an MCP request. A Bearer token is attached only when we actually hold a key — the free endpoint is anonymous, and sending an empty/garbage token would make it 401 instead of serving the anonymous tier. After ``initialize`` the Streamable-HTTP spec expects the negotiated ``MCP-Protocol-Version`` on every follow-up request, so we echo it once known. zapplication/jsonz#application/json, text/event-stream)z Content-TypeAcceptz User-AgentzMcp-Session-IdzMCP-Protocol-VersionzBearer Authorization)_MCP_USER_AGENT)rAr%rCheaderss r _mcp_headersrJs`+7%G /$. !;*:&'7#6W#6#6 Nrtextc#Kd}|pd}|sdS|ds|dr? tj|}n#tj$rYdSwxYw||Ed{VdSgfd}|dD]}|d}|d r=|td d i|dkr||Ed{Vg||Ed{VdS) atYield JSON-RPC message dicts from a plain-JSON or SSE response body. Handles ``application/json`` (a single object) and ``text/event-stream`` (SSE: events separated by blank lines; an event's one-or-more ``data:`` lines concatenate into a single JSON payload). Unparseable chunks and non-``data`` SSE fields (``event:``/``id:``/comments) are skipped. c3XKt|tr |Ed{VdS||VdSdSN) isinstancelist)payloads r_emitz!_iter_mcp_messages.._emitsS gt $ $            MMMMM! rN{[csdS tjdS#tj$rYdSwxYw)N )jsonloadsjoinJSONDecodeError) data_linessr_flushz"_iter_mcp_messages.._flush sV 4 :dii 3344 4#   44 s&.AArW zdata:) r> startswithrXrYr[splitrstripappendlenlstrip)rKrRbodyparsedr]rawliner\s @r_iter_mcp_messagesris JB    D  sts33 Z%%FF#    FF 5==       Jzz$zz$ ??7 # #    d3w<<==188:: ; ; ; ; ZZ\\R  uVVXX & & & & & & &JuVVXXs A!!A43A4 request_idDict[str, Any]ci}t|D]?}t|trd|vsd|vs |d|kr|cS|}@|S)avSelect the JSON-RPC response for *request_id* from an MCP response body. Streamable-HTTP servers may emit progress/log notifications before the final result, so we scan the whole stream and return the result/error message whose ``id`` matches our request. Falls back to the last result/error-bearing message if no id matches; ``{}`` if none is present. resulterrorid)rirOdictget)rKrjfallbackmsgs r_mcp_response_envelopertso "H!$''#t$$ X__3  774==J & &JJJ Orenvelopecd|vr-tdt|ddd|dpi}|dr'tdt|dd|d}t|tr|S|d gpgD]}t|trl|d d krSt|d pd }|sW t j|cS#t j$rYwxYwtd t|dd)a Extract the tool result payload from a ``tools/call`` envelope. Prefers ``structuredContent`` (authoritative machine-readable form); otherwise scans text blocks for the first JSON-parseable one. Raises on a JSON-RPC error or a tool-level ``isError``. rnzParallel MCP error: NirmisErrorzParallel MCP tool error: structuredContentcontenttyperKrSz,Parallel MCP returned no parseable content: ) RuntimeErrorr rqrOrprXrYr[)rurm structuredblockrKs r _mcp_payloadr~.s(P#hw6G2H2H#2NPPQQQ \\( # # )rF zz)LJs6{{4C47HJJKKK/00J*d##Ir**0b eT " " uyy'8'8F'B'Buyy((.B//D  z$''''''     Js6{{4C47HJJ  s!D77E E  tool_name argumentsc tjt5}tt j}|ttd|d|dtittddd}| |j d }t|j|}|d pid pt}|tt|||dd d tt j} |tt|||d| d||dd} | t#t| j| cdddS#1swxYwYdS)u<Run the MCP handshake then a single ``tools/call`` and return its payload. initialize → (capture ``Mcp-Session-Id``) → notifications/initialized → tools/call ``tool_name``. Returns the parsed tool payload dict (see :func:`_mcp_payload`). A Bearer token is attached only when *api_key* is set. )timeoutNz2.0 initialize)nameversion)protocolVersion capabilities clientInfo)jsonrpcromethodparams)rIrXzmcp-session-idrmrznotifications/initialized)rrz tools/call)rr)httpxClient_MCP_TIMEOUT_SECONDSr rrpost_MCP_SEARCH_URLrJ_MCP_PROTOCOL_VERSIONr _MCP_CLIENT_VERSIONraise_for_statusrIrqrtrKr~) rrr%r/init_idinitmcp_session_idinit_envnegotiated_versioncall_idcalls r _mcp_callrMs0 2 3 3 38Hvdjll##{{  w// &'<$& 0#6##    " ))*:;;)$)W==\\( # # )r . ./@ A A %$    :LMM".IJJ    djll##{{  :LMM &#,9EE     249gFFGGq8H8H8H8H8H8H8H8H8H8H8H8H8H8H8H8H8H8HsFF;;F?F?querylimitintctd||gtd|}g}t|dpgdt |dD]\}}t |t s|dpg}||dpd|d pd|rd |nd|dzd d d |idtdS)aNRun a ``web_search`` tool call against the hosted Search MCP. Returns the standard provider search shape (``{"success": True, "data": {"web": [...]}}``). The MCP serves a fixed result count, so ``limit`` is applied client-side. The MCP requires ``objective`` (REST treats it as optional), so we mirror the query. web_search) objectivesearch_queriesrAresultsNexcerptsurlrStitle rr descriptionpositionTwebr,)successdataprovider attribution) rr enumeraterqmaxrOrprbrZ_FREE_MCP_ATTRIBUTION)rrr%rQ web_resultsirmrs r_mcp_web_searchrs6$g)++  G)+K I 6 6 <"oE1 oNOO   6&$''  ::j))/Rzz%((.BG,,25=Esxx1112E        $,   rurls List[str]List[Dict[str, Any]]c tdt|dtd|}i}|dpgD]H}t |t r1|dr||d|Ig}|D]}||}|||dddd |id 7|d pd}|d p)d |dpg}|||||||dd|S)uRun a ``web_fetch`` tool call against the hosted Search MCP. Returns the per-URL extract shape that :func:`tools.web_tools.web_extract_tool` expects — exactly one row per input URL, in request order (including duplicates). We pass ``full_content=True`` so the page body comes back as markdown (matching the keyed SDK path and what extract callers/summarizers expect), falling back to excerpts only when full content is absent. Any input the MCP didn't return is emitted as a per-URL error row. web_fetchT)r full_contentrArrNrSz'extraction failed (no content returned) sourceURLrrryrnmetadatarr rrrrrry raw_contentr) rrPrrqrOrp setdefaultrbrZ) rr%rQby_urlitemrrrrys r_mcp_web_fetchrsdTARARSSG)+F I&&,"11 dD ! ! 1dhhuoo 1   d5k4 0 0 0$&G  zz# < NN!F!,c 2     !!'R((>**Ufkk$((::N:N:TRT.U.U"&*->>        NrcteZdZdZeddZeddZddZddZdd Z dddZ ddZ ddZ dS)ParallelWebSearchProviderz,Parallel.ai search + async extract provider.r r cdS)Nr,rselfs rrzParallelWebSearchProvider.namezrcdS)Nr#rrs r display_namez&ParallelWebSearchProvider.display_namerrboolcjttjddS)aReturn True when ``PARALLEL_API_KEY`` is set. Deliberately key-based: this gates the registry's active-provider walk and the ``hermes tools`` picker (auto-selecting Parallel for a user who hasn't named it), so it must not claim availability on the keyless path. The keyless free-MCP path is reached independently via :func:`tools.web_tools._get_backend`'s ``parallel`` terminal default. r!rS)rr)r*r>rs r is_availablez&ParallelWebSearchProvider.is_availables+BI0"55;;==>>>rcdSNTrrs rsupports_searchz)ParallelWebSearchProvider.supports_searchtrcdSrrrs rsupports_extractz*ParallelWebSearchProvider.supports_extract rrrrrrkc  ddlm}|rdddStjdd}|s.t d||t||d St}t d |||t |g||td tt|d di}g}t|jpgd t|d D]P\}} | jpg} || jpd| jpd| rd| nd|d zdQdd|idS#t*$r} dt-| dcYd } ~ Sd } ~ wt.$r} dd| dcYd } ~ Sd } ~ wt0$r-} t d| dd| dcYd } ~ Sd } ~ wwxYw)aExecute a Parallel search (sync). With ``PARALLEL_API_KEY`` set, uses the v1 ``search`` REST endpoint with the configured mode (``PARALLEL_SEARCH_MODE`` env var, default "advanced"; limit requested via advanced_settings.max_results, capped at 20). Without a key, falls back to the free hosted Search MCP so search still works with zero setup. ris_interruptedF Interrupted)rrnr!rSz+Parallel search (free MCP): '%s' (limit=%d)Nr$z3Parallel search (v1 REST): '%s' (mode=%s, limit=%d) max_resultsr)rrr?rAadvanced_settingsrrTr)rrParallel SDK not installed: zParallel search error: %szParallel search failed: )tools.interruptrr)r*r>loggerinforr@r0searchrminrrrrrbrrrZr+r rrwarning) rrrrr%r?responserrrmrrs rrz ParallelWebSearchProvider.searchs5 Q 6 6 6 6 6 6~ B#(=AAAi 2B77==??G C A5%'ueTBBBB'))D KKEtU   ())00 %w*,,#0#c%mmR2H2H"I 1HK&(8(>B#eQ--'PQQ   6!?0b""%z/R!'!3=E'Msxx'9'9'92$%E  $e[-ABB B 9 9 9$s3xx88 8 8 8 8 8 8    ===       Q Q Q NN6 < < <$/O#/O/OPP P P P P P P QsNE0AE0.DE00 G%:F G% G%F+%G%+ G%8"G G% G%rrkwargsrrc K ddlm}|r d|DStjdd}|sVt dt|tj tt|dd{VSt dt|t |d d it d{V}g}|jpgD]Y}|jpd}|sd |jpg}|jpd} |jpd} || | ||| | d dZ|jpgD]g} t/| ddpd} t/| ddp#t/| ddpt/| ddpd} || dd| d| idh|S#t0$rfd|DcYdSdwt2$rfd|DcYdSdwt4$r3t dfd|DcYdSdwwxYw)uQExtract content from one or more URLs. With ``PARALLEL_API_KEY`` set, uses the async SDK's v1 ``extract`` for full page content. Without a key, falls back to the free hosted Search MCP's ``web_fetch`` tool so extraction works with zero setup, mirroring the keyless search path. Returns the legacy list-of-results shape that :func:`tools.web_tools.web_extract_tool` expects: one entry per successful URL plus one entry per failed URL with an ``error`` field. Errors are not raised — they're returned as per-URL items. rrcg|]}|ddd S)rrS)rrnrr).0us r z5ParallelWebSearchProvider.extract..as/HIA CCrr!rSz0Parallel extract (free MCP web_fetch): %d URL(s)Nz%Parallel extract (v1 REST): %d URL(s)rT)rrrArrrrmessagery error_typezextraction failedrrc8g|]}|ddtdS)rSrrryrn)r rrrs rrz5ParallelWebSearchProvider.extract..s,\\\RSArCHHMM\\\rc$g|] }|dddd S)rSrrrrs rrz5ParallelWebSearchProvider.extract..s?B2@d_b@d@deerzParallel extract error: %sc$g|] }|dddd S)rSzParallel extract failed: rrrs rrz5ParallelWebSearchProvider.extract..s?B2@a\_@a@abbr)rrr)r*r>rrrcasyncio to_threadrrPr4extractrrrrZrrrrberrorsr(r+rrr)rrrrr%rrrmryrrrnerr_urlerr_msgrs @rrz!ParallelWebSearchProvider.extractNsI  6 6 6 6 6 6~ MQi 2B77==??G Q FD %.~tDzz4PPPPPPPPP KK?T K K K/0088#14"8*,,9H -/G"*0b   -3A$kk&/*?R@@Gj&B *"!&#*'.25$F$F ".B  !%339rE9d33+ui66+ulD99++  &!##%!(%0'$: N ] ] ]\\\\W[\\\ \ \ \ \ \ \             NN7 = = =       sNGA>G D7G I" G5/I5 I HI I"(I IIcdddddddgdS) Nr#freeuFree web search + extraction via Parallel's hosted Search MCP — no key needed. Add PARALLEL_API_KEY for the v1 REST Search API (richer modes, higher limits).r!u>Parallel API key (optional — unlocks the v1 REST Search API)zhttps://parallel.ai)keyrr)rbadgetagenv_varsrrs rget_setup_schemaz*ParallelWebSearchProvider.get_setup_schemas65 .^0   rNr r )r r)r)rr rrr rk)rrrrr r)r rk) __name__ __module__ __qualname____doc__propertyrrrrrrrrrrrrrs66 XX ? ? ? ?>Q>Q>Q>Q>Q@XXXXt      rrr)r r)r rrN)rArBr%rBrCrBr rD)rKr )rKr rjr r rk)rurkr rk)rr rrkr%rBr rk)rr rrr%rBr rk)rrr%rBr r))r __future__rrrXloggingr)rtypingrrrragent.web_search_providerr getLoggerrrrrr rrHrrrrr0r4r6_get_parallel_client_get_async_parallel_clientr@rJrirtr~rrrrrrrrsC$$L#"""""  """""""""" 777777  8 $ $3$ $%==(;== P 4444"$$$$$64 & & & &(.>$(6,,,,^$>AHAHAHAHH''''T4444nF F F F F 1F F F F F r