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.mdindex 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 Stepsdiff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.mdindex 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 moniWeb search works with no configuration: queries go to the You.com keylessfree 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:```bashexport 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 fallbackfor every engine; dropping to it is logged at `WARNING`, since its scrapedresults 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 serverbefore 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 Examplediff --git a/docs/user-guide/deep-research.md b/docs/user-guide/deep-research.mdindex 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.pyindex 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.pyindex 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.pyindex 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_resultsrequested = (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._engineif 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.pyindex 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 Trueassert is_credential_optional("web_search", "YOUDOTCOM_API_KEY") is True+ assert is_credential_optional("web_search", "SERPLY_API_KEY") is Truedef 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.pyindex 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 fromWebSearchTool._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.pyindex 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, monkeypatdef 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 FastAPIfrom 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.pyindex 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 ToolRegistryfrom 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().specassert 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