From 30104f38ce67404f663e528ef21ef03c9fa5fa6b Mon Sep 17 00:00:00 2001 From: Gilad Katz <29776916+giladk1221@users.noreply.github.com> Date: Wed, 23 Sep 2026 01:15:51 +0300 Subject: [PATCH] fix(search): protect WebIQ result fields and simplify endpoint configuration --- cookbook/webiq/README.md | 78 ------------------- litellm/llms/webiq/search/transformation.py | 25 ++++-- .../test_webiq_search_transformation.py | 77 +++++++++++++++--- 3 files changed, 86 insertions(+), 94 deletions(-) delete mode 100644 cookbook/webiq/README.md diff --git a/cookbook/webiq/README.md b/cookbook/webiq/README.md deleted file mode 100644 index ead1214303b..00000000000 --- a/cookbook/webiq/README.md +++ /dev/null @@ -1,78 +0,0 @@ -# Microsoft Web IQ search - -Use `search_provider="webiq"` with a Microsoft Web IQ API key. This integration calls the [Web Search v3 REST API](https://webiq.microsoft.ai/documentation/api-reference/web/), which is separate from Grounding with Bing - -Set `WEBIQ_API_KEY` in the process environment or pass `api_key` explicitly. The provider sends it in the `x-apikey` header. This initial integration uses API-key authentication; it does not acquire or refresh Entra ID tokens - -```python -import asyncio -from litellm import asearch, search - -result = search( - query="retrieval augmented generation research", - search_provider="webiq", - max_results=5, - country="US", -) -print(result.model_dump()) - -async def main(): - result = await asearch(query="retrieval augmented generation research", search_provider="webiq") - print(result.model_dump()) - -asyncio.run(main()) -``` - -The provider requests `contentFormat="passage"` and `maxLength=5000` by default, following the [Web IQ quick start](https://webiq.microsoft.ai/documentation/). `content` becomes the standard result's `snippet`, while `lastUpdatedAt` supplies `date` and `last_updated` when available. Crawl timestamps are preserved as `crawledAt`, not presented as publication dates. Other response metadata, including `traceId` and instrumentation fields, is preserved; the integration does not send instrumentation pings - -## Gateway - -Add this search tool to your existing proxy configuration: - -```yaml -search_tools: - - search_tool_name: webiq-search - litellm_params: - search_provider: webiq - api_key: os.environ/WEBIQ_API_KEY -``` - -Set `LITELLM_PROXY_URL` to your existing LiteLLM deployment URL, without a trailing slash. This is the gateway URL your application calls; the provider itself calls `https://api.microsoft.ai/v3/search/web` - -```bash -curl "$LITELLM_PROXY_URL/v1/search/webiq-search" \ - -H "Authorization: Bearer $LITELLM_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{"query":"retrieval augmented generation research","max_results":5}' -``` - -To select Web IQ for existing web-search interception, merge these settings into the proxy configuration. Set `enabled_providers` to the model providers used by your application; this example selects Bedrock - -```yaml -litellm_settings: - callbacks: - - websearch_interception - websearch_interception_params: - search_tool_name: webiq-search - enabled_providers: ["bedrock"] -``` - -The existing interception implementation controls supported client endpoints, tool conversion, streaming, and model continuation. Selecting Web IQ does not add a separate agentic loop - -## Parameters - -| LiteLLM parameter | Web IQ request | -| --- | --- | -| `query` | `query`; a list of queries is joined with spaces | -| `max_results` | `maxResults` | -| `country` | `region`, uppercased | -| `search_domain_filter` | `site:` query operators, with `-domain` entries mapped to `-site:` exclusions | -| `max_tokens_per_page` | Not forwarded; Web IQ's `maxLength` measures characters, not tokens | - -Pass native options such as `language`, `region`, `location`, `contentFormat`, `maxLength`, `maxResults`, and `safeSearch` as keyword arguments. Explicit native values override mapped values and integration defaults. Web IQ validates its own parameter limits - -Domain filters narrow search relevance. Microsoft also notes that `site:` queries can return adult content regardless of `safeSearch`; see the API reference before relying on domain filtering in a restricted-content application - -The default API base is `https://api.microsoft.ai/v3`. `api_base` or the operator's `WEBIQ_API_BASE` can select a different base, with `/search/web` appended once. A caller-selected host cannot receive a server-managed API key unless the host matches the default or operator-configured base; pass explicit credentials for an intentional override - -No default Web IQ price is registered by this integration. Do not interpret missing cost data as free usage. Live Web IQ validation requires an enabled account and a valid API key diff --git a/litellm/llms/webiq/search/transformation.py b/litellm/llms/webiq/search/transformation.py index a34d12bb556..4bf0a3da205 100644 --- a/litellm/llms/webiq/search/transformation.py +++ b/litellm/llms/webiq/search/transformation.py @@ -7,7 +7,6 @@ import httpx from pydantic import BaseModel, ConfigDict, TypeAdapter, ValidationError from litellm.llms.base_llm.search.transformation import BaseSearchConfig, SearchResponse, SearchResult -from litellm.secret_managers.main import get_secret_str if TYPE_CHECKING: from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj @@ -44,7 +43,7 @@ def _query_with_domains(query: str, domains: object) -> str: class WebIQSearchConfig(BaseSearchConfig): - WEBIQ_API_BASE: Final = "https://api.microsoft.ai/v3" + DEFAULT_API_BASE: Final = "https://api.microsoft.ai/v3" @staticmethod def ui_friendly_name() -> str: @@ -61,8 +60,8 @@ class WebIQSearchConfig(BaseSearchConfig): caller_api_key=api_key, caller_api_base=api_base, key_env_vars=("WEBIQ_API_KEY",), - base_env_var="WEBIQ_API_BASE", - default_api_base=self.WEBIQ_API_BASE, + base_env_var=None, + default_api_base=self.DEFAULT_API_BASE, ) if not resolved_key: raise ValueError("Set WEBIQ_API_KEY or pass api_key for Microsoft Web IQ search") @@ -79,7 +78,7 @@ class WebIQSearchConfig(BaseSearchConfig): data: dict[str, object] | list[dict[str, object]] | None = None, # mutable-ok: BaseSearchConfig interface **kwargs: object, # kwargs-ok: BaseSearchConfig interface ) -> str: - base: Final = (api_base or get_secret_str("WEBIQ_API_BASE") or self.WEBIQ_API_BASE).rstrip("/") + base: Final = (api_base or self.DEFAULT_API_BASE).rstrip("/") return base if base.endswith("/search/web") else f"{base}/search/web" def transform_search_request( @@ -135,9 +134,21 @@ class WebIQSearchConfig(BaseSearchConfig): snippet=result.content, date=result.lastUpdatedAt or None, last_updated=result.lastUpdatedAt or None, - **(result.model_extra or MappingProxyType({})), + **MappingProxyType( + { + key: value + for key, value in (result.model_extra or MappingProxyType({})).items() + if key not in SearchResult.model_fields + } + ), ) for result in parsed.webResults ], - **(parsed.model_extra or MappingProxyType({})), + **MappingProxyType( + { + key: value + for key, value in (parsed.model_extra or MappingProxyType({})).items() + if key not in SearchResponse.model_fields + } + ), ) diff --git a/tests/test_litellm/llms/webiq/search/test_webiq_search_transformation.py b/tests/test_litellm/llms/webiq/search/test_webiq_search_transformation.py index ff683c2f39a..95889c9bbc9 100644 --- a/tests/test_litellm/llms/webiq/search/test_webiq_search_transformation.py +++ b/tests/test_litellm/llms/webiq/search/test_webiq_search_transformation.py @@ -13,7 +13,6 @@ from litellm.llms.webiq.search.transformation import WebIQSearchConfig @pytest.fixture(autouse=True) def webiq_environment(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]: monkeypatch.delenv("WEBIQ_API_KEY", raising=False) - monkeypatch.delenv("WEBIQ_API_BASE", raising=False) monkeypatch.setattr( # test-quality-ok: select HTTPX so respx can intercept the external HTTP boundary litellm, "disable_aiohttp_transport", True ) @@ -23,7 +22,7 @@ def webiq_environment(monkeypatch: pytest.MonkeyPatch) -> Iterator[None]: def test_search_maps_request_and_preserves_sources(respx_mock: respx.MockRouter) -> None: - endpoint: Final = f"{WebIQSearchConfig.WEBIQ_API_BASE}/search/web" + endpoint: Final = f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web" route: Final = respx_mock.post(endpoint).respond( json={ "webResults": [ @@ -82,12 +81,11 @@ def test_search_maps_request_and_preserves_sources(respx_mock: respx.MockRouter) } -async def test_asearch_uses_environment_credentials_and_custom_endpoint( +async def test_asearch_uses_environment_credentials_at_default_endpoint( respx_mock: respx.MockRouter, monkeypatch: pytest.MonkeyPatch ) -> None: monkeypatch.setenv("WEBIQ_API_KEY", "environment-key") - monkeypatch.setenv("WEBIQ_API_BASE", "https://webiq.example/v3/") - route: Final = respx_mock.post("https://webiq.example/v3/search/web").respond(json={"webResults": []}) + route: Final = respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond(json={"webResults": []}) response: Final = await litellm.asearch(query="no matches", search_provider="webiq") @@ -100,9 +98,25 @@ async def test_asearch_uses_environment_credentials_and_custom_endpoint( } +async def test_asearch_uses_explicit_credentials_at_custom_endpoint(respx_mock: respx.MockRouter) -> None: + route: Final = respx_mock.post("https://webiq.example/v3/search/web").respond(json={"webResults": []}) + + response: Final = await litellm.asearch( + query="no matches", search_provider="webiq", api_key="custom-key", api_base="https://webiq.example/v3/" + ) + + assert response.model_dump() == {"object": "search", "results": []} + assert route.calls.last.request.headers["x-apikey"] == "custom-key" + assert json.loads(route.calls.last.request.content) == { + "query": "no matches", + "contentFormat": "passage", + "maxLength": 5000, + } + + @pytest.mark.parametrize("updated", [None, "", "2026-02-01T00:00:00Z"]) def test_optional_updated_date_never_uses_crawl_time(respx_mock: respx.MockRouter, updated: str | None) -> None: - respx_mock.post(f"{WebIQSearchConfig.WEBIQ_API_BASE}/search/web").respond( + respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond( json={ "webResults": [ { @@ -120,7 +134,7 @@ def test_optional_updated_date_never_uses_crawl_time(respx_mock: respx.MockRoute def test_missing_optional_dates_and_result_order(respx_mock: respx.MockRouter) -> None: - respx_mock.post(f"{WebIQSearchConfig.WEBIQ_API_BASE}/search/web").respond( + respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond( json={ "webResults": [ {"title": title, "url": f"https://example.com/{title}", "content": title} @@ -137,7 +151,7 @@ def test_missing_optional_dates_and_result_order(respx_mock: respx.MockRouter) - @pytest.mark.parametrize("body", ["not json", "{}", '{"webResults": null}', '{"webResults": [{}]}']) def test_malformed_response_is_not_reported_as_empty_success(respx_mock: respx.MockRouter, body: str) -> None: - respx_mock.post(f"{WebIQSearchConfig.WEBIQ_API_BASE}/search/web").respond(text=body) + respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond(text=body) with pytest.raises(openai.APIError, match="invalid search response") as error: litellm.search(query="query", search_provider="webiq", api_key="key") assert error.value.status_code == 502 @@ -145,7 +159,7 @@ def test_malformed_response_is_not_reported_as_empty_success(respx_mock: respx.M @pytest.mark.parametrize("status", [401, 403, 429, 503]) def test_upstream_http_errors_keep_status(respx_mock: respx.MockRouter, status: int) -> None: - respx_mock.post(f"{WebIQSearchConfig.WEBIQ_API_BASE}/search/web").respond( + respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond( status_code=status, json={"error": {"message": "upstream failure"}}, headers={"Retry-After": "2"} ) with pytest.raises(openai.APIError, match="upstream failure") as error: @@ -220,3 +234,48 @@ def test_explicit_key_wins_and_headers_are_not_mutated(monkeypatch: pytest.Monke def test_missing_key_fails_before_network() -> None: with pytest.raises(ValueError, match="WEBIQ_API_KEY"): WebIQSearchConfig().validate_environment({}) + + +@pytest.mark.parametrize( + "result_metadata, response_metadata", + [ + ({"snippet": "upstream", "date": "upstream", "last_updated": "upstream"}, {}), + ({}, {"results": "upstream", "object": "upstream"}), + ], +) +def test_metadata_cannot_replace_standard_search_fields( + respx_mock: respx.MockRouter, result_metadata: dict[str, str], response_metadata: dict[str, str] +) -> None: + respx_mock.post(f"{WebIQSearchConfig.DEFAULT_API_BASE}/search/web").respond( + json={ + "webResults": [ + { + "title": "Title", + "url": "https://example.com", + "content": "Passage", + "lastUpdatedAt": "2026-01-02T00:00:00Z", + "language": "en", + **result_metadata, + } + ], + "traceId": "trace-1", + **response_metadata, + } + ) + + response: Final = litellm.search(query="query", search_provider="webiq", api_key="key") + + assert response.model_dump() == { + "object": "search", + "results": [ + { + "title": "Title", + "url": "https://example.com", + "snippet": "Passage", + "date": "2026-01-02T00:00:00Z", + "last_updated": "2026-01-02T00:00:00Z", + "language": "en", + } + ], + "traceId": "trace-1", + }