Python
Add Serper.dev search provider (#207)
Manav Shrivastava3a11e24b1147
diff --git a/coworker/config.py b/coworker/config.pyindex ab79143d..2801708c 100644--- a/coworker/config.py+++ b/coworker/config.py@@ -89,7 +89,7 @@ class Config:auto_approve_shadow: bool = Falsehost: 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__.pyindex 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.pyindex 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.pyindex 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 keyassert 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):