Skip to content

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

feat: add Exa AI-powered search provider (#24)

Teoc9abce73964f
diff --git a/pyproject.toml b/pyproject.toml
index 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.py
index 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.py
new file mode 100644
index 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__.py
new file mode 100644
index 0000000..e69de29
diff --git a/tests/test_web/test_exa_provider.py b/tests/test_web/test_exa_provider.py
new file mode 100644
index 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")