web_search_provider.py 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101
  1. """Web Search Provider ABC.
  2. The single plugin-facing surface every web provider (brave-free, ddgs, searxng,
  3. exa, parallel, tavily, keenable, firecrawl) implements; registered via
  4. ``PluginContext.register_web_search_provider()`` and selected by
  5. ``web.search_backend`` / ``web.extract_backend`` / ``web.backend``.
  6. Response shapes (legacy contract, the tool wrapper does not translate)::
  7. search: {"success": True, "data": {"web": [{"title", "url", "description", "position"}, ...]}}
  8. extract: {"success": True, "data": [{"url", "title", "content", "raw_content", "metadata"}, ...]}
  9. failure: {"success": False, "error": str}
  10. """
  11. from __future__ import annotations
  12. import abc
  13. import os
  14. from typing import Any, Dict, List
  15. from agent.provider_base import ProviderBase
  16. def get_provider_env(name: str) -> str:
  17. """Config-aware env lookup (``os.environ`` first, then ``~/.hermes/.env``) so
  18. credentials set through the config layer are visible in gateway sessions /
  19. delegate children / subprocess runs. Stripped value, or ``""`` when unset.
  20. Falls back to a bare ``os.getenv`` when the config module is unavailable (stripped installs, early
  21. import contexts). See #40190. Never when a profile secret scope is bound: a scoped miss means the
  22. served profile has no key, and ``os.environ`` holds the LAUNCH profile's — a routed profile without
  23. an Exa/Parallel key must be refused, not search on another profile's key.
  24. """
  25. try:
  26. from hermes_cli.config import get_env_value
  27. val = get_env_value(name)
  28. except Exception as exc:
  29. try:
  30. from agent.secret_scope import UnscopedSecretError
  31. except ImportError:
  32. UnscopedSecretError = () # type: ignore[assignment,misc]
  33. if isinstance(exc, UnscopedSecretError):
  34. raise
  35. val = None
  36. scope_bound, multiplex_active = _secret_scope_state()
  37. if val is None and multiplex_active and not scope_bound:
  38. from agent.secret_scope import UnscopedSecretError
  39. raise UnscopedSecretError(name, f"get_provider_env({name!r}) called with no active profile scope")
  40. if val is None and not scope_bound:
  41. val = os.getenv(name, "")
  42. return (val or "").strip()
  43. def _secret_scope_state() -> tuple[bool, bool]:
  44. try:
  45. from agent.secret_scope import current_secret_scope, is_multiplex_active
  46. except Exception:
  47. return False, False
  48. return current_secret_scope() is not None, is_multiplex_active()
  49. class WebSearchProvider(ProviderBase):
  50. """Abstract base class for a web search/extract backend: implement :meth:`is_available`
  51. and at least one of :meth:`search` / :meth:`extract`; the ``supports_*`` flags route each capability."""
  52. @abc.abstractmethod
  53. def is_available(self) -> bool:
  54. """True when this provider can service calls. Cheap check only (env var, importable
  55. dep, instance URL) — NO network; runs at tool registration and on every ``hermes tools`` paint."""
  56. def supports_search(self) -> bool:
  57. """True if this provider implements :meth:`search`."""
  58. return True
  59. def is_keyless_available(self) -> bool:
  60. """True when this provider can serve calls WITHOUT credentials (public anonymous
  61. free tiers such as Exa / Parallel MCP); used only when NO provider is configured or
  62. keyed. Must never make :meth:`is_available` True, or the legacy preference walk would
  63. route keyed users onto a higher-priority backend's free tier. Cheap, no network."""
  64. return False
  65. def supports_extract(self) -> bool:
  66. """True if this provider implements :meth:`extract` (sync or ``async def`` —
  67. the dispatcher awaits coroutine functions)."""
  68. return False
  69. def search(self, query: str, limit: int = 5) -> dict[str, Any]:
  70. """Execute a web search. Callers gate on :meth:`supports_search`."""
  71. raise NotImplementedError(
  72. f"{self.name} does not support search (override supports_search)"
  73. )
  74. def extract(self, urls: list[str], **kwargs: Any) -> Any:
  75. """Extract content from URLs (callers gate on :meth:`supports_extract`); may be ``async def``.
  76. Returns ``[{"url", "title", "content", "raw_content", "metadata"?, "error"?}, ...]`` (``error``
  77. only on per-URL failure). Ignore unknown ``kwargs`` (``format``, ``include_raw``, ``max_chars``)."""
  78. raise NotImplementedError(
  79. f"{self.name} does not support extract (override supports_extract)"
  80. )