.cjyP dZddlmZddlZddlZddlZddlmZmZmZddl m Z m Z m Z m Z mZddlZddlmZmZddlmZmZejeZdZd Zd Zd Zd Zd ZdPdZdQdZ dRdZ!dSdZ"dSdZ#dTdZ$dUdZ%dVd Z&dWd#Z'dXd'Z(dYd)Z)dZd+Z*d[d.Z+ d\d]d6Z,d7d8d9d:d;d<d=d>d:id?d@d=d>d:idAd@d:dBd<d:dCd<dDdEd0dFdDdGd0dFdHd1gdIdJZ-dKZ.ej/d7d7e-e.e%dLgdMdNOdS)^uX 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.5)lowmediumhighxhigh returnDict[str, Any]ct ddlm}|dipiS#t$ricYSwxYw)Nr load_configx_search)hermes_cli.configrget Exceptionrs 5/home/ice/.hermes/hermes-agent/tools/x_search_tool.py_load_x_search_configr!Fs^111111{}}  R006B6  s %( 77strct}t|dpdptS)Nmodel)r!r"rstripDEFAULT_X_SEARCH_MODEL)cfgs r _get_x_search_modelr)Os>  ! !C   &B ' ' - - / / I3IJ Optional[str]cnt}|d}|!t|sdSt|}|t vr0dt }td|d|d|S)Nreasoning_effort, z*x_search.reasoning_effort must be one of: z (got ))r!rr"r&lowerX_SEARCH_REASONING_EFFORTSjoin ValueError)r( raw_valueeffortalloweds r _get_x_search_reasoning_effortr7Ts  ! !C*++II 4 4 6 6t ^^ ! ! # # ) ) + +F ///))677 # # # # # #    Mr*intct}|dt} tdt |S#t $r tcYSwxYw)Ntimeout_seconds)r!r DEFAULT_X_SEARCH_TIMEOUT_SECONDSmaxr8rr(r4s r _get_x_search_timeout_secondsr?dsd  ! !C)+KLLI02s9~~&&& 000////0AAAct}|dt} tdt |S#t $r tcYSwxYw)Nretriesr)r!rDEFAULT_X_SEARCH_RETRIESr=r8rr>s r _get_x_search_retriesrDmsc  ! !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>textrvr{z )r"rr&r\r2)rtrvpartsitemrzctyper{s r _extract_response_textrs$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) Nrwrxryrzr url_citationurlr%title start_index end_index)rrrr)rr\)rt citationsr}rz annotations r _extract_inline_citationsrs&(I Hb))/R 88F  y ( ( xx 2..4"  G%kk-<<B   >>&))^;;  )~~eR88!+!#?GK 799+-- 04[1_--" :" :G! :#=+++)<7)<)<(:&;&=&= !+   ))+++% : : :%gaT&B&BMSWXX &+*;*;w+?U?UDaK!O'**   3sC7Q;$78899999999((*BC : : :k))EaK!O   3sC7Q;$78899999999 :  KLL L}}'--+..4"55 4T::%'  7  ! !"5 6 6 6  8  ! !"6 7 7 7 ??   /  ! !+ . . . ==?? -  ! !) , , ,''R MRBR>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*.2R8"B32R83 C#=CC#R8C##R8'C65R86 D&D!D&R8!D&&CR8AI R8 M!BK&!R8&M!AMR8M!!ER88XAT$X$X6AVX X#AX:XXruSearch X (Twitter) posts, profiles, and threads using xAI's built-in X Search tool. Read-only discovery only: use this for current discussion, reactions, or claims on public X rather than general web pages. Do not use it to post, reply, like, DM, upload media, delete, or inspect the user's authenticated X account — those require a separate authenticated X API surface outside this tool. Available when xAI credentials are configured (SuperGrok OAuth or XAI_API_KEY).objectstringzWhat to look up on X.)rx descriptionarrayrxz;Optional list of X handles to include exclusively (max 10).)rxitemsrz/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.)rxrdefaultz?Whether xAI should analyze videos attached to matching X posts.rrrrirjrr)rx propertiesrequired)namer parametersc vt|dd|d|d|dd|ddt|ddt|d d S) Nrr%rrrirjrFrr)rrrR)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+)rr8)rrE)rrR)rUrVrWr"rrX)rcr"rWr"rr)rir"rjr"rrk)rtrrr")rtrrr)rgrrr")NNr%r%FF)rr"rrVrrVrir"rjr"rrRrrRrr")0__doc__ __future__rrloggingrrrrtypingrrr r r rtools.registryr r tools.xai_httprr getLoggerrrrMr'r<rCr1r^r!r)r7r?rDrQrTrbrhrsrrrrX_SEARCH_SCHEMArregisterr*r rsP''R#"""""  ----------33333333333333////////NNNNNNNN  8 $ $,##& ? KKKK     0000((((%%%%,    &&@&&&&$(<.2.2',',y y y y y z  P!6   (+\""   (+P## !J !H "` ++ "` ++9! ! DII%%11h        ( !      r*