Skip to content
Python

Add Serper.dev search provider (#207)

Manav Shrivastava3a11e24b1147
diff --git a/coworker/config.py b/coworker/config.py
index ab79143d..2801708c 100644
--- a/coworker/config.py
+++ b/coworker/config.py
@@ -89,7 +89,7 @@ class Config:
auto_approve_shadow: bool = False
host: str = "127.0.0.1"
port: int = 8765
- # Web search provider: "duckduckgo" (keyless default) | "tavily" | "brave" (need a key).
+ # Web search provider: "duckduckgo" (keyless default) | "tavily" | "brave" | "serper" (need a key).
web_search_provider: str = "duckduckgo"
# OpenWorker Cloud (sign-in + managed connectors). Config, never constants:
# dev/staging/BYO-VPC deployments point these at their own instances.
diff --git a/coworker/web/__init__.py b/coworker/web/__init__.py
index 159de66a..276e34d7 100644
--- a/coworker/web/__init__.py
+++ b/coworker/web/__init__.py
@@ -6,6 +6,7 @@ from .providers import (
BraveProvider,
DuckDuckGoProvider,
SearchResult,
+ SerperProvider,
TavilyProvider,
WebSearchProvider,
build_provider,
@@ -20,6 +21,7 @@ __all__ = [
"DuckDuckGoProvider",
"TavilyProvider",
"BraveProvider",
+ "SerperProvider",
"build_provider",
"provider_names",
"make_web_search_tool",
diff --git a/coworker/web/providers.py b/coworker/web/providers.py
index 23cad857..04d70682 100644
--- a/coworker/web/providers.py
+++ b/coworker/web/providers.py
@@ -1,8 +1,8 @@
"""Web search providers — a keyless default + pluggable third-party services.
-`duckduckgo` works with no API key (our "starting version of our own"). `tavily` and `brave`
-give better results but need a key (configured via the SecretStore / env). All providers
-return a uniform `list[SearchResult]`; the heavy client libs are lazy-imported.
+`duckduckgo` works with no API key (our "starting version of our own"). `tavily`, `brave` and
+`serper` give better results but need a key (configured via the SecretStore / env). All
+providers return a uniform `list[SearchResult]`; the heavy client libs are lazy-imported.
"""
from __future__ import annotations
@@ -108,10 +108,45 @@ class BraveProvider(WebSearchProvider):
]
+class SerperProvider(WebSearchProvider):
+ """Google search results via serper.dev — $0.001/search, 2500 free searches.
+
+ POSTs to the Serper API and maps organic results into uniform SearchResult
+ items. Requires a key from https://serper.dev (free tier includes 2500 searches
+ with no time limit).
+ """
+
+ name = "serper"
+ requires_key = True
+
+ def __init__(self, api_key: str) -> None:
+ self.api_key = api_key
+
+ def search(self, query: str, max_results: int = 5) -> list[SearchResult]:
+ import httpx
+
+ resp = httpx.post(
+ "https://google.serper.dev/search",
+ headers={"X-API-KEY": self.api_key},
+ json={"q": query, "num": max_results},
+ timeout=_TIMEOUT,
+ )
+ data = resp.json()
+ return [
+ SearchResult(
+ title=r.get("title", ""),
+ url=r.get("link", ""),
+ snippet=r.get("snippet", ""),
+ )
+ for r in data.get("organic", [])
+ ]
+
+
_PROVIDERS = {
"duckduckgo": DuckDuckGoProvider,
"tavily": TavilyProvider,
"brave": BraveProvider,
+ "serper": SerperProvider,
}
diff --git a/tests/test_web_search.py b/tests/test_web_search.py
index d1c2d0fd..389b50f2 100644
--- a/tests/test_web_search.py
+++ b/tests/test_web_search.py
@@ -1,7 +1,7 @@
"""Tests for web search — provider abstraction, the tool, and config resolution.
No network: a FakeProvider is injected; third-party key handling and the REST config path
-are exercised without hitting DuckDuckGo/Tavily/Brave.
+are exercised without hitting DuckDuckGo/Tavily/Brave/Serper.
"""
from __future__ import annotations
@@ -18,6 +18,7 @@ from coworker.web import (
from coworker.web.providers import (
BraveProvider,
DuckDuckGoProvider,
+ SerperProvider,
TavilyProvider,
WebSearchProvider,
)
@@ -77,8 +78,49 @@ def test_build_provider_default_is_keyless_duckduckgo():
def test_build_provider_third_party_requires_key():
with pytest.raises(ValueError):
build_provider("tavily") # no key
+ with pytest.raises(ValueError):
+ build_provider("serper") # no key
assert isinstance(build_provider("tavily", "tvly-x"), TavilyProvider)
assert isinstance(build_provider("brave", "brv-x"), BraveProvider)
+ assert isinstance(build_provider("serper", "srp-x"), SerperProvider)
+ assert "serper" in provider_names()
+
+
+def test_serper_sends_correct_request_and_maps_organic_results(monkeypatch):
+ """Verify the Serper API request shape and response mapping without a network call."""
+ import httpx
+
+ sent = {}
+
+ class _Resp:
+ @staticmethod
+ def json():
+ return {
+ "organic": [
+ {
+ "title": "Example Title",
+ "link": "https://example.com",
+ "snippet": "An example snippet.",
+ }
+ ]
+ }
+
+ def fake_post(url, **kwargs):
+ sent.update(url=url, **kwargs)
+ return _Resp()
+
+ monkeypatch.setattr(httpx, "post", fake_post)
+
+ results = build_provider("serper", "srp-test-key").search("anthropic", max_results=3)
+
+ assert sent["url"] == "https://google.serper.dev/search"
+ assert sent["headers"]["X-API-KEY"] == "srp-test-key"
+ assert sent["json"]["q"] == "anthropic"
+ assert sent["json"]["num"] == 3
+ assert len(results) == 1
+ assert results[0].title == "Example Title"
+ assert results[0].url == "https://example.com"
+ assert results[0].snippet == "An example snippet."
def test_tool_surfaces_missing_key_error(tmp_path):