From cdf2c92d2b80405320cc2b127b1c392fb1a0a1ec Mon Sep 17 00:00:00 2001
From: Rowan Aldean <56801656+RowanAldean@users.noreply.github.com>
Date: Wed, 30 Sep 2026 23:18:16 +0100
Subject: [PATCH] feat(web_search): add opt-in Parallel provider
---
docs/advanced/configuration.mdx | 18 ++-
strix/config/settings.py | 7 +-
strix/interface/environment.py | 9 ++
strix/tools/web_search/tool.py | 75 ++++++++++++-
tests/test_config_loader.py | 25 +++++
tests/test_web_search.py | 187 +++++++++++++++++++++++++++++++-
6 files changed, 314 insertions(+), 7 deletions(-)
diff --git a/docs/advanced/configuration.mdx b/docs/advanced/configuration.mdx
index 247c0994e..fac557e38 100644
--- a/docs/advanced/configuration.mdx
+++ b/docs/advanced/configuration.mdx
@@ -141,9 +141,25 @@ affecting the agents that do the actual testing.
- Web search provider: `auto`, `perplexity`, or `exa`. With `auto`, Strix uses Exa when `EXA_API_KEY` is set, and Perplexity otherwise. Set an explicit provider to pin one when you configure both keys.
+ Web search provider: `auto`, `perplexity`, `exa`, or `parallel`. With `auto`, Strix uses Exa when `EXA_API_KEY` is set, and Perplexity otherwise. Set an explicit provider to pin one. Parallel is opt-in and must be selected explicitly.
+
+ API key for [Parallel Search](https://docs.parallel.ai/search/search-quickstart).
+ Set `STRIX_WEB_SEARCH_PROVIDER=parallel` to use it for the built-in `web_search` tool.
+ Requests use `/v1/search` in `fast` mode, returning up to five source URLs with
+ relevant excerpts. Output is capped at 12,000 characters plus a truncation notice.
+ Queries may contain up to 5,000 characters; the full query is the search objective,
+ with its first 200 characters also supplied as a search query.
+ This uses the authenticated API, not the free Search MCP. `web_get_contents`
+ remains Exa-only and requires `EXA_API_KEY`.
+
+
+```bash
+export STRIX_WEB_SEARCH_PROVIDER="parallel"
+export PARALLEL_API_KEY="your-parallel-api-key"
+```
+
Exa search mode: `auto`, `fast`, `instant`, `deep-lite`, `deep`, or `deep-reasoning`. Lower modes return results faster. Higher modes plan across more steps and take more time. This setting applies only to the Exa provider.
diff --git a/strix/config/settings.py b/strix/config/settings.py
index 9b216aa99..35314598b 100644
--- a/strix/config/settings.py
+++ b/strix/config/settings.py
@@ -179,7 +179,7 @@ class TelemetrySettings(BaseSettings):
run_record_timings: bool = Field(default=False, alias="STRIX_RUN_RECORD_TIMINGS")
-WebSearchProvider = Literal["auto", "perplexity", "exa"]
+WebSearchProvider = Literal["auto", "perplexity", "exa", "parallel"]
ExaSearchType = Literal["auto", "fast", "instant", "deep-lite", "deep", "deep-reasoning"]
@@ -196,6 +196,11 @@ class IntegrationSettings(BaseSettings):
alias="EXA_API_KEY",
repr=False,
)
+ parallel_api_key: str | None = Field(
+ default=None,
+ alias="PARALLEL_API_KEY",
+ repr=False,
+ )
web_search_provider: WebSearchProvider = Field(
default="auto",
alias="STRIX_WEB_SEARCH_PROVIDER",
diff --git a/strix/interface/environment.py b/strix/interface/environment.py
index 522067df8..e7ee0634d 100644
--- a/strix/interface/environment.py
+++ b/strix/interface/environment.py
@@ -26,6 +26,8 @@ def _missing_web_search_vars(integrations: IntegrationSettings) -> list[str]:
return [] if integrations.exa_api_key else ["EXA_API_KEY"]
if integrations.web_search_provider == "perplexity":
return [] if integrations.perplexity_api_key else ["PERPLEXITY_API_KEY"]
+ if integrations.web_search_provider == "parallel":
+ return [] if integrations.parallel_api_key else ["PARALLEL_API_KEY"]
if integrations.exa_api_key or integrations.perplexity_api_key:
return []
return ["EXA_API_KEY", "PERPLEXITY_API_KEY"]
@@ -111,6 +113,9 @@ def validate_environment() -> None:
" - API key for Exa web search (enables real-time research)\n",
style="white",
)
+ elif var == "PARALLEL_API_KEY":
+ error_text.append("• PARALLEL_API_KEY", style="bold cyan")
+ error_text.append(" - API key for Parallel web search\n", style="white")
elif var == "STRIX_REASONING_EFFORT":
error_text.append("• ", style="white")
error_text.append("STRIX_REASONING_EFFORT", style="bold cyan")
@@ -137,6 +142,10 @@ def validate_environment() -> None:
)
elif var == "EXA_API_KEY":
error_text.append("export EXA_API_KEY='your-exa-key-here'\n", style="dim white")
+ elif var == "PARALLEL_API_KEY":
+ error_text.append(
+ "export PARALLEL_API_KEY='your-parallel-key-here'\n", style="dim white"
+ )
elif var == "STRIX_REASONING_EFFORT":
error_text.append(
"export STRIX_REASONING_EFFORT='high'\n",
diff --git a/strix/tools/web_search/tool.py b/strix/tools/web_search/tool.py
index f525b1ea4..656701f35 100644
--- a/strix/tools/web_search/tool.py
+++ b/strix/tools/web_search/tool.py
@@ -1,4 +1,4 @@
-"""Security-focused web research tools (Exa or Perplexity)."""
+"""Security-focused web research tools (Exa, Perplexity, or Parallel)."""
from __future__ import annotations
@@ -133,6 +133,55 @@ def _exa_content(api_key: str, query: str, search_type: str, num_results: int) -
return "\n\n".join(blocks)
+_PARALLEL_MAX_CHARS = 12000
+
+
+def _parallel_content(api_key: str, query: str) -> str:
+ with requests.post(
+ "https://api.parallel.ai/v1/search",
+ headers={"x-api-key": api_key, "Content-Type": "application/json"},
+ json={
+ "objective": query,
+ "search_queries": [query[:200]],
+ "mode": "fast",
+ "max_chars_total": _PARALLEL_MAX_CHARS,
+ "advanced_settings": {"max_results": 5},
+ },
+ timeout=300,
+ ) as response:
+ response.raise_for_status()
+ body = response.json()
+ if not isinstance(body, dict):
+ raise TypeError("Parallel response must be an object")
+ results: list[Any] | None = cast("dict[str, Any]", body).get("results")
+ if not isinstance(results, list):
+ raise TypeError("Parallel response has no results list")
+ if not results:
+ return "No web search results found."
+
+ blocks: list[str] = []
+ for item in results[:5]:
+ if not isinstance(item, dict):
+ continue
+ result = cast("dict[str, Any]", item)
+ if not result.get("url"):
+ continue
+ url = str(result["url"])
+ parts = [f"### {result.get('title') or url}\n{url}"]
+ excerpts: list[Any] | None = result.get("excerpts")
+ if isinstance(excerpts, list):
+ parts.extend(
+ text.strip() for text in excerpts if isinstance(text, str) and text.strip()
+ )
+ blocks.append("\n\n".join(parts))
+ if not blocks:
+ raise ValueError("Parallel response has no usable results")
+ content = "\n\n".join(blocks)
+ if len(content) > _PARALLEL_MAX_CHARS:
+ return f"{content[:_PARALLEL_MAX_CHARS]}\n[truncated at {_PARALLEL_MAX_CHARS} characters]"
+ return content
+
+
def _normalize_url(url: str) -> str:
"""Canonical form for matching: case-fold scheme and host only, drop a trailing slash."""
parts = urlsplit(url.strip())
@@ -177,6 +226,10 @@ def _resolve_provider( # noqa: PLR0911 - each provider/missing-key case needs i
if not exa_key:
return _not_configured_error("EXA_API_KEY")
return ("exa", exa_key)
+ if provider == "parallel":
+ if not integrations.parallel_api_key:
+ return _not_configured_error("PARALLEL_API_KEY")
+ return ("parallel", integrations.parallel_api_key)
if exa_key:
return ("exa", exa_key)
@@ -216,7 +269,7 @@ def _guarded_call[T]( # noqa: PLR0911 - each error class needs its own sanitize
except requests.exceptions.RequestException:
logger.exception("%s network error", tool)
return {"success": False, "error": f"{tool} network error. Try again later"}
- except (KeyError, IndexError, ValueError):
+ except (KeyError, IndexError, TypeError, ValueError):
logger.exception("%s response shape unexpected", tool)
return {"success": False, "error": f"{tool} returned an unexpected response. Try again"}
except Exception:
@@ -233,9 +286,16 @@ def _do_search(query: str) -> dict[str, Any]:
if isinstance(resolved, dict):
return resolved
provider, api_key = resolved
+ if provider == "parallel" and len(query) > 5000:
+ return {
+ "success": False,
+ "error": "Parallel search queries must be at most 5000 characters",
+ }
logger.info("web_search provider=%s query (len=%d): %s", provider, len(query), query[:120])
def fetch() -> str:
+ if provider == "parallel":
+ return _parallel_content(api_key, query)
if provider == "exa":
return _exa_content(
api_key,
@@ -248,7 +308,10 @@ def _do_search(query: str) -> dict[str, Any]:
outcome = _guarded_call(
"Web search",
(
- "Web search rejected the query. Refine it "
+ "Parallel rejected the request. Check PARALLEL_API_KEY, account credits, "
+ "rate limits, and query length"
+ if provider == "parallel"
+ else "Web search rejected the query. Refine it "
"(more specific, shorter, no unusual characters) and retry"
),
fetch,
@@ -318,7 +381,7 @@ def _do_get_contents(urls: list[str]) -> dict[str, Any]:
@function_tool(timeout=330)
async def web_search(ctx: RunContextWrapper, query: str) -> str:
- """Real-time web search (Exa or Perplexity) — your primary research tool.
+ """Real-time web search (Exa, Perplexity, or Parallel) — your primary research tool.
Use it liberally for anything that's not in your training data:
@@ -354,6 +417,10 @@ async def web_search(ctx: RunContextWrapper, query: str) -> str:
full page text when a summary is not enough. With Perplexity you get
a single synthesized cited answer.
+ With Parallel you get ranked titles, source URLs, and relevant excerpts,
+ capped to keep the response concise. These are source excerpts, not a
+ synthesized answer. ``web_get_contents`` still requires an Exa key.
+
**Good example queries** (each is a full sentence, names a
version/product, and asks one concrete thing):
diff --git a/tests/test_config_loader.py b/tests/test_config_loader.py
index 463853d22..0a42d11c6 100644
--- a/tests/test_config_loader.py
+++ b/tests/test_config_loader.py
@@ -31,6 +31,7 @@ _LLM_ENV_KEYS = [
"LLM_TIMEOUT",
"PERPLEXITY_API_KEY",
"EXA_API_KEY",
+ "PARALLEL_API_KEY",
"STRIX_WEB_SEARCH_PROVIDER",
# RuntimeSettings
"STRIX_IMAGE",
@@ -99,6 +100,30 @@ def test_read_json_overrides_maps_exa_and_provider(tmp_path: Path) -> None:
}
+def test_parallel_settings_persistence_and_env_precedence(
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ target = tmp_path / "cli-config.json"
+ loader.apply_config_override(target)
+ monkeypatch.setenv("STRIX_WEB_SEARCH_PROVIDER", "parallel")
+ monkeypatch.setenv("PARALLEL_API_KEY", "parallel-file-key")
+ loader.persist_current()
+ assert target.stat().st_mode & 0o777 == 0o600
+
+ monkeypatch.delenv("PARALLEL_API_KEY")
+ monkeypatch.delenv("STRIX_WEB_SEARCH_PROVIDER")
+ loader.apply_config_override(target)
+ integrations = loader.load_settings().integrations
+ assert integrations.web_search_provider == "parallel"
+ assert integrations.parallel_api_key == "parallel-file-key"
+ assert "parallel-file-key" not in repr(integrations)
+
+ monkeypatch.setenv("PARALLEL_API_KEY", "parallel-env-key")
+ loader.apply_config_override(target)
+ assert loader.load_settings().integrations.parallel_api_key == "parallel-env-key"
+
+
def test_read_json_overrides_skips_keys_already_in_environ(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
diff --git a/tests/test_web_search.py b/tests/test_web_search.py
index 6aff26ba1..96ff9653f 100644
--- a/tests/test_web_search.py
+++ b/tests/test_web_search.py
@@ -1,4 +1,4 @@
-"""Tests for web_search/web_get_contents provider selection and the Exa backend."""
+"""Tests for web_search/web_get_contents provider selection and backends."""
from __future__ import annotations
@@ -34,6 +34,19 @@ class _FakeResponse:
return self._body
+@pytest.fixture(autouse=True)
+def _isolate_search_settings(monkeypatch: pytest.MonkeyPatch) -> None:
+ for key in (
+ "PERPLEXITY_API_KEY",
+ "EXA_API_KEY",
+ "PARALLEL_API_KEY",
+ "STRIX_WEB_SEARCH_PROVIDER",
+ "STRIX_EXA_SEARCH_TYPE",
+ "STRIX_EXA_NUM_RESULTS",
+ ):
+ monkeypatch.delenv(key, raising=False)
+
+
def test_auto_prefers_exa_when_both_keys_set() -> None:
integrations = IntegrationSettings(PERPLEXITY_API_KEY="pk", EXA_API_KEY="ek")
assert tool._resolve_provider(integrations) == ("exa", "ek")
@@ -167,6 +180,9 @@ def test_do_search_reports_empty_exa_results_as_unexpected(
({"STRIX_WEB_SEARCH_PROVIDER": "exa", "EXA_API_KEY": "ek"}, []),
({"STRIX_WEB_SEARCH_PROVIDER": "perplexity", "EXA_API_KEY": "ek"}, ["PERPLEXITY_API_KEY"]),
({"STRIX_WEB_SEARCH_PROVIDER": "perplexity", "PERPLEXITY_API_KEY": "pk"}, []),
+ ({"STRIX_WEB_SEARCH_PROVIDER": "parallel", "EXA_API_KEY": "ek"}, ["PARALLEL_API_KEY"]),
+ ({"STRIX_WEB_SEARCH_PROVIDER": "parallel", "PARALLEL_API_KEY": "key"}, []),
+ ({"PARALLEL_API_KEY": "key"}, ["EXA_API_KEY", "PERPLEXITY_API_KEY"]),
],
)
def test_environment_validation_follows_provider_rules(
@@ -414,3 +430,172 @@ def test_do_search_reports_the_provider_it_used(monkeypatch: pytest.MonkeyPatch)
"provider": "exa",
"content": "answer",
}
+
+
+@pytest.mark.parametrize(
+ ("provider", "keys", "expected"),
+ [
+ ("parallel", {"PARALLEL_API_KEY": "key", "EXA_API_KEY": "ek"}, ("parallel", "key")),
+ ("parallel", {"EXA_API_KEY": "ek"}, "PARALLEL_API_KEY"),
+ ("auto", {"PARALLEL_API_KEY": "key", "EXA_API_KEY": "ek"}, ("exa", "ek")),
+ ("auto", {"PARALLEL_API_KEY": "key", "PERPLEXITY_API_KEY": "pk"}, ("perplexity", "pk")),
+ ("auto", {"PARALLEL_API_KEY": "key"}, "EXA_API_KEY or PERPLEXITY_API_KEY"),
+ ],
+)
+def test_parallel_selection_is_opt_in(
+ provider: str,
+ keys: dict[str, str],
+ expected: tuple[str, str] | str,
+) -> None:
+ integrations = IntegrationSettings.model_validate(
+ {"STRIX_WEB_SEARCH_PROVIDER": provider, **keys}
+ )
+ result = tool._resolve_provider(integrations)
+ if isinstance(expected, str):
+ assert isinstance(result, dict)
+ assert result["success"] is False
+ assert expected in result["error"]
+ else:
+ assert result == expected
+
+
+@pytest.fixture
+def _parallel_settings(monkeypatch: pytest.MonkeyPatch) -> None:
+ class _Settings:
+ integrations = IntegrationSettings(
+ STRIX_WEB_SEARCH_PROVIDER="parallel",
+ PARALLEL_API_KEY="test-parallel-secret",
+ )
+
+ monkeypatch.setattr(tool, "load_settings", _Settings)
+
+
+@pytest.mark.usefixtures("_parallel_settings")
+def test_parallel_request_and_tool_response(monkeypatch: pytest.MonkeyPatch) -> None:
+ captured: dict[str, Any] = {}
+
+ def fake_post(url: str, **kwargs: Any) -> _FakeResponse:
+ captured.update(url=url, **kwargs)
+ return _FakeResponse(
+ {
+ "results": [
+ {
+ "title": "Vendor advisory",
+ "url": "https://vendor.example/advisory",
+ "excerpts": [" Affected versions. ", "Fixed versions."],
+ },
+ {"title": None, "url": "https://vendor.example/docs", "excerpts": []},
+ {"title": "Missing URL"},
+ "malformed entry",
+ ]
+ }
+ )
+
+ monkeypatch.setattr(requests, "post", fake_post)
+ query = "Find affected versions and mitigations in the vendor advisory. " * 4
+ result = tool._do_search(query)
+ assert captured["url"] == "https://api.parallel.ai/v1/search"
+ assert captured["headers"] == {
+ "x-api-key": "test-parallel-secret",
+ "Content-Type": "application/json",
+ }
+ assert captured["json"] == {
+ "objective": query,
+ "search_queries": [query[:200]],
+ "mode": "fast",
+ "max_chars_total": 12000,
+ "advanced_settings": {"max_results": 5},
+ }
+ assert captured["timeout"] == 300
+ assert result == {
+ "success": True,
+ "query": query,
+ "provider": "parallel",
+ "content": "### Vendor advisory\nhttps://vendor.example/advisory\n\n"
+ "Affected versions.\n\nFixed versions.\n\n"
+ "### https://vendor.example/docs\nhttps://vendor.example/docs",
+ }
+
+
+@pytest.mark.usefixtures("_parallel_settings")
+@pytest.mark.parametrize(
+ ("body", "success", "text"),
+ [
+ ({"results": []}, True, "No web search results found."),
+ ({}, False, "unexpected response"),
+ ({"results": "invalid"}, False, "unexpected response"),
+ ({"results": [{"title": "No URL"}]}, False, "unexpected response"),
+ ],
+)
+def test_parallel_empty_or_malformed_results(
+ monkeypatch: pytest.MonkeyPatch,
+ body: dict[str, Any],
+ success: bool,
+ text: str,
+) -> None:
+ monkeypatch.setattr(requests, "post", lambda *_a, **_kw: _FakeResponse(body))
+ result = tool._do_search("vendor advisory")
+ assert result["success"] is success
+ assert text in result["content" if success else "error"]
+
+
+def test_parallel_caps_output(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setattr(
+ requests,
+ "post",
+ lambda *_a, **_kw: _FakeResponse(
+ {
+ "results": [{"url": "https://vendor.example", "excerpts": ["x" * 20000]}],
+ }
+ ),
+ )
+ result = tool._parallel_content("key", "vendor advisory")
+ assert result.startswith("### https://vendor.example\nhttps://vendor.example")
+ assert result.endswith("\n[truncated at 12000 characters]")
+ assert len(result) == 12000 + len("\n[truncated at 12000 characters]")
+
+
+@pytest.mark.usefixtures("_parallel_settings")
+@pytest.mark.parametrize("status", [401, 402, 422, 429, 503])
+def test_parallel_http_failures_are_sanitized(monkeypatch: pytest.MonkeyPatch, status: int) -> None:
+ def fail(*_args: Any, **_kwargs: Any) -> _FakeResponse:
+ response = requests.Response()
+ response.status_code = status
+ raise requests.HTTPError("test-parallel-secret: upstream body", response=response)
+
+ monkeypatch.setattr(requests, "post", fail)
+ result = tool._do_search("vendor advisory")
+ assert result["success"] is False
+ assert "test-parallel-secret" not in result["error"]
+ assert "upstream body" not in result["error"]
+ assert ("PARALLEL_API_KEY" if status < 500 else "unavailable") in result["error"]
+
+
+@pytest.mark.usefixtures("_parallel_settings")
+@pytest.mark.parametrize(
+ ("exception", "message"),
+ [(requests.Timeout, "timed out"), (requests.ConnectionError, "network error")],
+)
+def test_parallel_network_failures(
+ monkeypatch: pytest.MonkeyPatch,
+ exception: type[requests.RequestException],
+ message: str,
+) -> None:
+ def fail(*_args: Any, **_kwargs: Any) -> _FakeResponse:
+ raise exception("upstream error")
+
+ monkeypatch.setattr(requests, "post", fail)
+ result = tool._do_search("vendor advisory")
+ assert result["success"] is False
+ assert message in result["error"]
+
+
+@pytest.mark.usefixtures("_parallel_settings")
+def test_parallel_rejects_oversized_objective_before_http(monkeypatch: pytest.MonkeyPatch) -> None:
+ def unexpected_call(*_args: Any, **_kwargs: Any) -> _FakeResponse:
+ pytest.fail("Invalid input must not make a request")
+
+ monkeypatch.setattr(requests, "post", unexpected_call)
+ result = tool._do_search("x" * 5001)
+ assert result["success"] is False
+ assert "5000" in result["error"]