diff --git a/docs/advanced/configuration.mdx b/docs/advanced/configuration.mdx index 2048eefe6..c05b2acda 100644 --- a/docs/advanced/configuration.mdx +++ b/docs/advanced/configuration.mdx @@ -125,9 +125,27 @@ 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. Excerpts are shortened to keep output within 12,000 characters + plus a truncation notice. Source titles and URLs are always preserved, even if + those headers alone exceed the budget. + 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 eb61a793d..e1fca0d0f 100644 --- a/strix/config/settings.py +++ b/strix/config/settings.py @@ -170,7 +170,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"] @@ -187,6 +187,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..6717dd4a3 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,71 @@ 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_result_content(results: list[tuple[str, str]]) -> str: + # Reserve every source header before spending the remaining budget on excerpts. + header_chars = sum(len(header) for header, _ in results) + 2 * (len(results) - 1) + remaining = max(0, _PARALLEL_MAX_CHARS - header_chars) + blocks: list[str] = [] + truncated = False + for header, excerpts in results: + excerpt = excerpts[: max(0, remaining - 2)] + blocks.append(f"{header}\n\n{excerpt}" if excerpt else header) + if excerpt: + remaining -= len(excerpt) + 2 + truncated |= len(excerpt) < len(excerpts) + content = "\n\n".join(blocks) + if truncated: + content += "\n[excerpts truncated to preserve source links]" + return content + + +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[tuple[str, 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"]) + header = f"### {result.get('title') or url}\n{url}" + parts: list[str] = [] + 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((header, "\n\n".join(parts))) + if not blocks: + raise ValueError("Parallel response has no usable results") + return _parallel_result_content(blocks) + + 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 +242,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 +285,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 +302,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 +324,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 +397,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 +433,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..20e2b2134 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,214 @@ 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") + notice = "\n[excerpts truncated to preserve source links]" + assert result.endswith(notice) + assert len(result) == 12000 + len(notice) + + +@pytest.mark.parametrize("first_excerpt_size", [11920, 20000]) +def test_parallel_truncation_keeps_all_source_headers( + monkeypatch: pytest.MonkeyPatch, + first_excerpt_size: int, +) -> None: + results = [ + { + "title": f"Vendor advisory {index}", + "url": f"https://vendor.example/advisory/{index}/" + "a" * 100, + "excerpts": ["x" * (first_excerpt_size if index == 0 else 2000)], + } + for index in range(5) + ] + monkeypatch.setattr( + requests, + "post", + lambda *_a, **_kw: _FakeResponse({"results": results}), + ) + content = tool._parallel_content("key", "vendor advisories") + for result in results: + assert f"### {result['title']}\n{result['url']}" in content + notice = "\n[excerpts truncated to preserve source links]" + assert content.endswith(notice) + assert len(content) <= 12000 + len(notice) + + +@pytest.mark.parametrize("spare_chars", [-1, 0, 1, 2, 3]) +def test_parallel_keeps_headers_when_no_excerpt_fits( + monkeypatch: pytest.MonkeyPatch, + spare_chars: int, +) -> None: + headers = ["### First\nhttps://first.example", "### Second\nhttps://second.example"] + header_text = "\n\n".join(headers) + monkeypatch.setattr(tool, "_PARALLEL_MAX_CHARS", len(header_text) + spare_chars) + content = tool._parallel_result_content([(header, "excerpt") for header in headers]) + assert all(header in content for header in headers) + notice = "\n[excerpts truncated to preserve source links]" + assert content.endswith(notice) + assert len(content) <= max(len(header_text), tool._PARALLEL_MAX_CHARS) + len(notice) + + +@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"]