provider.py 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290
  1. """Perplexity web search + page snippets — plugin form.
  2. Subclasses :class:`agent.web_search_provider.WebSearchProvider`. Two
  3. capabilities advertised:
  4. - ``supports_search()`` -> True (Perplexity Search API ``POST /search``)
  5. - ``supports_extract()`` -> True (``POST /sdk/content/snippets`` — the
  6. query-relevant page-excerpt route behind ``pplx content snippets``)
  7. Both are sync — the underlying call is ``httpx.post(...)``.
  8. Config keys this provider responds to::
  9. web:
  10. search_backend: "perplexity" # explicit per-capability
  11. extract_backend: "perplexity" # explicit per-capability
  12. backend: "perplexity" # shared fallback for both
  13. Env vars::
  14. PERPLEXITY_API_KEY=... # required for direct search and extract
  15. PERPLEXITY_BASE_URL=... # optional override of https://api.perplexity.ai
  16. No anonymous tier at Perplexity itself. The managed route serves search through
  17. ``perplexity-gateway.<TOOL_GATEWAY_DOMAIN>`` as ``search_type: "fast"``, which the
  18. gateway serves to any Nous identity (paid, unpaid or anonymous guest); a direct key
  19. takes precedence.
  20. Managed extract stays on Firecrawl.
  21. Extract caveat: Perplexity's only supported page-content route returns the
  22. passages of a page relevant to a *query* (elisions marked ``…``), not the
  23. whole page. ``web_extract`` has no query, so the URL's own path words are
  24. used as the relevance query, which approximates "what is this page about".
  25. Use Firecrawl / Exa / Parallel when a verbatim full-page dump is required.
  26. """
  27. from __future__ import annotations
  28. import logging
  29. from typing import Any, Dict, List
  30. from urllib.parse import urlparse
  31. import httpx
  32. from agent.web_search_provider import WebSearchProvider
  33. from hermes_cli.version_info import hermes_user_agent
  34. logger = logging.getLogger(__name__)
  35. _DEFAULT_BASE_URL = "https://api.perplexity.ai"
  36. _KEY_URL = "https://www.perplexity.ai/account/api"
  37. # Identify Hermes to Perplexity: the same static harness identity Hermes sends Kimi and
  38. # OpenCode, plus Perplexity's integration header. No per-user identifier and no separate
  39. # request; the call already carries the user's own API key.
  40. def _headers() -> dict[str, str]:
  41. return {
  42. "HTTP-Referer": "https://hermes-agent.nousresearch.com",
  43. "X-Title": "Hermes Agent",
  44. "User-Agent": hermes_user_agent("HermesAgent"),
  45. "X-Pplx-Integration": "hermes-agent",
  46. }
  47. # Search API hard cap for search_type=web.
  48. _MAX_SEARCH_RESULTS = 20
  49. # Snippet budgets (backend limits: max_tokens 1-16384, per page 1-4096).
  50. _MAX_TOKENS = 16384
  51. _MAX_TOKENS_PER_PAGE = 4096
  52. def _missing_key_error() -> str:
  53. return f"PERPLEXITY_API_KEY is not set. Get a key at {_KEY_URL}"
  54. def _managed_gateway(token_reader=None):
  55. """Nous Tool Gateway config when web_search is on the managed route, else None."""
  56. from tools import managed_tool_gateway as gw
  57. from tools.web_tools import _managed_web_search
  58. if not _managed_web_search():
  59. return None
  60. return gw.resolve_free_search_gateway(token_reader=token_reader)
  61. def _perplexity_request(endpoint: str, payload: dict[str, Any], gateway=None) -> dict[str, Any]:
  62. """POST to Perplexity or the supplied gateway; return parsed JSON.
  63. Raises ``ValueError`` when the key is missing or on any non-2xx status,
  64. carrying the response body so Perplexity's own error text (invalid key,
  65. BAD_REQUEST, rate limit) reaches the model verbatim.
  66. """
  67. from agent.web_search_provider import get_provider_env
  68. api_key = get_provider_env("PERPLEXITY_API_KEY")
  69. headers = _headers()
  70. if gateway is not None:
  71. # Nous-owned key behind the gateway: identify the harness only, not a per-user integration.
  72. base_url, api_key, headers = gateway.gateway_origin.rstrip("/"), gateway.nous_user_token, {"User-Agent": headers["User-Agent"]}
  73. elif api_key:
  74. base_url = (get_provider_env("PERPLEXITY_BASE_URL") or _DEFAULT_BASE_URL).rstrip("/")
  75. else:
  76. raise ValueError(_missing_key_error())
  77. url = f"{base_url}/{endpoint.lstrip('/')}"
  78. logger.info("Perplexity %s request to %s", endpoint, url)
  79. response = httpx.post(
  80. url,
  81. json=payload,
  82. timeout=60,
  83. headers={
  84. "Authorization": f"Bearer {api_key}",
  85. "Content-Type": "application/json",
  86. **headers,
  87. },
  88. )
  89. if response.status_code >= 400:
  90. body = (response.text or "").strip()
  91. raise ValueError(body or f"HTTP {response.status_code}")
  92. return response.json()
  93. def _normalize_search_results(response: dict[str, Any]) -> dict[str, Any]:
  94. """Map Search API ``{results: [{title,url,snippet,...}]}`` to the tool shape."""
  95. web_results = []
  96. for i, result in enumerate(response.get("results") or []):
  97. web_results.append(
  98. {
  99. "title": result.get("title", "") or "",
  100. "url": result.get("url", "") or "",
  101. "description": result.get("snippet", "") or "",
  102. "position": i + 1,
  103. }
  104. )
  105. return {"success": True, "data": {"web": web_results}}
  106. def _normalize_snippets(response: dict[str, Any], urls: list[str]) -> list[dict[str, Any]]:
  107. """Map ``{results: [{url,text?,tokens_count?,error?}]}`` to extract documents.
  108. One document per requested URL, in request order. A URL the backend
  109. omitted or flagged with ``error`` becomes a document carrying ``error``
  110. rather than raising — a 200 does not mean every page succeeded.
  111. """
  112. by_url = {r.get("url", ""): r for r in (response.get("results") or []) if isinstance(r, dict)}
  113. documents: list[dict[str, Any]] = []
  114. for url in urls:
  115. result = by_url.get(url, {})
  116. text = result.get("text") or ""
  117. doc: dict[str, Any] = {
  118. "url": url,
  119. "title": "",
  120. "content": text,
  121. "raw_content": text,
  122. "metadata": {"sourceURL": url},
  123. }
  124. error = result.get("error")
  125. if error or not text:
  126. doc["error"] = str(error) if error else "no content returned"
  127. documents.append(doc)
  128. return documents
  129. def _query_for_urls(urls: list[str]) -> str:
  130. """Derive a relevance query from URL path words (``/bloom-filter`` -> ``bloom filter``)."""
  131. words: list[str] = []
  132. for url in urls:
  133. parsed = urlparse(url)
  134. for token in parsed.path.replace("-", " ").replace("_", " ").replace("/", " ").split():
  135. if token.lower() not in words and not token.isdigit():
  136. words.append(token.lower())
  137. if not parsed.path.strip("/"):
  138. words.append(parsed.netloc)
  139. return " ".join(words)[:500] or " ".join(urls)[:500]
  140. class PerplexityWebSearchProvider(WebSearchProvider):
  141. """Direct or managed search; direct-key content snippets for extract."""
  142. @property
  143. def name(self) -> str:
  144. return "perplexity"
  145. @property
  146. def display_name(self) -> str:
  147. return "Perplexity"
  148. def is_available(self) -> bool:
  149. """True with a ``PERPLEXITY_API_KEY``, or on the managed route with a likely-usable Nous token."""
  150. from agent.web_search_provider import get_provider_env
  151. from tools.managed_tool_gateway import peek_nous_access_token
  152. return bool(get_provider_env("PERPLEXITY_API_KEY")) or _managed_gateway(token_reader=peek_nous_access_token) is not None
  153. def supports_search(self) -> bool:
  154. return True
  155. def supports_extract(self) -> bool:
  156. return True
  157. def search(self, query: str, limit: int = 5) -> dict[str, Any]:
  158. """Execute a Perplexity Search API query.
  159. ``search_context_size: low`` keeps ``snippet`` at description length;
  160. the default (``high``) returns multi-KB page excerpts per hit, which
  161. belongs in ``web_extract`` rather than a results list.
  162. """
  163. try:
  164. from tools.interrupt import is_interrupted
  165. if is_interrupted():
  166. return {"success": False, "error": "Interrupted"}
  167. from agent.web_search_provider import get_provider_env
  168. from tools.managed_tool_gateway import resolve_free_search_gateway
  169. from tools.web_tools import _managed_web_search
  170. direct = bool(get_provider_env("PERPLEXITY_API_KEY"))
  171. managed = False if direct else _managed_web_search()
  172. gateway = resolve_free_search_gateway() if managed else None
  173. if gateway is None and managed:
  174. from tools.tool_backend_helpers import NOUS_MANAGED_PROVIDER, selection_error
  175. raise ValueError(selection_error(
  176. "web", NOUS_MANAGED_PROVIDER, "there is no usable Nous identity (sign in with `/login`)"))
  177. logger.info("Perplexity search: '%s' (limit=%d%s)", query, limit, ", managed" if gateway else "")
  178. payload = {
  179. "query": query,
  180. "max_results": max(1, min(limit, _MAX_SEARCH_RESULTS)),
  181. "search_context_size": "low",
  182. }
  183. if gateway is not None:
  184. payload["search_type"] = "fast"
  185. raw = _perplexity_request("search", payload, gateway)
  186. return _normalize_search_results(raw)
  187. except ValueError as exc:
  188. return {"success": False, "error": str(exc)}
  189. except Exception as exc:
  190. logger.warning("Perplexity search error: %s", exc)
  191. return {"success": False, "error": f"Perplexity search failed: {exc}"}
  192. def extract(self, urls: list[str], **kwargs: Any) -> list[dict[str, Any]]:
  193. """Return query-relevant snippets for one or more URLs.
  194. Sync — the underlying call is httpx.post(...). Per-URL failures
  195. become items with ``error``; a missing key errors every URL.
  196. """
  197. try:
  198. from tools.interrupt import is_interrupted
  199. if is_interrupted():
  200. return [{"url": u, "error": "Interrupted", "title": ""} for u in urls]
  201. logger.info("Perplexity snippets: %d URL(s)", len(urls))
  202. raw = _perplexity_request(
  203. "sdk/content/snippets",
  204. {
  205. "query": _query_for_urls(urls),
  206. "urls": list(urls),
  207. "max_tokens": _MAX_TOKENS,
  208. "max_tokens_per_page": _MAX_TOKENS_PER_PAGE,
  209. },
  210. )
  211. return _normalize_snippets(raw, list(urls))
  212. except ValueError as exc:
  213. return [{"url": u, "title": "", "content": "", "error": str(exc)} for u in urls]
  214. except Exception as exc:
  215. logger.warning("Perplexity extract error: %s", exc)
  216. return [
  217. {"url": u, "title": "", "content": "", "error": f"Perplexity extract failed: {exc}"}
  218. for u in urls
  219. ]
  220. def get_setup_schema(self) -> dict[str, Any]:
  221. return {
  222. "name": "Perplexity",
  223. "badge": "paid",
  224. "tag": (
  225. "Perplexity Search API — ranked, date-stamped web results plus "
  226. "query-relevant page snippets for extract."
  227. ),
  228. "env_vars": [
  229. {
  230. "key": "PERPLEXITY_API_KEY",
  231. "prompt": "Perplexity API key",
  232. "url": _KEY_URL,
  233. },
  234. ],
  235. "web_tier": "paid",
  236. }