Skip to content

Personal AI, On Personal Devices

Python

feat: add Serply web_search engine for Google operators (#985)

Serply96501bb3c5ac
diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md
index 238a4db9..4c5f2b38 100644
--- a/docs/getting-started/configuration.md
+++ b/docs/getting-started/configuration.md
@@ -1120,7 +1120,9 @@ OpenJarvis respects the following environment variables:
| `MINIMAX_API_KEY` | API key for MiniMax cloud inference. Required for the `cloud` engine with MiniMax models (MiniMax-M3, MiniMax-M2.7, MiniMax-M2.7-highspeed, MiniMax-M2.5, MiniMax-M2.5-highspeed). |
| `TAVILY_API_KEY` | API key for the Tavily web search engine. Optional — when set, `auto` engine selection prefers Tavily. |
| `YOUDOTCOM_API_KEY` | API key for the You.com web search engine. Optional — raises the keyless free-tier limits and enables You.com Contents extraction for URL queries. |
-| `OPENJARVIS_WEB_SEARCH_ENGINE` | Web search engine for the `web_search` tool: `auto` (default), `youcom`, `tavily`, or `duckduckgo`. |
+| `SERPLY_API_KEY` | API key for the Serply web search engine, which proxies Google. Optional. When set and no other search key is, `auto` engine selection prefers Serply over the keyless tier. Keys: [serply.io](https://serply.io). |
+| `SERPLY_PROXY_LOCATION` | Two-letter country code asking Serply for that country's Google result set, for example `DE`. Optional. Unset means the API answers from its own default region. See [serply.io/docs](https://serply.io/docs). |
+| `OPENJARVIS_WEB_SEARCH_ENGINE` | Web search engine for the `web_search` tool: `auto` (default), `youcom`, `tavily`, `serply`, or `duckduckgo`. |
## Next Steps
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 6b494936..c44e8c26 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -137,21 +137,31 @@ You get a ChatGPT-like interface with streaming responses, tool use, energy moni
Web search works with no configuration: queries go to the You.com keyless
free tier, which is rate limited per IP and needs no signup. To raise those
-limits, or to use Tavily instead, add `YOUDOTCOM_API_KEY` or `TAVILY_API_KEY`
-under **Settings → Tools → Web Search** after the app starts, or export one
-before starting quickstart:
+limits, or to use Tavily or Serply instead, add `YOUDOTCOM_API_KEY`,
+`TAVILY_API_KEY` or `SERPLY_API_KEY` under **Settings → Tools → Web Search**
+after the app starts, or export one before starting quickstart:
```bash
export YOUDOTCOM_API_KEY="..." # free key: https://you.com/platform
+export SERPLY_API_KEY="..." # free tier: https://serply.io
./scripts/quickstart.sh
```
Set `OPENJARVIS_WEB_SEARCH_ENGINE` to pick an engine explicitly — `youcom`,
-`tavily`, or `duckduckgo`. The default, `auto`, uses Tavily when
-`TAVILY_API_KEY` is set and You.com otherwise. DuckDuckGo remains the fallback
+`tavily`, `serply`, or `duckduckgo`. The default, `auto`, uses Tavily when
+`TAVILY_API_KEY` is set, then You.com, then Serply, and settles on the You.com
+keyless tier when no key is set at all. DuckDuckGo remains the fallback
for every engine; dropping to it is logged at `WARNING`, since its scraped
results are unranked.
+Serply proxies Google itself, so Google search operators reach the index
+unchanged: `site:arxiv.org` restricts the corpus and `after:2026-01-01` bounds
+results by date, neither of which an AI-search index can honour. Set
+`SERPLY_PROXY_LOCATION` to a two-letter country code such as `DE` to ask for
+that country's result set instead of the default region. Keys and request
+options are documented at [serply.io](https://serply.io) and
+[serply.io/docs](https://serply.io/docs).
+
The script does not automatically source `.env` files. Run `source .env`
first if that is where you keep the key. Stop any existing OpenJarvis server
before restarting so it inherits the updated environment.
@@ -280,7 +290,7 @@ Agents add multi-turn reasoning and tool-calling capabilities. The `orchestrator
| `retrieval` | Search the memory store for relevant context. |
| `llm` | Make sub-queries to another model. |
| `file_read` | Read files with path validation. |
-| `web_search` | Web search via You.com (keyless by default) or Tavily, with a DuckDuckGo fallback. |
+| `web_search` | Web search via You.com (keyless by default), Tavily, or Serply, with a DuckDuckGo fallback. |
### CLI Example
diff --git a/docs/user-guide/deep-research.md b/docs/user-guide/deep-research.md
index cb638c0d..b8803f62 100644
--- a/docs/user-guide/deep-research.md
+++ b/docs/user-guide/deep-research.md
@@ -160,6 +160,6 @@ Smaller chunk sizes work better for code, where each function or class is a natu
**Slow responses** -- The agent makes multiple search passes. Each turn involves a model call. Reduce `max_turns` or use a smaller model (`qwen3.5:4b`) for faster but less thorough results.
-**Web search not working** -- The `web_search` tool needs no API key by default; it uses the You.com keyless free tier, which is rate limited per IP. Set `YOUDOTCOM_API_KEY` (free key at [you.com/platform](https://you.com/platform?utm_source=open-jarvis-openjarvis&utm_medium=oss_integration&utm_campaign=2026-09-oss-integrations&utm_content=docs)) for higher limits, or install Tavily with `uv sync --extra tools-search` and set `TAVILY_API_KEY`. A `WARNING` naming the failed engine is logged whenever search drops to the DuckDuckGo fallback.
+**Web search not working** -- The `web_search` tool needs no API key by default; it uses the You.com keyless free tier, which is rate limited per IP. Set `YOUDOTCOM_API_KEY` (free key at [you.com/platform](https://you.com/platform?utm_source=open-jarvis-openjarvis&utm_medium=oss_integration&utm_campaign=2026-09-oss-integrations&utm_content=docs)) for higher limits, or install Tavily with `uv sync --extra tools-search` and set `TAVILY_API_KEY`. Set `SERPLY_API_KEY` ([serply.io](https://serply.io)) to search through Google itself, which is the only engine here that honours Google operators such as `site:` and `after:` in a research query. A `WARNING` naming the failed engine is logged whenever search drops to the DuckDuckGo fallback.
**Wrong chunks retrieved** -- Try re-indexing with different chunk sizes. For technical documents, smaller chunks (`256`) often retrieve more precisely. For narrative text, larger chunks (`1024`) preserve more context.
diff --git a/src/openjarvis/core/credentials.py b/src/openjarvis/core/credentials.py
index 4b3d28e5..c81aa1a9 100644
--- a/src/openjarvis/core/credentials.py
+++ b/src/openjarvis/core/credentials.py
@@ -33,7 +33,7 @@ def _default_path() -> Path:
TOOL_CREDENTIALS: dict[str, list[str]] = {
- "web_search": ["TAVILY_API_KEY", "YOUDOTCOM_API_KEY"],
+ "web_search": ["TAVILY_API_KEY", "YOUDOTCOM_API_KEY", "SERPLY_API_KEY"],
"get_weather": ["OPENWEATHERMAP_API_KEY"],
"image_generate": ["OPENAI_API_KEY"],
"slack": ["SLACK_BOT_TOKEN", "SLACK_APP_TOKEN"],
@@ -71,9 +71,10 @@ TOOL_CREDENTIALS: dict[str, list[str]] = {
# by ``jarvis doctor``, and by anything else reading credential status — which
# leaves no way to describe a tool that also works without one. ``web_search``
# is the first such tool: the You.com keyless tier serves it with no key at all,
-# and both listed keys only raise limits or result quality.
+# and every listed key only raises limits, changes the engine, or improves
+# result quality.
OPTIONAL_TOOL_CREDENTIALS: dict[str, frozenset[str]] = {
- "web_search": frozenset({"TAVILY_API_KEY", "YOUDOTCOM_API_KEY"}),
+ "web_search": frozenset({"TAVILY_API_KEY", "YOUDOTCOM_API_KEY", "SERPLY_API_KEY"}),
}
diff --git a/src/openjarvis/security/data_boundary_audit.py b/src/openjarvis/security/data_boundary_audit.py
index 15c17c5d..82177274 100644
--- a/src/openjarvis/security/data_boundary_audit.py
+++ b/src/openjarvis/security/data_boundary_audit.py
@@ -69,6 +69,7 @@ API_KEY_ENV_VARS = {
),
"TAVILY_API_KEY": ("Tavily web search", {"tavily", "web_search"}),
"YOUDOTCOM_API_KEY": ("You.com web search", {"youcom", "web_search"}),
+ "SERPLY_API_KEY": ("Serply web search", {"serply", "web_search"}),
}
CHANNEL_SECRET_FIELDS: tuple[tuple[str, str, str], ...] = (
@@ -1085,15 +1086,27 @@ def _web_search_destination() -> str:
source of truth; ``test_data_boundary_audit`` asserts the two agree.
"""
engine = (os.environ.get("OPENJARVIS_WEB_SEARCH_ENGINE") or "auto").strip().lower()
- if engine not in {"auto", "youcom", "tavily", "duckduckgo"}:
+ if engine not in {"auto", "youcom", "tavily", "duckduckgo", "serply"}:
engine = "auto"
if engine == "auto":
- engine = "tavily" if os.environ.get("TAVILY_API_KEY") else "youcom"
+ if os.environ.get("TAVILY_API_KEY"):
+ engine = "tavily"
+ elif os.environ.get("YOUDOTCOM_API_KEY"):
+ engine = "youcom"
+ elif os.environ.get("SERPLY_API_KEY"):
+ engine = "serply"
+ else:
+ engine = "youcom"
if engine == "tavily":
return "Tavily web search API"
if engine == "duckduckgo":
return "DuckDuckGo (HTML scrape)"
+ if engine == "serply":
+ location = os.environ.get("SERPLY_PROXY_LOCATION")
+ if location:
+ return f"Serply web search API (Google SERP, region {location})"
+ return "Serply web search API (Google SERP)"
tier = "keyed" if os.environ.get("YOUDOTCOM_API_KEY") else "keyless free tier"
return f"You.com web search API ({tier})"
diff --git a/src/openjarvis/tools/web_search.py b/src/openjarvis/tools/web_search.py
index e50d7619..75558e37 100644
--- a/src/openjarvis/tools/web_search.py
+++ b/src/openjarvis/tools/web_search.py
@@ -7,7 +7,8 @@ API-backed engine over the DuckDuckGo HTML scrape:
* ``TAVILY_API_KEY`` set → Tavily (unchanged for existing installs)
* ``YOUDOTCOM_API_KEY`` set → You.com, keyed
-* neither → You.com, keyless free tier (no signup, rate limited per IP)
+* ``SERPLY_API_KEY`` set → Serply, a Google SERP proxy
+* none of them → You.com, keyless free tier (no signup, rate limited per IP)
The keyless tier is what makes a fresh install API-backed with zero config.
DuckDuckGo remains the last resort for every engine, and dropping to it is now
@@ -36,8 +37,14 @@ YOUCOM_KEYLESS_SEARCH_URL = "https://api.you.com/v1/agents/search"
YOUCOM_CONTENTS_URL = "https://api.you.com/v1/contents"
YOUCOM_API_KEY_ENV = "YOUDOTCOM_API_KEY"
+SERPLY_SEARCH_URL = "https://api.serply.io/v1/search"
+SERPLY_API_KEY_ENV = "SERPLY_API_KEY"
+# Two-letter country code asking Serply for a locale-specific Google result
+# set. Unset means the API answers from its own default region.
+SERPLY_LOCATION_ENV = "SERPLY_PROXY_LOCATION"
+
ENGINE_ENV = "OPENJARVIS_WEB_SEARCH_ENGINE"
-ENGINES = ("auto", "youcom", "tavily", "duckduckgo")
+ENGINES = ("auto", "youcom", "tavily", "duckduckgo", "serply")
# Identifies OpenJarvis to You.com. The keyless tier carries no API key, so the
# User-Agent is the only attribution signal; sent to You.com hosts only.
@@ -80,6 +87,8 @@ class WebSearchTool(BaseTool):
*,
engine: str | None = None,
youcom_api_key: str | None = None,
+ serply_api_key: str | None = None,
+ serply_location: str | None = None,
):
"""Configure the search engine.
@@ -91,6 +100,8 @@ class WebSearchTool(BaseTool):
"""
self._api_key = api_key or os.environ.get("TAVILY_API_KEY")
self._youcom_api_key = youcom_api_key or os.environ.get(YOUCOM_API_KEY_ENV)
+ self._serply_api_key = serply_api_key or os.environ.get(SERPLY_API_KEY_ENV)
+ self._serply_location = serply_location or os.environ.get(SERPLY_LOCATION_ENV)
self._max_results = max_results
requested = (engine or os.environ.get(ENGINE_ENV) or "auto").strip().lower()
@@ -106,14 +117,20 @@ class WebSearchTool(BaseTool):
def _resolve_engine(self) -> str:
"""Resolve ``auto`` to a concrete engine from what the env can serve.
- Tavily wins when its key is set so existing installs are unchanged.
- Otherwise You.com handles the query — keyed if a key is present,
- keyless if not, which is the zero-config API-backed path.
+ Keyed engines come first, in the order they were added, so every
+ install that already had a key resolves exactly as it did before:
+ Tavily, then keyed You.com, then Serply. The keyless You.com tier is
+ last and remains the zero-config API-backed path, which means a Serply
+ key only ever wins over having no key at all.
"""
if self._engine != "auto":
return self._engine
if self._api_key:
return "tavily"
+ if self._youcom_api_key:
+ return "youcom"
+ if self._serply_api_key:
+ return "serply"
return "youcom"
@property
@@ -143,7 +160,11 @@ class WebSearchTool(BaseTool):
"requires_api_key": "TAVILY_API_KEY",
# web_search needs no key at all on the You.com keyless tier,
# so the keys above are upgrades rather than prerequisites.
- "optional_api_keys": ["TAVILY_API_KEY", YOUCOM_API_KEY_ENV],
+ "optional_api_keys": [
+ "TAVILY_API_KEY",
+ YOUCOM_API_KEY_ENV,
+ SERPLY_API_KEY_ENV,
+ ],
"engine": engine,
"engines": list(ENGINES),
"fallback": "duckduckgo",
@@ -347,6 +368,73 @@ class WebSearchTool(BaseTool):
return str(markdown)
return None
+ @staticmethod
+ def _format_serply_results(payload: dict[str, Any]) -> tuple[str, int]:
+ """Render a Serply search payload in the shared result format.
+
+ Only ``results`` is mapped. The payload also carries ``answers``,
+ ``knowledge_graph`` and ``related_questions``, but those are filled for
+ some queries and empty for others, so nothing here depends on them.
+ """
+ parts: list[str] = []
+ count = 0
+ for item in payload.get("results") or []:
+ title = item.get("title") or "Untitled"
+ url = item.get("link", "")
+ content = item.get("description", "")
+ parts.append(f"### {title}\nSource: {url}\nSummary: {content}")
+ count += 1
+ return "\n\n---\n\n".join(parts), count
+
+ def _serply_search(self, query: str, max_results: int) -> ToolResult:
+ """Search via Serply, which proxies Google.
+
+ The query reaches Google as written, so operators survive the round
+ trip: ``site:`` restricts the corpus and ``after:``/``before:`` bound
+ results by date, neither of which an AI-search index can honour.
+ Setting ``SERPLY_PROXY_LOCATION`` to a country code asks for that
+ country's result set instead of the API's default region.
+ """
+ import httpx
+
+ headers = {
+ "Accept": "application/json",
+ "X-Api-Key": self._serply_api_key or "",
+ }
+ if self._serply_location:
+ headers["X-Proxy-Location"] = self._serply_location
+ try:
+ response = httpx.get(
+ SERPLY_SEARCH_URL,
+ params={"q": query, "num": max_results},
+ headers=headers,
+ timeout=30.0,
+ )
+ response.raise_for_status()
+ payload = response.json()
+ except httpx.HTTPStatusError as exc:
+ status = exc.response.status_code
+ if status == 401:
+ raise _WebSearchEngineError(
+ f"Serply rejected the credential in {SERPLY_API_KEY_ENV}"
+ ) from exc
+ raise _WebSearchEngineError(
+ f"Serply search failed with HTTP {status}"
+ ) from exc
+ except (httpx.HTTPError, ValueError) as exc:
+ raise _WebSearchEngineError(f"Serply search failed: {exc}") from exc
+
+ formatted, count = self._format_serply_results(payload)
+ metadata: dict[str, Any] = {"num_results": count, "engine": "serply"}
+ if self._serply_location:
+ metadata["serply_location"] = self._serply_location
+ return ToolResult(
+ tool_name="web_search",
+ content=formatted or "No results found.",
+ success=True,
+ metadata=metadata,
+ )
+
def _duckduckgo_search(self, query: str, max_results: int) -> str:
"""Search using DuckDuckGo as fallback."""
from ddgs import DDGS
@@ -419,6 +507,8 @@ class WebSearchTool(BaseTool):
try:
if engine == "youcom":
return self._youcom_search(query, max_results)
+ if engine == "serply":
+ return self._serply_search(query, max_results)
return self._tavily_search(query, max_results)
except _WebSearchEngineError as exc:
reason = str(exc)
diff --git a/tests/core/test_credentials.py b/tests/core/test_credentials.py
index eb33f113..603aaed6 100644
--- a/tests/core/test_credentials.py
+++ b/tests/core/test_credentials.py
@@ -186,6 +186,7 @@ class TestOptionalCredentials:
assert is_credential_optional("web_search", "TAVILY_API_KEY") is True
assert is_credential_optional("web_search", "YOUDOTCOM_API_KEY") is True
+ assert is_credential_optional("web_search", "SERPLY_API_KEY") is True
def test_other_tool_keys_stay_required(self):
from openjarvis.core.credentials import is_credential_optional
@@ -213,3 +214,15 @@ class TestOptionalCredentials:
assert load_credentials(path=path)["web_search"]["YOUDOTCOM_API_KEY"] == (
"ydc-key"
)
+
+ def test_serply_key_can_be_persisted(self, tmp_path, monkeypatch):
+ """Same guard for the Serply key: declared, so the Settings UI can
+ store it, and still not required for web_search to run."""
+ from openjarvis.core.credentials import load_credentials, save_credential
+
+ path = tmp_path / "credentials.toml"
+ monkeypatch.delenv("SERPLY_API_KEY", raising=False)
+ save_credential("web_search", "SERPLY_API_KEY", "srp-key", path=path)
+ assert load_credentials(path=path)["web_search"]["SERPLY_API_KEY"] == (
+ "srp-key"
+ )
diff --git a/tests/security/test_data_boundary_audit.py b/tests/security/test_data_boundary_audit.py
index 823dff64..2214b4da 100644
--- a/tests/security/test_data_boundary_audit.py
+++ b/tests/security/test_data_boundary_audit.py
@@ -1352,6 +1352,8 @@ class TestWebSearchDestination:
for key in (
"TAVILY_API_KEY",
"YOUDOTCOM_API_KEY",
+ "SERPLY_API_KEY",
+ "SERPLY_PROXY_LOCATION",
"OPENJARVIS_WEB_SEARCH_ENGINE",
):
monkeypatch.delenv(key, raising=False)
@@ -1384,6 +1386,23 @@ class TestWebSearchDestination:
monkeypatch.setenv("OPENJARVIS_WEB_SEARCH_ENGINE", "duckduckgo")
assert "DuckDuckGo" in _web_search_destination()
+ def test_serply_is_named(self, monkeypatch):
+ from openjarvis.security.data_boundary_audit import _web_search_destination
+
+ self._clear(monkeypatch)
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-key")
+ assert "Serply" in _web_search_destination()
+
+ def test_serply_region_is_named_when_configured(self, monkeypatch):
+ """The proxy region decides which country's Google answers the query,
+ so the audit has to disclose it and not just the vendor."""
+ from openjarvis.security.data_boundary_audit import _web_search_destination
+
+ self._clear(monkeypatch)
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-key")
+ monkeypatch.setenv("SERPLY_PROXY_LOCATION", "DE")
+ assert "region DE" in _web_search_destination()
+
def test_matches_the_tool_resolution(self, monkeypatch):
"""Guard against the audit's copy of the precedence rule drifting from
WebSearchTool._resolve_engine, which is the source of truth."""
@@ -1394,18 +1413,24 @@ class TestWebSearchDestination:
"youcom": "You.com",
"tavily": "Tavily",
"duckduckgo": "DuckDuckGo",
+ "serply": "Serply",
}
+ engines = (None, "auto", "youcom", "tavily", "duckduckgo", "serply")
for tavily in (None, "tvly-key"):
for youcom in (None, "ydc-key"):
- for engine in (None, "auto", "youcom", "tavily", "duckduckgo"):
- self._clear(monkeypatch)
- if tavily:
- monkeypatch.setenv("TAVILY_API_KEY", tavily)
- if youcom:
- monkeypatch.setenv("YOUDOTCOM_API_KEY", youcom)
- if engine:
- monkeypatch.setenv("OPENJARVIS_WEB_SEARCH_ENGINE", engine)
- resolved = WebSearchTool()._resolve_engine()
- assert labels[resolved] in _web_search_destination(), (
- f"tavily={tavily} youcom={youcom} engine={engine}"
- )
+ for serply in (None, "srp-key"):
+ for engine in engines:
+ self._clear(monkeypatch)
+ if tavily:
+ monkeypatch.setenv("TAVILY_API_KEY", tavily)
+ if youcom:
+ monkeypatch.setenv("YOUDOTCOM_API_KEY", youcom)
+ if serply:
+ monkeypatch.setenv("SERPLY_API_KEY", serply)
+ if engine:
+ monkeypatch.setenv("OPENJARVIS_WEB_SEARCH_ENGINE", engine)
+ resolved = WebSearchTool()._resolve_engine()
+ assert labels[resolved] in _web_search_destination(), (
+ f"tavily={tavily} youcom={youcom} serply={serply} "
+ f"engine={engine}"
+ )
diff --git a/tests/server/test_tools_endpoint.py b/tests/server/test_tools_endpoint.py
index 4af23591..697dce3d 100644
--- a/tests/server/test_tools_endpoint.py
+++ b/tests/server/test_tools_endpoint.py
@@ -86,7 +86,8 @@ def test_weather_tool_picker_recognizes_connector_credential(tmp_path, monkeypat
def test_tool_credentials_browser_lifecycle(tmp_path, monkeypatch):
"""The browser API can save, report, and remove a Tavily key.
- ``web_search`` declares a You.com key alongside it, so status reports both.
+ ``web_search`` declares You.com and Serply keys alongside it, so status
+ reports all three.
"""
from fastapi import FastAPI
from fastapi.testclient import TestClient
@@ -96,6 +97,7 @@ def test_tool_credentials_browser_lifecycle(tmp_path, monkeypatch):
monkeypatch.setenv("OPENJARVIS_HOME", str(tmp_path / "openjarvis-home"))
monkeypatch.delenv("TAVILY_API_KEY", raising=False)
monkeypatch.delenv("YOUDOTCOM_API_KEY", raising=False)
+ monkeypatch.delenv("SERPLY_API_KEY", raising=False)
app = FastAPI()
tools_router = create_agent_manager_router(MagicMock())[3]
app.include_router(tools_router)
@@ -110,6 +112,7 @@ def test_tool_credentials_browser_lifecycle(tmp_path, monkeypatch):
assert client.get("/v1/tools/web_search/credentials/status").json() == {
"TAVILY_API_KEY": True,
"YOUDOTCOM_API_KEY": False,
+ "SERPLY_API_KEY": False,
}
deleted = client.delete(
@@ -120,6 +123,7 @@ def test_tool_credentials_browser_lifecycle(tmp_path, monkeypatch):
assert client.get("/v1/tools/web_search/credentials/status").json() == {
"TAVILY_API_KEY": False,
"YOUDOTCOM_API_KEY": False,
+ "SERPLY_API_KEY": False,
}
diff --git a/tests/tools/test_web_search.py b/tests/tools/test_web_search.py
index 7c959e9a..abd219ae 100644
--- a/tests/tools/test_web_search.py
+++ b/tests/tools/test_web_search.py
@@ -11,6 +11,19 @@ from openjarvis.core.registry import ToolRegistry
from openjarvis.tools.web_search import WebSearchTool
[email protected](autouse=True)
+def _no_ambient_serply_key(monkeypatch):
+ """Keep the Serply env out of every test in this module.
+
+ Tests here clear the Tavily and You.com keys case by case, so a third
+ engine key read from the ambient environment would flip ``auto`` and turn
+ the suite red on a machine that happens to have one set, which is the
+ failure mode reported in #972. Tests that want the key set it themselves.
+ """
+ monkeypatch.delenv("SERPLY_API_KEY", raising=False)
+ monkeypatch.delenv("SERPLY_PROXY_LOCATION", raising=False)
+
+
class TestWebSearchTool:
def test_spec_name_and_category(self):
tool = WebSearchTool(api_key="test-key")
@@ -772,6 +785,26 @@ class TestEngineSelection:
monkeypatch.delenv("OPENJARVIS_WEB_SEARCH_ENGINE", raising=False)
assert WebSearchTool()._resolve_engine() == "youcom"
+ def test_auto_prefers_serply_over_the_keyless_tier(self, monkeypatch):
+ """A Serply key only ever wins over having no key at all."""
+ monkeypatch.delenv("TAVILY_API_KEY", raising=False)
+ monkeypatch.delenv("YOUDOTCOM_API_KEY", raising=False)
+ monkeypatch.delenv("OPENJARVIS_WEB_SEARCH_ENGINE", raising=False)
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-x")
+ assert WebSearchTool()._resolve_engine() == "serply"
+
+ def test_serply_never_displaces_an_existing_keyed_engine(self, monkeypatch):
+ """Adding a Serply key must not change where an install already goes."""
+ monkeypatch.delenv("OPENJARVIS_WEB_SEARCH_ENGINE", raising=False)
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-x")
+
+ monkeypatch.setenv("TAVILY_API_KEY", "tvly-x")
+ monkeypatch.setenv("YOUDOTCOM_API_KEY", "ydc-key")
+ assert WebSearchTool()._resolve_engine() == "tavily"
+
+ monkeypatch.delenv("TAVILY_API_KEY", raising=False)
+ assert WebSearchTool()._resolve_engine() == "youcom"
+
def test_explicit_engine_overrides_key_presence(self, monkeypatch):
monkeypatch.setenv("TAVILY_API_KEY", "tvly-x")
assert WebSearchTool(engine="youcom")._resolve_engine() == "youcom"
@@ -798,6 +831,8 @@ class TestEngineSelection:
spec = WebSearchTool().spec
assert spec.metadata["engine"] == "youcom"
assert "YOUDOTCOM_API_KEY" in spec.metadata["optional_api_keys"]
+ assert "SERPLY_API_KEY" in spec.metadata["optional_api_keys"]
+ assert "serply" in spec.metadata["engines"]
# Backwards compatible for readers of the old single-key field.
assert spec.metadata["requires_api_key"] == "TAVILY_API_KEY"
@@ -956,6 +991,156 @@ class TestYouComSearch:
assert "YOUDOTCOM_API_KEY" not in result.metadata["fallback_reason"]
+class TestSerplySearch:
+ """The Serply engine, exercised against mocked HTTP."""
+
+ PAYLOAD = {
+ "results": [
+ {
+ "title": "Result A",
+ "link": "https://example.com/a",
+ "description": "Desc A",
+ "position": 1,
+ "realPosition": 1,
+ },
+ {
+ "title": "Result B",
+ "link": "https://example.com/b",
+ "description": "Desc B",
+ "position": 2,
+ "realPosition": 2,
+ },
+ ],
+ "answers": [],
+ "knowledge_graph": {},
+ "related_questions": [],
+ }
+
+ def _mock_get(self, monkeypatch, payload=None, status=200):
+ import httpx
+
+ calls = {}
+
+ def _get(url, **kwargs):
+ calls["url"] = url
+ calls["params"] = kwargs.get("params")
+ calls["headers"] = kwargs.get("headers")
+ resp = MagicMock()
+ resp.status_code = status
+ resp.json.return_value = payload if payload is not None else self.PAYLOAD
+ if status >= 400:
+ resp.text = "error body"
+ resp.raise_for_status.side_effect = httpx.HTTPStatusError(
+ f"HTTP {status}", request=MagicMock(), response=resp
+ )
+ else:
+ resp.raise_for_status = MagicMock()
+ return resp
+
+ monkeypatch.setattr(httpx, "get", _get)
+ return calls
+
+ def test_endpoint_and_key_header(self, monkeypatch):
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-x")
+ calls = self._mock_get(monkeypatch)
+
+ result = WebSearchTool(engine="serply").execute(query="test query")
+
+ assert result.success is True
+ assert calls["url"] == "https://api.serply.io/v1/search"
+ assert calls["headers"]["X-Api-Key"] == "srp-x"
+ assert result.metadata["engine"] == "serply"
+
+ def test_result_format_matches_the_other_engines(self, monkeypatch):
+ """Same labeled Source/Summary shape agents already parse (#390)."""
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-x")
+ self._mock_get(monkeypatch)
+
+ result = WebSearchTool(engine="serply").execute(query="test query")
+
+ assert "### Result A" in result.content
+ assert "Source: https://example.com/a" in result.content
+ assert "Summary: Desc A" in result.content
+ assert "### Result B" in result.content
+ assert result.metadata["num_results"] == 2
+
+ def test_max_results_passed_as_num(self, monkeypatch):
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-x")
+ calls = self._mock_get(monkeypatch)
+ WebSearchTool(engine="serply", max_results=3).execute(query="q", max_results=7)
+ assert calls["params"] == {"q": "q", "num": 7}
+
+ def test_query_reaches_the_api_unmodified(self, monkeypatch):
+ """The point of a SERP proxy is that Google's operators survive, so
+ nothing here may rewrite, quote or strip the query."""
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-x")
+ calls = self._mock_get(monkeypatch)
+
+ query = "transformer inference site:arxiv.org after:2026-01-01"
+ WebSearchTool(engine="serply").execute(query=query)
+
+ assert calls["params"]["q"] == query
+
+ def test_empty_results(self, monkeypatch):
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-x")
+ self._mock_get(monkeypatch, payload={"results": []})
+ result = WebSearchTool(engine="serply").execute(query="q")
+ assert result.success is True
+ assert result.content == "No results found."
+
+ def test_no_proxy_location_header_by_default(self, monkeypatch):
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-x")
+ calls = self._mock_get(monkeypatch)
+
+ result = WebSearchTool(engine="serply").execute(query="q")
+
+ assert "X-Proxy-Location" not in calls["headers"]
+ assert "serply_location" not in result.metadata
+
+ def test_proxy_location_header_when_configured(self, monkeypatch):
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-x")
+ monkeypatch.setenv("SERPLY_PROXY_LOCATION", "DE")
+ calls = self._mock_get(monkeypatch)
+
+ result = WebSearchTool(engine="serply").execute(query="q")
+
+ assert calls["headers"]["X-Proxy-Location"] == "DE"
+ assert result.metadata["serply_location"] == "DE"
+
+ def test_rejected_key_names_the_env_var(self, monkeypatch):
+ """A 401 is a credential problem, and the fallback reason has to say
+ which variable to fix rather than just 'HTTP 401'."""
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-bad")
+ self._mock_get(monkeypatch, status=401)
+
+ mock_ddgs = MagicMock()
+ mock_ddgs.text.return_value = []
+ mock_module = MagicMock()
+ mock_module.DDGS.return_value = mock_ddgs
+ monkeypatch.setitem(sys.modules, "ddgs", mock_module)
+
+ result = WebSearchTool(engine="serply").execute(query="q")
+
+ assert result.metadata["fallback_from"] == "serply"
+ assert result.metadata["degraded"] is True
+ assert "SERPLY_API_KEY" in result.metadata["fallback_reason"]
+
+ def test_other_http_error_reports_the_status(self, monkeypatch):
+ monkeypatch.setenv("SERPLY_API_KEY", "srp-x")
+ self._mock_get(monkeypatch, status=500)
+
+ mock_ddgs = MagicMock()
+ mock_ddgs.text.return_value = []
+ mock_module = MagicMock()
+ mock_module.DDGS.return_value = mock_ddgs
+ monkeypatch.setitem(sys.modules, "ddgs", mock_module)
+
+ result = WebSearchTool(engine="serply").execute(query="q")
+
+ assert "HTTP 500" in result.metadata["fallback_reason"]
+ assert "SERPLY_API_KEY" not in result.metadata["fallback_reason"]
+
+
class TestFallbackVisibility:
def test_fallback_is_logged_at_warning(self, monkeypatch, caplog):
"""Regression for the silent-degradation half of #923: a typo'd key