provider.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260
  1. """xAI Web Search — search-only provider backed by Grok's server-side ``web_search`` tool on the
  2. Responses API (https://docs.x.ai/developers/tools/web-search); Grok is asked for structured JSON
  3. so rows match every other Hermes web provider. Config: ``web.backend: "xai"``; optional ``web.xai``:
  4. ``model`` (default grok-build-0.1), ``allowed_domains`` / ``excluded_domains`` (max 5, mutually
  5. exclusive), ``timeout`` (default 90s). Auth: Grok OAuth via ``hermes auth``, else XAI_API_KEY.
  6. """
  7. from __future__ import annotations
  8. import json
  9. import logging
  10. import re
  11. from typing import Any, Dict, List, Optional
  12. from plugins.web._common import BaseWebSearchProvider, search_fail as _fail, search_ok, setup_schema, title_hit as _row
  13. from tools.xai_http import has_xai_credentials, hermes_xai_user_agent, resolve_xai_http_credentials
  14. logger = logging.getLogger(__name__)
  15. DEFAULT_MODEL = "grok-build-0.1"
  16. DEFAULT_TIMEOUT = 90
  17. _MAX_DOMAIN_FILTERS = 5 # xAI hard cap on allowed_domains / excluded_domains
  18. # Tolerates leading/trailing prose — reasoning models occasionally narrate before the JSON block.
  19. _JSON_BLOCK_RE = re.compile(r"\{[\s\S]*\}", re.MULTILINE)
  20. def _load_xai_web_config() -> dict[str, Any]:
  21. """Read ``web.xai`` from config.yaml (returns {} on miss)."""
  22. try:
  23. from hermes_cli.config import load_config
  24. cfg = load_config()
  25. for key in ("web", "xai"):
  26. cfg = cfg.get(key) if isinstance(cfg, dict) else None
  27. return cfg if isinstance(cfg, dict) else {}
  28. except Exception as exc:
  29. logger.debug("Could not load web.xai config: %s", exc)
  30. return {}
  31. def _coerce_domain_list(value: Any) -> list[str]:
  32. return [item.strip() for item in value if isinstance(item, str) and item.strip()][:_MAX_DOMAIN_FILTERS] if isinstance(value, list) else []
  33. def _coerce(cast, value: Any, default: Any) -> Any:
  34. try:
  35. return cast(value)
  36. except (TypeError, ValueError):
  37. return default
  38. class XAIWebSearchProvider(BaseWebSearchProvider):
  39. """Sends a structured prompt with ``tools=[{"type": "web_search"}]`` and parses the JSON Grok
  40. returns; falls back to message annotations, then ``citations``. Trust model: Grok *generates*
  41. the URLs/titles/descriptions and is steerable by the query text — validate before fetching."""
  42. NAME = "xai"
  43. DISPLAY_NAME = "xAI Web Search (Grok)"
  44. def is_available(self) -> bool:
  45. """Cheap probe (env var OR auth-store tokens). Deliberately NOT
  46. ``resolve_xai_http_credentials``: must never refresh tokens or take the
  47. auth-store lock, since this runs on every ``hermes tools`` repaint."""
  48. return has_xai_credentials()
  49. def search(self, query: str, limit: int = 5) -> dict[str, Any]:
  50. try:
  51. from tools.interrupt import is_interrupted
  52. if is_interrupted():
  53. return _fail("Interrupted")
  54. except Exception:
  55. pass
  56. creds = resolve_xai_http_credentials()
  57. api_key = str(creds.get("api_key") or "").strip()
  58. base_url = str(creds.get("base_url") or "https://api.x.ai/v1").strip().rstrip("/")
  59. if not api_key:
  60. return _fail("No xAI credentials found. Run `hermes auth` to sign in with xAI Grok OAuth, or set XAI_API_KEY.")
  61. # Same clamp range as web_search_tool so explicit limits aren't downgraded.
  62. limit = max(1, min(_coerce(int, limit, 5), 100))
  63. cfg = _load_xai_web_config()
  64. model = (cfg["model"].strip() if isinstance(cfg.get("model"), str) else "") or DEFAULT_MODEL
  65. web_search_tool = self._web_search_tool(cfg)
  66. if web_search_tool is None:
  67. # xAI rejects this combo — surface a clear error rather than an API 400.
  68. return _fail("web.xai.allowed_domains and web.xai.excluded_domains cannot both be set (xAI restriction).")
  69. # include=no_inline_citations keeps the JSON block clean; URLs come from annotations/citations.
  70. payload: dict[str, Any] = {"model": model, "input": [{"role": "user", "content": self._build_prompt(query, limit)}], "tools": [web_search_tool], "include": ["no_inline_citations"]}
  71. try:
  72. import httpx
  73. except ImportError:
  74. return _fail("httpx is not installed (required for xAI web search)")
  75. logger.info("xAI web search via %s: '%s' (limit=%d, model=%s)", base_url, query, limit, model)
  76. data, error = self._post_responses(
  77. base_url, payload, api_key, _coerce(float, cfg.get("timeout", DEFAULT_TIMEOUT), DEFAULT_TIMEOUT),
  78. is_oauth_path=(creds.get("provider") == "xai-oauth"),
  79. )
  80. if error:
  81. return error
  82. # xAI sometimes returns HTTP 200 with an error envelope (overloaded, refusal);
  83. # without this check we'd report success-with-no-rows and mask a real failure.
  84. api_error = data.get("error") if isinstance(data, dict) else None
  85. if isinstance(api_error, dict):
  86. err_msg = api_error.get("message") or api_error.get("code") or "unknown error"
  87. logger.warning("xAI web search returned error envelope: %s", err_msg)
  88. return _fail(f"xAI returned an error: {err_msg}")
  89. # Empty list on 0 hits is a success (matches brave-free / exa).
  90. return search_ok(self._extract_results(data, limit=limit))
  91. @staticmethod
  92. def _web_search_tool(cfg: dict[str, Any]) -> Optional[dict[str, Any]]:
  93. """``web_search`` tool spec with optional domain filters; None when both
  94. allowed and excluded are set (xAI rejects the combination)."""
  95. filters = {k: _coerce_domain_list(cfg.get(k)) for k in ("allowed_domains", "excluded_domains")}
  96. filters = {k: v for k, v in filters.items() if v}
  97. if len(filters) == 2:
  98. return None
  99. return {"type": "web_search", "filters": filters} if filters else {"type": "web_search"}
  100. @staticmethod
  101. def _post_responses(base_url: str, payload: dict[str, Any], api_key: str, timeout: float, *, is_oauth_path: bool) -> tuple[Any, Optional[dict[str, Any]]]:
  102. """POST ``/responses`` → ``(parsed_json, None)`` or ``(None, failure_envelope)``.
  103. Two attempts: on a first-call 401 with OAuth creds, force-refresh once and retry
  104. (opaque tokens the resolver can't pre-check; mid-window revocation/rotation).
  105. XAI_API_KEY creds can't be refreshed, so they skip the retry rather than burn quota.
  106. """
  107. import httpx
  108. headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json", "User-Agent": hermes_xai_user_agent()}
  109. def _refreshed_key() -> str:
  110. """New bearer after a 401, or "" when refresh fails / returns the same token (retry would be pointless)."""
  111. try:
  112. key = str(resolve_xai_http_credentials(force_refresh=True, api_key_hint=api_key).get("api_key") or "").strip()
  113. return key if key != api_key else ""
  114. except Exception as refresh_exc:
  115. logger.warning("xAI web search OAuth refresh after 401 failed: %s", refresh_exc)
  116. return ""
  117. resp = None
  118. for attempt in range(2):
  119. try:
  120. resp = httpx.post(f"{base_url}/responses", headers=headers, json=payload, timeout=timeout)
  121. resp.raise_for_status()
  122. break
  123. except httpx.HTTPStatusError as exc:
  124. status = exc.response.status_code if exc.response is not None else 0
  125. if status == 401 and attempt == 0 and is_oauth_path:
  126. logger.info("xAI web search got 401 on first attempt; forcing OAuth refresh and retrying once.")
  127. if new_key := _refreshed_key():
  128. api_key, headers["Authorization"] = new_key, f"Bearer {new_key}"
  129. continue
  130. try:
  131. body = exc.response.text[:300] if exc.response is not None else ""
  132. except Exception:
  133. body = ""
  134. logger.warning("xAI web search HTTP %d: %s", status, body)
  135. return None, _fail(f"xAI web search returned HTTP {status}: {body}".rstrip())
  136. except httpx.RequestError as exc:
  137. logger.warning("xAI web search request error: %s", exc)
  138. return None, _fail(f"Could not reach xAI: {exc}")
  139. if resp is None:
  140. return None, _fail("xAI web search produced no response")
  141. try:
  142. return resp.json(), None
  143. except Exception as exc:
  144. logger.warning("xAI web search bad JSON: %s", exc)
  145. return None, _fail("Could not parse xAI Responses API reply as JSON")
  146. @staticmethod
  147. def _build_prompt(query: str, limit: int) -> str:
  148. """Ask for a JSON *object* (cheap to match with ``_JSON_BLOCK_RE``) and forbid
  149. prose/fences/inline citations to keep the payload parseable."""
  150. return (
  151. "Use the web_search tool to find current information for the query below, then respond with ONLY a single "
  152. "JSON object — no prose, no markdown fences, no inline citation links — matching this exact schema:\n\n"
  153. '{"results": [{"title": "string", "url": "string", "description": "1-2 sentence summary"}]}\n\n'
  154. f'Return at most {limit} results, ordered by relevance, with absolute https:// URLs. If no usable results exist, return '
  155. '{"results": []}.\n\n'
  156. f"Query: {query}"
  157. )
  158. @classmethod
  159. def _extract_results(cls, response_data: dict[str, Any], *, limit: int) -> list[dict[str, Any]]:
  160. """Rows in order of preference: (1) the JSON object in ``output_text`` blocks,
  161. (2) ``url_citation`` annotations paired with surrounding text, (3) the raw
  162. ``citations`` list. (2) only short-circuits when it yields rows, so future
  163. annotation types don't mask real data in ``citations``."""
  164. text_blocks, annotations = cls._collect_output_text(response_data)
  165. parsed = next((p for p in (cls._try_parse_json_results(b, limit=limit) for b in text_blocks) if p), None)
  166. if parsed or (annotations and (parsed := cls._results_from_annotations(annotations, "\n".join(text_blocks), limit=limit))):
  167. return parsed
  168. citations = response_data.get("citations") or []
  169. return [_row("", str(u), "", i + 1) for i, u in enumerate(citations[:limit]) if isinstance(u, str) and u.strip()] if isinstance(citations, list) else []
  170. @staticmethod
  171. def _collect_output_text(response_data: dict[str, Any]) -> tuple[list[str], list[dict[str, Any]]]:
  172. """(text_blocks, annotations) from ``response.output`` message chunks."""
  173. output = response_data.get("output")
  174. chunks = [
  175. chunk
  176. for item in (output if isinstance(output, list) else [])
  177. if isinstance(item, dict) and item.get("type") == "message" and isinstance(item.get("content"), list)
  178. for chunk in item["content"]
  179. if isinstance(chunk, dict) and chunk.get("type") == "output_text"
  180. ]
  181. text_blocks = [c["text"] for c in chunks if isinstance(c.get("text"), str) and c["text"].strip()]
  182. annotations = [a for c in chunks if isinstance(c.get("annotations"), list) for a in c["annotations"] if isinstance(a, dict)]
  183. return text_blocks, annotations
  184. @staticmethod
  185. def _try_parse_json_results(text: str, *, limit: int) -> Optional[list[dict[str, Any]]]:
  186. """Parse a JSON object with a ``results`` array out of ``text``; None when absent.
  187. Whole string first, then the regex-matched block (reasoning models prefix narration)."""
  188. match = _JSON_BLOCK_RE.search(text)
  189. for candidate in [text] + ([match.group(0)] if match and match.group(0) != text else []):
  190. try:
  191. parsed = json.loads(candidate)
  192. except (json.JSONDecodeError, ValueError):
  193. continue
  194. results = parsed.get("results") if isinstance(parsed, dict) else None
  195. if not isinstance(results, list):
  196. continue
  197. normalized: list[dict[str, Any]] = []
  198. for row in results[:limit]:
  199. url = str(row.get("url", "")).strip() if isinstance(row, dict) else ""
  200. if url:
  201. # Renumber from kept rows so a dropped malformed row leaves no gap.
  202. normalized.append(_row(str(row.get("title", "")).strip(), url, str(row.get("description", "")).strip(), len(normalized) + 1))
  203. if normalized:
  204. return normalized
  205. return None
  206. @staticmethod
  207. def _results_from_annotations(annotations: list[dict[str, Any]], joined_text: str, *, limit: int) -> list[dict[str, Any]]:
  208. """Fallback rows from ``url_citation`` annotations: URL plus ~200 chars of
  209. preceding text as the description (the annotation title is just a number)."""
  210. seen: set[str] = set()
  211. results: list[dict[str, Any]] = []
  212. for ann in annotations:
  213. url = str(ann.get("url", "")).strip() if ann.get("type") == "url_citation" else ""
  214. if not url or url in seen:
  215. continue
  216. seen.add(url)
  217. description = ""
  218. start, end = ann.get("start_index"), ann.get("end_index")
  219. if isinstance(start, int) and isinstance(end, int) and 0 <= start < end <= len(joined_text):
  220. description = joined_text[max(0, start - 200):start].strip()
  221. if len(description) > 200:
  222. description = description[-200:].strip()
  223. results.append(_row("", url, description, len(results) + 1))
  224. if len(results) >= limit:
  225. break
  226. return results
  227. def get_setup_schema(self) -> dict[str, Any]:
  228. # Auth resolution is delegated to the shared ``xai_grok`` post_setup hook
  229. # (same one image_gen.xai / tts.xai use) for a consistent OAuth-or-key prompt.
  230. return setup_schema(
  231. "xAI Web Search (Grok)", "paid",
  232. "Agentic web search via Grok's web_search tool — uses xAI Grok OAuth or XAI_API_KEY.", post_setup="xai_grok",
  233. )