unique-search-proxy-core 2026.44.0.dev2__tar.gz → 2026.44.0.dev4__tar.gz

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-search-proxy-core
-Version: 2026.44.0.dev2
+Version: 2026.44.0.dev4
 Summary: Shared Pydantic types for the Unique Search Proxy API
 Author: ThePhilAz
 Author-email: ThePhilAz <rami.azouz@philico.com>
@@ -8,7 +8,7 @@ Requires-Dist: httpx>=0.28.0,<0.29
 Requires-Dist: pydantic>=2.12.5,<3.0.0
 Requires-Dist: pydantic-settings>=2.10.1,<3
 Requires-Dist: pyhumps>=3.8.0,<4
-Requires-Dist: unique-toolkit[monitoring]>=2026.44.0.dev7,<2026.44.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.44.0.dev9,<2026.44.0rc0
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique-search-proxy-core"
-version = "2026.44.0.dev2"
+version = "2026.44.0.dev4"
 description = "Shared Pydantic types for the Unique Search Proxy API"
 authors = [{ name = "ThePhilAz", email = "rami.azouz@philico.com" }]
 readme = "README.md"
@@ -10,7 +10,7 @@ dependencies = [
     "pydantic>=2.12.5,<3.0.0",
     "pydantic-settings>=2.10.1,<3",
     "pyhumps>=3.8.0,<4",
-    "unique-toolkit[monitoring]>=2026.44.0.dev7,<2026.44.0rc0",
+    "unique-toolkit[monitoring]>=2026.44.0.dev9,<2026.44.0rc0",
 
 ]
 

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/unique_search_proxy_core/schema.py

@@ -4,7 +4,7 @@ from enum import StrEnum
 from typing import Annotated, Any, Literal, overload
 
 import humps
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field
 from pydantic.alias_generators import to_camel
 from pydantic.fields import ComputedFieldInfo, FieldInfo
 
@@ -97,7 +97,9 @@ class WebSearchResult(BaseModel):
 
 class WebSearchResults(BaseModel):
     model_config = camelized_model_config
-    results: list[WebSearchResult]
+    results: list[WebSearchResult] = Field(
+        validation_alias=AliasChoices("results", "curated")
+    )
 
     def __len__(self) -> int:
         return len(self.results)

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/unique_search_proxy_core/search_engines/__init__.py

@@ -19,6 +19,11 @@ from unique_search_proxy_core.search_engines.config_types import (
     parse_search_engine_config,
     parse_search_request,
 )
+from unique_search_proxy_core.search_engines.custom_api.schema import (
+    CustomApiConfig,
+    CustomApiRequestMethod,
+    CustomApiSearchRequest,
+)
 from unique_search_proxy_core.search_engines.google.schema import (
     GoogleConfig,
     GoogleSearchRequest,
@@ -32,6 +37,9 @@ __all__ = [
     "BaseSearchEngineConfig",
     "BraveConfig",
     "BraveSearchRequest",
+    "CustomApiConfig",
+    "CustomApiRequestMethod",
+    "CustomApiSearchRequest",
     "GoogleConfig",
     "GoogleSearchRequest",
     "PerplexityConfig",

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/unique_search_proxy_core/search_engines/base.py

@@ -36,12 +36,14 @@ class SearchEngineType(StrEnum):
     GOOGLE = "google"
     BRAVE = "brave"
     PERPLEXITY = "perplexity"
+    CUSTOM_API = "custom_api"
 
 
 _SEARCH_ENGINE_MODE_MAP: dict[SearchEngineType, SearchEngineMode] = {
     SearchEngineType.GOOGLE: SearchEngineMode.STANDARD,
     SearchEngineType.BRAVE: SearchEngineMode.STANDARD,
     SearchEngineType.PERPLEXITY: SearchEngineMode.STANDARD,
+    SearchEngineType.CUSTOM_API: SearchEngineMode.STANDARD,
 }
 
 

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/unique_search_proxy_core/search_engines/config_types.py

@@ -6,20 +6,24 @@ from typing import Annotated, Any, Mapping, TypeAlias, Union, cast
 
 from pydantic import BaseModel, Field, TypeAdapter
 
-from unique_search_proxy_core.search_engines.base import (
-    BaseSearchEngineConfig,
-    SearchEngineType,
+from unique_search_proxy_core.param_policy.exposable_config import (
+    ExposableParamsConfig,
 )
+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
 
-SearchEngineConfigTypes: TypeAlias = GoogleConfig | BraveConfig | PerplexityConfig
+SearchEngineConfigTypes: TypeAlias = (
+    GoogleConfig | BraveConfig | PerplexityConfig | CustomApiConfig
+)
 
-ENGINE_NAME_TO_CONFIG: dict[str, type[BaseSearchEngineConfig]] = {
+ENGINE_NAME_TO_CONFIG: dict[str, type[ExposableParamsConfig]] = {
     SearchEngineType.GOOGLE.value: GoogleConfig,
     SearchEngineType.BRAVE.value: BraveConfig,
     SearchEngineType.PERPLEXITY.value: PerplexityConfig,
+    SearchEngineType.CUSTOM_API.value: CustomApiConfig,
 }
 
 _search_engine_config_adapter: TypeAdapter[SearchEngineConfigTypes] = TypeAdapter(
@@ -33,7 +37,7 @@ def parse_search_engine_config(data: object) -> SearchEngineConfigTypes:
 
 def get_search_engine_config_types_from_names(
     engine_names: list[str],
-) -> type[BaseSearchEngineConfig]:
+) -> type[ExposableParamsConfig]:
     """Build a union of config models for the given engine slugs (runtime narrowing)."""
     assert len(engine_names) >= 1, "At least one search engine must be active"
 
@@ -46,12 +50,12 @@ def get_search_engine_config_types_from_names(
         raise ValueError(f"No search engine config found for names: {engine_names}")
     if len(selected_types) == 1:
         return selected_types[0]
-    return cast(type[BaseSearchEngineConfig], reduce(operator.or_, selected_types))
+    return cast(type[ExposableParamsConfig], reduce(operator.or_, selected_types))
 
 
 def _union_members_from_mapping(
-    mapping: Mapping[str, type[BaseSearchEngineConfig]],
-) -> tuple[type[BaseSearchEngineConfig], ...]:
+    mapping: Mapping[str, type[ExposableParamsConfig]],
+) -> tuple[type[ExposableParamsConfig], ...]:
     return tuple(mapping.values())
 
 

unique_search_proxy_core-2026.44.0.dev4/unique_search_proxy_core/search_engines/custom_api/__init__.py

@@ -0,0 +1,11 @@
+from unique_search_proxy_core.search_engines.custom_api.schema import (
+    CustomApiConfig,
+    CustomApiRequestMethod,
+    CustomApiSearchRequest,
+)
+
+__all__ = [
+    "CustomApiConfig",
+    "CustomApiRequestMethod",
+    "CustomApiSearchRequest",
+]

unique_search_proxy_core-2026.44.0.dev4/unique_search_proxy_core/search_engines/custom_api/schema.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated, ClassVar, Literal
+
+from pydantic import BaseModel, Field
+from unique_toolkit._common.pydantic.rjsf_tags import RJSFMetaTag
+
+from unique_search_proxy_core.param_policy.derive import derive_request_model
+from unique_search_proxy_core.param_policy.exposable_config import (
+    ExposableParamsConfig,
+)
+from unique_search_proxy_core.param_policy.request_base import SearchRequestBase
+from unique_search_proxy_core.search_engines.base import SearchEngineType
+
+
+class CustomApiRequestMethod(StrEnum):
+    GET = "GET"
+    POST = "POST"
+
+
+class CustomApiConfig(ExposableParamsConfig):
+    """Tenant-configured search endpoint executed by Search Proxy."""
+
+    _request_model_name: ClassVar[str] = "CustomApiSearchRequest"
+    _exposed_params_model_name: ClassVar[str] = "CustomApiExposedParams"
+
+    engine: Annotated[
+        Literal[SearchEngineType.CUSTOM_API], RJSFMetaTag.SpecialWidget.hidden()
+    ] = Field(
+        default=SearchEngineType.CUSTOM_API,
+        title="Search engine",
+        description="Provider discriminator; must be `custom_api` for this config.",
+    )
+    api_endpoint: str = Field(
+        default="https://api.example.com/search",
+        title="API endpoint",
+        description="HTTP(S) endpoint called by Search Proxy.",
+    )
+    api_headers: str = Field(
+        default='{"Content-Type": "application/json"}',
+        title="API headers",
+        description="JSON object containing headers sent to the custom API.",
+    )
+    api_additional_query_params: str = Field(
+        default="{}",
+        title="Additional query parameters",
+        description="JSON object merged into the custom API query parameters.",
+    )
+    api_additional_body_params: str = Field(
+        default="{}",
+        title="Additional body parameters",
+        description="JSON object merged into the custom API JSON body.",
+    )
+    api_request_method: CustomApiRequestMethod = Field(
+        default=CustomApiRequestMethod.GET,
+        title="Request method",
+        description="HTTP method used to call the custom API.",
+    )
+    timeout: int = Field(
+        default=120,
+        description="Custom API request timeout in seconds.",
+    )
+
+    @classmethod
+    def request_model(cls) -> type[BaseModel]:
+        return derive_request_model(
+            cls,
+            base=SearchRequestBase,
+            name=cls._request_model_name,
+        )
+
+
+CustomApiSearchRequest = CustomApiConfig.request_model()
+
+
+__all__ = [
+    "CustomApiConfig",
+    "CustomApiRequestMethod",
+    "CustomApiSearchRequest",
+]

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/unique_search_proxy_core/url_safety/__init__.py

@@ -5,8 +5,10 @@ from unique_search_proxy_core.url_safety.egress import (
 from unique_search_proxy_core.url_safety.models import (
     BlockedCrawlTarget,
     CrawlTargetValidationError,
+    CustomApiTargetValidationError,
     ResolvedCrawlTarget,
     UrlSafetyOutcome,
+    UrlSafetyValidationError,
     bypass_crawl_target,
 )
 from unique_search_proxy_core.url_safety.service import UrlSafetyService
@@ -18,7 +20,9 @@ from unique_search_proxy_core.url_safety.settings import (
 __all__ = [
     "BlockedCrawlTarget",
     "CrawlTargetValidationError",
+    "CustomApiTargetValidationError",
     "ResolvedCrawlTarget",
+    "UrlSafetyValidationError",
     "UrlSafetyOutcome",
     "UrlSafetyService",
     "UrlSafetySettings",

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/unique_search_proxy_core/url_safety/dns.py

@@ -2,7 +2,19 @@ from __future__ import annotations
 
 import asyncio
 import socket
-from ipaddress import ip_address
+from ipaddress import IPv4Network, IPv6Network, ip_address, ip_network
+
+_TRUSTED_PRIVATE_NETWORKS: tuple[IPv4Network | IPv6Network, ...] = (
+    ip_network("10.0.0.0/8"),
+    ip_network("172.16.0.0/12"),
+    ip_network("192.168.0.0/16"),
+    ip_network("fc00::/7"),
+)
+
+
+def is_trusted_private_address(address: str) -> bool:
+    parsed_address = ip_address(address)
+    return any(parsed_address in network for network in _TRUSTED_PRIVATE_NETWORKS)
 
 
 async def resolve_host_addresses(host: str) -> tuple[str, ...]:
@@ -17,6 +29,8 @@ async def resolve_host_addresses(host: str) -> tuple[str, ...]:
 
 def block_reason_for_resolved_addresses(
     resolved_addresses: tuple[str, ...],
+    *,
+    allow_trusted_private: bool = False,
 ) -> tuple[str, str] | None:
     if not resolved_addresses:
         return (
@@ -25,17 +39,23 @@ def block_reason_for_resolved_addresses(
         )
 
     for resolved_address in resolved_addresses:
-        if not ip_address(resolved_address).is_global:
-            return (
-                "private",
-                "Target host resolves to a private or special-use IP address",
-            )
+        address = ip_address(resolved_address)
+        if address.is_global:
+            continue
+        if allow_trusted_private and is_trusted_private_address(resolved_address):
+            continue
+        return (
+            "private",
+            "Target host resolves to a private or special-use IP address",
+        )
 
     return None
 
 
 async def resolve_and_validate_host(
     host: str,
+    *,
+    allow_trusted_private: bool = False,
 ) -> tuple[tuple[str, ...], tuple[str, str] | None]:
     try:
         resolved_addresses = await resolve_host_addresses(host)
@@ -45,7 +65,10 @@ async def resolve_and_validate_host(
             "Target host could not be resolved during safety validation",
         )
 
-    return resolved_addresses, block_reason_for_resolved_addresses(resolved_addresses)
+    return resolved_addresses, block_reason_for_resolved_addresses(
+        resolved_addresses,
+        allow_trusted_private=allow_trusted_private,
+    )
 
 
 async def validate_resolved_host(host: str) -> tuple[str, str] | None:

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/unique_search_proxy_core/url_safety/models.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from typing import ClassVar
 from urllib.parse import urlsplit
 
 from unique_search_proxy_core.url_safety.netloc import (
@@ -60,7 +61,9 @@ class UrlSafetyOutcome:
     blocked: BlockedCrawlTarget | None = None
 
 
-class CrawlTargetValidationError(ValueError):
+class UrlSafetyValidationError(ValueError):
+    target_label: ClassVar[str] = "URL"
+
     def __init__(self, blocked_targets: list[BlockedCrawlTarget]) -> None:
         self.blocked_targets: list[BlockedCrawlTarget] = blocked_targets
 
@@ -68,7 +71,17 @@ class CrawlTargetValidationError(ValueError):
             f"{target.display_target} ({target.reason})"
             for target in self.blocked_targets
         )
-        super().__init__(f"Blocked crawl target(s) due to URL safety policy: {details}")
+        super().__init__(
+            f"Blocked {self.target_label} target(s) due to URL safety policy: {details}"
+        )
+
+
+class CrawlTargetValidationError(UrlSafetyValidationError):
+    target_label = "crawl"
+
+
+class CustomApiTargetValidationError(UrlSafetyValidationError):
+    target_label = "Custom API"
 
 
 def bypass_crawl_target(url: str) -> ResolvedCrawlTarget:

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/unique_search_proxy_core/url_safety/policy.py

@@ -1,12 +1,28 @@
 from __future__ import annotations
 
+from collections.abc import Collection
 from ipaddress import ip_address
 from urllib.parse import urlsplit
 
+from unique_search_proxy_core.url_safety import dns
 from unique_search_proxy_core.url_safety.settings import url_safety_settings
 
 
-def validate_target_cheap(url: str) -> tuple[str, str] | None:
+def is_trusted_private_host(
+    hostname: str,
+    trusted_private_hosts: Collection[str],
+) -> bool:
+    normalized_host = hostname.rstrip(".").lower()
+    return normalized_host in {
+        host.rstrip(".").lower() for host in trusted_private_hosts
+    }
+
+
+def validate_target_cheap(
+    url: str,
+    *,
+    trusted_private_hosts: Collection[str] = (),
+) -> tuple[str, str] | None:
     """Static validation only — no DNS. Returns (category, reason) if blocked, None otherwise."""
     if not url:
         return "empty", "URL is empty"
@@ -30,10 +46,19 @@ def validate_target_cheap(url: str) -> tuple[str, str] | None:
     ):
         return "localhost", "Target points to a localhost host"
 
-    if normalized_host.endswith(url_safety_settings.service_suffix):
+    trusted_private_host = is_trusted_private_host(
+        normalized_host,
+        trusted_private_hosts,
+    )
+
+    if not trusted_private_host and normalized_host.endswith(
+        url_safety_settings.service_suffix
+    ):
         return "cluster", "Target points to an internal service host"
 
-    if normalized_host.endswith(url_safety_settings.cluster_local_suffix):
+    if not trusted_private_host and normalized_host.endswith(
+        url_safety_settings.cluster_local_suffix
+    ):
         return "cluster", "Target points to an internal cluster-local host"
 
     try:
@@ -41,12 +66,14 @@ def validate_target_cheap(url: str) -> tuple[str, str] | None:
     except ValueError:
         pass
     else:
-        if not target_ip.is_global:
+        if not target_ip.is_global and not (
+            trusted_private_host and dns.is_trusted_private_address(normalized_host)
+        ):
             return "private", "Target points to a private or special-use IP address"
 
         return None
 
-    if "." not in normalized_host:
+    if not trusted_private_host and "." not in normalized_host:
         return "cluster", "Target points to a single-label internal host"
 
     return None

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/unique_search_proxy_core/url_safety/resolver.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import asyncio
+from collections.abc import Collection
 from ipaddress import ip_address
 from urllib.parse import urlsplit
 
@@ -11,14 +12,24 @@ from unique_search_proxy_core.url_safety.models import (
     ResolvedCrawlTarget,
 )
 from unique_search_proxy_core.url_safety.netloc import extract_hostname
-from unique_search_proxy_core.url_safety.policy import validate_target_cheap
+from unique_search_proxy_core.url_safety.policy import (
+    is_trusted_private_host,
+    validate_target_cheap,
+)
 
 
-async def resolve_crawl_target(url: str) -> ResolvedCrawlTarget:
+async def resolve_crawl_target(
+    url: str,
+    *,
+    trusted_private_hosts: Collection[str] = (),
+) -> ResolvedCrawlTarget:
     """Validate and resolve a single URL, performing DNS exactly once."""
     normalized_url = url.strip()
 
-    validation_error = validate_target_cheap(normalized_url)
+    validation_error = validate_target_cheap(
+        normalized_url,
+        trusted_private_hosts=trusted_private_hosts,
+    )
     if validation_error is not None:
         category, reason = validation_error
         raise CrawlTargetValidationError(
@@ -50,7 +61,11 @@ async def resolve_crawl_target(url: str) -> ResolvedCrawlTarget:
         target_ip = ip_address(normalized_host)
     except ValueError:
         resolved_addresses, validation_error = await dns.resolve_and_validate_host(
-            normalized_host
+            normalized_host,
+            allow_trusted_private=is_trusted_private_host(
+                normalized_host,
+                trusted_private_hosts,
+            ),
         )
         if validation_error is not None:
             category, reason = validation_error

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/unique_search_proxy_core/url_safety/service.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+from collections.abc import Collection
 from ipaddress import ip_address
 from urllib.parse import urlsplit
 
@@ -10,6 +11,7 @@ from unique_search_proxy_core.url_safety import dns, redirect, resolver
 from unique_search_proxy_core.url_safety.models import (
     BlockedCrawlTarget,
     CrawlTargetValidationError,
+    CustomApiTargetValidationError,
     ResolvedCrawlTarget,
     UrlSafetyOutcome,
     bypass_crawl_target,
@@ -124,3 +126,20 @@ class UrlSafetyService:
     @staticmethod
     async def resolve_crawl_target(url: str) -> ResolvedCrawlTarget:
         return await resolver.resolve_crawl_target(url)
+
+    @staticmethod
+    async def resolve_custom_api_target(
+        url: str,
+        *,
+        trusted_private_hosts: Collection[str],
+    ) -> ResolvedCrawlTarget:
+        if not url_safety_settings.enabled:
+            return bypass_crawl_target(url)
+
+        try:
+            return await resolver.resolve_crawl_target(
+                url,
+                trusted_private_hosts=trusted_private_hosts,
+            )
+        except CrawlTargetValidationError as exc:
+            raise CustomApiTargetValidationError(exc.blocked_targets) from exc

{unique_search_proxy_core-2026.44.0.dev2 → unique_search_proxy_core-2026.44.0.dev4}/unique_search_proxy_core/url_safety/settings.py

@@ -1,6 +1,10 @@
 from __future__ import annotations
 
-from pydantic import Field
+import os
+import sys
+from pathlib import Path
+
+from pydantic import AliasChoices, Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
@@ -27,6 +31,17 @@ class UrlSafetySettings(BaseSettings):
         "metadata.azure.internal",
         "metadata.google.internal",
     ]
+    custom_api_trusted_private_hosts: list[str] = Field(
+        default_factory=list,
+        validation_alias=AliasChoices(
+            "CUSTOM_WEB_SEARCH_API_TRUSTED_PRIVATE_HOSTS",
+            "custom_api_trusted_private_hosts",
+        ),
+        description=(
+            "Exact operator-approved Custom API hostnames or IPs that may resolve "
+            "to RFC 1918 or IPv6 unique-local addresses."
+        ),
+    )
     cluster_local_suffix: str = ".cluster.local"
     service_suffix: str = ".svc"
     max_redirect_hops: int = 10
@@ -40,4 +55,26 @@ class UrlSafetySettings(BaseSettings):
     )
 
 
-url_safety_settings = UrlSafetySettings()
+def _get_settings() -> UrlSafetySettings:
+    if "pytest" in sys.modules:
+        env_file = Path(os.getcwd()) / "tests/test.env"
+    else:
+        env_file = Path(os.getcwd()) / ".env"
+
+    class _Settings(UrlSafetySettings):
+        model_config = SettingsConfigDict(
+            title=UrlSafetySettings.__name__,
+            env_file=env_file,
+            env_file_encoding="utf-8",
+            env_prefix="URL_SAFETY_",
+            extra="ignore",
+            case_sensitive=False,
+            frozen=True,
+        )
+
+    # This subclass only selects the env file; keep generated config docs stable.
+    _Settings.__name__ = UrlSafetySettings.__name__
+    return _Settings()
+
+
+url_safety_settings = _get_settings()