unique-web-search 2026.28.0.dev2__tar.gz → 2026.28.0.dev4__tar.gz

{unique_web_search-2026.28.0.dev2 → unique_web_search-2026.28.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-web-search
-Version: 2026.28.0.dev2
+Version: 2026.28.0.dev4
 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>
@@ -17,7 +17,7 @@ Requires-Dist: tavily-python>=0.7.11,<1
 Requires-Dist: unidecode>=1.4.0,<2
 Requires-Dist: azure-ai-projects>=1.0.0,<2
 Requires-Dist: azure-identity>=1.25.0,<2
-Requires-Dist: unique-toolkit[monitoring]>=2026.28.0.dev5,<2026.28.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.28.0.dev12,<2026.28.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
@@ -27,9 +27,8 @@ Requires-Dist: httpx>=0.28.1
 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.28.0.dev2,<2026.28.0rc0
-Requires-Dist: unique-search-proxy-sdk>=2026.28.0.dev2,<2026.28.0rc0
+Requires-Dist: unique-search-proxy-core>=2026.28.0.dev3,<2026.28.0rc0
+Requires-Dist: unique-search-proxy-sdk>=2026.28.0.dev3,<2026.28.0rc0
 Requires-Python: >=3.12, <4.0
 Description-Content-Type: text/markdown
 

{unique_web_search-2026.28.0.dev2 → unique_web_search-2026.28.0.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_web_search"
-version = "2026.28.0.dev2"
+version = "2026.28.0.dev4"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12,<4.0"
@@ -23,7 +23,7 @@ dependencies = [
     "unidecode>=1.4.0,<2",
     "azure-ai-projects>=1.0.0,<2",
     "azure-identity>=1.25.0,<2",
-    "unique-toolkit[monitoring]>=2026.28.0.dev5,<2026.28.0rc0",
+    "unique-toolkit[monitoring]>=2026.28.0.dev12,<2026.28.0rc0",
     "azure-core>=1.36.0,<2",
     "google-cloud-aiplatform>=1.128.0,<2",
     "google-auth>=2.43.0,<3",
@@ -33,9 +33,8 @@ dependencies = [
     "certifi>=2025.11.12",
     "jinja2>=3.1.6",
     "playwright>=1.58.0",
-    "perplexityai>=0.34.0",
-    "unique-search-proxy-core>=2026.28.0.dev2,<2026.28.0rc0",
-    "unique-search-proxy-sdk>=2026.28.0.dev2,<2026.28.0rc0",
+    "unique-search-proxy-core>=2026.28.0.dev3,<2026.28.0rc0",
+    "unique-search-proxy-sdk>=2026.28.0.dev3,<2026.28.0rc0",
 ]
 
 [build-system]

{unique_web_search-2026.28.0.dev2 → unique_web_search-2026.28.0.dev4}/src/unique_web_search/config.py

@@ -173,7 +173,7 @@ class WebSearchConfig(BaseToolConfig):
         default_factory=DefaultSearchEngine,  # type: ignore (This type is computed at runtime so pyright is not able to infer it)
         title="Search Engine",
         description="Choose and configure which search engine to use for web searches (e.g. Google, Bing, Brave).",
-        discriminator="search_engine_name",
+        discriminator="engine",
     )
 
     crawler_config: ActivatedCrawler = Field(  # type: ignore (This type is computed at runtime so pyright is not able to infer it)

{unique_web_search-2026.28.0.dev2 → unique_web_search-2026.28.0.dev4}/src/unique_web_search/service.py

@@ -115,7 +115,7 @@ class WebSearchTool(Tool[WebSearchConfig]):
         """Derive the search-engine mode, respecting CustomAPI overrides."""
         cfg = self.search_engine_service.config
         override = cfg.search_engine_mode if isinstance(cfg, CustomAPIConfig) else None
-        return get_search_engine_mode(cfg.search_engine_name, override=override)
+        return get_search_engine_mode(cfg.engine, override=override)
 
     @override
     def tool_description(self) -> LanguageModelToolDescription:

unique_web_search-2026.28.0.dev4/src/unique_web_search/services/_registry.py

@@ -0,0 +1,115 @@
+"""Generic self-registration registry for pluggable service implementations."""
+
+from __future__ import annotations
+
+import importlib
+import operator
+import pkgutil
+from dataclasses import dataclass
+from enum import Enum
+from functools import reduce
+from typing import Any, Callable, Generic, Iterable, TypeVar
+
+from pydantic import BaseModel
+
+K = TypeVar("K", bound=Enum)
+S = TypeVar("S", bound="BaseSpec[Any]")
+
+
+@dataclass(frozen=True)
+class BaseSpec(Generic[K]):
+    """Metadata shared by every registered implementation."""
+
+    name: str
+    key: K
+    config_cls: type[BaseModel]
+    impl_cls: type
+
+
+class Registry(Generic[K, S]):
+    """Collects implementation specs keyed by a discriminator enum value."""
+
+    def __init__(self, spec_cls: type[S]) -> None:
+        self._spec_cls = spec_cls
+        self._by_key: dict[K, S] = {}
+
+    def register(
+        self,
+        *,
+        name: str,
+        key: K,
+        config_cls: type[BaseModel],
+        **extra: Any,
+    ) -> Callable[[type], type]:
+        def deco(impl_cls: type) -> type:
+            if key in self._by_key:
+                raise ValueError(f"{key!r} already registered")
+            self._by_key[key] = self._spec_cls(
+                name=name,
+                key=key,
+                config_cls=config_cls,
+                impl_cls=impl_cls,
+                **extra,
+            )
+            return impl_cls
+
+        return deco
+
+    @property
+    def specs(self) -> tuple[S, ...]:
+        return tuple(self._by_key.values())
+
+    def __getitem__(self, key: K) -> S:
+        return self._by_key[key]
+
+    def by_name(self) -> dict[str, S]:
+        return {spec.name: spec for spec in self._by_key.values()}
+
+    def name_to_config(self) -> dict[str, type[BaseModel]]:
+        return {spec.name: spec.config_cls for spec in self._by_key.values()}
+
+    def config_types_from_names(self, names: list[str]) -> type[BaseModel]:
+        assert len(names) >= 1, "At least one name must be provided"
+
+        by_name = self.by_name()
+        selected_types = [
+            by_name[name.lower()].config_cls
+            for name in names
+            if name.lower() in by_name
+        ]
+        if not selected_types:
+            raise ValueError(f"No config found for names: {names}")
+        if len(selected_types) == 1:
+            return selected_types[0]
+        return reduce(operator.or_, selected_types)
+
+    def default_config(self, names: list[str]) -> type[BaseModel]:
+        assert len(names) >= 1, "At least one name must be provided"
+        return self.by_name()[names[0].lower()].config_cls
+
+    def autodiscover(
+        self,
+        path: Iterable[str],
+        package: str,
+        *,
+        exclude: frozenset[str] | set[str] = frozenset(),
+    ) -> None:
+        for info in pkgutil.iter_modules(path):
+            if info.ispkg or info.name.startswith("_") or info.name in exclude:
+                continue
+            importlib.import_module(f"{package}.{info.name}")
+
+    def assert_enum_coverage(
+        self,
+        *enums: type[Enum],
+        exempt: frozenset[Enum] | set[Enum] = frozenset(),
+    ) -> None:
+        registered = set(self._by_key.keys())
+        for enum_cls in enums:
+            for member in enum_cls:
+                if member in exempt:
+                    continue
+                if member not in registered:
+                    raise AssertionError(
+                        f"{enum_cls.__name__}.{member.name} has no registry entry"
+                    )

{unique_web_search-2026.28.0.dev2 → unique_web_search-2026.28.0.dev4}/src/unique_web_search/services/executors/v1/executor.py

@@ -272,9 +272,9 @@ class WebSearchV1Executor(BaseWebSearchExecutor[WebSearchToolParameters]):
     async def _search(
         self, query: str, date_restrict: str | None
     ) -> list[WebSearchResult]:
-        engine = self.search_service.config.search_engine_name.value
+        engine = self.search_service.config.engine.value
         start_time = time()
-        _LOGGER.info(f"Company {self.company_id} Searching with {self.search_service}")
+        _LOGGER.info(f"Company {self.company_id} Searching with {engine}")
         with metric_scope(search_duration, search_errors, engine=engine):
             search_total.labels(engine=engine).inc()
             search_results = await self.search_service.search(
@@ -282,14 +282,12 @@ class WebSearchV1Executor(BaseWebSearchExecutor[WebSearchToolParameters]):
             )
         end_time = time()
         delta_time = end_time - start_time
-        _LOGGER.info(
-            f"Searched with {self.search_service} completed in {delta_time} seconds"
-        )
+        _LOGGER.info(f"Searched with {engine} completed in {delta_time} seconds")
         self.debug_info.steps.append(
             StepDebugInfo(
                 step_name="search",
                 execution_time=delta_time,
-                config=self.search_service.config.search_engine_name.name,
+                config=self.search_service.config.engine.name,
                 extra={
                     "query": query,
                     "date_restrict": date_restrict,

{unique_web_search-2026.28.0.dev2 → unique_web_search-2026.28.0.dev4}/src/unique_web_search/services/executors/v2/executor.py

@@ -119,14 +119,15 @@ class WebSearchV2Executor(BaseWebSearchExecutor[WebSearchPlan]):
             )
         )
 
-        engine = self.search_service.config.search_engine_name.value
+        engine = self.search_service.config.engine.value
         time_start = time()
-        _LOGGER.info(f"Company {self.company_id} Searching with {self.search_service}")
+        _LOGGER.info(f"Company {self.company_id} Searching with {engine}")
 
         await self._message_log_callback.log_queries([step.query_or_url])
         with metric_scope(search_duration, search_errors, engine=engine):
             search_total.labels(engine=engine).inc()
             results = await self.search_service.search(step.query_or_url)
+
         await self._message_log_callback.log_web_search_results(results)
 
         delta_time = time() - time_start
@@ -135,7 +136,7 @@ class WebSearchV2Executor(BaseWebSearchExecutor[WebSearchPlan]):
             StepDebugInfo(
                 step_name=f"{step_name}.search",
                 execution_time=delta_time,
-                config=self.search_service.config.search_engine_name.name,
+                config=engine,
                 extra={
                     "query": step.query_or_url,
                     "number_of_results": len(results),
@@ -144,9 +145,7 @@ class WebSearchV2Executor(BaseWebSearchExecutor[WebSearchPlan]):
             )
         )
 
-        _LOGGER.info(
-            f"Searched with {self.search_service} completed in {delta_time} seconds"
-        )
+        _LOGGER.info(f"Searched with {engine} completed in {delta_time} seconds")
 
         if self.search_service.requires_scraping and results:
             results = await self._crawl_search_results(step_name, results)
@@ -159,7 +158,7 @@ class WebSearchV2Executor(BaseWebSearchExecutor[WebSearchPlan]):
         """Crawl URLs for the given search results and fill content. Call when results non-empty."""
         crawler = self.crawler_service.config.crawler_type.value
         time_start = time()
-        _LOGGER.info(f"Company {self.company_id} Crawling with {self.crawler_service}")
+        _LOGGER.info(f"Company {self.company_id} Crawling with {crawler}")
         with metric_scope(crawl_duration, crawl_errors, crawler=crawler):
             crawl_results = await self.crawler_service.crawl(
                 [result.url for result in results]
@@ -172,7 +171,7 @@ class WebSearchV2Executor(BaseWebSearchExecutor[WebSearchPlan]):
             StepDebugInfo(
                 step_name=f"{step_name}.crawl",
                 execution_time=delta_time,
-                config=self.crawler_service.config.crawler_type.name,
+                config=crawler,
                 extra={
                     "number_of_results": len(results),
                     "contents": [result.model_dump() for result in results],
@@ -180,7 +179,7 @@ class WebSearchV2Executor(BaseWebSearchExecutor[WebSearchPlan]):
             )
         )
         _LOGGER.info(
-            f"Crawled {len(results)} pages with {self.crawler_service} completed in {delta_time} seconds"
+            f"Crawled {len(results)} pages with {crawler} completed in {delta_time} seconds"
         )
         return results
 
@@ -217,7 +216,7 @@ class WebSearchV2Executor(BaseWebSearchExecutor[WebSearchPlan]):
             StepDebugInfo(
                 step_name=f"{step_name}.crawl",
                 execution_time=delta_time,
-                config=self.crawler_service.config.crawler_type.name,
+                config=crawler,
                 extra={
                     "url": step.query_or_url,
                     "content": results,

{unique_web_search-2026.28.0.dev2 → unique_web_search-2026.28.0.dev4}/src/unique_web_search/services/executors/v3/executor.py

@@ -95,11 +95,9 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
             )
         )
 
-        engine = self.search_service.config.search_engine_name.value
+        engine = self.search_service.config.engine.value
         time_start = time()
-        _LOGGER.info(
-            "Company %s Searching with %s", self.company_id, self.search_service
-        )
+        _LOGGER.info(f"Company {self.company_id} Searching with {engine}")
 
         await self._message_log_callback.log_queries([query])
         with metric_scope(search_duration, search_errors, engine=engine):
@@ -112,7 +110,7 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
             StepDebugInfo(
                 step_name="SEARCH.search",
                 execution_time=delta_time,
-                config=self.search_service.config.search_engine_name.name,
+                config=engine,
                 extra={
                     "query": query,
                     "number_of_results": len(results),
@@ -183,7 +181,9 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
         urls = list(urls)
         crawler = self.crawler_service.config.crawler_type.value
         time_start = time()
-        _LOGGER.info("Company %s Crawling %s URLs", self.company_id, len(urls))
+        _LOGGER.info(
+            f"Company {self.company_id} Crawling {len(urls)} URLs with {crawler}"
+        )
         await self._message_log_callback.log_queries(urls)
         with metric_scope(crawl_duration, crawl_errors, crawler=crawler):
             contents = await self.crawler_service.crawl(urls)
@@ -199,7 +199,7 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
             StepDebugInfo(
                 step_name="FETCH_URLS.crawl",
                 execution_time=delta_time,
-                config=self.crawler_service.config.crawler_type.name,
+                config=crawler,
                 extra={"urls": urls, "number_of_results": len(results)},
             )
         )

{unique_web_search-2026.28.0.dev2 → unique_web_search-2026.28.0.dev4}/src/unique_web_search/services/search_engine/README.md

@@ -67,19 +67,17 @@ GOOGLE_SEARCH_ENGINE_ID=your_search_engine_id
 #### Configuration
 
 ```python
-from unique_web_search.services.search_engine.google import GoogleConfig, GoogleSearch
-from unique_web_search.services.search_engine.utils.google.schema import GoogleSearchOptionalQueryParams
+from unique_search_proxy_core.search_engines.google.schema import GoogleConfig
+from unique_search_proxy_core.param_policy.exposable_param import ExposableParam
+from unique_web_search.services.search_engine.google import GoogleSearch
 
 config = GoogleConfig(
-    search_engine_name=SearchEngineType.GOOGLE,
-    fetch_size=10,  # Number of results to fetch
-    custom_search_config=GoogleSearchOptionalQueryParams(
-        safe="active",  # Safe search: off, active, high
-        cr="countryUS",  # Country restriction
-        lr="lang_en",  # Language restriction
-        siteSearch="example.com",  # Limit to specific site
-        dateRestrict="m1"  # Results from last month
-    )
+    fetch_size=10,
+    search_engine_id="your-search-engine-id",  # optional; env default when unset
+    safe="active",
+    gl=ExposableParam(expose=False, value="us"),
+    site_search=ExposableParam(expose=False, value="example.com"),
+    date_restrict=ExposableParam(expose=False, value="m1"),
 )
 
 search = GoogleSearch(config)
@@ -140,7 +138,6 @@ USE_UNIQUE_PRIVATE_ENDPOINT_TRANSPORT=false
 from unique_web_search.services.search_engine.bing import BingSearchConfig, BingSearch
 
 config = BingSearchConfig(
-    search_engine_name=SearchEngineType.BING,
     agent_id="your-agent-id",  # Azure AI Agent ID
     endpoint="https://your-project.openai.azure.com",  # Azure AI Project endpoint
     requires_scraping=False  # Grounding returns full content
@@ -206,12 +203,10 @@ BRAVE_SEARCH_API_KEY=your_brave_api_key
 #### Configuration
 
 ```python
-from unique_web_search.services.search_engine.brave import BraveSearchConfig, BraveSearch
+from unique_search_proxy_core.search_engines.brave.schema import BraveConfig
+from unique_web_search.services.search_engine.brave import BraveSearch
 
-config = BraveSearchConfig(
-    search_engine_name=SearchEngineType.BRAVE,
-    fetch_size=10
-)
+config = BraveConfig(fetch_size=10)
 
 search = BraveSearch(config)
 results = await search.search("privacy-focused search")
@@ -384,9 +379,8 @@ results = await search.search("dynamic web content")
 from unique_web_search.services.search_engine.vertexai import VertexAIConfig, VertexAI
 
 config = VertexAIConfig(
-    search_engine_name=SearchEngineType.VERTEXAI,
-    model_name="gemini-2.5-flash",  # or "gemini-2.5-pro"
-    grounding_system_instruction="Provide detailed technical answers with citations",
+    vertexai_model_name="gemini-3-flash-preview",
+    generation_instructions="Provide detailed technical answers with citations",
     enable_entreprise_search=False,  # Use enterprise search if available
     enable_redirect_resolution=True,  # Resolve URL redirects
     requires_scraping=False
@@ -459,7 +453,6 @@ from unique_web_search.services.search_engine.custom_api import CustomAPIConfig,
 from unique_web_search.settings import CUSTOM_API_REQUEST_METHOD
 
 config = CustomAPIConfig(
-    search_engine_name=SearchEngineType.CUSTOM_API,
     api_endpoint="https://your-api.example.com/search",
     api_request_method=CUSTOM_API_REQUEST_METHOD.GET,
     api_headers={"X-API-Key": "your_api_key"},
@@ -481,7 +474,6 @@ Headers: X-API-Key: your_api_key
 **POST Request Example:**
 ```python
 config = CustomAPIConfig(
-    search_engine_name=SearchEngineType.CUSTOM_API,
     api_endpoint="https://your-api.example.com/search",
     api_request_method=CUSTOM_API_REQUEST_METHOD.POST,
     api_headers={
@@ -529,15 +521,11 @@ Body:
 
 ## Common Configuration
 
-All search engines support these common configuration options:
+Search engine configs use a discriminated union on the `engine` field:
 
-### BaseSearchEngineConfig
-
-```python
-class BaseSearchEngineConfig:
-    search_engine_name: SearchEngineType  # Required
-    fetch_size: int = 5  # Number of results to fetch (where applicable)
-```
+- **Google, Brave, Perplexity**: import config types directly from `unique_search_proxy_core`
+- **Bing, VertexAI**: extend core agent configs (`BingAgentConfig`, `VertexAIAgentConfig`) with web-only fields
+- **Custom API**: standalone `BaseModel` with `engine: Literal[SearchEngineType.CUSTOM_API]`
 
 ### Factory Pattern
 
@@ -667,19 +655,37 @@ except Exception as e:
 To add a new search engine:
 
 1. Create a new file in this directory (e.g., `newsearchengine.py`)
-2. Implement the configuration class inheriting from `BaseSearchEngineConfig`
+2. If the engine exists in `unique_search_proxy_core`, extend its config with web-only fields; otherwise define a `BaseModel` with `engine: Literal[SearchEngineType.NEW]`
 3. Implement the search engine class inheriting from `SearchEngine`
-4. Add the search engine type to `SearchEngineType` enum in `base.py`
-5. Register it in `__init__.py`'s factory function
+4. Register the engine with `@register_search_engine(...)` on the class — no `__init__.py` edit needed (modules are auto-discovered via `pkgutil`)
+5. Add the config and implementation types to the static `SearchEngineConfigTypes` / `SearchEngineTypes` unions in `__init__.py` (required for pyright; guarded by `tests/test_search_engine_registry.py`)
 6. Add tests in `tests/test_search_engines.py`
 
-Example template:
+The shared registration machinery lives in [`services/_registry.py`](../_registry.py); crawlers will reuse the same core in a future migration.
+
+Example template (web-only engine):
 
 ```python
-class NewSearchEngineConfig(BaseSearchEngineConfig[SearchEngineType.NEW]):
-    search_engine_name: Literal[SearchEngineType.NEW] = SearchEngineType.NEW
+from unique_search_proxy_core.search_engines.base import SearchEngineType
+from unique_toolkit.agentic.tools.config import get_configuration_dict
+
+from unique_web_search.services.search_engine.base import SearchEngine, SearchEngineMode
+from unique_web_search.services.search_engine.registry import register_search_engine
+
+class NewSearchEngineConfig(BaseModel):
+    model_config = get_configuration_dict(title="New Search Engine")
+
+    engine: Literal[SearchEngineType.NEW] = SearchEngineType.NEW
+    fetch_size: int = Field(default=5, ...)
     # Add custom configuration fields
 
+@register_search_engine(
+    name="new",
+    key=SearchEngineType.NEW,
+    config_cls=NewSearchEngineConfig,
+    mode=SearchEngineMode.STANDARD,
+    config_display_name="New Search Engine",
+)
 class NewSearchEngine(SearchEngine[NewSearchEngineConfig]):
     def __init__(self, config: NewSearchEngineConfig):
         super().__init__(config)
@@ -689,9 +695,11 @@ class NewSearchEngine(SearchEngine[NewSearchEngineConfig]):
     def requires_scraping(self) -> bool:
         return False  # or True, depending on your implementation
     
-    async def search(self, query: str, **kwargs) -> list[WebSearchResult]:
-        # Implement search logic
-        pass
+    async def _proxy_search(self, query: str, **kwargs) -> list[WebSearchResult]:
+        ...
+
+    async def _legacy_search(self, query: str, **kwargs) -> list[WebSearchResult]:
+        ...
 ```
 
 ## Performance Considerations

unique_web_search-2026.28.0.dev4/src/unique_web_search/services/search_engine/__init__.py

@@ -0,0 +1,85 @@
+from pydantic import BaseModel
+
+from unique_web_search.services.search_engine.base import (
+    SearchEngine,
+    SearchEngineMode,
+)
+from unique_web_search.services.search_engine.registry import (
+    SEARCH_ENGINE_REGISTRY,
+    get_search_engine_mode,
+    get_search_engine_service,
+)
+
+SEARCH_ENGINE_REGISTRY.autodiscover(__path__, __name__, exclude=frozenset({"schema"}))
+
+from unique_search_proxy_core.search_engines import (  # noqa: E402
+    BraveConfig,
+    GoogleConfig,
+    PerplexityConfig,
+    SearchEngineType,
+)
+
+from unique_web_search.services.search_engine.bing import (  # noqa: E402
+    BingSearch,
+    BingSearchConfig,
+)
+from unique_web_search.services.search_engine.brave import BraveSearch  # noqa: E402
+from unique_web_search.services.search_engine.custom_api import (  # noqa: E402
+    CustomAPI,
+    CustomAPIConfig,
+)
+from unique_web_search.services.search_engine.google import GoogleSearch  # noqa: E402
+from unique_web_search.services.search_engine.perplexity import (  # noqa: E402
+    PerplexitySearch,
+)
+from unique_web_search.services.search_engine.vertexai import (  # noqa: E402
+    VertexAI,
+    VertexAIConfig,
+)
+
+SearchEngineTypes = (
+    GoogleSearch | BingSearch | CustomAPI | BraveSearch | PerplexitySearch | VertexAI
+)
+SearchEngineConfigTypes = (
+    GoogleConfig
+    | BingSearchConfig
+    | CustomAPIConfig
+    | BraveConfig
+    | PerplexityConfig
+    | VertexAIConfig
+)
+
+ENGINE_NAME_TO_CONFIG = SEARCH_ENGINE_REGISTRY.name_to_config()
+
+
+def get_search_engine_config_types_from_names(
+    engine_names: list[str],
+) -> type[BaseModel]:
+    return SEARCH_ENGINE_REGISTRY.config_types_from_names(engine_names)
+
+
+def get_default_search_engine_config(
+    engine_names: list[str],
+) -> type[BaseModel]:
+    return SEARCH_ENGINE_REGISTRY.default_config(engine_names)
+
+
+__all__ = [
+    "SearchEngineMode",
+    "SearchEngineType",
+    "get_search_engine_mode",
+    "GoogleConfig",
+    "GoogleSearch",
+    "BingSearchConfig",
+    "BingSearch",
+    "BraveSearch",
+    "BraveConfig",
+    "PerplexitySearch",
+    "PerplexityConfig",
+    "get_search_engine_service",
+    "SearchEngine",
+    "get_search_engine_config_types_from_names",
+    "get_default_search_engine_config",
+    "VertexAIConfig",
+    "VertexAI",
+]

unique_web_search-2026.28.0.dev4/src/unique_web_search/services/search_engine/base.py

@@ -0,0 +1,62 @@
+from abc import ABC, abstractmethod
+from enum import StrEnum
+from typing import ClassVar, Generic, TypeVar
+
+from pydantic import BaseModel
+
+from unique_web_search.services.proxy.bridge import search_proxy_client_enabled
+from unique_web_search.services.search_engine.schema import (
+    WebSearchResult,
+)
+
+
+class SearchEngineMode(StrEnum):
+    STANDARD = "standard"
+    AGENT = "agent"
+
+
+class LocalSearchEngineType(StrEnum):
+    CUSTOM_API = "custom_api"
+
+
+SearchEngineConfig = TypeVar(
+    "SearchEngineConfig",
+    bound=BaseModel,
+)
+
+
+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:
+        _legacy_search: Direct search implementation (no proxy).
+        requires_scraping: Whether the search engine requires scraping.
+
+    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
+
+    @property
+    def requires_scraping(self) -> bool:
+        """Whether the search engine requires scraping."""
+        return False
+
+    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."""