unique_web_search 2026.24.0.dev1__tar.gz → 2026.24.0.dev3__tar.gz

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-web-search
-Version: 2026.24.0.dev1
+Version: 2026.24.0.dev3
 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.24.0.dev7,<2026.24.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.24.0.dev10,<2026.24.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,6 +27,7 @@ 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-Python: >=3.12, <4.0
 Description-Content-Type: text/markdown
 

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_web_search"
-version = "2026.24.0.dev1"
+version = "2026.24.0.dev3"
 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.24.0.dev7,<2026.24.0rc0",
+    "unique-toolkit[monitoring]>=2026.24.0.dev10,<2026.24.0rc0",
     "azure-core>=1.36.0,<2",
     "google-cloud-aiplatform>=1.128.0,<2",
     "google-auth>=2.43.0,<3",
@@ -33,6 +33,7 @@ dependencies = [
     "certifi>=2025.11.12",
     "jinja2>=3.1.6",
     "playwright>=1.58.0",
+    "perplexityai>=0.34.0",
 ]
 
 [build-system]

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev3}/src/unique_web_search/client_settings.py

@@ -200,3 +200,38 @@ def get_brave_search_settings() -> BraveSearchSettings:
     if _brave_search_settings is None:
         _brave_search_settings = BraveSearchSettings.from_env_settings()
     return _brave_search_settings
+
+
+class PerplexitySearchSettings(BaseModel):
+    api_key: str | None = None
+
+    @property
+    def is_configured(self) -> bool:
+        return self.api_key is not None
+
+    @classmethod
+    def from_env_settings(cls):
+        missing_settings = []
+
+        if env_settings.perplexity_api_key is None:
+            missing_settings.append("API Key")
+
+        if missing_settings:
+            _LOGGER.warning(
+                "Perplexity Search API missing required settings: "
+                f"{', '.join(missing_settings)}"
+            )
+        else:
+            _LOGGER.info("Perplexity Search API is properly configured")
+
+        return cls(api_key=env_settings.perplexity_api_key)
+
+
+_perplexity_search_settings: PerplexitySearchSettings | None = None
+
+
+def get_perplexity_search_settings() -> PerplexitySearchSettings:
+    global _perplexity_search_settings
+    if _perplexity_search_settings is None:
+        _perplexity_search_settings = PerplexitySearchSettings.from_env_settings()
+    return _perplexity_search_settings

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev3}/src/unique_web_search/prompts.py

@@ -39,11 +39,28 @@ When multiple sources are available, prioritize:
 4. **Primary sources**: Original reports over summaries
 5. **Domain expertise**: Medical info from health institutions, financial from finance sources
 
-**When sources are insufficient**: Clearly state "Based on available search results..." and indicate limitations.
-
 **REMEMBER**: Source numbers reset with each new WebSearch. Only use numbers from the most recent tool response.
 """
 
+_TOOL_FORMAT_INFORMATION_SYNTHESIS_SECTION = """
+## Synthesizing WebSearch results
+
+After one or more WebSearch tool calls, **synthesize** findings in your answer. Do not only cite facts when a single source made the answer obvious.
+
+**Evidence ledger (per facet or sub-question):** Track each facet with a confidence label:
+
+- **Confirmed** — the exact fact is supported by cited tool content [sourceX].
+- **Partial** — only part of the facet is supported; say what is missing [sourceX].
+- **Not found** — no on-topic public evidence after reasonable search/refinement; state what you tried (no citation required for absence).
+- **Related** — tool content is adjacent but does not answer the exact ask; cite it [sourceX] and label it **related, not confirmed**.
+
+**Mandatory behaviors:**
+
+- **Always summarize partial findings** before saying something is unavailable. Never reply with only "I couldn't find X" if the tool returned related material—put related material in a **Related leads** (or equivalent) subsection with citations.
+- For multi-facet tasks (diligence, Source of Wealth, company profiles), use a structured answer: direct answer → evidence by facet → gaps and limitations → related leads → optional next steps.
+- Distinguish **Confirmed** from **Related** in prose—do not imply ownership, revenue, or UBO facts unless citations support them.
+""".strip()
+
 
 _TOOL_FORMAT_INFORMATION_V3_DOMAIN_DIVERSITY_SECTION = """
 ## Domain Diversity Requirement
@@ -61,4 +78,6 @@ DEFAULT_TOOL_FORMAT_INFORMATION_FOR_SYSTEM_PROMPT_V3 = (
     DEFAULT_TOOL_FORMAT_INFORMATION_FOR_SYSTEM_PROMPT.rstrip()
     + "\n\n"
     + _TOOL_FORMAT_INFORMATION_V3_DOMAIN_DIVERSITY_SECTION
+    + "\n\n"
+    + _TOOL_FORMAT_INFORMATION_SYNTHESIS_SECTION
 )

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev3}/src/unique_web_search/services/executors/v3/executor.py

@@ -58,11 +58,13 @@ class WebSearchV3Executor(BaseWebSearchExecutor[WebSearchV3ToolParameters]):
         p = self.tool_parameters
         if isinstance(p.payload, SearchPayload):
             await self._message_log_callback.log_progress("_Executing Search_")
-            return await self._run_search(query=p.payload.query, objective=p.objective)
+            return await self._run_search(
+                query=p.payload.query, objective=p.relevance_focus()
+            )
         if isinstance(p.payload, FetchUrlsPayload):
             await self._message_log_callback.log_progress("_Reading Web Pages_")
             return await self._run_fetch_urls(
-                urls=p.payload.urls, objective=p.objective
+                urls=p.payload.urls, objective=p.relevance_focus()
             )
 
         msg = "WebSearchV3ToolParameters requires exactly one of 'query' or 'urls'."

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev3}/src/unique_web_search/services/executors/v3/prompts/tool_description.j2

@@ -3,7 +3,11 @@ The WebSearch tool returns up-to-date information from the web. It exposes two c
 - **Search** (`command: "search"`) — runs the configured search engine and returns SERP rows (URL, domain, title, snippet). Gives a high-level read of what relevant pages contain without crawling them. Useful for **exploration** and quick lookups when a snippet is enough to answer.
 - **Fetch** (`command: "read_urls"`) — crawls one or more URLs and returns full-page text. Useful for **deep dives** when the task is complex and needs exact figures, quotes, regulatory text, or specs, and when the user provides a URL directly.
 
-Each call performs **one** operation. Drive multi-part tasks by chaining calls.
+Each call performs **one** operation. Drive multi-part tasks by chaining calls; use **parallel** `search` calls for independent facets (short `query` each, not one long query).
+
+**`phase`:** `exploratory` (map what exists) | `target` (precise facet in `gap`) | `redirect` (related context when the facet is not on the web). **`gap`:** one atomic facet per call.
+
+**Complex research:** build an evidence ledger as you go and **synthesize** in the final answer—do not stop at "not found" if results contain related context.
 
 ### Fields
 
@@ -11,4 +15,4 @@ Each call performs **one** operation. Drive multi-part tasks by chaining calls.
 
 Never invent URLs.
 
-For a deeper playbook on when to search vs fetch (snippet hedging, canonical-source topics, sub-question decomposition, URL-selection rules, anti-patterns), activate the `web-search-v3` skill before/while using this tool.
+For the full playbook (search vs fetch, diligence decomposition, partial evidence, synthesis, URL-selection, anti-patterns, SoW examples), activate the `web-search-v3` skill before/while using this tool.

unique_web_search-2026.24.0.dev3/src/unique_web_search/services/executors/v3/prompts/tool_description_for_system_prompt.j2

@@ -0,0 +1,78 @@
+Use `WebSearch` for up-to-date information from the web. It exposes two capabilities, picked per call via `command`. Each invocation performs **one** operation; complex user tasks are handled by **chaining** invocations — use **parallel** `search` calls when several facets are independent (one short `query` per call, not one long query).
+
+### `phase` — research phase (required on every call)
+
+Set **`phase`** on each WebSearch invocation (replaces the old `objective` field):
+
+- **`exploratory`** — sense what exists on the web and what is closest to the user's ask. Use broad, short mapping queries. Typical at the start of a complex task or when scoping an entity.
+- **`target`** — pursue one specific facet named in `payload.gap` with a precise, short `payload.query`. Use for verifiable facts (revenue, ownership, officers, filings).
+- **`redirect`** — last resort when the exact facet is not on the public web. Search for **related, attributable** context (sector, peers, parent company, adjacent news). Label results as related, not confirmed; never invent figures or ownership.
+
+**`payload.gap`** — one atomic facet per call (not the whole user question). **`payload.query`** — ~3–8 keywords only; decompose multi-facet asks into parallel `search` calls instead of one bloated query.
+
+#### `command: "search"` — search the web
+
+Runs the configured search engine and returns SERP rows (URL, domain, title, snippet). It is **fast** and gives a **high-level read** of what relevant pages contain without paying the cost of crawling them.
+
+Use it when:
+
+- You need to **discover sources**: you don't yet have URLs and need the engine to surface candidates for a topic.
+- The user's question can be answered from **snippets alone** — a definition, a status, a current value, a short factual lookup.
+- You're at the **start of a complex task** and need to map out what's out there before deciding which pages are worth a deeper read.
+- You want to **scope or sanity-check** a topic cheaply (does this entity / event / product even exist? how recent is the latest coverage?).
+- You need to **cover a new gap / sub-question** in a multi-step task — issue another search rather than blindly fetching.
+
+#### `command: "read_urls"` — fetch full page content
+
+Crawls one or more URLs and returns the full-page text. It is **slower** than search but gives the **complete content** of the chosen pages, not just a snippet.
+
+Use it when:
+
+- The user **pasted a URL** or asked you to read a specific page — go straight here, do not search first.
+- The task is **complex / in-depth** and needs more than a snippet: exact figures, full quotes, regulatory text, contract language, statute numbers, API specs, version numbers.
+- The previous search returned **paraphrased / hedged snippets** ("around", "approximately", "is expected to", "reportedly") for a question that needs precision.
+- The topic is **canonical-source-driven** — financial filings (10-K, 10-Q, earnings releases), regulator publications, official product docs, peer-reviewed papers, primary press releases — where the page itself is the source of truth.
+- You found a **highly relevant** SERP hit but the title/snippet alone doesn't support the claim you want to make.
+- The snippets from the previous "search" commands are relevant but do not fully answer the question or fill the gap and fetching the full page is necessary.
+
+**Current date:** {{ date_string }}
+
+### Balance exploration and exploitation
+
+- **Explore first.** Start with `command: "search"` to get a cheap, high-level read of candidate pages. Cover one `gap` per call.
+- **Refine, don't escalate prematurely.** If the first search did not fill the `gap`, issue another `command: "search"` with a refined query (different keywords, narrower entity, different timeframe) before reaching for `read_urls`.
+- **Exploit when snippets aren't enough.** Switch to `command: "read_urls"` when snippets paraphrase / hedge, or the task needs exact figures, quotes, regulatory text, specs, or canonical-source content. Pick **1-3 high-signal URLs** from the most recent SERP — complementary domains preferred.
+- **User-provided URLs go straight to fetch.** If the user pasted URL(s), the first call should be `command: "read_urls"`. Do not "search" for a URL the user already supplied.
+- **Latency is a fair trade.** `read_urls` takes longer than `search`. That latency is acceptable on complex queries where the user expects depth — give them the answer that's actually grounded. Don't fetch when a snippet already answers the question; don't refuse to fetch when the snippet doesn't.
+
+### WebSearch — Complex and diligence-style research
+
+Use this pattern when the user needs **multiple facts about an entity** (ownership, revenue, officers, filings, sanctions, geography, industry context)—including Source of Wealth / KYC-style profiles where not everything is on the public web.
+
+- **Before the first WebSearch call** (in your reasoning, not in tool args), decompose the task into **5–10 atomic gaps**—each gap is one verifiable facet (e.g. legal name and jurisdiction, revenue scale, ownership / UBO signals, key executives, recent filings, adverse media, industry peer context).
+- **Execute gradually:** one `command: "search"` (and `read_urls` when snippets are insufficient) **per gap**, in a deliberate order (identity → scale → ownership → corroboration). Use `phase: "exploratory"` to map, then `phase: "target"` per facet; use `phase: "redirect"` only when a target facet has no public evidence after refinement.
+- **After each tool round**, update a mental **evidence ledger** per facet: **Confirmed**, **Partial**, **Not found**, or **Related only**. Do not discard partial or adjacent SERP hits—they may matter in the final synthesis.
+
+### WebSearch — When public evidence is missing or indirect
+
+- **Do not stop** after one empty or weak SERP for a gap. Refine the query (keywords, entity disambiguation, registry/filing terms, language) before marking a gap **Not found**.
+- If the **exact** fact is not published on the open web, still surface **related, attributable context** from search results: sector, approximate scale, parent/subsidiary links, adjacent filings, news mentioning the person or company, comparable peers. Label these clearly as **related, not confirmed** for the original ask.
+- **Never invent** figures, ownership percentages, or ultimate-beneficial-owner claims. **Never** present related context as if it answered the exact question.
+
+### WebSearch — Synthesizing before you answer
+
+After WebSearch research (or when the user needs an interim summary), **synthesize**—do not dump raw tool output or answer only the facets that were easy to find.
+
+For **complex** tasks, structure the answer as:
+
+1. **Direct answer** — what you can support with citations.
+2. **Evidence by facet** — facet → finding → confidence (**Confirmed** / **Partial** / **Related**) → [sourceX].
+3. **Gaps and limitations** — what was not found on the public web and which searches you tried.
+4. **Related leads** — indirect but useful pointers for the user's underlying goal (all cited).
+5. **Suggested next steps** (optional)—e.g. corporate registry, paid databases, user-provided documents—only when appropriate.
+
+For **simple** lookups, a short cited answer is enough; do not force the full structure.
+
+For the deeper explore-then-exploit playbook (snippet hedging, decomposition, partial evidence, synthesis, URL-selection, anti-patterns, worked examples including Source of Wealth), activate the `web-search-v3` skill before/while using this tool.
+
+Tool arguments are defined by the tool schema; the live JSON schema comes from the tool definition.

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev3}/src/unique_web_search/services/executors/v3/schema.py

@@ -11,12 +11,29 @@ class Command(StrEnum):
     FETCH_URLS = "read_urls"
 
 
+class SearchPhase(StrEnum):
+    """How this WebSearch call fits in the research arc."""
+
+    EXPLORATORY = "exploratory"
+    TARGET = "target"
+    REDIRECT = "redirect"
+
+
 class SearchPayload(BaseModel):
     gap: str = Field(
-        description="A brief description of the gap that the query is meant to fill"
+        description=(
+            "One atomic facet this call addresses (e.g. '2023 revenue band for Company X in CH')—"
+            "not the whole user question. Pair with `phase`: exploratory scopes the topic; "
+            "target pursues this facet precisely; redirect seeks related context when the facet "
+            "is unlikely to be on the public web."
+        )
     )
     query: str = Field(
-        description="Search query for the configured search engine. Query must be fixed for the entire rounds."
+        description=(
+            "Short search-engine keyword line (~3–8 words, not a sentence). "
+            "Do not pack multiple facets into one query—issue parallel `search` calls with "
+            "one `gap` each instead. Do not paste the user question or `gap` text here."
+        )
     )
 
 
@@ -35,14 +52,31 @@ class WebSearchV3ToolParameters(BaseModel):
         description="The command to execute. Must be either 'search' or 'read_urls'."
     )
 
-    objective: str = Field(
-        description="One concise sentence: what this call is meant to accomplish."
+    phase: SearchPhase = Field(
+        description=(
+            "Research phase for this call. "
+            "`exploratory` — sense what exists on the web and what is closest to the user's ask "
+            "(broad, mapping queries). "
+            "`target` — pursue one specific facet in `payload.gap` with a precise, short `query`. "
+            "`redirect` — last resort when the exact facet is not on the public web; find related, "
+            "attributable context (sector, peers, parent entity, adjacent news)—not invented facts."
+        )
     )
 
     payload: SearchPayload | FetchUrlsPayload = Field(
         description="The payload of the command. Must be either a SearchPayload or a FetchUrlsPayload."
     )
 
+    def relevance_focus(self) -> str:
+        """Focus string for notify UI, snippet judging, and content processing."""
+        phase_label = self.phase.value
+        if isinstance(self.payload, SearchPayload):
+            return f"[{phase_label}] {self.payload.gap}"
+        urls_preview = ", ".join(self.payload.urls[:3])
+        if len(self.payload.urls) > 3:
+            urls_preview += ", …"
+        return f"[{phase_label}] {urls_preview}"
+
     @classmethod
     def schema_hint(cls) -> str:
         """Return a markdown-bulleted hint mirroring the field descriptions of this model.
@@ -68,6 +102,9 @@ class WebSearchV3ToolParameters(BaseModel):
             if name == "command":
                 choices = " or ".join(f'`"{c.value}"`' for c in Command)
                 lines.append(f"- **`{name}`** — {choices}.")
+            elif name == "phase":
+                choices = " | ".join(f'`"{c.value}"`' for c in SearchPhase)
+                lines.append(f"- **`{name}`** — {choices}.")
             elif name == "payload":
                 continue
             else:

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev3}/src/unique_web_search/services/search_engine/__init__.py

@@ -35,6 +35,10 @@ from unique_web_search.services.search_engine.jina import (
     JinaConfig,
     JinaSearch,
 )
+from unique_web_search.services.search_engine.perplexity import (
+    PerplexitySearch,
+    PerplexitySearchConfig,
+)
 from unique_web_search.services.search_engine.tavily import (
     TavilyConfig,
     TavilySearch,
@@ -51,6 +55,7 @@ SearchEngineTypes = (
     | JinaSearch
     | TavilySearch
     | BraveSearch
+    | PerplexitySearch
     | FireCrawlSearch
     | VertexAI
 )
@@ -61,6 +66,7 @@ SearchEngineConfigTypes = (
     | JinaConfig
     | TavilyConfig
     | BraveSearchConfig
+    | PerplexitySearchConfig
     | FireCrawlConfig
     | VertexAIConfig
 )
@@ -71,6 +77,7 @@ ENGINE_NAME_TO_CONFIG = {
     "tavily": TavilyConfig,
     "bing": BingSearchConfig,
     "brave": BraveSearchConfig,
+    "perplexity": PerplexitySearchConfig,
     "firecrawl": FireCrawlConfig,
     "vertexai": VertexAIConfig,
     "custom_api": CustomAPIConfig,
@@ -94,6 +101,8 @@ def get_search_engine_service(
             return BingSearch(search_engine_config, language_model_service)
         case SearchEngineType.BRAVE:
             return BraveSearch(search_engine_config)
+        case SearchEngineType.PERPLEXITY:
+            return PerplexitySearch(search_engine_config)
         case SearchEngineType.VERTEXAI:
             return VertexAI(search_engine_config, language_model_service)
         case SearchEngineType.CUSTOM_API:
@@ -140,6 +149,8 @@ __all__ = [
     "BingSearch",
     "BraveSearch",
     "BraveSearchConfig",
+    "PerplexitySearch",
+    "PerplexitySearchConfig",
     "get_search_engine_service",
     "BaseSearchEngineConfig",
     "SearchEngine",

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev3}/src/unique_web_search/services/search_engine/base.py

@@ -21,6 +21,7 @@ class SearchEngineType(StrEnum):
     FIRECRAWL = "Firecrawl"
     TAVILY = "Tavily"
     BRAVE = "Brave"
+    PERPLEXITY = "Perplexity"
     BING = "Bing"
     DUCKDUCKGO = "DuckDuckGo"
     VERTEXAI = "VertexAI"
@@ -33,6 +34,7 @@ _SEARCH_ENGINE_MODE_MAP: dict[SearchEngineType, SearchEngineMode] = {
     SearchEngineType.FIRECRAWL: SearchEngineMode.STANDARD,
     SearchEngineType.TAVILY: SearchEngineMode.STANDARD,
     SearchEngineType.BRAVE: SearchEngineMode.STANDARD,
+    SearchEngineType.PERPLEXITY: SearchEngineMode.STANDARD,
     SearchEngineType.DUCKDUCKGO: SearchEngineMode.STANDARD,
     SearchEngineType.BING: SearchEngineMode.AGENT,
     SearchEngineType.VERTEXAI: SearchEngineMode.AGENT,
@@ -62,6 +64,7 @@ _SearchEngineExposedName = {
     SearchEngineType.FIRECRAWL: "Firecrawl Search",
     SearchEngineType.TAVILY: "Tavily Search",
     SearchEngineType.BRAVE: "Brave Search",
+    SearchEngineType.PERPLEXITY: "Perplexity Search",
     SearchEngineType.BING: "Grounding with Bing",
     SearchEngineType.DUCKDUCKGO: "DuckDuckGo Search",
     SearchEngineType.VERTEXAI: "Grounding with VertexAI",

unique_web_search-2026.24.0.dev3/src/unique_web_search/services/search_engine/perplexity.py

@@ -0,0 +1,121 @@
+import logging
+from typing import Annotated, Literal, TypeVar
+
+from perplexity import AsyncPerplexity, Omit
+from perplexity.types.search_create_response import Result
+from pydantic import Field
+from unique_toolkit._common.pydantic_helpers import DeactivatedNone
+
+from unique_web_search.client_settings import get_perplexity_search_settings
+from unique_web_search.services.client.proxy_config import async_client
+from unique_web_search.services.search_engine import (
+    BaseSearchEngineConfig,
+    SearchEngine,
+    SearchEngineType,
+)
+from unique_web_search.services.search_engine.base import get_search_engine_model_config
+from unique_web_search.services.search_engine.schema import WebSearchResult
+
+_LOGGER = logging.getLogger(__name__)
+
+# Perplexity Search API allows 1–20 results per request.
+MAX_RESULTS_PER_REQUEST = 20
+
+
+class PerplexitySearchConfig(BaseSearchEngineConfig[SearchEngineType.PERPLEXITY]):
+    model_config = get_search_engine_model_config(SearchEngineType.PERPLEXITY)
+    search_engine_name: Literal[SearchEngineType.PERPLEXITY] = (
+        SearchEngineType.PERPLEXITY
+    )
+    country: Annotated[str, Field(title="Active")] | DeactivatedNone = Field(
+        default=None,
+        description="The country to use for the search. It's a two-letter country code.",
+    )
+    max_tokens: Annotated[int, Field(title="Active")] | DeactivatedNone = Field(
+        default=None,
+        description="The maximum number of tokens to use for the context. It's a positive integer.",
+    )
+    search_mode: (
+        Annotated[Literal["web", "academic", "sec"], Field(title="Active")]
+        | DeactivatedNone
+    ) = Field(
+        default=None,
+        description="The search mode to use for the search. It's a string.",
+    )
+    search_recency_filter: (
+        Annotated[
+            Literal["hour", "day", "week", "month", "year"], Field(title="Active")
+        ]
+        | DeactivatedNone
+    ) = Field(
+        default=None,
+        description="The recency filter to use for the search. It's a string.",
+    )
+    search_type: (
+        Annotated[Literal["web", "people"], Field(title="Active")] | DeactivatedNone
+    ) = Field(
+        default=None,
+        description="The search type to use for the search. It's a string.",
+    )
+
+    requires_scraping: bool = False
+
+
+class PerplexitySearch(SearchEngine[PerplexitySearchConfig]):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.is_configured = get_perplexity_search_settings().is_configured
+
+    @property
+    def requires_scraping(self) -> bool:
+        return self.config.requires_scraping
+
+    async def search(self, query: str, **kwargs) -> list[WebSearchResult]:
+        settings = get_perplexity_search_settings()
+        assert settings.is_configured
+
+        max_results = min(self.config.fetch_size, MAX_RESULTS_PER_REQUEST)
+
+        async with async_client() as http_client:
+            perplexity_client = AsyncPerplexity(
+                api_key=settings.api_key, http_client=http_client
+            )
+            response = await perplexity_client.search.create(
+                query=query,
+                max_results=max_results,
+                country=_return_omit_if_none(self.config.country),
+                max_tokens=_return_omit_if_none(self.config.max_tokens),
+                search_mode=_return_omit_if_none(self.config.search_mode),
+                search_recency_filter=_return_omit_if_none(
+                    self.config.search_recency_filter
+                ),
+                search_type=_return_omit_if_none(self.config.search_type),
+            )
+
+        return self._to_web_search_results(response.results)
+
+    def _to_web_search_results(
+        self, results: list[Result] | None
+    ) -> list[WebSearchResult]:
+        if not results:
+            _LOGGER.warning("No search results found in Perplexity search response")
+            return []
+
+        return [
+            WebSearchResult(
+                url=result.url,
+                title=result.title,
+                snippet=result.snippet or "No Snippet Found",
+            )
+            for result in results
+        ]
+
+
+T = TypeVar("T")
+
+
+def _return_omit_if_none(value: T | None) -> T | Omit:
+    if value is None:
+        return Omit()
+    else:
+        return value

{unique_web_search-2026.24.0.dev1 → unique_web_search-2026.24.0.dev3}/src/unique_web_search/settings.py

@@ -60,6 +60,9 @@ class Base(BaseSettings):
     brave_search_api_key: str | None = None
     brave_search_api_endpoint: str | None = None
 
+    # Perplexity API settings
+    perplexity_api_key: str | None = None
+
     # VertexAI API settings
     vertexai_service_account_credentials: str | None = None
     vertexai_service_account_scopes: list[str] | None = None