mirror of
https://github.com/usestrix/strix.git
synced 2026-11-16 09:21:54 +00:00
feat(web_search): add opt-in Parallel provider
This commit is contained in:
parent
6b7ae2ebe4
commit
cdf2c92d2b
6 changed files with 314 additions and 7 deletions
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
|
|
@ -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):
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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"]
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue