feat(web_search): add opt-in Parallel provider

This commit is contained in:
Rowan Aldean 2026-09-30 23:18:16 +01:00 • committed by Cursor Agent
parent 6b7ae2ebe4
commit cdf2c92d2b
No known key found for this signature in database
6 changed files with 314 additions and 7 deletions

View file

@ -141,9 +141,25 @@ affecting the agents that do the actual testing.
</ParamField>
<ParamField path="STRIX_WEB_SEARCH_PROVIDER" default="auto" type="string">
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.
</ParamField>
<ParamField path="PARALLEL_API_KEY" type="string">
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`.
</ParamField>
```bash
export STRIX_WEB_SEARCH_PROVIDER="parallel"
export PARALLEL_API_KEY="your-parallel-api-key"
```
<ParamField path="STRIX_EXA_SEARCH_TYPE" default="auto" type="string">
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.
</ParamField>

View file

@ -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",

View file

@ -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",

View file

@ -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):

View file

@ -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:

View file

@ -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"]