unique_web_search 2026.26.0.dev8__tar.gz → 2026.26.0.dev10__tar.gz

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-web-search
-Version: 2026.26.0.dev8
+Version: 2026.26.0.dev10
 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>
@@ -28,7 +28,8 @@ Requires-Dist: certifi>=2025.11.12
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: playwright>=1.58.0
 Requires-Dist: perplexityai>=0.34.0
-Requires-Dist: unique-search-proxy-core>=2026.26.0.dev6,<2026.26.0rc0
+Requires-Dist: unique-search-proxy-core>=2026.26.0.dev7,<2026.26.0rc0
+Requires-Dist: unique-search-proxy-sdk>=2026.26.0.dev5,<2026.26.0rc0
 Requires-Python: >=3.12, <4.0
 Description-Content-Type: text/markdown
 

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_web_search"
-version = "2026.26.0.dev8"
+version = "2026.26.0.dev10"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12,<4.0"
@@ -34,8 +34,8 @@ dependencies = [
     "jinja2>=3.1.6",
     "playwright>=1.58.0",
     "perplexityai>=0.34.0",
-    "unique-search-proxy-core>=2026.26.0.dev6,<2026.26.0rc0",
-    # "unique-search-proxy-sdk>=2026.24.0.dev0",
+    "unique-search-proxy-core>=2026.26.0.dev7,<2026.26.0rc0",
+    "unique-search-proxy-sdk>=2026.26.0.dev5,<2026.26.0rc0",
 ]
 
 [build-system]
@@ -93,5 +93,5 @@ extend-select = ["I"]
 
 [tool.uv.sources]
 unique-toolkit = { workspace = true }
-# unique-search-proxy-sdk = { workspace = true }
+unique-search-proxy-sdk = { workspace = true }
 unique-search-proxy-core = { workspace = true }

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/src/unique_web_search/client_settings.py

@@ -235,30 +235,3 @@ def get_perplexity_search_settings() -> PerplexitySearchSettings:
     if _perplexity_search_settings is None:
         _perplexity_search_settings = PerplexitySearchSettings.from_env_settings()
     return _perplexity_search_settings
-
-
-class SearchProxySettings(BaseModel):
-    base_url: str | None = None
-
-    @property
-    def is_configured(self) -> bool:
-        return self.base_url is not None
-
-    @classmethod
-    def from_env_settings(cls):
-        if env_settings.search_proxy_base_url is None:
-            _LOGGER.warning("Unique Search Proxy missing required setting: Base URL")
-        else:
-            _LOGGER.info("Unique Search Proxy is properly configured")
-
-        return cls(base_url=env_settings.search_proxy_base_url)
-
-
-_search_proxy_settings: SearchProxySettings | None = None
-
-
-def get_search_proxy_settings() -> SearchProxySettings:
-    global _search_proxy_settings
-    if _search_proxy_settings is None:
-        _search_proxy_settings = SearchProxySettings.from_env_settings()
-    return _search_proxy_settings

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/src/unique_web_search/services/argument_screening/config.py

@@ -42,6 +42,17 @@ class ArgumentScreeningConfig(BaseModel):
         title="Screening Guidelines",
         description="Rules the screening agent follows to decide whether arguments are safe. This is the primary field for administrators to customize.",
     )
+    organization_specific_blocked_keywords: Annotated[
+        list[str],
+        RJSFMetaTag({"ui:options": {"orderable": False}}),
+    ] = Field(
+        default_factory=list,
+        title="Organization-Specific Blocked Keywords",
+        description=(
+            "Terms, domains, product names, portals, or internal project names "
+            "that must always block WebSearch when detected."
+        ),
+    )
     system_prompt: Annotated[
         str,
         RJSFMetaTag.StringWidget.textarea(rows=4),

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/src/unique_web_search/services/argument_screening/prompts/__init__.py

@@ -7,6 +7,9 @@ _PROMPTS_DIR = Path(__file__).parent
 DEFAULT_SYSTEM_PROMPT: str = load_template(_PROMPTS_DIR, "system_prompt.j2")
 DEFAULT_USER_PROMPT_TEMPLATE: str = load_template(_PROMPTS_DIR, "user_prompt.j2")
 DEFAULT_GUIDELINES: str = load_template(_PROMPTS_DIR, "guidelines.j2")
+DEFAULT_GUIDELINES_WITH_KEYWORDS_TEMPLATE: str = load_template(
+    _PROMPTS_DIR, "guidelines_with_keywords.j2"
+)
 DEFAULT_REJECTION_RESPONSE_TEMPLATE: str = load_template(
     _PROMPTS_DIR, "rejection_response.j2"
 )

unique_web_search-2026.26.0.dev10/src/unique_web_search/services/argument_screening/prompts/guidelines.j2

@@ -0,0 +1,40 @@
+Flag the request as "no-go" if the arguments would send client-identifying data (CID), bank-client relationship information, confidential financial information, credentials, or internal/private infrastructure details to WebSearch.
+
+The goal is not general GDPR classification. The goal is to prevent clear-text data that could directly, indirectly, or potentially indirectly identify a private person or entity as a client, prospect, employee, counterparty, or related party of the organization from leaving the Unique environment through WebSearch.
+
+When any violation is detected, stop immediately. Do not echo, summarize, transform, or reproduce the sensitive values. The reason must reference only the violated category, for example "client-identifying data", "bank-client relationship", "financial identifier", "blocked organization keyword", "credentials", or "internal infrastructure".
+
+Apply all rules even when names, keywords, domains, or identifiers are misspelled, abbreviated, spaced out, hyphenated, split across words, or otherwise obfuscated.
+
+## Blocked By Default
+Mark as "no-go" if the query contains any of the following:
+
+- Direct identifiers of a private individual or private entity: full name, partial name with context, address, email address, phone number, date of birth, passport number, national ID, tax ID, social security number, driver's license number, employee ID, client ID, customer number, CRM ID, ticket ID, or any similar unique identifier.
+- Financial identifiers: bank account number, IBAN, routing number, SWIFT/BIC tied to a person or account, credit/debit card number, portfolio number, custody account, mandate ID, transaction reference, payment reference, invoice number tied to a client, loan number, mortgage number, or insurance policy number.
+- Bank-client relationship signals: any statement or question implying that a private person or private entity is a client, customer, prospect, account holder, beneficial owner, portfolio owner, mandate holder, borrower, investor, relationship-managed client, or onboarding/KYC subject.
+- Financial context linked to an identifiable person or private entity: holdings, portfolio value, assets under management, transactions, trades, account balance, source of wealth, income, salary, compensation, creditworthiness, risk rating, KYC/AML status, sanctions/PEP screening, complaints, legal disputes, debt, collateral, or tax situation.
+- Indirect or potentially indirect identification: combinations of attributes that could identify a client even without a name, such as date of birth plus nationality plus profession, location plus relationship manager plus portfolio size, branch plus rare occupation, company plus owner details, or any narrow combination of facts about a non-public person or private entity.
+- Confidential business or non-public information: MNPI, trade secrets, internal reports, unpublished client lists, internal project names, confidential contracts, deal names, acquisition targets, or proprietary research.
+- Authentication and secrets: passwords, PINs, API keys, tokens, private keys, recovery phrases, session cookies, authorization headers, or secret URLs.
+- Internal or private infrastructure: private URLs, intranet hosts, internal IP addresses, VPN hosts, non-public service names, internal dashboards, private storage links, internal ticket links, or environment-specific system details.
+
+## Public Information That Can Be Allowed
+Mark as "go" only when the query is clearly outside CID and does not include organization-specific blocked keywords:
+
+- General knowledge, technical, legal, or regulatory questions not tied to an identifiable private person, private entity, or the organization.
+- Public organizations, public products, market news, public events, or public company information where no private client relationship is implied.
+- Public figures in their public capacity, such as politicians, executives, athletes, or public officials, when the query concerns publicly available public-role information and not private banking, personal financial, health, family, address, or contact details.
+- Aggregated or anonymized statistics where no individual, client, small group, relationship manager, branch, or private entity can be singled out.
+
+## Ambiguity Rule
+If it is unclear whether the query contains CID or implies a bank-client relationship, choose "no-go". WebSearch is an external disclosure path, so the safe default is to block ambiguous private-person or client-context queries.
+
+## Reason Style
+Return a short category-only reason. Do not include raw names, account numbers, emails, phone numbers, domains, URLs, or any sensitive values in the reason.
+
+## Organization-Specific Blocked Keywords
+Mark as "no-go" for any query containing organization-specific blocked terms or close variants, including misspellings, spacing, punctuation, hyphenation, domain variants, product names, internal project names, portal names, or other configured sensitive terms.
+
+This keyword rule applies even if the rest of the query looks public or harmless. If no organization-specific terms are configured, ignore this section.
+
+Configured blocked terms:

unique_web_search-2026.26.0.dev10/src/unique_web_search/services/argument_screening/prompts/guidelines_with_keywords.j2

@@ -0,0 +1,7 @@
+{{ guidelines.rstrip() }}
+
+{% for keyword in organization_specific_blocked_keywords -%}
+- {{ keyword }}
+{% else -%}
+- [none configured]
+{% endfor %}

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/src/unique_web_search/services/argument_screening/service.py

@@ -22,6 +22,9 @@ from unique_web_search.services.argument_screening.config import (
 from unique_web_search.services.argument_screening.exceptions import (
     ArgumentScreeningUnparseableResponseException,
 )
+from unique_web_search.services.argument_screening.prompts import (
+    DEFAULT_GUIDELINES_WITH_KEYWORDS_TEMPLATE,
+)
 from unique_web_search.services.message_log import WebSearchMessageLogger
 from unique_web_search.services.structured_llm import (
     StructuredLlmUnparseableResponseError,
@@ -92,9 +95,18 @@ class ArgumentScreeningService:
         _LOGGER.info("Running argument screening agent...")
 
         serialized_args = json.dumps(arguments, indent=2, default=str)
+        rendered_guidelines = Template(
+            DEFAULT_GUIDELINES_WITH_KEYWORDS_TEMPLATE
+        ).render(
+            guidelines=self._config.guidelines,
+            organization_specific_blocked_keywords=(
+                self._config.organization_specific_blocked_keywords
+            ),
+        )
+
         user_prompt = Template(self._config.user_prompt_template).render(
             arguments=serialized_args,
-            guidelines=self._config.guidelines,
+            guidelines=rendered_guidelines,
         )
 
         try:

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/src/unique_web_search/services/crawlers/base.py

@@ -1,6 +1,6 @@
 from abc import ABC, abstractmethod
 from enum import StrEnum
-from typing import Generic, TypeVar
+from typing import ClassVar, Generic, TypeVar
 
 from pydantic import BaseModel
 from unique_search_proxy_core.url_safety import (
@@ -17,6 +17,7 @@ from unique_web_search.services.helpers import (
     clean_model_title_generator,
     experimental_model_title_generator,
 )
+from unique_web_search.services.proxy.bridge import search_proxy_client_enabled
 
 
 class CrawlerType(StrEnum):
@@ -52,17 +53,25 @@ CrawlerConfig = TypeVar(
 
 
 class BaseCrawler(ABC, Generic[CrawlerConfig]):
+    supports_proxy_crawl: ClassVar[bool] = False
+
     def __init__(self, config: CrawlerConfig):
         self.config = config
 
     async def crawl(self, urls: list[str]) -> list[str]:
+        if search_proxy_client_enabled and self.supports_proxy_crawl:
+            return await self._proxy_crawl(urls)
+
         try:
             targets = await UrlSafetyService.validate_batch_urls(urls)
         except CrawlTargetValidationError as exc:
             for target in exc.blocked_targets:
                 crawl_blocked.labels(reason_category=target.category).inc()
             raise
-        return await self._crawl(targets)
+        return await self._legacy_crawl(targets)
+
+    @abstractmethod
+    async def _proxy_crawl(self, urls: list[str]) -> list[str]: ...
 
     @abstractmethod
-    async def _crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]: ...
+    async def _legacy_crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]: ...

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/src/unique_web_search/services/crawlers/basic.py

@@ -20,6 +20,10 @@ from unique_web_search.services.crawlers.url_safety import (
     ResolvedCrawlTarget,
 )
 from unique_web_search.services.crawlers.utils import get_random_user_agent
+from unique_web_search.services.proxy.bridge import (
+    open_search_proxy_client,
+)
+from unique_web_search.services.proxy.mappers import map_crawl_response
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -51,6 +55,8 @@ class BasicCrawlerConfig(BaseCrawlerConfig[CrawlerType.BASIC]):
 
 
 class BasicCrawler(BaseCrawler[BasicCrawlerConfig]):
+    supports_proxy_crawl = True
+
     def __init__(self, config: BasicCrawlerConfig):
         super().__init__(config)
 
@@ -63,7 +69,19 @@ class BasicCrawler(BaseCrawler[BasicCrawlerConfig]):
     #     tags=["basic", "scrape"],
     # )
     @override
-    async def _crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]:
+    async def _proxy_crawl(self, urls: list[str]) -> list[str]:
+        async with open_search_proxy_client(
+            timeout=float(self.config.timeout),
+        ) as client:
+            response = await client.crawl.basic(
+                urls=urls,
+                timeout=int(self.config.timeout),
+                max_concurrent_requests=self.config.max_concurrent_requests,
+            )
+            return map_crawl_response(response, urls)
+
+    @override
+    async def _legacy_crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]:
         async with async_client(timeout=Timeout(self.config.timeout)) as client:
             tasks = [self._crawl_url_with_client(client, target) for target in targets]
             results = await asyncio.gather(*tasks, return_exceptions=True)

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/src/unique_web_search/services/crawlers/crawl4ai.py

@@ -1,6 +1,6 @@
 import logging
 from enum import StrEnum
-from typing import Any, Literal
+from typing import Any, Literal, override
 
 from pydantic import BaseModel, Field
 from unique_toolkit.agentic.tools.config import get_configuration_dict
@@ -169,6 +169,9 @@ class Crawl4AiCrawler(BaseCrawler[Crawl4AiCrawlerConfig]):
     # @track(
     #     tags=["crawl4ai", "scrape"],
     # )
+    @override
+    async def _proxy_crawl(self, urls: list[str]) -> list[str]:
+        raise NotImplementedError("Crawl4AiCrawler does not support proxy crawl")
 
     @staticmethod
     def _get_ssrf_guard_hook():
@@ -209,7 +212,8 @@ class Crawl4AiCrawler(BaseCrawler[Crawl4AiCrawlerConfig]):
 
         return _ssrf_guard_hook
 
-    async def _crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]:
+    @override
+    async def _legacy_crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]:
         urls = [target.normalized_url for target in targets]
         # Lazy import of crawl4ai - only import when actually needed
         from crawl4ai import (

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/src/unique_web_search/services/crawlers/firecrawl.py

@@ -1,4 +1,4 @@
-from typing import Literal
+from typing import Literal, override
 
 from firecrawl import AsyncFirecrawl
 
@@ -11,6 +11,10 @@ from unique_web_search.services.crawlers.base import (
     CrawlerType,
 )
 from unique_web_search.services.crawlers.url_safety import ResolvedCrawlTarget
+from unique_web_search.services.proxy.bridge import (
+    open_search_proxy_client,
+)
+from unique_web_search.services.proxy.mappers import map_crawl_response
 
 
 class FirecrawlCrawlerConfig(BaseCrawlerConfigExperimental[CrawlerType.FIRECRAWL]):
@@ -18,6 +22,8 @@ class FirecrawlCrawlerConfig(BaseCrawlerConfigExperimental[CrawlerType.FIRECRAWL
 
 
 class FirecrawlCrawler(BaseCrawler[FirecrawlCrawlerConfig]):
+    supports_proxy_crawl = True
+
     def __init__(self, config: FirecrawlCrawlerConfig):
         super().__init__(config)
 
@@ -25,8 +31,22 @@ class FirecrawlCrawler(BaseCrawler[FirecrawlCrawlerConfig]):
     # @track(
     #     tags=["firecrawl", "scrape"],
     # )
-    async def _crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]:
+    @override
+    async def _proxy_crawl(self, urls: list[str]) -> list[str]:
+        async with open_search_proxy_client(
+            timeout=float(self.config.timeout),
+        ) as client:
+            response = await client.crawl.firecrawl(
+                urls=urls,
+                timeout=int(self.config.timeout),
+                only_main_content=True,
+            )
+            return map_crawl_response(response, urls)
+
+    @override
+    async def _legacy_crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]:
         urls = [target.normalized_url for target in targets]
+
         api_key = get_firecrawl_search_settings().api_key
         assert api_key is not None, "Firecrawl API key is not configured"
 

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/src/unique_web_search/services/crawlers/jina.py

@@ -1,8 +1,9 @@
 import asyncio
-from typing import Any, Literal
+from typing import Any, Literal, cast, override
 
 from httpx import AsyncClient
 from pydantic import BaseModel, Field, HttpUrl
+from unique_search_proxy_core.crawlers.jina.schema import JinaEngine, JinaReturnFormat
 
 from unique_web_search.client_settings import get_jina_search_settings
 from unique_web_search.services.crawlers.base import (
@@ -11,6 +12,10 @@ from unique_web_search.services.crawlers.base import (
     CrawlerType,
 )
 from unique_web_search.services.crawlers.url_safety import ResolvedCrawlTarget
+from unique_web_search.services.proxy.bridge import (
+    open_search_proxy_client,
+)
+from unique_web_search.services.proxy.mappers import map_crawl_response
 
 
 class ReaderBody(BaseModel):
@@ -46,6 +51,8 @@ class JinaCrawlerConfig(BaseCrawlerConfigExperimental[CrawlerType.JINA]):
 
 
 class JinaCrawler(BaseCrawler[JinaCrawlerConfig]):
+    supports_proxy_crawl = True
+
     def __init__(self, config: JinaCrawlerConfig):
         super().__init__(config)
 
@@ -53,8 +60,28 @@ class JinaCrawler(BaseCrawler[JinaCrawlerConfig]):
     # @track(
     #     tags=["jina", "scrape"],
     # )
-    async def _crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]:
+    @override
+    async def _proxy_crawl(self, urls: list[str]) -> list[str]:
+        headers = self.config.headers
+        async with open_search_proxy_client(
+            timeout=float(self.config.timeout),
+        ) as client:
+            response = await client.crawl.jina(
+                urls=urls,
+                timeout=int(self.config.timeout),
+                return_format=cast(
+                    JinaReturnFormat,
+                    headers.get("X-Return-Format", "markdown"),
+                ),
+                engine=cast(JinaEngine, headers.get("X-Engine", "browser")),
+                do_not_track=headers.get("DNT") == "1",
+            )
+            return map_crawl_response(response, urls)
+
+    @override
+    async def _legacy_crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]:
         urls = [target.normalized_url for target in targets]
+
         jina_settings = get_jina_search_settings()
         api_key = jina_settings.api_key
         assert api_key is not None, "Jina API key is not configured"

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/src/unique_web_search/services/crawlers/tavily.py

@@ -10,6 +10,10 @@ from unique_web_search.services.crawlers.base import (
     CrawlerType,
 )
 from unique_web_search.services.crawlers.url_safety import ResolvedCrawlTarget
+from unique_web_search.services.proxy.bridge import (
+    open_search_proxy_client,
+)
+from unique_web_search.services.proxy.mappers import map_crawl_response
 
 
 class TavilyCrawlerConfig(BaseCrawlerConfigExperimental[CrawlerType.TAVILY]):
@@ -18,6 +22,8 @@ class TavilyCrawlerConfig(BaseCrawlerConfigExperimental[CrawlerType.TAVILY]):
 
 
 class TavilyCrawler(BaseCrawler[TavilyCrawlerConfig]):
+    supports_proxy_crawl = True
+
     def __init__(self, config: TavilyCrawlerConfig):
         super().__init__(config)
 
@@ -25,8 +31,23 @@ class TavilyCrawler(BaseCrawler[TavilyCrawlerConfig]):
     # @track(
     #     tags=["tavily", "scrape"],
     # )
-    async def _crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]:
+    async def _proxy_crawl(self, urls: list[str]) -> list[str]:
+        async with open_search_proxy_client(
+            timeout=float(self.config.timeout),
+        ) as client:
+            response = await client.crawl.tavily(
+                urls=urls,
+                timeout=int(self.config.timeout),
+                extract_depth=self.config.depth,
+                format="markdown",
+                include_images=False,
+                include_favicon=False,
+            )
+            return map_crawl_response(response, urls)
+
+    async def _legacy_crawl(self, targets: list[ResolvedCrawlTarget]) -> list[str]:
         urls = [target.normalized_url for target in targets]
+
         api_key = get_tavily_search_settings().api_key
         assert api_key is not None, "Tavily API key is not configured"
 

unique_web_search-2026.26.0.dev10/src/unique_web_search/services/proxy/__init__.py

@@ -0,0 +1,21 @@
+from unique_web_search.services.proxy.bridge import (
+    open_search_proxy_client,
+    search_proxy_client_enabled,
+)
+from unique_web_search.services.proxy.mappers import (
+    agent_answer_text,
+    map_agent_answer,
+    map_crawl_response,
+    map_search_response,
+    result_to_markdown,
+)
+
+__all__ = [
+    "agent_answer_text",
+    "map_agent_answer",
+    "map_crawl_response",
+    "map_search_response",
+    "open_search_proxy_client",
+    "result_to_markdown",
+    "search_proxy_client_enabled",
+]

unique_web_search-2026.26.0.dev10/src/unique_web_search/services/proxy/bridge.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from unique_search_proxy_sdk import UniqueSearchProxyClient
+
+from unique_web_search.settings import env_settings
+
+search_proxy_client_enabled = env_settings.search_proxy_base_url is not None
+
+
+@asynccontextmanager
+async def open_search_proxy_client(
+    timeout: float,
+) -> AsyncIterator[UniqueSearchProxyClient]:
+    base_url = env_settings.search_proxy_base_url
+    assert base_url is not None, "Unique Search Proxy base URL is not configured"
+
+    async with UniqueSearchProxyClient(
+        base_url=base_url,
+        timeout=timeout,
+    ) as client:
+        yield client
+
+
+__all__ = [
+    "open_search_proxy_client",
+    "search_proxy_client_enabled",
+]

unique_web_search-2026.26.0.dev10/src/unique_web_search/services/proxy/mappers.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from unique_search_proxy_sdk._generated.models.agent_search_response import (
+    AgentSearchResponse,
+)
+from unique_search_proxy_sdk._generated.models.crawl_response import CrawlResponse
+from unique_search_proxy_sdk._generated.models.crawl_url_result import CrawlUrlResult
+from unique_search_proxy_sdk._generated.models.per_url_error import PerUrlError
+from unique_search_proxy_sdk._generated.models.search_response import SearchResponse
+
+if TYPE_CHECKING:
+    from unique_web_search.services.search_engine.schema import WebSearchResult
+    from unique_web_search.services.search_engine.utils.grounding.response_parsing import (
+        ResponseParser,
+    )
+
+
+def map_search_response(response: SearchResponse) -> list[WebSearchResult]:
+    from unique_web_search.services.search_engine.schema import WebSearchResult
+
+    return [
+        WebSearchResult(
+            url=result.url,
+            title=result.title,
+            snippet=result.snippet,
+            content=result.content if isinstance(result.content, str) else "",
+        )
+        for result in response.curated
+    ]
+
+
+_CRAWL_RESULT_TEMPLATE = "URL: {url}\n\n{body}"
+
+
+def _crawl_result_body(result: CrawlUrlResult) -> str:
+    if isinstance(result.content, str):
+        return result.content
+
+    if isinstance(result.error, PerUrlError):
+        return f"Error: {result.error.message}"
+
+    return "Error: No content returned by search proxy"
+
+
+def result_to_markdown(result: CrawlUrlResult) -> str:
+    return _CRAWL_RESULT_TEMPLATE.format(
+        url=result.url,
+        body=_crawl_result_body(result),
+    )
+
+
+def map_crawl_response(response: CrawlResponse, urls: list[str]) -> list[str]:
+    return [result_to_markdown(result) for result in response.results]
+
+
+async def map_agent_answer(
+    answer: str,
+    parsers: Sequence[ResponseParser],
+) -> list[WebSearchResult]:
+    from unique_web_search.services.search_engine.utils.grounding.response_parsing import (
+        convert_response_to_search_results,
+    )
+
+    return await convert_response_to_search_results(answer, list(parsers))
+
+
+def agent_answer_text(response: AgentSearchResponse) -> str:
+    if isinstance(response.answer, str):
+        return response.answer
+    return ""

{unique_web_search-2026.26.0.dev8 → unique_web_search-2026.26.0.dev10}/src/unique_web_search/services/search_engine/base.py

@@ -1,10 +1,11 @@
 from abc import ABC, abstractmethod
 from enum import StrEnum
-from typing import Generic, TypeVar
+from typing import ClassVar, Generic, TypeVar
 
 from pydantic import BaseModel, ConfigDict, Field
 from unique_toolkit.agentic.tools.config import get_configuration_dict
 
+from unique_web_search.services.proxy.bridge import search_proxy_client_enabled
 from unique_web_search.services.search_engine.schema import (
     WebSearchResult,
 )
@@ -104,16 +105,16 @@ class SearchEngine(ABC, Generic[SearchEngineConfig]):
     """Base class for the search engine. It provides the common methods to search the web. This allows to use different search engines easily.
 
     Abstract Methods:
-        _extract_urls: Clean the response from the search engine.
-        _get_request_params: Get the request parameters.
+        _legacy_search: Direct search implementation (no proxy).
         requires_scraping: Whether the search engine requires scraping.
 
-    Args:
-        assistant: The assistant configuration.
-        chat_manager: The chat manager.
+    Subclasses with proxy support set ``supports_proxy_search = True`` and
+    implement ``_proxy_search``.
 
     """
 
+    supports_proxy_search: ClassVar[bool] = False
+
     def __init__(self, config: SearchEngineConfig):
         self.config = config
 
@@ -122,6 +123,16 @@ class SearchEngine(ABC, Generic[SearchEngineConfig]):
     def requires_scraping(self) -> bool:
         """Whether the search engine requires scraping."""
 
-    @abstractmethod
     async def search(self, query: str, **kwargs) -> list[WebSearchResult]:
         """Search the web for the given query using the search engine."""
+        if search_proxy_client_enabled and self.supports_proxy_search:
+            return await self._proxy_search(query=query, **kwargs)
+        return await self._legacy_search(query=query, **kwargs)
+
+    @abstractmethod
+    async def _proxy_search(self, query: str, **kwargs) -> list[WebSearchResult]:
+        """Search the web via the search proxy."""
+
+    @abstractmethod
+    async def _legacy_search(self, query: str, **kwargs) -> list[WebSearchResult]:
+        """Search the web directly without the search proxy."""