unique_web_search 2026.44.0.dev0__tar.gz → 2026.44.0.dev2__tar.gz

{unique_web_search-2026.44.0.dev0 → unique_web_search-2026.44.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-web-search
-Version: 2026.44.0.dev0
+Version: 2026.44.0.dev2
 Summary: 
 Author: Andreas Hauri, Gustav Hartz, Rami Azouz
 Author-email: Andreas Hauri <andreas@unique.ch>, Gustav Hartz <gustav.hartz.ext@unique.ch>, Rami Azouz <rami.ext@unique.ch>
@@ -16,7 +16,7 @@ Requires-Dist: tavily-python>=0.7.11,<1
 Requires-Dist: unidecode>=1.4.0,<2
 Requires-Dist: azure-ai-projects>=2.3,<3
 Requires-Dist: azure-identity>=1.25.0,<2
-Requires-Dist: unique-toolkit[monitoring]>=2026.44.0.dev0,<2026.44.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.44.0.dev9,<2026.44.0rc0
 Requires-Dist: azure-core>=1.36.0,<2
 Requires-Dist: google-cloud-aiplatform>=1.128.0,<2
 Requires-Dist: google-auth>=2.43.0,<3
@@ -25,8 +25,8 @@ Requires-Dist: rapidfuzz>=3.0.0,<4
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: certifi>=2025.11.12
 Requires-Dist: jinja2>=3.1.6
-Requires-Dist: unique-search-proxy-core>=2026.44.0.dev0,<2026.44.0rc0
-Requires-Dist: unique-search-proxy-sdk>=2026.44.0.dev0,<2026.44.0rc0
+Requires-Dist: unique-search-proxy-core>=2026.44.0.dev4,<2026.44.0rc0
+Requires-Dist: unique-search-proxy-sdk>=2026.44.0.dev2,<2026.44.0rc0
 Requires-Dist: openai>=1.105.0,<3
 Requires-Python: >=3.12, <4.0
 Description-Content-Type: text/markdown
@@ -45,7 +45,9 @@ Outbound web access should go through **Unique Search Proxy** (`connectors/uniqu
 | **Legacy** | URL unset | Direct provider calls from this process (`_legacy_search` / `_legacy_crawl`) |
 
 - **New standard engines (Brave, Perplexity) are proxy-only** — legacy raises.
-- **Custom API** always runs locally (never routed through the proxy).
+- **Custom API** uses proxy egress only when
+  `FEATURE_FLAG_SEARCH_PROXY_ENABLE_CUSTOM_API_UN_26736` is enabled; otherwise
+  the legacy path reports URL-safety outcomes without blocking.
 - Future provider work targets Search Proxy only; legacy is preserved for migrated engines.
 
 Packages involved: [`unique-search-proxy-core`](../../connectors/unique_search_proxy/unique_search_proxy_core/README.md) (schemas), [`unique-search-proxy-sdk`](../../connectors/unique_search_proxy/unique_search_proxy_sdk/README.md) (HTTP), [`unique-search-proxy`](../../connectors/unique_search_proxy/unique_search_proxy_client/README.md) (server). System overview: [`connectors/unique_search_proxy/README.md`](../../connectors/unique_search_proxy/README.md).
@@ -65,7 +67,7 @@ Query → normalised results (URL / title / snippet / optional content). Optiona
 | Google | legacy + proxy | Requires scraping by default |
 | Brave | **proxy-only** | Rich snippets; `ExposableParam` knobs |
 | Perplexity | **proxy-only** | Content extraction knobs; `ExposableParam` |
-| Custom API | always local | Your REST endpoint |
+| Custom API | legacy + proxy | Your REST endpoint; proxy mode rejects redirects |
 
 Standard engines that live in proxy-core use **`ExposableParam`** (`expose` + `value`) for optional provider knobs. See [Search Engines README](./src/unique_web_search/services/search_engine/README.md).
 

{unique_web_search-2026.44.0.dev0 → unique_web_search-2026.44.0.dev2}/README.md

@@ -12,7 +12,9 @@ Outbound web access should go through **Unique Search Proxy** (`connectors/uniqu
 | **Legacy** | URL unset | Direct provider calls from this process (`_legacy_search` / `_legacy_crawl`) |
 
 - **New standard engines (Brave, Perplexity) are proxy-only** — legacy raises.
-- **Custom API** always runs locally (never routed through the proxy).
+- **Custom API** uses proxy egress only when
+  `FEATURE_FLAG_SEARCH_PROXY_ENABLE_CUSTOM_API_UN_26736` is enabled; otherwise
+  the legacy path reports URL-safety outcomes without blocking.
 - Future provider work targets Search Proxy only; legacy is preserved for migrated engines.
 
 Packages involved: [`unique-search-proxy-core`](../../connectors/unique_search_proxy/unique_search_proxy_core/README.md) (schemas), [`unique-search-proxy-sdk`](../../connectors/unique_search_proxy/unique_search_proxy_sdk/README.md) (HTTP), [`unique-search-proxy`](../../connectors/unique_search_proxy/unique_search_proxy_client/README.md) (server). System overview: [`connectors/unique_search_proxy/README.md`](../../connectors/unique_search_proxy/README.md).
@@ -32,7 +34,7 @@ Query → normalised results (URL / title / snippet / optional content). Optiona
 | Google | legacy + proxy | Requires scraping by default |
 | Brave | **proxy-only** | Rich snippets; `ExposableParam` knobs |
 | Perplexity | **proxy-only** | Content extraction knobs; `ExposableParam` |
-| Custom API | always local | Your REST endpoint |
+| Custom API | legacy + proxy | Your REST endpoint; proxy mode rejects redirects |
 
 Standard engines that live in proxy-core use **`ExposableParam`** (`expose` + `value`) for optional provider knobs. See [Search Engines README](./src/unique_web_search/services/search_engine/README.md).
 

{unique_web_search-2026.44.0.dev0 → unique_web_search-2026.44.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_web_search"
-version = "2026.44.0.dev0"
+version = "2026.44.0.dev2"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12,<4.0"
@@ -22,7 +22,7 @@ dependencies = [
     "unidecode>=1.4.0,<2",
     "azure-ai-projects>=2.3,<3",
     "azure-identity>=1.25.0,<2",
-    "unique-toolkit[monitoring]>=2026.44.0.dev0,<2026.44.0rc0",
+    "unique-toolkit[monitoring]>=2026.44.0.dev9,<2026.44.0rc0",
     "azure-core>=1.36.0,<2",
     "google-cloud-aiplatform>=1.128.0,<2",
     "google-auth>=2.43.0,<3",
@@ -31,8 +31,8 @@ dependencies = [
     "httpx>=0.28.1",
     "certifi>=2025.11.12",
     "jinja2>=3.1.6",
-    "unique-search-proxy-core>=2026.44.0.dev0,<2026.44.0rc0",
-    "unique-search-proxy-sdk>=2026.44.0.dev0,<2026.44.0rc0",
+    "unique-search-proxy-core>=2026.44.0.dev4,<2026.44.0rc0",
+    "unique-search-proxy-sdk>=2026.44.0.dev2,<2026.44.0rc0",
     "openai>=1.105.0,<3",
 ]
 

{unique_web_search-2026.44.0.dev0 → unique_web_search-2026.44.0.dev2}/src/unique_web_search/metrics.py

@@ -10,6 +10,11 @@ search_total = m.counter("search_total", "Search calls by engine", ["engine"])
 search_errors = m.counter(
     "search_errors_total", "Search failures", ["engine", "error_type"]
 )
+custom_api_url_safety_report = m.counter(
+    "custom_api_url_safety_report_total",
+    "Report-only URL safety outcomes for legacy Custom API searches",
+    ["outcome", "reason_category"],
+)
 
 # End-to-End Tool (P1)
 tool_duration = m.histogram(

{unique_web_search-2026.44.0.dev0 → unique_web_search-2026.44.0.dev2}/src/unique_web_search/services/search_engine/README.md

@@ -6,7 +6,11 @@ Implementations wrap standard search APIs and grounding (agent) providers behind
 
 ```python
 # SearchEngine.search (services/search_engine/base.py)
-if search_proxy_client_enabled and engine is proxy-supported:
+if (
+    search_proxy_client_enabled
+    and engine is proxy-supported            # config.engine is SearchEngineType / AgentEngineType
+    and await self._proxy_routing_enabled()  # per-engine gate; Custom API checks its feature flag
+):
     return await self._proxy_search(...)   # standard → /v1/search; agent → /v1/agent-search
 return await self._legacy_search(...)      # direct provider call from this process
 ```
@@ -15,7 +19,7 @@ return await self._legacy_search(...)      # direct provider call from this proc
 |------|---------|-------|--------|
 | **Standard** | Google | yes | yes |
 | **Standard** | Brave, Perplexity | yes | **raises** (proxy-only) |
-| **Standard** | Custom API | never | always |
+| **Standard** | Custom API | yes | yes |
 | **Agent** | Bing, VertexAI | yes | yes |
 
 Deployment configs for Google / Brave / Perplexity (and agent base fields) live in **`unique_search_proxy_core`**. This package registers tool wrappers and adds web-only fields where needed (e.g. `requires_scraping` on Bing/VertexAI).
@@ -127,13 +131,20 @@ Config: `unique_search_proxy_core.search_engines.perplexity.schema.PerplexityCon
 PERPLEXITY_API_KEY=...
 ```
 
-### Custom API Search (always local)
+### Custom API Search
 
-**Provider:** your REST endpoint · **Never proxy-routed**
+**Provider:** your REST endpoint · **Proxy:** legacy + proxy
 
-Config: `unique_web_search.services.search_engine.custom_api.CustomAPIConfig` (`LocalSearchEngineType.CUSTOM_API`)
+Config: `unique_web_search.services.search_engine.custom_api.CustomAPIConfig` (engine `SearchEngineType.CUSTOM_API`; registered under `LocalSearchEngineType.CUSTOM_API`)
 
-Response must be JSON with a `results` array of `{url, title, snippet, content?}`.
+Response must be JSON with a `results` or legacy `curated` array of
+`{url, title, snippet, content?}`. When
+`FEATURE_FLAG_SEARCH_PROXY_ENABLE_CUSTOM_API_UN_26736` is enabled, the endpoint
+is validated against the Search Proxy URL-safety policy, DNS is pinned, and
+redirects are rejected. Exact private hosts can be operator-approved with
+`CUSTOM_WEB_SEARCH_API_TRUSTED_PRIVATE_HOSTS`; this exception applies only to
+Customized API endpoints. Use the same value in assistants-core for accurate
+report-only metrics before proxy routing is enabled.
 
 ```bash
 CUSTOM_WEB_SEARCH_API_ENDPOINT=https://your-api.example.com/search

{unique_web_search-2026.44.0.dev0 → unique_web_search-2026.44.0.dev2}/src/unique_web_search/services/search_engine/base.py

@@ -8,14 +8,14 @@ from pydantic import BaseModel
 from unique_search_proxy_core.agent_engines.base import AgentEngineType
 from unique_search_proxy_core.agent_engines.config_types import ENGINE_NAME_TO_CONFIG
 from unique_search_proxy_core.context import LOCAL_REQUEST_CONTEXT, RequestContext
+from unique_search_proxy_core.param_policy.exposable_config import (
+    ExposableParamsConfig,
+)
 from unique_search_proxy_core.param_policy.exposable_param import (
     resolve_exposable_value,
 )
 from unique_search_proxy_core.param_policy.exposed_params import ExposedParams
-from unique_search_proxy_core.search_engines.base import (
-    BaseSearchEngineConfig,
-    SearchEngineType,
-)
+from unique_search_proxy_core.search_engines.base import SearchEngineType
 
 from unique_web_search.services.proxy.bridge import (
     open_search_proxy_client,
@@ -45,8 +45,7 @@ class LocalSearchEngineType(StrEnum):
     CUSTOM_API = "custom_api"
 
 
-# Engine ids that the search proxy can serve. Every other engine
-# (e.g. ``LocalSearchEngineType``) is routed to the local legacy implementation.
+# Engine ids that the search proxy can serve.
 ProxyEngineType = SearchEngineType | AgentEngineType
 
 # Fields present on agent-engine configs that are not accepted as proxy call kwargs.
@@ -69,8 +68,7 @@ class SearchEngine(ABC, Generic[SearchEngineConfig]):
     provide the direct ``_legacy_search`` implementation.
 
     ``search`` uses the proxy whenever it is enabled and the engine is supported by
-    it, otherwise it reroutes to the local legacy implementation. Engines that the
-    proxy cannot serve (e.g. custom APIs) always fall back to ``_legacy_search``.
+    it, otherwise it reroutes to the local legacy implementation.
     """
 
     # Set by agent engines (Bing/VertexAI) and consumed by the agent proxy path.
@@ -90,6 +88,14 @@ class SearchEngine(ABC, Generic[SearchEngineConfig]):
         """Whether the search engine requires scraping."""
         return False
 
+    async def _proxy_routing_enabled(self) -> bool:
+        """Whether this engine may use Search Proxy for the current request."""
+        return True
+
+    @property
+    def _standard_proxy_client_timeout(self) -> float:
+        return _STANDARD_PROXY_TIMEOUT
+
     @property
     def _proxy_engine(self) -> ProxyEngineType | None:
         """The proxy engine id for this config, or ``None`` if not proxy-supported."""
@@ -105,7 +111,11 @@ class SearchEngine(ABC, Generic[SearchEngineConfig]):
     ) -> list[WebSearchResult]:
         """Search the web for the given query using the search engine."""
         proxy_engine = self._proxy_engine
-        if search_proxy_client_enabled and proxy_engine is not None:
+        if (
+            search_proxy_client_enabled
+            and proxy_engine is not None
+            and await self._proxy_routing_enabled()
+        ):
             return await self._proxy_search(query, params, proxy_engine)
         return await self._legacy_search(query=query, params=params)
 
@@ -127,9 +137,9 @@ class SearchEngine(ABC, Generic[SearchEngineConfig]):
         engine: SearchEngineType,
     ) -> list[WebSearchResult]:
         """Merge deployment config with per-call params and dispatch via the proxy SDK."""
-        if not isinstance(self.config, BaseSearchEngineConfig):
+        if not isinstance(self.config, ExposableParamsConfig):
             raise TypeError(
-                f"Standard proxy search requires BaseSearchEngineConfig, "
+                f"Standard proxy search requires ExposableParamsConfig, "
                 f"got {type(self.config).__name__}"
             )
         overrides = (
@@ -140,7 +150,7 @@ class SearchEngine(ABC, Generic[SearchEngineConfig]):
         invocation.pop("engine", None)
         invocation.pop("query", None)
         async with open_search_proxy_client(
-            timeout=_STANDARD_PROXY_TIMEOUT,
+            timeout=self._standard_proxy_client_timeout,
             context=self._request_context,
         ) as client:
             response = await client.search.search(

{unique_web_search-2026.44.0.dev0 → unique_web_search-2026.44.0.dev2}/src/unique_web_search/services/search_engine/custom_api.py

@@ -1,13 +1,27 @@
 import json
-from typing import Any, Literal, TypeVar, override
+import logging
+from typing import Any, TypeVar, override
 
 from httpx import AsyncClient
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
 from pydantic.json_schema import SkipJsonSchema
 from unique_search_proxy_core.context import LOCAL_REQUEST_CONTEXT, RequestContext
 from unique_search_proxy_core.param_policy.exposed_params import ExposedParams
+from unique_search_proxy_core.search_engines.custom_api.schema import (
+    CustomApiConfig as ProxyCustomApiConfig,
+)
+from unique_search_proxy_core.search_engines.custom_api.schema import (
+    CustomApiSearchRequest,
+)
+from unique_search_proxy_core.url_safety import (
+    CustomApiTargetValidationError,
+    UrlSafetyService,
+)
+from unique_toolkit.agentic.feature_flags import FeatureFlagNames
 from unique_toolkit.agentic.tools.config import get_configuration_dict
+from unique_toolkit.experimental.resources.feature_flags import is_flag_enabled
 
+from unique_web_search.metrics import custom_api_url_safety_report
 from unique_web_search.services.search_engine.base import (
     LocalSearchEngineType,
     SearchEngine,
@@ -20,6 +34,8 @@ from unique_web_search.services.search_engine.schema import (
 )
 from unique_web_search.settings import CUSTOM_API_REQUEST_METHOD, env_settings
 
+_LOGGER = logging.getLogger(__name__)
+
 T = TypeVar("T")
 
 
@@ -64,11 +80,9 @@ ApiRequestMethodType, ApiRequestMethodField = conditional_type(
 )
 
 
-class CustomAPIConfig(BaseModel):
+class CustomAPIConfig(ProxyCustomApiConfig):
     model_config = get_configuration_dict(title="Customized API")
 
-    engine: Literal[LocalSearchEngineType.CUSTOM_API] = LocalSearchEngineType.CUSTOM_API
-
     api_endpoint: ApiEndpointType = ApiEndpointField  # type: ignore (Dynamic type generation)
     api_headers: ApiHeadersType = ApiHeadersField  # type: ignore (Dynamic type generation)
     api_additional_query_params: ApiAdditionalQueryParamsType = (  # type: ignore (Dynamic type generation)
@@ -88,6 +102,43 @@ class CustomAPIConfig(BaseModel):
     )
     timeout: int = Field(default=120, description="The timeout of the custom API")
 
+    @model_validator(mode="before")
+    @classmethod
+    def apply_operator_config_precedence(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+
+        resolved_value = dict(value)
+        operator_values = {
+            "apiEndpoint": env_settings.custom_web_search_api_endpoint,
+            "apiHeaders": env_settings.custom_web_search_api_headers,
+            "apiAdditionalQueryParams": (
+                env_settings.custom_web_search_api_additional_query_params
+            ),
+            "apiAdditionalBodyParams": (
+                env_settings.custom_web_search_api_additional_body_params
+            ),
+            "apiRequestMethod": env_settings.custom_web_search_api_method,
+        }
+        aliases = {
+            "apiEndpoint": "api_endpoint",
+            "apiHeaders": "api_headers",
+            "apiAdditionalQueryParams": "api_additional_query_params",
+            "apiAdditionalBodyParams": "api_additional_body_params",
+            "apiRequestMethod": "api_request_method",
+        }
+        for alias, operator_value in operator_values.items():
+            if operator_value is None:
+                continue
+            resolved_value.pop(aliases[alias], None)
+            resolved_value[alias] = operator_value
+        return resolved_value
+
+    @classmethod
+    def request_model(cls) -> type[BaseModel]:
+        """Use the proxy's wire contract, excluding tool-only configuration fields."""
+        return CustomApiSearchRequest
+
 
 @register_search_engine(
     name="custom_api",
@@ -107,6 +158,17 @@ class CustomAPI(SearchEngine[CustomAPIConfig]):
         self.api_endpoint = config.api_endpoint
         self.is_configured = True  # No possibility to check if the API is configured from our side. So we assume it is configured.
 
+    async def _proxy_routing_enabled(self) -> bool:
+        return await is_flag_enabled(
+            FeatureFlagNames.search_proxy_enable_custom_api_un_26736,
+            company_id=self._request_context.company_id,
+            user_id=self._request_context.user_id,
+        )
+
+    @property
+    def _standard_proxy_client_timeout(self) -> float:
+        return float(self.config.timeout) + 5.0
+
     @override
     async def _legacy_search(
         self,
@@ -114,10 +176,10 @@ class CustomAPI(SearchEngine[CustomAPIConfig]):
         params: ExposedParams | None,
     ) -> list[WebSearchResult]:
         del params
+        await self._report_url_safety()
         params_dict, body = self._prepare_request_params_and_body(query)
-        async_client_params = self._client_config | {
-            "timeout": self.config.timeout,
-        }
+        async_client_params: dict[str, Any] = dict(self._client_config)
+        async_client_params["timeout"] = self.config.timeout
         async with AsyncClient(**async_client_params) as client:
             response = await client.request(
                 method=self._request_method,
@@ -135,6 +197,43 @@ class CustomAPI(SearchEngine[CustomAPIConfig]):
         validated_response = WebSearchResults.model_validate(response.json())
         return validated_response.results
 
+    async def _report_url_safety(self) -> None:
+        try:
+            await UrlSafetyService.resolve_custom_api_target(
+                self.config.api_endpoint,
+                trusted_private_hosts=(
+                    env_settings.custom_web_search_api_trusted_private_hosts
+                ),
+            )
+        except CustomApiTargetValidationError as exc:
+            reason_category = exc.blocked_targets[0].category
+            custom_api_url_safety_report.labels(
+                outcome="would_block",
+                reason_category=reason_category,
+            ).inc()
+            _LOGGER.warning(
+                "Search Proxy URL safety would block this Custom API endpoint; "
+                "continuing through the legacy direct path because proxy routing "
+                "is disabled company_id=%s category=%s",
+                self._request_context.company_id,
+                reason_category,
+            )
+        except Exception as exc:
+            custom_api_url_safety_report.labels(
+                outcome="validation_error",
+                reason_category="unexpected",
+            ).inc()
+            _LOGGER.warning(
+                "Custom API URL safety report failed company_id=%s error_type=%s",
+                self._request_context.company_id,
+                type(exc).__name__,
+            )
+        else:
+            custom_api_url_safety_report.labels(
+                outcome="allowed",
+                reason_category="none",
+            ).inc()
+
     @property
     def requires_scraping(self) -> bool:
         return self.config.requires_scraping

{unique_web_search-2026.44.0.dev0 → unique_web_search-2026.44.0.dev2}/src/unique_web_search/settings.py

@@ -77,6 +77,7 @@ class Base(BaseSettings):
     custom_web_search_api_additional_query_params: str | None = None
     custom_web_search_api_additional_body_params: str | None = None
     custom_web_search_api_client_config: str | None = None
+    custom_web_search_api_trusted_private_hosts: list[str] = []
 
     # Proxy settings
     ## Shared settings