Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai
Python agentsagentskillscitationsclaude-codecodexcodex-plugincodex-skilldeep-researchdeep-research-agentdeepresearchmcp-serverresearchresearch-agentresearch-tools
feat: add Exa AI-powered search provider (#24)
Teoc9abce73964f
diff --git a/pyproject.toml b/pyproject.tomlindex 9d5e46d..4ecdf33 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -35,7 +35,8 @@ dependencies = [[project.optional-dependencies]mcp = ["mcp>=1.6"]-all = ["hyperresearch[mcp]"]+exa = ["exa-py>=2.0.0"]+all = ["hyperresearch[mcp,exa]"]dev = ["pytest>=7.4","pytest-cov>=4.1",diff --git a/src/hyperresearch/web/base.py b/src/hyperresearch/web/base.pyindex 32d7c84..fb0c0d5 100644--- a/src/hyperresearch/web/base.py+++ b/src/hyperresearch/web/base.py@@ -161,4 +161,9 @@ def get_provider(except ImportError:raise ImportError("crawl4ai provider requires: pip install hyperresearch[crawl4ai]")- raise ValueError(f"Unknown web provider: {name!r}. Available: builtin, crawl4ai")+ if name == "exa":+ from hyperresearch.web.exa_provider import ExaProvider++ return ExaProvider()++ raise ValueError(f"Unknown web provider: {name!r}. Available: builtin, crawl4ai, exa")diff --git a/src/hyperresearch/web/exa_provider.py b/src/hyperresearch/web/exa_provider.pynew file mode 100644index 0000000..8c904c2--- /dev/null+++ b/src/hyperresearch/web/exa_provider.py@@ -0,0 +1,135 @@+"""Exa web provider — AI-native neural search returning ranked URLs with content.++Exa (https://exa.ai) is a search API designed for agents: results are ranked by+semantic relevance to the query and contents (text, highlights, summary) can be+returned in a single request.++Configuration:+ export EXA_API_KEY="your-api-key" # https://dashboard.exa.ai/api-keys++ # in .hyperresearch/config.toml+ [web]+ provider = "exa"++Optional install:+ pip install "hyperresearch[exa]"+"""++from __future__ import annotations++import os+from datetime import UTC, datetime+from typing import Any++from hyperresearch.web.base import WebResult+++class ExaProvider:+ """Web provider backed by the Exa search API.++ Supports both `search` (neural ranking) and `fetch` (URL → contents).+ Content is returned as plain text (Exa's extracted main-page text);+ when text is empty, falls back to highlights, then summary.+ """++ name = "exa"++ def __init__(+ self,+ api_key: str | None = None,+ search_type: str = "auto",+ text_max_characters: int = 8000,+ category: str | None = None,+ include_domains: list[str] | None = None,+ exclude_domains: list[str] | None = None,+ ):+ try:+ from exa_py import Exa+ except ImportError as exc:+ raise ImportError(+ 'exa provider requires: pip install "hyperresearch[exa]"'+ ) from exc++ key = api_key or os.environ.get("EXA_API_KEY", "").strip()+ if not key:+ raise RuntimeError(+ "EXA_API_KEY is not set. Get a free key at "+ "https://dashboard.exa.ai/api-keys and export it."+ )++ self._client = Exa(api_key=key)+ # Tracking header so Exa can attribute traffic to this integration.+ self._client.headers["x-exa-integration"] = "hyperresearch"++ self._search_type = search_type+ self._text_max_characters = text_max_characters+ self._category = category+ self._include_domains = include_domains+ self._exclude_domains = exclude_domains++ def search(self, query: str, max_results: int = 5) -> list[WebResult]:+ """Search the web via Exa and return ranked results with content."""+ kwargs: dict[str, Any] = {+ "num_results": max_results,+ "type": self._search_type,+ "contents": {+ "text": {"max_characters": self._text_max_characters},+ "highlights": True,+ },+ }+ if self._category:+ kwargs["category"] = self._category+ if self._include_domains:+ kwargs["include_domains"] = self._include_domains+ if self._exclude_domains:+ kwargs["exclude_domains"] = self._exclude_domains++ response = self._client.search(query, **kwargs)+ return [_to_web_result(r) for r in response.results]++ def fetch(self, url: str) -> WebResult:+ """Fetch a single URL via Exa /contents and return clean text."""+ response = self._client.get_contents(+ [url],+ text={"max_characters": self._text_max_characters},+ )+ if not response.results:+ raise RuntimeError(f"Exa returned no contents for {url}")+ return _to_web_result(response.results[0])+++def _to_web_result(item: Any) -> WebResult:+ """Convert an exa-py Result into a hyperresearch WebResult.++ Cascades through text → highlights → summary so the caller always gets+ something usable in `content`, regardless of which content modes Exa+ populated for this row.+ """+ text = getattr(item, "text", None) or ""+ highlights = getattr(item, "highlights", None) or []+ summary = getattr(item, "summary", None) or ""++ if text.strip():+ content = text+ elif highlights:+ content = "\n\n".join(h for h in highlights if h)+ else:+ content = summary++ metadata: dict[str, Any] = {}+ for field in ("author", "published_date", "score", "favicon", "image"):+ value = getattr(item, field, None)+ if value:+ metadata[field] = value+ if highlights:+ metadata["highlights"] = list(highlights)+ if summary and summary != content:+ metadata["summary"] = summary++ return WebResult(+ url=getattr(item, "url", "") or "",+ title=getattr(item, "title", None) or "",+ content=content,+ fetched_at=datetime.now(UTC),+ metadata=metadata,+ )diff --git a/tests/test_web/__init__.py b/tests/test_web/__init__.pynew file mode 100644index 0000000..e69de29diff --git a/tests/test_web/test_exa_provider.py b/tests/test_web/test_exa_provider.pynew file mode 100644index 0000000..5b31222--- /dev/null+++ b/tests/test_web/test_exa_provider.py@@ -0,0 +1,227 @@+"""Tests for the Exa web provider — mocks the exa-py SDK."""++from __future__ import annotations++from types import SimpleNamespace+from typing import Any+from unittest.mock import MagicMock++import pytest++from hyperresearch.web.base import WebResult, get_provider+++def _make_result(+ *,+ url: str = "https://example.com/article",+ title: str = "Example Article",+ text: str | None = "Full article body text.",+ highlights: list[str] | None = None,+ summary: str | None = None,+ score: float | None = 0.83,+ author: str | None = "Jane Doe",+ published_date: str | None = "2026-04-01",+) -> SimpleNamespace:+ return SimpleNamespace(+ url=url,+ id="abc",+ title=title,+ text=text,+ highlights=highlights or [],+ summary=summary,+ score=score,+ author=author,+ published_date=published_date,+ favicon=None,+ image=None,+ )+++def _make_response(results: list[Any]) -> SimpleNamespace:+ return SimpleNamespace(results=results)+++def _patch_sdk(monkeypatch: pytest.MonkeyPatch, client: MagicMock) -> None:+ """Patch `exa_py.Exa` at the source module — that's where the provider imports from."""+ import exa_py++ factory = MagicMock(return_value=client)+ monkeypatch.setattr(exa_py, "Exa", factory)+++def test_provider_registered_via_factory(monkeypatch: pytest.MonkeyPatch) -> None:+ """get_provider('exa') returns an ExaProvider instance."""+ monkeypatch.setenv("EXA_API_KEY", "test-key")+ client = MagicMock()+ client.headers = {}+ _patch_sdk(monkeypatch, client)++ prov = get_provider("exa")++ assert prov.name == "exa"+++def test_missing_api_key_raises(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.delenv("EXA_API_KEY", raising=False)++ with pytest.raises(RuntimeError, match="EXA_API_KEY"):+ get_provider("exa")+++def test_integration_header_set(monkeypatch: pytest.MonkeyPatch) -> None:+ """The x-exa-integration header must be set so Exa can attribute traffic."""+ monkeypatch.setenv("EXA_API_KEY", "test-key")+ client = MagicMock()+ client.headers = {}+ _patch_sdk(monkeypatch, client)++ get_provider("exa")++ assert client.headers["x-exa-integration"] == "hyperresearch"+++def test_search_returns_web_results(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("EXA_API_KEY", "test-key")+ client = MagicMock()+ client.headers = {}+ client.search.return_value = _make_response([+ _make_result(url="https://a.test", title="A", text="Body A"),+ _make_result(url="https://b.test", title="B", text="Body B"),+ ])+ _patch_sdk(monkeypatch, client)++ prov = get_provider("exa")+ results = prov.search("transformers", max_results=2)++ assert len(results) == 2+ assert all(isinstance(r, WebResult) for r in results)+ assert results[0].url == "https://a.test"+ assert results[0].title == "A"+ assert results[0].content == "Body A"+ assert results[0].metadata["author"] == "Jane Doe"+ assert results[0].metadata["score"] == 0.83+++def test_search_passes_num_results_and_contents(monkeypatch: pytest.MonkeyPatch) -> None:+ """Verify the call shape matches Exa's current API (contents object, not deprecated kwargs)."""+ monkeypatch.setenv("EXA_API_KEY", "test-key")+ client = MagicMock()+ client.headers = {}+ client.search.return_value = _make_response([])+ _patch_sdk(monkeypatch, client)++ prov = get_provider("exa")+ prov.search("foo", max_results=7)++ args, kwargs = client.search.call_args+ assert args == ("foo",)+ assert kwargs["num_results"] == 7+ assert kwargs["type"] == "auto"+ assert "text" in kwargs["contents"]+ assert kwargs["contents"]["highlights"] is True+++def test_content_falls_back_to_highlights(monkeypatch: pytest.MonkeyPatch) -> None:+ """When text is empty, content should be joined highlights."""+ monkeypatch.setenv("EXA_API_KEY", "test-key")+ client = MagicMock()+ client.headers = {}+ client.search.return_value = _make_response([+ _make_result(text="", highlights=["snippet 1", "snippet 2"]),+ ])+ _patch_sdk(monkeypatch, client)++ prov = get_provider("exa")+ results = prov.search("q")++ assert results[0].content == "snippet 1\n\nsnippet 2"+ assert results[0].metadata["highlights"] == ["snippet 1", "snippet 2"]+++def test_content_falls_back_to_summary(monkeypatch: pytest.MonkeyPatch) -> None:+ """When text and highlights are missing, content should be the summary."""+ monkeypatch.setenv("EXA_API_KEY", "test-key")+ client = MagicMock()+ client.headers = {}+ client.search.return_value = _make_response([+ _make_result(text=None, highlights=[], summary="A short summary."),+ ])+ _patch_sdk(monkeypatch, client)++ prov = get_provider("exa")+ results = prov.search("q")++ assert results[0].content == "A short summary."+++def test_content_handles_all_fields_missing(monkeypatch: pytest.MonkeyPatch) -> None:+ """No text / highlights / summary should yield empty content, not crash."""+ monkeypatch.setenv("EXA_API_KEY", "test-key")+ client = MagicMock()+ client.headers = {}+ client.search.return_value = _make_response([+ _make_result(text=None, highlights=[], summary=None),+ ])+ _patch_sdk(monkeypatch, client)++ prov = get_provider("exa")+ results = prov.search("q")++ assert results[0].content == ""+++def test_fetch_uses_get_contents(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("EXA_API_KEY", "test-key")+ client = MagicMock()+ client.headers = {}+ client.get_contents.return_value = _make_response([+ _make_result(url="https://x.test", title="X", text="Body"),+ ])+ _patch_sdk(monkeypatch, client)++ prov = get_provider("exa")+ result = prov.fetch("https://x.test")++ assert isinstance(result, WebResult)+ assert result.url == "https://x.test"+ assert result.content == "Body"+ args, _ = client.get_contents.call_args+ assert args[0] == ["https://x.test"]+++def test_fetch_raises_when_no_results(monkeypatch: pytest.MonkeyPatch) -> None:+ monkeypatch.setenv("EXA_API_KEY", "test-key")+ client = MagicMock()+ client.headers = {}+ client.get_contents.return_value = _make_response([])+ _patch_sdk(monkeypatch, client)++ prov = get_provider("exa")++ with pytest.raises(RuntimeError, match="no contents"):+ prov.fetch("https://nope.test")+++def test_unknown_provider_lists_exa_in_error(monkeypatch: pytest.MonkeyPatch) -> None:+ """The error message for unknown providers should advertise 'exa' as available."""+ with pytest.raises(ValueError, match="exa"):+ get_provider("not-a-real-provider")+++def test_provider_disabled_when_module_missing(monkeypatch: pytest.MonkeyPatch) -> None:+ """If exa-py isn't installed, instantiating the provider raises ImportError."""+ monkeypatch.setenv("EXA_API_KEY", "test-key")++ import builtins++ real_import = builtins.__import__++ def fake_import(name: str, *args: Any, **kwargs: Any) -> Any:+ if name == "exa_py":+ raise ImportError("No module named 'exa_py'")+ return real_import(name, *args, **kwargs)++ monkeypatch.setattr(builtins, "__import__", fake_import)++ with pytest.raises(ImportError, match="hyperresearch\\[exa\\]"):+ get_provider("exa")