jOL dZddlmZddlZddlZddlZddlmZmZmZddl m Z m Z m Z m Z mZddlZddlmZmZddlmZmZejeZdZd Zd Zd Zd ZdMdZdNdZdOdZ dOdZ!dPdZ"dQdZ#dRdZ$dSd Z%dTd$Z&dUd&Z'dVd(Z(dWd+Z) dXdYd3Z*d4d5d6d7d8d9d:d;d7idd=d7d?d9d7d@d9dAdBd-dCdAdDd-dCdEd.gdFdGZ+dHZ,ej-d4d4e+e,e#dIgdJdKLdS)ZuX Search tool backed by xAI's built-in ``x_search`` Responses API tool. Authentication -------------- The tool registers when **either** xAI credential path is available: * ``XAI_API_KEY`` is set in ``~/.hermes/.env`` or the process environment (paid xAI API key), OR * The user is signed in via xAI Grok OAuth — SuperGrok subscription — i.e. ``hermes auth add xai-oauth`` has been run and the stored refresh token still works. Credential preference at call time matches :func:`tools.xai_http.resolve_xai_http_credentials`: SuperGrok OAuth first, direct OAuth resolver second, ``XAI_API_KEY`` last. That helper also auto-refreshes the OAuth access token when it's within the refresh skew window, so a ``True`` from :func:`check_x_search_requirements` means the bearer is fetchable AND non-empty. Defensive output ---------------- The tool surfaces two additional signals beyond xAI's raw response so callers can tell a real citation-backed answer from an unsourced one: * ``from_date`` / ``to_date`` are validated client-side before the HTTP call. Malformed (non ``YYYY-MM-DD``), inverted (``from_date > to_date``), and pure-future ranges (``from_date`` later than today UTC) fail fast with a clear error instead of burning an API call. ``to_date`` in the future is still allowed so callers can legitimately request "from yesterday to tomorrow". * Successful responses carry ``degraded`` and ``degraded_reason`` fields. ``degraded`` is ``True`` when any narrowing filter (handles or dates) was active AND xAI returned no citations in either the top-level ``citations`` array or the inline ``url_citation`` annotations. In that case the ``answer`` came from the model's own knowledge rather than the X index, and the caller should treat the result as unsourced. Salvaged from PR #10786 (originally by @Jaaneek); credential resolution reworked to honor both auth modes per Teknium's design. ) annotationsN)datedatetimetimezone)AnyDictListOptionalTuple)registry tool_error)hermes_xai_user_agentresolve_xai_http_credentialszhttps://api.x.ai/v1zgrok-4.20-reasoning returnDict[str, Any]ct ddlm}|dipiS#t$ricYSwxYw)Nr load_configx_search)hermes_cli.configrget Exceptionrs 8/home/ubuntu/.hermes/hermes-agent/tools/x_search_tool.py_load_x_search_configrEs^111111{}}  R006B6  s %( 77strct}t|dpdptS)Nmodel)rrrstripDEFAULT_X_SEARCH_MODEL)cfgs r_get_x_search_modelr%Ns>  ! !C   &B ' ' - - / / I3IJintct}|dt} tdt |S#t $r tcYSwxYw)Ntimeout_seconds)rr DEFAULT_X_SEARCH_TIMEOUT_SECONDSmaxr'rr$ raw_values r_get_x_search_timeout_secondsr/Ssd  ! !C)+KLLI02s9~~&&& 000////0AAAct}|dt} tdt |S#t $r tcYSwxYw)Nretriesr)rrDEFAULT_X_SEARCH_RETRIESr,r'rr-s r_get_x_search_retriesr4\sc  ! !C #;<%i== }}8#GY77  y [9%<%< 1+//11 1 1!++-- 1 1 1   L..3355  " ",k3355,,&&((,,,  " "r&payloadc4t|dpd}|r|Sg}|dgpgD]}|ddkr|dgpgD]h}|d}|dvrMt|dpd}|r||id |S) N output_textr!outputtypemessagecontent>textrhrmz )rrr"rLjoin)rfrhpartsitemrlctyperms r_extract_response_textrrs$gkk-006B77==??KE Hb))/R'' 88F  y ( ( xx 2..4" ' 'GKK''E///7;;v..4"55;;=='LL&&&  ' ;;u   # # % %%r&List[Dict[str, Any]]c g}|dgpgD]}|ddkr|dgpgD]}|dgpgD]}|ddkr||dd|d d|d |d d |S) Nrirjrkrlr url_citationurlr!title start_index end_index)rvrwrxry)rrL)rf citationsrprl annotations r_extract_inline_citationsr|s&(I Hb))/R 88F  y ( ( xx 2..4"  G%kk-<<B   >>&))^;;  )~~eR88!+!R  Qdii6O6O Q Q Q  z!%+" ) &$4$#2            *A ===z !",Q//"1gg.              -q4 @@@z !"b9V9X9Xbbb"1gg.             *A ===z !"Q"1gg.         s: A*A%A*%A*.2Q,"B32Q,3 C#=CC#Q,C##CQ,:AG?<Q,?LBJQ,L8AL Q,LEQ,,V9;ASV9V9*AU V9 V9AV4.V94V9rzSearch X (Twitter) posts, profiles, and threads using xAI's built-in X Search tool. Use this for current discussion, reactions, or claims on X rather than general web pages. Available when xAI credentials are configured (SuperGrok OAuth or XAI_API_KEY).objectstringzWhat to look up on X.)rj descriptionarrayrjz;Optional list of X handles to include exclusively (max 10).)rjitemsrz/Optional list of X handles to exclude (max 10).z)Optional start date in YYYY-MM-DD format.z'Optional end date in YYYY-MM-DD format.booleanz?Whether xAI should analyze images attached to matching X posts.)rjrdefaultz?Whether xAI should analyze videos attached to matching X posts.rrrr[r\rr)rj propertiesrequired)namer parametersc vt|dd|d|d|dd|ddt|ddt|d d S) Nrr!rrr[r\rFrr)rrrB)argskws r_handle_x_searchrs hhw##((#67788$899((;++B''#'1Mu(U(U#V#V#'1Mu(U(U#V#V   r& XAI_API_KEYu🐦i)rtoolsetschemahandlercheck_fn requires_envemojimax_result_size_chars)rr)rr)rr')rr5)rrB)rErFrGrrrH)rTrrGrrr)r[rr\rrr])rfrrr)rfrrrs)rYr}rr)NNr!r!FF)rrrrFrrFr[rr\rrrBrrBrr).__doc__ __future__rrloggingrrrrtypingrrr r r rtools.registryr r tools.xai_httprr getLoggerrrr=r#r+r3rNrr%r/r4rArDrSrZrerrr|rrX_SEARCH_SCHEMArregisterr&rrs5''R#"""""  ----------33333333333333////////NNNNNNNN  8 $ $,.#&  KKKK 0000((((%%%%,    &&@&&&&$(<.2.2',',r r r r r l  ; !6   (+\""   (+P## !J !H "` ++ "` ++9! ! DII%%..b        ( !      r&