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