unique-search-proxy 2026.44.0.dev1__tar.gz → 2026.44.0.dev3__tar.gz

{unique_search_proxy-2026.44.0.dev1 → unique_search_proxy-2026.44.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-search-proxy
-Version: 2026.44.0.dev1
+Version: 2026.44.0.dev3
 Summary: Web Search Proxy implementation
 Author: ThePhilAz
 Author-email: ThePhilAz <rami.azouz@philico.com>
@@ -20,8 +20,8 @@ Requires-Dist: certifi>=2025.11.12,<2027
 Requires-Dist: google-genai>=1.73.0,<2
 Requires-Dist: google-auth>=2.43.0,<3
 Requires-Dist: jinja2>=3.1.6,<4
-Requires-Dist: unique-toolkit[monitoring]>=2026.44.0.dev2,<2026.44.0rc0
-Requires-Dist: unique-search-proxy-core>=2026.44.0.dev1,<2026.44.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.44.0.dev7,<2026.44.0rc0
+Requires-Dist: unique-search-proxy-core>=2026.44.0.dev3,<2026.44.0rc0
 Requires-Dist: openai>=1.105.0,<3
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -172,6 +172,23 @@ Response includes **curated** normalised results and opaque **raw** provider pay
 }
 ```
 
+Customized API endpoints must return a JSON object with a `results` array:
+
+```json
+{
+  "results": [
+    {
+      "url": "https://example.com",
+      "title": "Example",
+      "snippet": "Result summary",
+      "content": "Optional full content"
+    }
+  ]
+}
+```
+
+Each result requires `url`, `title`, and `snippet`; `content` is optional.
+
 ### 5.3 Agent search (`POST /v1/agent-search`)
 
 Thin egress — proxy returns opaque agent text; callers own parsing and citation extraction:
@@ -248,6 +265,11 @@ proxy routing fails during startup. The application cannot verify that the
 proxy implements equivalent URL-safety controls, so this state is highlighted
 in the Prometheus metric and Grafana dashboard.
 
+`CUSTOM_WEB_SEARCH_API_TRUSTED_PRIVATE_HOSTS` is a JSON array of exact
+operator-approved Customized API hostnames or IPs that may use RFC 1918 or IPv6
+unique-local addresses. It does not apply to crawler targets, permit localhost
+or cloud metadata targets, or configure network routing or private DNS.
+
 With `WORKERS > 1`, the entrypoint sets `PROMETHEUS_MULTIPROC_DIR` for correct metric aggregation.
 
 ---

{unique_search_proxy-2026.44.0.dev1 → unique_search_proxy-2026.44.0.dev3}/README.md

@@ -144,6 +144,23 @@ Response includes **curated** normalised results and opaque **raw** provider pay
 }
 ```
 
+Customized API endpoints must return a JSON object with a `results` array:
+
+```json
+{
+  "results": [
+    {
+      "url": "https://example.com",
+      "title": "Example",
+      "snippet": "Result summary",
+      "content": "Optional full content"
+    }
+  ]
+}
+```
+
+Each result requires `url`, `title`, and `snippet`; `content` is optional.
+
 ### 5.3 Agent search (`POST /v1/agent-search`)
 
 Thin egress — proxy returns opaque agent text; callers own parsing and citation extraction:
@@ -220,6 +237,11 @@ proxy routing fails during startup. The application cannot verify that the
 proxy implements equivalent URL-safety controls, so this state is highlighted
 in the Prometheus metric and Grafana dashboard.
 
+`CUSTOM_WEB_SEARCH_API_TRUSTED_PRIVATE_HOSTS` is a JSON array of exact
+operator-approved Customized API hostnames or IPs that may use RFC 1918 or IPv6
+unique-local addresses. It does not apply to crawler targets, permit localhost
+or cloud metadata targets, or configure network routing or private DNS.
+
 With `WORKERS > 1`, the entrypoint sets `PROMETHEUS_MULTIPROC_DIR` for correct metric aggregation.
 
 ---

{unique_search_proxy-2026.44.0.dev1 → unique_search_proxy-2026.44.0.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique-search-proxy"
-version = "2026.44.0.dev1"
+version = "2026.44.0.dev3"
 description = "Web Search Proxy implementation"
 authors = [{ name = "ThePhilAz", email = "rami.azouz@philico.com" }]
 readme = "README.md"
@@ -22,8 +22,8 @@ dependencies = [
     "google-genai>=1.73.0,<2",
     "google-auth>=2.43.0,<3",
     "jinja2>=3.1.6,<4",
-    "unique-toolkit[monitoring]>=2026.44.0.dev2,<2026.44.0rc0",
-    "unique-search-proxy-core>=2026.44.0.dev1,<2026.44.0rc0",
+    "unique-toolkit[monitoring]>=2026.44.0.dev7,<2026.44.0rc0",
+    "unique-search-proxy-core>=2026.44.0.dev3,<2026.44.0rc0",
     "openai>=1.105.0,<3",
 ]
 

{unique_search_proxy-2026.44.0.dev1 → unique_search_proxy-2026.44.0.dev3}/unique_search_proxy_client/web/core/search_engines/__init__.py

@@ -1,11 +1,15 @@
 from unique_search_proxy_core.search_engines.base import SearchEngineType
 from unique_search_proxy_core.search_engines.brave.schema import BraveConfig
+from unique_search_proxy_core.search_engines.custom_api.schema import CustomApiConfig
 from unique_search_proxy_core.search_engines.google.schema import GoogleConfig
 from unique_search_proxy_core.search_engines.perplexity.schema import PerplexityConfig
 
 from unique_search_proxy_client.web.core.search_engines.brave.service import (
     BraveSearchService,
 )
+from unique_search_proxy_client.web.core.search_engines.custom_api.service import (
+    CustomApiSearchService,
+)
 from unique_search_proxy_client.web.core.search_engines.descriptor import (
     SearchEngineDescriptor,
 )
@@ -47,11 +51,21 @@ def register_builtin_search_engines() -> None:
             service_cls=PerplexitySearchService,
         ),
     )
+    register_search_engine(
+        SearchEngineType.CUSTOM_API.value,
+        CustomApiSearchService,
+        descriptor=SearchEngineDescriptor(
+            config_model=CustomApiConfig,
+            service_cls=CustomApiSearchService,
+        ),
+    )
 
 
 __all__ = [
     "BraveConfig",
     "BraveSearchService",
+    "CustomApiConfig",
+    "CustomApiSearchService",
     "GoogleConfig",
     "GoogleSearchService",
     "PerplexityConfig",

unique_search_proxy-2026.44.0.dev3/unique_search_proxy_client/web/core/search_engines/custom_api/__init__.py

@@ -0,0 +1,5 @@
+from unique_search_proxy_client.web.core.search_engines.custom_api.service import (
+    CustomApiSearchService,
+)
+
+__all__ = ["CustomApiSearchService"]

unique_search_proxy-2026.44.0.dev3/unique_search_proxy_client/web/core/search_engines/custom_api/service.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import httpx
+from pydantic import ValidationError
+from unique_search_proxy_core.errors import (
+    BadRequestProxyError,
+    ForbiddenTargetError,
+    UpstreamError,
+    UpstreamTimeoutError,
+)
+from unique_search_proxy_core.schema import SearchEngineRaw, WebSearchResults
+from unique_search_proxy_core.search_engines.base import (
+    SearchEngineType,
+    get_search_engine_mode,
+)
+from unique_search_proxy_core.search_engines.custom_api.schema import (
+    CustomApiRequestMethod,
+    CustomApiSearchRequest,
+)
+from unique_search_proxy_core.url_safety import (
+    CustomApiTargetValidationError,
+    UrlSafetyService,
+    pinned_httpx_get_args,
+    url_safety_settings,
+)
+
+from unique_search_proxy_client.web.core.provider_response import (
+    raise_for_upstream_response,
+    transport_error_raw,
+)
+from unique_search_proxy_client.web.core.search_engines.service_base import (
+    SearchEngineService,
+)
+
+_LOGGER = logging.getLogger(__name__)
+_CUSTOM_API_PROVIDER_LABEL = "Custom API"
+
+
+def _parse_json_object(value: str, *, field_name: str) -> dict[str, Any]:
+    try:
+        parsed = json.loads(value)
+    except (TypeError, json.JSONDecodeError) as exc:
+        raise BadRequestProxyError(
+            f"{field_name} must be a valid JSON object",
+        ) from exc
+    if not isinstance(parsed, dict):
+        raise BadRequestProxyError(f"{field_name} must be a JSON object")
+    return parsed
+
+
+def _parse_headers(value: str) -> dict[str, str]:
+    parsed = _parse_json_object(value, field_name="apiHeaders")
+    if not all(
+        isinstance(key, str) and isinstance(item, str) for key, item in parsed.items()
+    ):
+        raise BadRequestProxyError("apiHeaders keys and values must be strings")
+    return parsed
+
+
+class CustomApiSearchService(SearchEngineService[CustomApiSearchRequest]):
+    """Tenant-configured API provider with fail-closed outbound URL controls."""
+
+    engine_id = SearchEngineType.CUSTOM_API.value
+
+    @property
+    def mode(self) -> str:
+        return get_search_engine_mode(SearchEngineType.CUSTOM_API).value
+
+    async def search(
+        self,
+        request: CustomApiSearchRequest,  # type: ignore[valid-type]
+    ) -> tuple[SearchEngineRaw, WebSearchResults]:
+        client = self._http_client
+        if client is None:
+            raise RuntimeError("HTTP client is required for Custom API search")
+
+        # Admin configuration must not grant access to unapproved private targets.
+        try:
+            resolved_target = await UrlSafetyService.resolve_custom_api_target(
+                request.api_endpoint,
+                trusted_private_hosts=(
+                    url_safety_settings.custom_api_trusted_private_hosts
+                ),
+            )
+        except CustomApiTargetValidationError as exc:
+            blocked = exc.blocked_targets[0]
+            raise ForbiddenTargetError(
+                "Custom API endpoint is blocked by URL safety policy",
+                details=[
+                    {
+                        "category": blocked.category,
+                        "reason": blocked.reason,
+                    }
+                ],
+            ) from exc
+
+        request_url, pin_headers, extensions = pinned_httpx_get_args(resolved_target)
+        headers = _parse_headers(request.api_headers)
+        headers.update(pin_headers)
+        params = _parse_json_object(
+            request.api_additional_query_params,
+            field_name="apiAdditionalQueryParams",
+        )
+        body = _parse_json_object(
+            request.api_additional_body_params,
+            field_name="apiAdditionalBodyParams",
+        )
+
+        try:
+            if request.api_request_method == CustomApiRequestMethod.GET:
+                params["query"] = request.query
+                response = await client.request(
+                    method=CustomApiRequestMethod.GET,
+                    url=request_url,
+                    headers=headers,
+                    params=params,
+                    json=body,
+                    extensions=extensions or None,
+                    timeout=request.timeout,
+                    follow_redirects=False,
+                )
+            elif request.api_request_method == CustomApiRequestMethod.POST:
+                body["query"] = request.query
+                response = await client.post(
+                    url=request_url,
+                    headers=headers,
+                    params=params,
+                    json=body,
+                    extensions=extensions or None,
+                    timeout=request.timeout,
+                    follow_redirects=False,
+                )
+            else:
+                raise BadRequestProxyError("Unsupported Custom API request method")
+        except httpx.TimeoutException as exc:
+            raise UpstreamTimeoutError(
+                f"Custom API search timed out after {request.timeout}s",
+                upstream_raw=transport_error_raw(exc),
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise UpstreamError(
+                "Custom API search request failed",
+                upstream_raw=transport_error_raw(exc),
+            ) from exc
+
+        if response.is_redirect:
+            raise ForbiddenTargetError("Custom API redirects are not allowed")
+        raise_for_upstream_response(
+            response,
+            provider_label=_CUSTOM_API_PROVIDER_LABEL,
+        )
+
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise UpstreamError("Custom API returned invalid JSON") from exc
+        if not isinstance(payload, dict):
+            raise UpstreamError("Custom API response must be a JSON object")
+
+        try:
+            curated = WebSearchResults.model_validate(payload)
+        except ValidationError as exc:
+            raise UpstreamError("Custom API returned an invalid result schema") from exc
+
+        _LOGGER.info("Custom API search returned %s curated results", len(curated))
+        return SearchEngineRaw(pages=[payload]), curated
+
+
+__all__ = ["CustomApiSearchService"]

{unique_search_proxy-2026.44.0.dev1 → unique_search_proxy-2026.44.0.dev3}/unique_search_proxy_client/web/core/search_engines/factory.py

@@ -7,6 +7,9 @@ from unique_search_proxy_core.search_engines.base import SearchEngine, SearchEng
 from unique_search_proxy_client.web.core.search_engines.brave.service import (
     BraveSearchService,
 )
+from unique_search_proxy_client.web.core.search_engines.custom_api.service import (
+    CustomApiSearchService,
+)
 from unique_search_proxy_client.web.core.search_engines.google.service import (
     GoogleSearchService,
 )
@@ -31,6 +34,8 @@ def get_search_engine_service(
             return BraveSearchService(http_client=http_client)
         case SearchEngineType.PERPLEXITY:
             return PerplexitySearchService(http_client=http_client)
+        case SearchEngineType.CUSTOM_API:
+            return CustomApiSearchService(http_client=http_client)
         case _:
             raise ValueError(f"Unsupported search engine: {engine}")
 

{unique_search_proxy-2026.44.0.dev1 → unique_search_proxy-2026.44.0.dev3}/unique_search_proxy_client/web/helm/generator/introspect.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass
 from typing import Any, Literal, cast, get_args, get_origin
 
 from pydantic import SecretStr
+from pydantic.aliases import AliasChoices
 from pydantic.fields import FieldInfo
 
 from unique_search_proxy_client.web.settings.secret_str import (
@@ -25,7 +26,17 @@ def snake_to_camel(name: str) -> str:
     return parts[0] + "".join(part.capitalize() for part in parts[1:])
 
 
-def env_var_name(field_name: str, env_prefix: str) -> str:
+def env_var_name(
+    field_name: str,
+    env_prefix: str,
+    field_info: FieldInfo | None = None,
+) -> str:
+    if field_info is not None:
+        aliases = field_info.validation_alias
+        choices = aliases.choices if isinstance(aliases, AliasChoices) else [aliases]
+        for choice in choices:
+            if isinstance(choice, str) and choice.isupper():
+                return choice
     return f"{env_prefix}{field_name.upper()}"
 
 
@@ -201,7 +212,7 @@ def iter_helm_fields(
         spec = HelmFieldSpec(
             python_name=field_name,
             helm_name=helm_name,
-            env_var=env_var_name(field_name, env_prefix),
+            env_var=env_var_name(field_name, env_prefix, field_info),
             sensitive=sensitive,
             required_when_enabled=required_when_enabled,
             schema_ref=schema_ref,

{unique_search_proxy-2026.44.0.dev1 → unique_search_proxy-2026.44.0.dev3}/unique_search_proxy_client/web/helm/url_safety_registration.py

@@ -33,6 +33,7 @@ _URL_SAFETY_SECTIONS: dict[str, list[str]] = {
         "allowed_schemes",
         "localhost_hosts",
         "metadata_hosts",
+        "custom_api_trusted_private_hosts",
     ],
 }
 
@@ -76,6 +77,7 @@ def configure_url_safety_helm_model(model: type[UrlSafetySettings]) -> None:
             "allowed_schemes": {"overridable": True},
             "localhost_hosts": {"overridable": True},
             "metadata_hosts": {"overridable": True},
+            "custom_api_trusted_private_hosts": {"overridable": True},
         },
     )
 

{unique_search_proxy-2026.44.0.dev1 → unique_search_proxy-2026.44.0.dev3}/unique_search_proxy_client/web/startup_report.py

@@ -6,6 +6,7 @@ from collections import defaultdict
 
 from pydantic import BaseModel
 
+from unique_search_proxy_client.web.helm.generator.introspect import env_var_name
 from unique_search_proxy_client.web.helm.registry import startup_report_groups
 from unique_search_proxy_client.web.settings.secret_str import (
     field_has_not_provided_default,
@@ -15,8 +16,8 @@ from unique_search_proxy_client.web.settings.secret_str import (
 _LOGGER = logging.getLogger(__name__)
 
 
-def _env_var_name(field_name: str, env_prefix: str) -> str:
-    return f"{env_prefix}{field_name.upper()}"
+def _env_var_name(model: BaseModel, field_name: str, env_prefix: str) -> str:
+    return env_var_name(field_name, env_prefix, model.model_fields[field_name])
 
 
 def _field_status(
@@ -26,7 +27,7 @@ def _field_status(
 ) -> str:
     value = getattr(model, field_name)
     field_info = model.model_fields[field_name]
-    env_var = _env_var_name(field_name, env_prefix)
+    env_var = _env_var_name(model, field_name, env_prefix)
 
     if field_has_not_provided_default(field_info):
         return "configured" if is_secret_configured(value) else "missing"
@@ -46,7 +47,7 @@ def _group_fields_by_status(
 ) -> dict[str, list[str]]:
     grouped: dict[str, list[str]] = defaultdict(list)
     for field_name in model.model_fields:
-        env_var = _env_var_name(field_name, env_prefix)
+        env_var = _env_var_name(model, field_name, env_prefix)
         status = _field_status(model, field_name, env_prefix)
         grouped[status].append(env_var)
     return grouped
@@ -72,7 +73,7 @@ def _format_group(title: str, model: BaseModel, env_prefix: str) -> list[str]:
     grouped = _group_fields_by_status(model, env_prefix)
     lines = [f"  [{title}] {_group_summary(grouped)}"]
     for field_name in model.model_fields:
-        env_var = _env_var_name(field_name, env_prefix)
+        env_var = _env_var_name(model, field_name, env_prefix)
         value = getattr(model, field_name)
         lines.append(f"    {env_var}={_format_settings_value(value)}")
     return lines