unique-search-proxy 0.2.0__py3-none-any.whl

unique_search_proxy/web/app.py

@@ -0,0 +1,116 @@
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from typing import List
+
+from dotenv import load_dotenv
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from unique_search_proxy.web.core import (
+    SearchEngineRequestType,
+    WebSearchResult,
+    get_search_engine,
+)
+
+# Load environment variables from .env file
+load_dotenv()
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class HealthCheckFilter(logging.Filter):
+    """Filter out health check requests from access logs."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        message = record.getMessage()
+        # Filter out GET /health requests
+        if "/health" in message and "GET" in message:
+            return False
+        return True
+
+
+# Apply filter to uvicorn access logger
+logging.getLogger("uvicorn.access").addFilter(HealthCheckFilter())
+
+
+class SearchResponse(BaseModel):
+    """Response model for search endpoint."""
+
+    results: List[WebSearchResult] = Field(..., description="Search results")
+
+
+class ErrorResponse(BaseModel):
+    """Response model for errors."""
+
+    status: str = Field(default="failed")
+    error: str = Field(..., description="Error message")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup
+    _LOGGER.info("Starting Unique Search Proxy...")
+    yield
+    # Shutdown
+    _LOGGER.info("Shutting down Unique Search Proxy...")
+
+
+app = FastAPI(
+    title="Unique Search Proxy",
+    description="A unified web search proxy API for multiple search backends",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+
+# Exception Handlers
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    _LOGGER.exception(f"Validation error: {exc}")
+    return JSONResponse(
+        status_code=400,
+        content=ErrorResponse(error=str(exc)).model_dump(),
+    )
+
+
+@app.exception_handler(Exception)
+async def generic_exception_handler(request: Request, exc: Exception):
+    _LOGGER.exception(f"An error occurred: {exc}")
+    return JSONResponse(
+        status_code=500,
+        content=ErrorResponse(error=str(exc)).model_dump(),
+    )
+
+
+@app.exception_handler(asyncio.TimeoutError)
+async def timeout_exception_handler(request: Request, exc: asyncio.TimeoutError):
+    _LOGGER.exception(f"A timeout occurred: {exc}")
+    return JSONResponse(
+        status_code=500,
+        content=ErrorResponse(error=f"Search engine timed out: {exc}").model_dump(),
+    )
+
+
+@app.post("/search", response_model=SearchResponse)
+async def search(request_data: SearchEngineRequestType):
+    search_engine = get_search_engine(request_data.search_engine)
+    search_engine = search_engine(params=request_data.params)
+
+    async with asyncio.timeout(request_data.timeout):
+        results = await search_engine.search(request_data.query)
+
+    return SearchResponse(results=results)
+
+
+@app.get("/health")
+async def health():
+    return {"status": "healthy"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(app, host="0.0.0.0", port=2349)

unique_search_proxy/web/core/__init__.py

@@ -0,0 +1,30 @@
+from typing import Annotated, Any, Protocol
+
+from pydantic import Field
+
+from unique_search_proxy.web.core.google_search import GoogleSearch, GoogleSearchRequest
+from unique_search_proxy.web.core.schema import SearchEngineType, WebSearchResult
+from unique_search_proxy.web.core.vertexai import VertexAiRequest, VertexAISearchEngine
+
+
+class SearchEngine(Protocol):
+    def __init__(self, params: Any): ...
+
+    async def search(self, query: str) -> list[WebSearchResult]: ...
+
+
+SearchEngineRequestType = Annotated[
+    GoogleSearchRequest | VertexAiRequest, Field(discriminator="search_engine")
+]
+
+
+def get_search_engine(search_engine_type: SearchEngineType) -> type[SearchEngine]:
+    if search_engine_type == SearchEngineType.GOOGLE:
+        return GoogleSearch
+    elif search_engine_type == SearchEngineType.VERTEXAI:
+        return VertexAISearchEngine
+    else:
+        raise ValueError(f"Invalid search engine type: {search_engine_type}")
+
+
+__all__ = ["get_search_engine", "SearchEngineRequestType"]

unique_search_proxy/web/core/google_search/__init__.py

@@ -0,0 +1,6 @@
+from unique_search_proxy.web.core.google_search.search import (
+    GoogleSearch,
+    GoogleSearchRequest,
+)
+
+__all__ = ["GoogleSearch", "GoogleSearchRequest"]

unique_search_proxy/web/core/google_search/exceptions.py

@@ -0,0 +1,26 @@
+class GoogleSearchException(Exception):
+    """Base exception for Google Search errors."""
+
+
+class GoogleSearchAPIKeyNotSetException(GoogleSearchException):
+    """Exception raised when the Google Search API key is not set."""
+
+    def __init__(self, message: str = "Google Search API key is not set"):
+        super().__init__(message)
+
+
+class GoogleSearchAPIEndpointNotSetException(GoogleSearchException):
+    """Exception raised when the Google Search API endpoint is not set."""
+
+    def __init__(self, message: str = "Google Search API endpoint is not set"):
+        super().__init__(message)
+
+
+class GoogleSearchEngineIDNotSetException(GoogleSearchException):
+    """Exception raised when the Google Search Engine ID is not set."""
+
+    def __init__(
+        self,
+        message: str = "Google Search Engine ID is not set. Provide a valid engine ID or set the GOOGLE_SEARCH_ENGINE_ID environment variable or the cx parameter in the GoogleSearchParams",
+    ):
+        super().__init__(message)

unique_search_proxy/web/core/google_search/schema.py

@@ -0,0 +1,21 @@
+from pydantic import BaseModel, Field
+
+from unique_search_proxy.web.core.schema import camelized_model_config
+
+
+class GoogleSearchQueryParams(BaseModel):
+    """
+    Pagination parameters for Google Custom Search API.
+    """
+
+    model_config = camelized_model_config
+
+    q: str = Field(..., description="Query string")
+    cx: str = Field(
+        ...,
+        description="The Programmable Search Engine ID to use for this request",
+    )
+    key: str = Field(..., description="API key for authentication")
+
+    start: int = Field(..., description="The index of the first result to return")
+    num: int = Field(..., description="The number of results to return")

unique_search_proxy/web/core/google_search/search.py

@@ -0,0 +1,110 @@
+import logging
+from typing import Literal
+
+from httpx import AsyncClient, Response
+from pydantic import BaseModel, Field
+
+from unique_search_proxy.web.core.google_search.exceptions import (
+    GoogleSearchAPIEndpointNotSetException,
+    GoogleSearchAPIKeyNotSetException,
+    GoogleSearchEngineIDNotSetException,
+)
+from unique_search_proxy.web.core.google_search.schema import GoogleSearchQueryParams
+from unique_search_proxy.web.core.google_search.settings import GoogleSearchSettings
+from unique_search_proxy.web.core.schema import (
+    SearchEngineType,
+    SearchRequest,
+    WebSearchResult,
+    camelized_model_config,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+# Pagingation size fixed to 10 because of the Google Search API limit
+PAGINATION_SIZE = 10
+MAX_TIMEOUT = 600
+
+
+# Pydantic Models
+class GoogleSearchParams(BaseModel):
+    """Parameters for the Google Search engine."""
+
+    model_config = camelized_model_config
+
+    cx: str | None = Field(
+        default=None,
+        description="The Programmable Search Engine ID to use for this request",
+    )
+    fetch_size: int = Field(
+        default=10, ge=1, le=100, description="The number of results to fetch"
+    )
+
+
+class GoogleSearchRequest(SearchRequest[SearchEngineType.GOOGLE, GoogleSearchParams]):
+    """Request model for the Google Search engine."""
+
+    model_config = camelized_model_config
+    search_engine: Literal[SearchEngineType.GOOGLE] = SearchEngineType.GOOGLE
+    params: GoogleSearchParams = Field(
+        default_factory=GoogleSearchParams,
+        description="Additional keyword arguments for the Google Search engine",
+    )
+
+
+class GoogleSearch:
+    def __init__(self, params: GoogleSearchParams):
+        google_search_settings = GoogleSearchSettings()
+        self.fetch_size = params.fetch_size
+        self.cx = params.cx or google_search_settings.engine_id
+
+        if not google_search_settings.api_key:
+            raise GoogleSearchAPIKeyNotSetException()
+        if not google_search_settings.api_endpoint:
+            raise GoogleSearchAPIEndpointNotSetException()
+        if not self.cx:
+            raise GoogleSearchEngineIDNotSetException()
+
+        self.api_key = google_search_settings.api_key
+        self.api_endpoint = google_search_settings.api_endpoint
+        self.engine_id = self.cx
+
+    async def search(self, query: str) -> list[WebSearchResult]:
+        """Extract the URLs from the search results."""
+
+        search_results = []
+        start_index = 1
+        fetch_size = self.fetch_size
+
+        for start_index in range(1, fetch_size + 1, PAGINATION_SIZE):
+            effective_num_fetch = min(fetch_size - start_index + 1, PAGINATION_SIZE)
+            params = GoogleSearchQueryParams(
+                q=query,
+                cx=self.engine_id,
+                key=self.api_key,
+                start=start_index,
+                num=effective_num_fetch,
+            )
+            async with AsyncClient(timeout=MAX_TIMEOUT) as client:
+                response = await client.get(
+                    self.api_endpoint, params=params.model_dump()
+                )
+                response.raise_for_status()
+                results = _map_google_search_response_to_web_search_result(response)
+                search_results.extend(results)
+
+        return search_results
+
+
+def _map_google_search_response_to_web_search_result(
+    response: Response,
+) -> list[WebSearchResult]:
+    """Clean the response from the search engine."""
+    results = response.json()
+    return [
+        WebSearchResult(
+            url=item.get("link", "URL not available"),
+            snippet=item.get("snippet", "Snippet not available"),
+            title=item.get("title", item.get("htmlTitle", "Title not available")),
+        )
+        for item in results.get("items", [])
+    ]

unique_search_proxy/web/core/google_search/settings.py

@@ -0,0 +1,15 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from unique_search_proxy.web.settings import get_env_path
+
+
+class GoogleSearchSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=get_env_path(),
+        env_file_encoding="utf-8",
+        env_prefix="google_search_",
+        extra="ignore",
+    )
+    api_key: str | None = None
+    api_endpoint: str | None = None
+    engine_id: str | None = None

unique_search_proxy/web/core/schema.py

@@ -0,0 +1,59 @@
+from enum import StrEnum
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+camelized_model_config = ConfigDict(alias_generator=to_camel)
+
+
+class SearchEngineType(StrEnum):
+    GOOGLE = "google"
+    VERTEXAI = "vertexai"
+
+
+T = TypeVar("T", bound=SearchEngineType)
+U = TypeVar("U", bound=BaseModel)
+
+
+# Pydantic Models
+class SearchRequest(BaseModel, Generic[T, U]):
+    """Request model for search endpoint."""
+
+    model_config = camelized_model_config
+    search_engine: T = Field(..., description="Search engine to use")
+
+    query: str = Field(..., min_length=1, description="Search query string")
+
+    timeout: int = Field(
+        default=10, ge=1, le=600, description="The request timeout in seconds"
+    )
+
+    params: U = Field(
+        ..., description="Additional keyword arguments for the search engine"
+    )
+
+
+class WebSearchResult(BaseModel):
+    """Result model for a web search."""
+
+    model_config = camelized_model_config
+
+    url: str
+    title: str
+    snippet: str = Field(
+        ...,
+        description="A short description of the content found on this website",
+    )
+    content: str = Field(
+        default="",
+        description="The content of the website",
+    )
+
+
+class WebSearchResults(BaseModel):
+    """Results model for a web search."""
+
+    model_config = camelized_model_config
+
+    results: list[WebSearchResult]

unique_search_proxy/web/core/vertexai/__init__.py

@@ -0,0 +1,6 @@
+from unique_search_proxy.web.core.vertexai.search import (
+    VertexAiRequest,
+    VertexAISearchEngine,
+)
+
+__all__ = ["VertexAISearchEngine", "VertexAiRequest"]

unique_search_proxy/web/core/vertexai/client.py

@@ -0,0 +1,34 @@
+import json
+import logging
+from base64 import b64decode
+
+from google.auth import load_credentials_from_dict
+from google.genai._api_client import BaseApiClient
+from google.genai.client import AsyncClient
+
+from unique_search_proxy.web.core.vertexai.exceptions import (
+    VertexAICredentialNotFoundException,
+)
+from unique_search_proxy.web.core.vertexai.settings import VertexAISettings
+
+_LOGGER = logging.getLogger(__name__)
+
+
+def _get_vertexai_base_api_client() -> BaseApiClient:
+    vertexai_settings = VertexAISettings()
+    vertexai_service_account_credentials = vertexai_settings.service_account_credentials
+    if vertexai_service_account_credentials is None:
+        raise VertexAICredentialNotFoundException()
+    service_account_info = json.loads(
+        b64decode(vertexai_service_account_credentials).decode("utf-8")
+    )
+
+    credentials, project_id = load_credentials_from_dict(
+        service_account_info, scopes=["https://www.googleapis.com/auth/cloud-platform"]
+    )
+    return BaseApiClient(vertexai=True, credentials=credentials, project=project_id)
+
+
+def get_vertex_client() -> AsyncClient:
+    base_api_client = _get_vertexai_base_api_client()
+    return AsyncClient(api_client=base_api_client)

unique_search_proxy/web/core/vertexai/config.py

@@ -0,0 +1,39 @@
+from google.genai import types
+from pydantic import BaseModel
+
+from unique_search_proxy.web.core.vertexai.prompts import (
+    VERTEX_GROUNDING_SYSTEM_INSTRUCTION,
+    VERTEX_STRUCTURED_RESULTS_SYSTEM_INSTRUCTION,
+)
+
+
+def get_vertex_grounding_config(
+    *,
+    system_instruction: str | None,
+    entreprise_search: bool = False,
+) -> types.GenerateContentConfig:
+    system_instruction = system_instruction or VERTEX_GROUNDING_SYSTEM_INSTRUCTION
+
+    if entreprise_search:
+        grounding_tool = types.Tool(enterprise_web_search=types.EnterpriseWebSearch())
+    else:
+        grounding_tool = types.Tool(google_search=types.GoogleSearch())
+
+    return types.GenerateContentConfig(
+        tools=[grounding_tool], system_instruction=system_instruction
+    )
+
+
+def get_vertex_structured_results_config(
+    *,
+    system_instruction: str | None,
+    response_schema: type[BaseModel],
+) -> types.GenerateContentConfig:
+    system_instruction = (
+        system_instruction or VERTEX_STRUCTURED_RESULTS_SYSTEM_INSTRUCTION
+    )
+    return types.GenerateContentConfig(
+        system_instruction=system_instruction,
+        response_mime_type="application/json",
+        response_schema=response_schema,
+    )

unique_search_proxy/web/core/vertexai/exceptions.py

@@ -0,0 +1,25 @@
+class VertexAIException(Exception):
+    """Base exception for VertexAI errors."""
+
+
+class VertexAIClientNotConfiguredException(VertexAIException):
+    """Exception raised when the VertexAI client is not configured."""
+
+    def __init__(self, message: str = "VertexAI client is not configured"):
+        super().__init__(message)
+
+
+class VertexAICredentialNotFoundException(VertexAIException):
+    """Exception raised when the VertexAI credential is not found."""
+
+    def __init__(
+        self, message: str = "VertexAI service account credentials are not set"
+    ):
+        super().__init__(message)
+
+
+class VertexAIContentResponseEmptyException(VertexAIException):
+    """Exception raised when the VertexAI content response is empty."""
+
+    def __init__(self, message: str = "VertexAI content response is empty"):
+        super().__init__(message)

unique_search_proxy/web/core/vertexai/gemini.py

@@ -0,0 +1,24 @@
+from google.genai import types
+from google.genai.client import AsyncClient
+
+from unique_search_proxy.web.core.vertexai.response_handler import (
+    PostProcessFunction,
+    T,
+)
+
+
+async def generate_content(
+    *,
+    client: AsyncClient,
+    model_name: str,
+    config: types.GenerateContentConfig,
+    contents: str,
+    post_process_function: PostProcessFunction[T],
+) -> T:
+    response = await client.models.generate_content(
+        model=model_name,
+        contents=contents,
+        config=config,
+    )
+
+    return post_process_function(response)

unique_search_proxy/web/core/vertexai/helpers.py

@@ -0,0 +1,25 @@
+import asyncio
+import logging
+
+from httpx import AsyncClient, HTTPError
+
+from unique_search_proxy.web.core.schema import WebSearchResult, WebSearchResults
+
+_LOGGER = logging.getLogger(__name__)
+
+
+async def _resolve_url(client: AsyncClient, web_search_result: WebSearchResult):
+    try:
+        resp = await client.head(web_search_result.url, follow_redirects=True)
+        web_search_result.url = str(resp.url)
+        return web_search_result
+    except HTTPError as e:
+        _LOGGER.error(f"Unable to redirect URL: {web_search_result.url}: {e}")
+        return web_search_result
+
+
+async def resolve_all(web_search_results: WebSearchResults):
+    async with AsyncClient(follow_redirects=True, timeout=10) as client:
+        tasks = [_resolve_url(client, result) for result in web_search_results.results]
+        results = await asyncio.gather(*tasks)
+        return WebSearchResults(results=results)

unique_search_proxy/web/core/vertexai/prompts.py

@@ -0,0 +1,28 @@
+VERTEX_GROUNDING_SYSTEM_INSTRUCTION = """
+You are my research copilot using Gemini’s browser research capabilities.  
+When given a research topic or question, do the following:
+
+1. **Discovery / Scoping**  
+   - Search for the most credible, recent sources (ideally from the last 12–18 months) on the topic.  
+   - Identify 8–12 key findings or major themes from those sources.  
+   - Provide a short summary (3-bullet) of each source, and **score** each one for credibility.  
+   - Highlight any **conflicting claims** or disagreements between sources.  
+
+2. **Verification**  
+   - For each major claim or data point, include inline **citations**: quotes, dates, and direct links to the original source.  
+   - If possible, note methodological concerns or limitations in the sources (for example, “the data was collected via self-reporting” or “the sample size was small”).
+
+3. **Synthesis**  
+   - Write a 1-paragraph **executive summary** that synthesizes the findings.  
+   - List **open questions** or gaps in the current research.  
+   - Suggest **next steps** or actions (e.g., areas for further research, stakeholders to consult).
+
+4. **Formatting / Constraints**  
+   - Use a clear structure (e.g., headings or bullet-points).  
+   - If relevant, format a **comparison table** (for example: comparing products, vendors, or approaches) with criteria like pricing, features, security, integrations.  
+   - Limit source count or depth if needed (you can ask: “only use up to 10 sources,” or “focus on academic or industry-report sources”).
+""".strip()
+
+VERTEX_STRUCTURED_RESULTS_SYSTEM_INSTRUCTION = """
+You are a helpful assistant that can structure results from a referenced response to web page content.
+""".strip()

unique_search_proxy/web/core/vertexai/response_handler.py

@@ -0,0 +1,87 @@
+import logging
+from typing import Any, Callable, Generic, TypeVar
+
+from google.genai import types
+from pydantic import BaseModel
+
+from unique_search_proxy.web.core.vertexai.exceptions import (
+    VertexAIContentResponseEmptyException,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+T = TypeVar("T", bound=BaseModel | str, covariant=True)
+T_Model = TypeVar("T_Model", bound=BaseModel)
+
+
+class PostProcessFunction(Generic[T]):
+    def __init__(self, callable: Callable[..., T], **kwargs: Any):
+        self.callable = callable
+        self.kwargs = kwargs
+
+    def __call__(self, response: types.GenerateContentResponse) -> T:
+        return self.callable(response, **self.kwargs)
+
+
+def parse_to_structured_results(
+    response: types.GenerateContentResponse, response_schema: type[T_Model]
+) -> T_Model:
+    return response_schema.model_validate(response.parsed)
+
+
+def add_citations(response: types.GenerateContentResponse) -> str:
+    text = response.text
+
+    if not text:
+        raise VertexAIContentResponseEmptyException()
+
+    try:
+        metadata = response.candidates[0].grounding_metadata  # type: ignore
+        supports = metadata.grounding_supports  # type: ignore
+        chunks = metadata.grounding_chunks  # type: ignore
+    except KeyError:
+        raise VertexAIContentResponseEmptyException()
+
+    text = _insert_citations_into_text(text, supports, chunks)  # type: ignore
+
+    return text
+
+
+def _build_citation_links(
+    chunk_indices: list[int], chunks: list[types.GroundingChunk]
+) -> str:
+    """Return a citation string like: [1](url), [2](url)."""
+    links = []
+    for idx in chunk_indices:
+        if 0 <= idx < len(chunks):
+            uri = chunks[idx].web.uri  # type: ignore
+            links.append(f"[{idx + 1}]({uri})")
+    return ", ".join(links)
+
+
+def _insert_citations_into_text(
+    text: str,
+    supports: list[types.GroundingSupport],
+    chunks: list[types.GroundingChunk],
+) -> str:
+    """Insert citation links into text based on grounding supports."""
+
+    sorted_supports = sorted(
+        supports,
+        key=lambda s: s.segment.end_index,  # type: ignore
+        reverse=True,
+    )
+
+    for support in sorted_supports:
+        chunk_indices = support.grounding_chunk_indices or []
+        if not chunk_indices:
+            continue
+
+        citation = _build_citation_links(chunk_indices, chunks)
+        if not citation:
+            continue
+
+        end_index = support.segment.end_index
+        text = text[:end_index] + citation + text[end_index:]
+
+    return text

unique_search_proxy/web/core/vertexai/search.py

@@ -0,0 +1,96 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from unique_search_proxy.web.core.schema import (
+    SearchEngineType,
+    SearchRequest,
+    WebSearchResult,
+    WebSearchResults,
+    camelized_model_config,
+)
+from unique_search_proxy.web.core.vertexai.client import (
+    get_vertex_client,
+)
+from unique_search_proxy.web.core.vertexai.config import (
+    get_vertex_grounding_config,
+    get_vertex_structured_results_config,
+)
+from unique_search_proxy.web.core.vertexai.gemini import (
+    generate_content,
+)
+from unique_search_proxy.web.core.vertexai.helpers import resolve_all
+from unique_search_proxy.web.core.vertexai.response_handler import (
+    PostProcessFunction,
+    add_citations,
+    parse_to_structured_results,
+)
+
+
+class VertexAiParams(BaseModel):
+    model_config = camelized_model_config
+
+    model_name: str = Field(
+        default="gemini-2.5-flash", description="The model name to use for the search"
+    )
+    entreprise_search: bool = Field(
+        default=False, description="Whether to use the entreprise search"
+    )
+    system_instruction: str | None = Field(
+        default=None, description="The system instruction to use for the search"
+    )
+    resolve_urls: bool = Field(default=True, description="Whether to resolve the URLs")
+
+
+class VertexAiRequest(SearchRequest[SearchEngineType.VERTEXAI, VertexAiParams]):
+    """Request model for the Vertex AI search engine."""
+
+    model_config = camelized_model_config
+    search_engine: Literal[SearchEngineType.VERTEXAI] = SearchEngineType.VERTEXAI
+    params: VertexAiParams = Field(
+        default_factory=VertexAiParams,
+        description="Additional keyword arguments for the Vertex AI search engine",
+    )
+
+
+class VertexAISearchEngine:
+    def __init__(
+        self,
+        params: VertexAiParams,
+    ):
+        self.model_name = params.model_name
+        self.entreprise_search = params.entreprise_search
+        self.system_instruction = params.system_instruction
+        self.resolve_urls = params.resolve_urls
+
+    async def search(self, query: str) -> list[WebSearchResult]:
+        client = get_vertex_client()
+        answer_with_citations = await generate_content(
+            client=client,
+            model_name=self.model_name,
+            config=get_vertex_grounding_config(
+                system_instruction=self.system_instruction,
+                entreprise_search=self.entreprise_search,
+            ),
+            contents=query,
+            post_process_function=PostProcessFunction[str](add_citations),
+        )
+
+        # Generate the structured results
+        structured_results = await generate_content(
+            client=client,
+            model_name=self.model_name,
+            config=get_vertex_structured_results_config(
+                system_instruction=None,
+                response_schema=WebSearchResults,
+            ),
+            contents=answer_with_citations,
+            post_process_function=PostProcessFunction[WebSearchResults](
+                parse_to_structured_results,
+                response_schema=WebSearchResults,
+            ),
+        )
+        if self.resolve_urls:
+            structured_results = await resolve_all(structured_results)  #  type: ignore
+
+        return structured_results.results

unique_search_proxy/web/core/vertexai/settings.py

@@ -0,0 +1,13 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from unique_search_proxy.web.settings import get_env_path
+
+
+class VertexAISettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=get_env_path(),
+        env_file_encoding="utf-8",
+        env_prefix="vertexai_",
+        extra="ignore",
+    )
+    service_account_credentials: str | None = None

unique_search_proxy/web/settings.py

@@ -0,0 +1,6 @@
+import os
+from pathlib import Path
+
+
+def get_env_path() -> Path:
+    return Path(os.getcwd()) / ".env"

unique_search_proxy-0.2.0.dist-info/METADATA

@@ -0,0 +1,315 @@
+Metadata-Version: 2.3
+Name: unique-search-proxy
+Version: 0.2.0
+Summary: Web Search Proxy implementation
+Author: ThePhilAz
+Author-email: ThePhilAz <rami.azouz@philico.com>
+Requires-Dist: fastapi>=0.115.0,<1.0.0
+Requires-Dist: uvicorn[standard]>=0.32.0,<1.0.0
+Requires-Dist: google-cloud-aiplatform>=1.128.0,<2.0.0
+Requires-Dist: google-auth>=2.43.0,<3.0.0
+Requires-Dist: google-generativeai>=0.8.5,<0.9.0
+Requires-Dist: pydantic>=2.12.5,<3.0.0
+Requires-Dist: httpx>=0.28.0,<0.29.0
+Requires-Dist: python-dotenv>=1.2.1,<2.0.0
+Requires-Dist: pydantic-settings>=2.12.0,<3.0.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Unique Search Proxy
+
+A unified web search proxy API that provides a consistent interface for multiple search backends. Built with FastAPI and designed for seamless integration with AI applications.
+
+## Overview
+
+This service acts as an abstraction layer over different search providers, allowing clients to switch between search engines without changing their integration code. Currently supports:
+
+| Engine | Description |
+|--------|-------------|
+| **Google Custom Search** | Direct integration with Google's Custom Search JSON API |
+| **Vertex AI (Gemini)** | AI-powered search using Google's Gemini models with grounding capabilities |
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- uv for dependency management
+- Google Cloud credentials (for Vertex AI)
+- Google Custom Search API key and Engine ID (for Google Search)
+
+### Installation
+
+```bash
+# Install dependencies
+uv sync
+
+# Copy and configure environment variables
+cp .env.example .env
+```
+
+### Environment Variables
+
+```bash
+# Google Custom Search
+GOOGLE_SEARCH_API_KEY=your-api-key
+GOOGLE_SEARCH_API_ENDPOINT=https://www.googleapis.com/customsearch/v1
+GOOGLE_SEARCH_ENGINE_ID=your-engine-id
+
+# Vertex AI
+VERTEXAI_SERVICE_ACCOUNT_CREDENTIALS=path/to/credentials.json
+```
+
+### Running the Service
+
+**Development:**
+```bash
+uv run python -m unique_search_proxy.web.app
+```
+
+**Docker (from published package — hash-verified):**
+
+CI generates a hash-pinned `requirements.txt` from `uv.lock` and passes it into the
+Docker build. Dependencies are installed with `--require-hashes`, then the package
+itself is installed with `--no-deps`. To reproduce locally:
+
+```bash
+uv export --locked --package unique-search-proxy --no-dev --no-emit-project \
+  -o deploy/requirements.txt
+docker build --build-arg PACKAGE_VERSION=0.2.0 -t search-proxy deploy/
+```
+
+Every transitive dependency is verified against its sha256 hash from the lockfile.
+
+**Docker (from local source — no registry required):**
+
+Build a wheel first, copy it into `deploy/`, then reference it:
+
+```bash
+uv build --wheel --out-dir deploy/
+docker build \
+  --build-arg LOCAL_WHEEL=unique_search_proxy-0.2.0-py3-none-any.whl \
+  -t search-proxy deploy/
+```
+
+**Running the container:**
+
+```bash
+docker run --rm -p 8080:8080 search-proxy
+
+# With custom environment variables
+docker run --rm -p 8080:8080 -e WORKERS=8 -e LOG_LEVEL=debug search-proxy
+```
+
+## API Documentation
+
+FastAPI provides automatic interactive API documentation:
+
+| URL | Description |
+|-----|-------------|
+| `/docs` | Swagger UI - interactive API explorer |
+| `/redoc` | ReDoc - alternative documentation |
+| `/openapi.json` | OpenAPI schema |
+
+## API Reference
+
+### Health Check
+
+```http
+GET /health
+```
+
+**Response:**
+```json
+{
+  "status": "healthy"
+}
+```
+
+---
+
+### Search
+
+```http
+POST /search
+Content-Type: application/json
+```
+
+**Request Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `search_engine` | string | No | `"google"` or `"vertexai"` (default: `"google"`) |
+| `query` | string | Yes | The search query |
+| `kwargs` | object | No | Engine-specific parameters |
+
+**Response:**
+```json
+{
+  "results": [
+    {
+      "url": "https://example.com/article",
+      "title": "Article Title",
+      "snippet": "A brief description of the content...",
+      "content": ""
+    }
+  ]
+}
+```
+
+---
+
+## Search Engine Configuration
+
+### Google Custom Search
+
+Uses Google's Custom Search JSON API for traditional web search results.
+
+**Parameters (`kwargs`):**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `cx` | string | env default | Custom Search Engine ID (overrides env) |
+| `fetchSize` | int | 10 | Number of results to fetch |
+| `timeout` | int | 10 | Request timeout in seconds |
+
+**Example:**
+```json
+{
+  "search_engine": "google",
+  "query": "latest AI developments",
+  "kwargs": {
+    "fetchSize": 20,
+    "timeout": 15
+  }
+}
+```
+
+---
+
+### Vertex AI (Gemini)
+
+Leverages Google's Gemini models with web grounding for AI-enhanced search results. This engine:
+
+1. Uses Gemini to search and synthesize information from the web
+2. Generates structured results with citations
+3. Optionally resolves shortened/redirect URLs to final destinations
+
+**Parameters (`kwargs`):**
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `modelName` | string | `"gemini-2.5-flash"` | Gemini model to use |
+| `entrepriseSearch` | bool | `false` | Use Enterprise Web Search |
+| `systemInstruction` | string | (built-in) | Custom system prompt |
+| `resolveUrls` | bool | `true` | Resolve redirect URLs |
+
+**Example:**
+```json
+{
+  "search_engine": "vertexai",
+  "query": "Compare the top 3 cloud providers for ML workloads",
+  "kwargs": {
+    "modelName": "gemini-2.5-flash",
+    "resolveUrls": true
+  }
+}
+```
+
+---
+
+## Project Structure
+
+```
+connectors/unique_search_proxy/
+├── unique_search_proxy/          # Python package (published to PyPI)
+│   ├── __init__.py
+│   └── web/                      # Web search API sub-module
+│       ├── __init__.py
+│       ├── app.py                # FastAPI application
+│       ├── settings.py           # Global settings
+│       └── core/                 # Search engine implementations
+│           ├── schema.py         # Shared schemas
+│           ├── google_search/    # Google Custom Search backend
+│           └── vertexai/         # Vertex AI (Gemini) backend
+├── tests/                        # Test suite
+├── deploy/                       # Container build artifacts
+│   ├── Dockerfile                # Hash-verified install or local wheel
+│   └── entrypoint.sh
+└── pyproject.toml
+```
+
+The package uses a sub-module hierarchy (`web/`) to support future extensions (e.g. `internal/` search) that can be deployed as separate containers from the same package.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       FastAPI App                           │
+│                      /search endpoint                       │
+└─────────────────────────┬───────────────────────────────────┘
+                          │
+                    ┌─────▼─────┐
+                    │  Factory  │
+                    └─────┬─────┘
+                          │
+          ┌───────────────┼───────────────┐
+          │                               │
+    ┌─────▼─────┐                   ┌─────▼─────┐
+    │  Google   │                   │ Vertex AI │
+    │  Search   │                   │  (Gemini) │
+    └───────────┘                   └───────────┘
+```
+
+The service uses a **factory pattern** to register and resolve search engines, making it easy to add new backends.
+
+## Error Handling
+
+All errors return a consistent format:
+
+```json
+{
+  "status": "failed",
+  "error": "Error description"
+}
+```
+
+| Status Code | Description |
+|-------------|-------------|
+| 400 | Validation error (invalid request) |
+| 500 | Internal server error |
+
+## Production Deployment
+
+The service includes a production-ready `deploy/entrypoint.sh` that uses Uvicorn:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `HOST` | `0.0.0.0` | Bind address |
+| `PORT` | `8080` | Listen port |
+| `WORKERS` | `4` | Uvicorn workers |
+| `TIMEOUT` | `120` | Keep-alive timeout |
+| `LOG_LEVEL` | `info` | Logging verbosity |
+
+## Development
+
+```bash
+# Run with hot reload
+uv run uvicorn unique_search_proxy.web.app:app --reload --port 2349
+
+# Format code
+uv run ruff format .
+
+# Lint
+uv run ruff check .
+
+# Run tests
+uv run pytest
+
+# Type check
+uv run basedpyright
+```
+
+## License
+
+Proprietary - Unique AG

unique_search_proxy-0.2.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+unique_search_proxy/__init__.py,sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855,0
+unique_search_proxy/web/__init__.py,sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855,0
+unique_search_proxy/web/app.py,sha256=408cda559312753b7cddff8875a79365d29d0b55c7bc4cb186edceb8d2e313e4,3173
+unique_search_proxy/web/core/__init__.py,sha256=0c43bf67670cc3fc7339c5479fef3ae41e7482588ecec32823b71e53c7882d02,1006
+unique_search_proxy/web/core/google_search/__init__.py,sha256=dbf858ceb67c2a6fae9e1167863a13fd5b14d36fbf1d0001cf2ab00fcab6a7b3,160
+unique_search_proxy/web/core/google_search/exceptions.py,sha256=3d7cae5fd325f9b9d2adcb7d92e74cffd2aa3ec79d58771bf9a78f658d0c08de,1002
+unique_search_proxy/web/core/google_search/schema.py,sha256=b7b1f70a4f819ce3b8af8345a0a852e6c7d92014f15a738baf81ea4a120ae7dd,668
+unique_search_proxy/web/core/google_search/search.py,sha256=0109b73cd07398987ba20868b7f202261411f9c180fa44c7b3e1196a4fb8d18e,3794
+unique_search_proxy/web/core/google_search/settings.py,sha256=ae43877090f0655520e0964df189d6510cca263be32ea3b11df41d49ca8386af,440
+unique_search_proxy/web/core/schema.py,sha256=114f8ab83bd98488eda8001406ec71e4b1fc6f01d311830c7824f2808328583e,1439
+unique_search_proxy/web/core/vertexai/__init__.py,sha256=144ee103b2d73af0985f60edb17423415b6ad7bfcfce841922ccc642722a4755,163
+unique_search_proxy/web/core/vertexai/client.py,sha256=2e97977d6faca92b62f06665647321b41fcb11d24b159a5ffd33f9053ed975a0,1220
+unique_search_proxy/web/core/vertexai/config.py,sha256=9938a8614f5da349761d94dedc3ceef6a4ae7c7520de9bba7027858f4ba01cc8,1209
+unique_search_proxy/web/core/vertexai/exceptions.py,sha256=28b8154962dfab72d7391fd7382052eba2afff13bc1a51a9879d54f40947a523,853
+unique_search_proxy/web/core/vertexai/gemini.py,sha256=dfeafdb7d6d5d8bf0d311d115844b24f0aca4b1bb194a1c58747915b574b99b2,560
+unique_search_proxy/web/core/vertexai/helpers.py,sha256=6e43c4c87b7bef80606a804cda569160fd237d383eabbeaec1f44a4d5d2caf55,903
+unique_search_proxy/web/core/vertexai/prompts.py,sha256=fa0abd47a6ed6ae6c380f8c4355866949501a8f617e80602060d8c17fa342996,1748
+unique_search_proxy/web/core/vertexai/response_handler.py,sha256=7696afa3e5aca5a99533074ce976bd4999aab8b33bbcbf2e63f2bc21cb42619e,2519
+unique_search_proxy/web/core/vertexai/search.py,sha256=77a55fd3786c6c49daea1f82dae5a9979bd2dff9edb7035294e69fa6452452ef,3275
+unique_search_proxy/web/core/vertexai/settings.py,sha256=c5ef80899fe709a2d20bce89469be710385baab4e8889bff600643f841adece9,382
+unique_search_proxy/web/settings.py,sha256=04ac4af15bc574b4da094b0951ae96a265a92f2ff394792b7f6b87e46063444e,103
+unique_search_proxy-0.2.0.dist-info/WHEEL,sha256=ab6157bc637547491fb4567cd7ddf26b04d63382916ca16c29a5c8e94c9c9ef7,79
+unique_search_proxy-0.2.0.dist-info/METADATA,sha256=a1272b4a570cb21ed15ccb6b99799118f091372ac929600cec95a16f7a4f7274,8852
+unique_search_proxy-0.2.0.dist-info/RECORD,,

unique_search_proxy-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.7.22
+Root-Is-Purelib: true
+Tag: py3-none-any