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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-search-proxy-core
-Version: 2026.36.0.dev2
+Version: 2026.36.0.dev4
 Summary: Shared Pydantic types for the Unique Search Proxy API
 Author: ThePhilAz
 Author-email: ThePhilAz <rami.azouz@philico.com>
@@ -8,7 +8,7 @@ Requires-Dist: httpx>=0.28.0,<0.29
 Requires-Dist: pydantic>=2.12.5,<3.0.0
 Requires-Dist: pydantic-settings>=2.10.1,<3
 Requires-Dist: pyhumps>=3.8.0,<4
-Requires-Dist: unique-toolkit[monitoring]>=2026.36.0.dev6,<2026.36.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.36.0.dev12,<2026.36.0rc0
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 
@@ -65,7 +65,7 @@ System overview → [../README.md](../README.md)
 
 **The config class owns its entire parameter lifecycle.** Every derived surface is a method on the deployment config — there are no standalone projection or resolver modules.
 
-### 3.1 Config-owned API (search engines)
+### 3.1 Config-owned API (search + agent engines)
 
 ```
 Admin JSON → GoogleConfig {expose, value}
@@ -78,15 +78,15 @@ Admin JSON → GoogleConfig {expose, value}
 | Method | Kind | Returns |
 |--------|------|---------|
 | `request_model()` (classmethod, cached) | search / agent / crawl | `SearchRequestBase` (required `query`) or `CrawlRequestBase` (required `urls`) + config fields; `ExposableParam` knobs unwrapped to optional plain types |
-| `exposed_params_model()` (instance) | search only | `ExposedParams` subclass with exactly the `expose=True` knobs (camelCase aliases, description-only schema), or `None` |
-| `merge(overrides, *, query)` (instance) | search only | deployment defaults + LLM overrides + query → validated `request_model()` instance |
+| `exposed_params_model()` (instance) | search / agent | `ExposedParams` subclass with exactly the `expose=True` knobs (camelCase aliases, description-only schema), or `None` |
+| `merge(overrides, *, query)` (instance) | search / agent | deployment defaults + LLM overrides + query → validated `request_model()` instance |
 | `provider_query_params(request)` (classmethod) | search only | request serialized for the upstream provider, minus `_provider_param_exclude_fields` (Google adds `search_engine_id`) |
 
-Agent engines (`BingAgentConfig`, …) and crawlers (`BasicConfig`, …) only implement `request_model()`. Crawlers have no exposable params and no `merge` — a crawl request is simply the deployment config fields plus `urls`.
+`ExposableParamsConfig` (in `param_policy/exposable_config.py`) implements the exposable-parameter lifecycle once; `BaseSearchEngineConfig` and `BaseAgentEngineConfig` both extend it. Crawlers (`BasicConfig`, …) only implement `request_model()`: they have no exposable params and no `merge` — a crawl request is simply the deployment config fields plus `urls`.
 
-### 3.2 ExposableParam — search-engine only
+### 3.2 ExposableParam
 
-Optional **search** parameters use `ExposableParam[T]`:
+Optional **search** and **agent** parameters use `ExposableParam[T]`:
 
 - **`value`** — admin default merged into every request (`null` = deactivated)
 - **`expose`** — when `true`, the parameter appears on the LLM-facing exposed-params model
@@ -153,13 +153,14 @@ flowchart TB
 | `schema.py` | Shared API models: `SearchResponse`, `AgentSearchResponse`, `CrawlResponse`, `WebSearchResult`, `ErrorResponse`, SSE events |
 | `errors.py` | `ProxyError` hierarchy and stable `ProxyErrorCode` enum |
 | `param_policy/exposable_param.py` | `ExposableParam` value object, factory-default merge, type introspection, OpenAPI naming |
+| `param_policy/exposable_config.py` | `ExposableParamsConfig` — the `exposed_params_model()` / `merge()` lifecycle shared by search and agent config bases |
 | `param_policy/exposed_params.py` | `ExposedParams` base for LLM-facing parameter models (schema noise stripping) |
 | `param_policy/request_base.py` | `SearchRequestBase` / `AgentRequestBase` / `CrawlRequestBase` (required leading fields) |
 | `param_policy/annotations.py` | Annotation unwrapping helpers (private, used by `derive`) |
 | `param_policy/derive.py` | `derive_request_model` / `derive_exposed_params_model` factories called by the config base classes |
 | `providers/schema.py` | JSON Schema + defaults for deployment UIs (`provider_config_json_schema`, …) |
 | `search_engines/` | Config models with the config-owned API (`request_model` / `exposed_params_model` / `merge` / `provider_query_params`), request union |
-| `agent_engines/` | Agent config/request models (`request_model`), output schema |
+| `agent_engines/` | Agent config/request models (`request_model`, `exposed_params_model`, `merge`), output schema, Bing grounding configuration + agent naming |
 | `crawlers/` | `*Config` deployment models + derived `*CrawlRequest` bodies (`request_model()`) |
 
 ---
@@ -223,8 +224,8 @@ from unique_search_proxy_core import (
 ## 7. Features summary
 
 - Discriminated provider configs (`engine`, `crawler` Literal discriminators)
-- **Search-only:** `ExposableParam` policy; config-owned `request_model` / `exposed_params_model` / `merge` / `provider_query_params`
-- **Agent:** `BingAgentConfig.request_model()` (injects `query`; excludes `output_schema`)
+- **Search & agent:** `ExposableParam` policy; config-owned `request_model` / `exposed_params_model` / `merge` (`provider_query_params` is search-only)
+- **Agent:** `BingAgentConfig.request_model()` (injects `query`; excludes `output_schema`); Bing exposes `market` / `setLang` / `freshness`, which are baked into the hashed agent name (`market` and `setLang` are `Literal`s over Bing's documented codes, like `BraveCountry`)
 - **Crawl:** `BasicConfig.request_model()` (injects `urls`); no exposable params / no merge
 - CamelCase JSON aliases on all models
 - Zero server dependencies (import-linter enforced in the client package)

{unique_search_proxy_core-2026.36.0.dev2 → unique_search_proxy_core-2026.36.0.dev4}/README.md

@@ -51,7 +51,7 @@ System overview → [../README.md](../README.md)
 
 **The config class owns its entire parameter lifecycle.** Every derived surface is a method on the deployment config — there are no standalone projection or resolver modules.
 
-### 3.1 Config-owned API (search engines)
+### 3.1 Config-owned API (search + agent engines)
 
 ```
 Admin JSON → GoogleConfig {expose, value}
@@ -64,15 +64,15 @@ Admin JSON → GoogleConfig {expose, value}
 | Method | Kind | Returns |
 |--------|------|---------|
 | `request_model()` (classmethod, cached) | search / agent / crawl | `SearchRequestBase` (required `query`) or `CrawlRequestBase` (required `urls`) + config fields; `ExposableParam` knobs unwrapped to optional plain types |
-| `exposed_params_model()` (instance) | search only | `ExposedParams` subclass with exactly the `expose=True` knobs (camelCase aliases, description-only schema), or `None` |
-| `merge(overrides, *, query)` (instance) | search only | deployment defaults + LLM overrides + query → validated `request_model()` instance |
+| `exposed_params_model()` (instance) | search / agent | `ExposedParams` subclass with exactly the `expose=True` knobs (camelCase aliases, description-only schema), or `None` |
+| `merge(overrides, *, query)` (instance) | search / agent | deployment defaults + LLM overrides + query → validated `request_model()` instance |
 | `provider_query_params(request)` (classmethod) | search only | request serialized for the upstream provider, minus `_provider_param_exclude_fields` (Google adds `search_engine_id`) |
 
-Agent engines (`BingAgentConfig`, …) and crawlers (`BasicConfig`, …) only implement `request_model()`. Crawlers have no exposable params and no `merge` — a crawl request is simply the deployment config fields plus `urls`.
+`ExposableParamsConfig` (in `param_policy/exposable_config.py`) implements the exposable-parameter lifecycle once; `BaseSearchEngineConfig` and `BaseAgentEngineConfig` both extend it. Crawlers (`BasicConfig`, …) only implement `request_model()`: they have no exposable params and no `merge` — a crawl request is simply the deployment config fields plus `urls`.
 
-### 3.2 ExposableParam — search-engine only
+### 3.2 ExposableParam
 
-Optional **search** parameters use `ExposableParam[T]`:
+Optional **search** and **agent** parameters use `ExposableParam[T]`:
 
 - **`value`** — admin default merged into every request (`null` = deactivated)
 - **`expose`** — when `true`, the parameter appears on the LLM-facing exposed-params model
@@ -139,13 +139,14 @@ flowchart TB
 | `schema.py` | Shared API models: `SearchResponse`, `AgentSearchResponse`, `CrawlResponse`, `WebSearchResult`, `ErrorResponse`, SSE events |
 | `errors.py` | `ProxyError` hierarchy and stable `ProxyErrorCode` enum |
 | `param_policy/exposable_param.py` | `ExposableParam` value object, factory-default merge, type introspection, OpenAPI naming |
+| `param_policy/exposable_config.py` | `ExposableParamsConfig` — the `exposed_params_model()` / `merge()` lifecycle shared by search and agent config bases |
 | `param_policy/exposed_params.py` | `ExposedParams` base for LLM-facing parameter models (schema noise stripping) |
 | `param_policy/request_base.py` | `SearchRequestBase` / `AgentRequestBase` / `CrawlRequestBase` (required leading fields) |
 | `param_policy/annotations.py` | Annotation unwrapping helpers (private, used by `derive`) |
 | `param_policy/derive.py` | `derive_request_model` / `derive_exposed_params_model` factories called by the config base classes |
 | `providers/schema.py` | JSON Schema + defaults for deployment UIs (`provider_config_json_schema`, …) |
 | `search_engines/` | Config models with the config-owned API (`request_model` / `exposed_params_model` / `merge` / `provider_query_params`), request union |
-| `agent_engines/` | Agent config/request models (`request_model`), output schema |
+| `agent_engines/` | Agent config/request models (`request_model`, `exposed_params_model`, `merge`), output schema, Bing grounding configuration + agent naming |
 | `crawlers/` | `*Config` deployment models + derived `*CrawlRequest` bodies (`request_model()`) |
 
 ---
@@ -209,8 +210,8 @@ from unique_search_proxy_core import (
 ## 7. Features summary
 
 - Discriminated provider configs (`engine`, `crawler` Literal discriminators)
-- **Search-only:** `ExposableParam` policy; config-owned `request_model` / `exposed_params_model` / `merge` / `provider_query_params`
-- **Agent:** `BingAgentConfig.request_model()` (injects `query`; excludes `output_schema`)
+- **Search & agent:** `ExposableParam` policy; config-owned `request_model` / `exposed_params_model` / `merge` (`provider_query_params` is search-only)
+- **Agent:** `BingAgentConfig.request_model()` (injects `query`; excludes `output_schema`); Bing exposes `market` / `setLang` / `freshness`, which are baked into the hashed agent name (`market` and `setLang` are `Literal`s over Bing's documented codes, like `BraveCountry`)
 - **Crawl:** `BasicConfig.request_model()` (injects `urls`); no exposable params / no merge
 - CamelCase JSON aliases on all models
 - Zero server dependencies (import-linter enforced in the client package)

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

@@ -1,6 +1,6 @@
 [project]
 name = "unique-search-proxy-core"
-version = "2026.36.0.dev2"
+version = "2026.36.0.dev4"
 description = "Shared Pydantic types for the Unique Search Proxy API"
 authors = [{ name = "ThePhilAz", email = "rami.azouz@philico.com" }]
 readme = "README.md"
@@ -10,7 +10,7 @@ dependencies = [
     "pydantic>=2.12.5,<3.0.0",
     "pydantic-settings>=2.10.1,<3",
     "pyhumps>=3.8.0,<4",
-    "unique-toolkit[monitoring]>=2026.36.0.dev6,<2026.36.0rc0",
+    "unique-toolkit[monitoring]>=2026.36.0.dev12,<2026.36.0rc0",
 
 ]
 
@@ -61,6 +61,10 @@ depcheck = "deptry ."
 [tool.pytest.ini_options]
 addopts = "--strict-markers --import-mode=importlib"
 asyncio_mode = "auto"
+markers = [
+    "ai: AI-authored or AI-generated tests",
+    "unit: unit tests",
+]
 
 [tool.uv.sources]
 unique-toolkit = { workspace = true }

{unique_search_proxy_core-2026.36.0.dev2 → unique_search_proxy_core-2026.36.0.dev4}/unique_search_proxy_core/agent_engines/base.py

@@ -10,11 +10,13 @@ from unique_toolkit._common.pydantic.rjsf_tags import RJSFMetaTag
 
 from unique_search_proxy_core.agent_engines.output_schema import AgentSearchOutput
 from unique_search_proxy_core.param_policy.derive import derive_request_model
+from unique_search_proxy_core.param_policy.exposable_config import (
+    ExposableParamsConfig,
+)
 from unique_search_proxy_core.param_policy.request_base import AgentRequestBase
 from unique_search_proxy_core.schema import (
     AgentSearchResponse,
     AgentSearchStreamEvent,
-    camelized_model_config,
 )
 
 if TYPE_CHECKING:
@@ -48,14 +50,23 @@ class AgentEngineType(StrEnum):
 _AGENT_REQUEST_EXCLUDED_FIELDS = frozenset({"output_schema"})
 
 
-class BaseAgentEngineConfig(BaseModel, Generic[T]):
-    """Shared agent-engine config; each engine narrows ``engine`` with a Literal."""
+class BaseAgentEngineConfig(ExposableParamsConfig, Generic[T]):
+    """Shared agent-engine config; each engine narrows ``engine`` with a Literal.
 
-    model_config = camelized_model_config
+    Like the standard search-engine config, this owns the whole parameter
+    lifecycle: :meth:`request_model` for the HTTP body, and (from
+    :class:`ExposableParamsConfig`) ``exposed_params_model()`` / ``merge()`` for
+    engines that publish ``ExposableParam`` knobs.
+    """
 
     #: Name of the derived request model; set by every concrete agent config.
     _request_model_name: ClassVar[str]
 
+    #: ``output_schema`` is a server-side concern, never a request default.
+    _merge_exclude_fields: ClassVar[frozenset[str]] = (
+        ExposableParamsConfig._merge_exclude_fields | _AGENT_REQUEST_EXCLUDED_FIELDS
+    )
+
     @classmethod
     def request_model(cls) -> type[BaseModel]:
         """HTTP request body model, cached per config class.

unique_search_proxy_core-2026.36.0.dev4/unique_search_proxy_core/agent_engines/bing/__init__.py

@@ -0,0 +1,21 @@
+from unique_search_proxy_core.agent_engines.bing.grounding import (
+    BING_AUTO_AGENT_NAME_PREFIX,
+    BingGroundingConfiguration,
+    bing_agent_config_hash,
+    bing_agent_name,
+    is_auto_provisioned_bing_agent_name,
+)
+from unique_search_proxy_core.agent_engines.bing.schema import (
+    BingAgentConfig,
+    BingAgentSearchRequest,
+)
+
+__all__ = [
+    "BING_AUTO_AGENT_NAME_PREFIX",
+    "BingAgentConfig",
+    "BingAgentSearchRequest",
+    "BingGroundingConfiguration",
+    "bing_agent_config_hash",
+    "bing_agent_name",
+    "is_auto_provisioned_bing_agent_name",
+]

unique_search_proxy_core-2026.36.0.dev4/unique_search_proxy_core/agent_engines/bing/grounding.py

@@ -0,0 +1,74 @@
+"""Bing grounding tool configuration shared by the proxy and legacy runners.
+
+Azure bakes these knobs into an *agent version* at creation time — they are not
+sent per request — so every runner derives its agent name from them. Keeping the
+value object and its hash payload here means the proxy client and the web-search
+tool cannot drift on what a given agent name stands for.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import astuple, dataclass
+
+#: Name prefix of every auto-provisioned Bing grounding agent.
+BING_AUTO_AGENT_NAME_PREFIX = "unique-grounding-with-bing"
+
+_CONFIG_HASH_LENGTH = 12
+_HASH_FIELD_SEPARATOR = "\0"
+
+
+@dataclass(frozen=True, slots=True)
+class BingGroundingConfiguration:
+    """Knobs forwarded to ``BingGroundingSearchConfiguration`` on the agent tool."""
+
+    fetch_size: int
+    market: str | None = None
+    set_lang: str | None = None
+    freshness: str | None = None
+
+    def hash_payload(self) -> str:
+        """Stable string identifying this tool configuration."""
+        return _HASH_FIELD_SEPARATOR.join(str(value) for value in astuple(self))
+
+
+def bing_agent_config_hash(
+    *,
+    model: str,
+    instructions: str,
+    grounding: BingGroundingConfiguration,
+) -> str:
+    """Return a short hex digest of everything baked into the agent version."""
+    payload = _HASH_FIELD_SEPARATOR.join(
+        (model, instructions, grounding.hash_payload()),
+    ).encode()
+    return hashlib.sha256(payload).hexdigest()[:_CONFIG_HASH_LENGTH]
+
+
+def bing_agent_name(
+    *,
+    model: str,
+    instructions: str,
+    grounding: BingGroundingConfiguration,
+) -> str:
+    """Build a Foundry-safe agent name unique to this configuration."""
+    digest = bing_agent_config_hash(
+        model=model,
+        instructions=instructions,
+        grounding=grounding,
+    )
+    return f"{BING_AUTO_AGENT_NAME_PREFIX}-{digest}"
+
+
+def is_auto_provisioned_bing_agent_name(name: str) -> bool:
+    """True for names this module would have generated."""
+    return name.startswith(f"{BING_AUTO_AGENT_NAME_PREFIX}-")
+
+
+__all__ = [
+    "BING_AUTO_AGENT_NAME_PREFIX",
+    "BingGroundingConfiguration",
+    "bing_agent_config_hash",
+    "bing_agent_name",
+    "is_auto_provisioned_bing_agent_name",
+]

unique_search_proxy_core-2026.36.0.dev4/unique_search_proxy_core/agent_engines/bing/schema.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+from typing import Annotated, Any, ClassVar, Literal, TypeAlias
+
+from pydantic import Field, GetCoreSchemaHandler
+from pydantic_core import CoreSchema, core_schema
+from unique_toolkit._common.pydantic.rjsf_tags import RJSFMetaTag
+
+from unique_search_proxy_core.agent_engines.base import (
+    AgentEngineType,
+    BaseAgentEngineConfig,
+)
+from unique_search_proxy_core.param_policy.exposable_param import ExposableParam
+from unique_search_proxy_core.schema import DeactivatedNone
+
+_BING_DOCS_BASE_URL = (
+    "https://learn.microsoft.com/en-us/previous-versions/bing/search-apis/"
+    "bing-web-search/reference"
+)
+_BING_QUERY_PARAMS_DOCS_URL = f"{_BING_DOCS_BASE_URL}/query-parameters"
+_BING_MARKET_CODES_DOCS_URL = f"{_BING_DOCS_BASE_URL}/market-codes"
+
+#: Markets Bing serves content for (``mkt``), in the documented order.
+BingMarket: TypeAlias = Literal[
+    "es-AR",
+    "en-AU",
+    "de-AT",
+    "nl-BE",
+    "fr-BE",
+    "pt-BR",
+    "en-CA",
+    "fr-CA",
+    "es-CL",
+    "da-DK",
+    "fi-FI",
+    "fr-FR",
+    "de-DE",
+    "zh-HK",
+    "en-IN",
+    "en-ID",
+    "it-IT",
+    "ja-JP",
+    "ko-KR",
+    "en-MY",
+    "es-MX",
+    "nl-NL",
+    "en-NZ",
+    "no-NO",
+    "zh-CN",
+    "pl-PL",
+    "en-PH",
+    "ru-RU",
+    "en-ZA",
+    "es-ES",
+    "sv-SE",
+    "fr-CH",
+    "de-CH",
+    "zh-TW",
+    "tr-TR",
+    "en-GB",
+    "en-US",
+    "es-US",
+]
+
+#: Languages Bing localizes its interface strings into (``setLang``).
+BingSetLang: TypeAlias = Literal[
+    "ar",
+    "eu",
+    "bn",
+    "bg",
+    "ca",
+    "zh-hans",
+    "zh-hant",
+    "hr",
+    "cs",
+    "da",
+    "nl",
+    "en",
+    "en-gb",
+    "et",
+    "fi",
+    "fr",
+    "gl",
+    "de",
+    "gu",
+    "he",
+    "hi",
+    "hu",
+    "is",
+    "it",
+    "jp",
+    "kn",
+    "ko",
+    "lv",
+    "lt",
+    "ms",
+    "ml",
+    "mr",
+    "nb",
+    "pl",
+    "pt-br",
+    "pt-pt",
+    "pa",
+    "ro",
+    "ru",
+    "sr",
+    "sk",
+    "sl",
+    "es",
+    "sv",
+    "ta",
+    "te",
+    "th",
+    "tr",
+    "uk",
+    "vi",
+]
+
+#: Named recency windows accepted by the Bing ``freshness`` knob.
+BingFreshnessPreset: TypeAlias = Literal["Day", "Week", "Month"]
+
+_FRESHNESS_DATE_PATTERN = r"^\d{4}-\d{2}-\d{2}(?:\.\.\d{4}-\d{2}-\d{2})?$"
+
+
+class BingFreshnessDate(str):
+    """A single ``YYYY-MM-DD`` day or an inclusive ``YYYY-MM-DD..YYYY-MM-DD`` span.
+
+    The constraint lives in the type instead of ``Field(pattern=...)`` because
+    request-model derivation strips ``Annotated`` metadata off union branches,
+    which would leave exactly the surface the LLM writes to unchecked. Freshness
+    is baked into the hashed agent name, so free text here would mint a Foundry
+    agent version per distinct string while Bing ignored the value itself.
+    """
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls,
+        source: type[Any],
+        handler: GetCoreSchemaHandler,
+    ) -> CoreSchema:
+        return core_schema.str_schema(pattern=_FRESHNESS_DATE_PATTERN)
+
+
+MarketOrNone: TypeAlias = Annotated[BingMarket, Field(title="Market")] | DeactivatedNone
+SetLangOrNone: TypeAlias = (
+    Annotated[BingSetLang, Field(title="Language")] | DeactivatedNone
+)
+FreshnessOrNone: TypeAlias = (
+    Annotated[BingFreshnessPreset, Field(title="Preset")]
+    | Annotated[BingFreshnessDate, Field(title="Day or range")]
+    | DeactivatedNone
+)
+
+ExposableMarket = ExposableParam[MarketOrNone]
+ExposableSetLang = ExposableParam[SetLangOrNone]
+ExposableFreshness = ExposableParam[FreshnessOrNone]
+
+
+class BingAgentConfig(BaseAgentEngineConfig[Literal[AgentEngineType.BING]]):
+    """Deployment + request defaults for Bing grounding via Azure AI Projects."""
+
+    _request_model_name: ClassVar[str] = "BingAgentSearchRequest"
+    _exposed_params_model_name: ClassVar[str] = "BingAgentExposedParams"
+
+    engine: Annotated[
+        Literal[AgentEngineType.BING], RJSFMetaTag.SpecialWidget.hidden()
+    ] = Field(
+        default=AgentEngineType.BING,
+        title="Agent engine",
+        description="Provider discriminator; must be `bing` for this config.",
+    )
+    fetch_size: int = Field(
+        default=5,
+        ge=1,
+        le=50,
+        description="Maximum number of Bing grounding results per query",
+    )
+    market: ExposableMarket = Field(
+        default=ExposableMarket(expose=False, value=None),
+        title="Market",
+        description=(
+            "Country/region **and** language the results come from (Bing `mkt`), "
+            "as `<language>-<country>`: `de-CH` returns German-language Swiss "
+            "results, `fr-CH` French-language Swiss ones, `en-GB` UK English. "
+            "Set it when the question is about a specific country or expects an "
+            "answer in that country's language. Left unset, Bing guesses the "
+            "market from the caller and may answer from another country. "
+            f"[Market codes]({_BING_MARKET_CODES_DOCS_URL})"
+        ),
+    )
+    set_lang: ExposableSetLang = Field(
+        default=ExposableSetLang(expose=False, value=None),
+        title="Interface language",
+        description=(
+            "Language of Bing's own interface strings in the response (Bing "
+            "`setLang`), e.g. `de`, `fr`, `pt-br`. It changes neither which "
+            "results come back nor the language they are written in — use the "
+            "market for that. Bing falls back to English for codes it does not "
+            "support. "
+            f"[Supported languages]({_BING_MARKET_CODES_DOCS_URL}#bing-supported-language-codes)"
+        ),
+    )
+    freshness: ExposableFreshness = Field(
+        default=ExposableFreshness(expose=False, value=None),
+        title="Freshness",
+        description=(
+            "Keep only pages Bing discovered recently (Bing `freshness`): `Day` "
+            "(last 24 hours), `Week` (last 7 days), `Month` (last 30 days), a "
+            "single `YYYY-MM-DD` day, or an inclusive "
+            "`YYYY-MM-DD..YYYY-MM-DD` range. Use it for news and fast-moving "
+            "topics; leave it unset for background or reference questions, where "
+            "it would hide older pages that are still correct. "
+            f"[Accepted values]({_BING_QUERY_PARAMS_DOCS_URL}#freshness)"
+        ),
+    )
+
+
+BingAgentSearchRequest = BingAgentConfig.request_model()
+
+
+__all__ = [
+    "BingAgentConfig",
+    "BingAgentSearchRequest",
+    "BingFreshnessDate",
+    "BingFreshnessPreset",
+    "BingMarket",
+    "BingSetLang",
+    "ExposableFreshness",
+    "ExposableMarket",
+    "ExposableSetLang",
+]

unique_search_proxy_core-2026.36.0.dev4/unique_search_proxy_core/agent_engines/vertexai/schema.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from typing import Annotated, ClassVar, Literal
+
+from pydantic import Field, field_validator
+from unique_toolkit._common.pydantic.rjsf_tags import RJSFMetaTag
+
+from unique_search_proxy_core.agent_engines.base import (
+    AgentEngineType,
+    BaseAgentEngineConfig,
+)
+from unique_search_proxy_core.agent_engines.vertexai.settings import (
+    resolve_enable_enterprise_search,
+    vertex_ai_env_settings,
+)
+
+
+def _get_force_activate_enterprise_search_description() -> str:
+    if vertex_ai_env_settings.force_activate_enterprise_search:
+        return "This parameter has been enforced by infra team."
+
+    return (
+        "When true, ground answers with Vertex AI Enterprise Web Search "
+        "(Agent Platform Search, SEC4-compliant)"
+    )
+
+
+def _enterprise_search_rjsf_tag() -> RJSFMetaTag:
+    return RJSFMetaTag.BooleanWidget.checkbox(
+        title="Enable Enterprise Search",
+        help=_get_force_activate_enterprise_search_description(),
+        disabled=vertex_ai_env_settings.force_activate_enterprise_search,
+    )
+
+
+EnableEnterpriseSearch = Annotated[bool, _enterprise_search_rjsf_tag()]
+
+
+class VertexAIAgentConfig(BaseAgentEngineConfig[Literal[AgentEngineType.VERTEXAI]]):
+    """Deployment + request defaults for Vertex AI grounding (Google GenAI)."""
+
+    _request_model_name: ClassVar[str] = "VertexAIAgentSearchRequest"
+    _exposed_params_model_name: ClassVar[str] = "VertexAIAgentExposedParams"
+
+    engine: Annotated[
+        Literal[AgentEngineType.VERTEXAI], RJSFMetaTag.SpecialWidget.hidden()
+    ] = Field(
+        default=AgentEngineType.VERTEXAI,
+        title="Agent engine",
+        description="Provider discriminator; must be `vertexai` for this config.",
+    )
+    vertexai_model_name: str = Field(
+        default=vertex_ai_env_settings.default_vertex_ai_model_name,
+        description="Gemini model name for grounded generation",
+    )
+    enable_enterprise_search: EnableEnterpriseSearch = Field(
+        default=vertex_ai_env_settings.force_activate_enterprise_search,
+        validate_default=True,
+    )
+
+    @field_validator("enable_enterprise_search", mode="before")
+    @classmethod
+    def validate_enable_enterprise_search(cls, v: object) -> bool:
+        """Pin the value on when infra forces enterprise search for ZDR tenants."""
+        return resolve_enable_enterprise_search(bool(v) if v is not None else False)
+
+
+VertexAIAgentSearchRequest = VertexAIAgentConfig.request_model()
+
+
+__all__ = [
+    "VertexAIAgentConfig",
+    "VertexAIAgentSearchRequest",
+]

unique_search_proxy_core-2026.36.0.dev4/unique_search_proxy_core/agent_engines/vertexai/settings.py

@@ -0,0 +1,52 @@
+import os
+import sys
+from pathlib import Path
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+_ENV_PREFIX = "VERTEXAI_AGENT_"
+
+
+class _VertexAIEnvSettings(BaseSettings):
+    default_vertex_ai_model_name: str = Field(
+        default="gemini-3-flash-preview",
+        description="Default Vertex AI model name for grounded generation",
+    )
+    force_activate_enterprise_search: bool = Field(
+        default=False,
+        description=(
+            "When true, pin Enable Enterprise Search on for ZDR tenants so the "
+            "toggle cannot be turned off in config or at request time."
+        ),
+    )
+
+
+def _get_settings() -> _VertexAIEnvSettings:
+    if "pytest" in sys.modules:
+        env_file = Path(os.getcwd()) / "tests/test.env"
+    else:
+        env_file = Path(os.getcwd()) / ".env"
+
+    class _Settings(_VertexAIEnvSettings):
+        model_config = SettingsConfigDict(
+            env_file=env_file,
+            env_prefix=_ENV_PREFIX,
+            extra="ignore",
+        )
+
+    return _Settings()
+
+
+vertex_ai_env_settings = _get_settings()
+
+
+def resolve_enable_enterprise_search(value: bool | None = False) -> bool:
+    """Return the effective enterprise-search flag after infra enforcement.
+
+    ZDR tenants set ``VERTEXAI_AGENT_FORCE_ACTIVATE_ENTERPRISE_SEARCH=true`` so
+    the cheaper standard grounding edition cannot be selected.
+    """
+    if vertex_ai_env_settings.force_activate_enterprise_search:
+        return True
+    return bool(value)

{unique_search_proxy_core-2026.36.0.dev2 → unique_search_proxy_core-2026.36.0.dev4}/unique_search_proxy_core/param_policy/derive.py

@@ -1,8 +1,9 @@
 """Model factories: deployment config class -> derived Pydantic models.
 
 Private-by-convention; the public entry points are the config-class methods
-(``BaseSearchEngineConfig.request_model()`` / ``exposed_params_model()`` and the
-agent/crawler ``request_model()`` counterparts), which delegate here.
+(``request_model()`` / ``exposed_params_model()`` on the search and agent bases
+through :class:`~unique_search_proxy_core.param_policy.exposable_config.ExposableParamsConfig`,
+and ``request_model()`` on the crawler base), which delegate here.
 
 Two factories, both plain ``create_model`` calls over ``model_fields``:
 

unique_search_proxy_core-2026.36.0.dev4/unique_search_proxy_core/param_policy/exposable_config.py

@@ -0,0 +1,107 @@
+"""Config base for engines carrying ``ExposableParam`` knobs.
+
+Standard search engines and agent engines own the same parameter lifecycle:
+partial exposable JSON is merged with the field's ``default_factory`` before
+validation, the admin-exposed subset is projected into an LLM-facing model, and
+deployment defaults are resolved into a validated request body. That lifecycle
+lives here so :class:`~unique_search_proxy_core.search_engines.base.BaseSearchEngineConfig`
+and :class:`~unique_search_proxy_core.agent_engines.base.BaseAgentEngineConfig`
+share one implementation.
+
+Subclasses supply the two pieces this base cannot know: ``request_model()``
+(which request base class the derived body extends) and the
+``_exposed_params_model_name`` / ``_merge_exclude_fields`` class vars.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Mapping
+
+from pydantic import BaseModel, model_validator
+
+from unique_search_proxy_core.param_policy import QUERY_FIELD
+from unique_search_proxy_core.param_policy.derive import derive_exposed_params_model
+from unique_search_proxy_core.param_policy.exposable_param import (
+    merge_exposable_params_with_factory_defaults,
+    resolve_exposable_value,
+)
+from unique_search_proxy_core.param_policy.exposed_params import ExposedParams
+from unique_search_proxy_core.schema import camelized_model_config
+
+#: Provider discriminator field carried by every engine config.
+ENGINE_FIELD = "engine"
+
+
+class ExposableParamsConfig(BaseModel):
+    """Deployment config whose optional knobs may be exposed to the LLM.
+
+    - :meth:`exposed_params_model` — the LLM-facing knobs of this deployment.
+    - :meth:`merge` — deployment defaults + LLM overrides -> validated request.
+    """
+
+    model_config = camelized_model_config
+
+    #: Name of the derived exposed-params model; set by every concrete config.
+    _exposed_params_model_name: ClassVar[str]
+
+    #: Config fields that never contribute a request default in :meth:`merge`.
+    #: The discriminator is set from the config itself; engine bases extend this
+    #: with their own server-side-only fields (e.g. the agent ``output_schema``).
+    _merge_exclude_fields: ClassVar[frozenset[str]] = frozenset({ENGINE_FIELD})
+
+    @model_validator(mode="before")
+    @classmethod
+    def _merge_exposable_factory_defaults(cls, data: Any) -> Any:
+        """Merge exposable knobs with field ``default_factory`` when JSON omits ``value``."""
+        return merge_exposable_params_with_factory_defaults(cls, data)
+
+    @classmethod
+    def request_model(cls) -> type[BaseModel]:
+        """HTTP request body model derived from this config."""
+        raise NotImplementedError
+
+    def exposed_params_model(self) -> type[ExposedParams] | None:
+        """Plain model class with exactly the knobs this deployment exposed.
+
+        One optional field per config field whose ``ExposableParam`` has
+        ``expose=True``: camelCase alias, description-only schema, no admin
+        defaults. Returns ``None`` when nothing is exposed. Consumers subclass
+        the result (or pass it as an extra base to ``create_model``) to graft
+        the knobs onto their own tool-parameter models.
+
+        Example: ``config.exposed_params_model()`` -> ``GoogleExposedParams``.
+        """
+        return derive_exposed_params_model(
+            self,
+            name=type(self)._exposed_params_model_name,
+        )
+
+    def merge(self, overrides: Mapping[str, Any], *, query: str) -> BaseModel:
+        """Deployment defaults + LLM/caller overrides + query -> validated request.
+
+        Defaults: plain fields contribute their value; ``ExposableParam`` knobs
+        contribute ``value`` when not ``None`` (deactivated knobs are dropped);
+        ``engine`` always comes from this config. ``overrides`` win over
+        defaults. Validates into :meth:`request_model`.
+
+        Example: ``config.merge({"date_restrict": "d7"}, query="ai news")``.
+        """
+        merged: dict[str, Any] = self._merge_defaults()
+        merged.update(overrides)
+        merged[QUERY_FIELD] = query
+        merged[ENGINE_FIELD] = getattr(self, ENGINE_FIELD)
+        return type(self).request_model().model_validate(merged)
+
+    def _merge_defaults(self) -> dict[str, Any]:
+        """Plain deployment default values (``ExposableParam`` resolved, ``None`` dropped)."""
+        defaults: dict[str, Any] = {}
+        for field_name in type(self).model_fields:
+            if field_name in type(self)._merge_exclude_fields:
+                continue
+            value = resolve_exposable_value(getattr(self, field_name))
+            if value is not None:
+                defaults[field_name] = value
+        return defaults
+
+
+__all__ = ["ENGINE_FIELD", "ExposableParamsConfig"]

{unique_search_proxy_core-2026.36.0.dev2 → unique_search_proxy_core-2026.36.0.dev4}/unique_search_proxy_core/param_policy/exposable_param.py

@@ -121,6 +121,17 @@ class ExposableParam(BaseModel, Generic[T]):
         return schema
 
 
+def resolve_exposable_value(value: Any) -> Any:
+    """Plain value behind a config attribute that may be an ``ExposableParam``.
+
+    Lets consumers read a deployment default without caring whether the field is
+    an exposable knob or a plain value.
+    """
+    if isinstance(value, ExposableParam):
+        return value.value
+    return value
+
+
 def _exposable_field_keys(field_name: str, field_info: FieldInfo) -> list[str]:
     keys = [field_name]
     if field_info.alias is not None:

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

@@ -2,26 +2,18 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from enum import StrEnum
-from typing import TYPE_CHECKING, Any, ClassVar, Generic, Mapping, TypeVar
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeVar
 
-from pydantic import BaseModel, Field, model_validator
+from pydantic import BaseModel, Field
 
 from unique_search_proxy_core.param_policy import QUERY_FIELD
-from unique_search_proxy_core.param_policy.derive import (
-    derive_exposed_params_model,
-    derive_request_model,
+from unique_search_proxy_core.param_policy.derive import derive_request_model
+from unique_search_proxy_core.param_policy.exposable_config import (
+    ENGINE_FIELD,
+    ExposableParamsConfig,
 )
-from unique_search_proxy_core.param_policy.exposable_param import (
-    ExposableParam,
-    merge_exposable_params_with_factory_defaults,
-)
-from unique_search_proxy_core.param_policy.exposed_params import ExposedParams
 from unique_search_proxy_core.param_policy.request_base import SearchRequestBase
-from unique_search_proxy_core.schema import (
-    SearchEngineRaw,
-    WebSearchResults,
-    camelized_model_config,
-)
+from unique_search_proxy_core.schema import SearchEngineRaw, WebSearchResults
 
 if TYPE_CHECKING:
     from httpx import AsyncClient
@@ -29,7 +21,6 @@ if TYPE_CHECKING:
 T = TypeVar("T", bound="SearchEngineType")
 SearchRequestT = TypeVar("SearchRequestT", bound=BaseModel)
 
-ENGINE_FIELD = "engine"
 FETCH_SIZE_FIELD = "fetch_size"
 TIMEOUT_FIELD = "timeout"
 
@@ -64,7 +55,7 @@ def get_search_engine_mode(
     return _SEARCH_ENGINE_MODE_MAP.get(engine_type, SearchEngineMode.STANDARD)
 
 
-class BaseSearchEngineConfig(BaseModel, Generic[T]):
+class BaseSearchEngineConfig(ExposableParamsConfig, Generic[T]):
     """Shared search-engine config; each engine narrows ``engine`` with a Literal.
 
     The config class owns its entire parameter lifecycle:
@@ -75,8 +66,6 @@ class BaseSearchEngineConfig(BaseModel, Generic[T]):
     - :meth:`provider_query_params` — request -> upstream provider dict.
     """
 
-    model_config = camelized_model_config
-
     #: Fields never forwarded to the upstream provider query string: the
     #: discriminator, request plumbing, and the query itself. Engine configs
     #: extend this to drop provider-internal fields — e.g. Google adds
@@ -85,9 +74,8 @@ class BaseSearchEngineConfig(BaseModel, Generic[T]):
         {ENGINE_FIELD, FETCH_SIZE_FIELD, TIMEOUT_FIELD, QUERY_FIELD},
     )
 
-    #: Names of the derived models; set by every concrete engine config.
+    #: Name of the derived request model; set by every concrete engine config.
     _request_model_name: ClassVar[str]
-    _exposed_params_model_name: ClassVar[str]
 
     engine: T
     fetch_size: int = Field(
@@ -103,12 +91,6 @@ class BaseSearchEngineConfig(BaseModel, Generic[T]):
         description="Request timeout in seconds",
     )
 
-    @model_validator(mode="before")
-    @classmethod
-    def _merge_exposable_factory_defaults(cls, data: Any) -> Any:
-        """Merge exposable knobs with field ``default_factory`` when JSON omits ``value``."""
-        return merge_exposable_params_with_factory_defaults(cls, data)
-
     @classmethod
     def request_model(cls) -> type[BaseModel]:
         """HTTP request body model, cached per config class.
@@ -124,52 +106,6 @@ class BaseSearchEngineConfig(BaseModel, Generic[T]):
             name=cls._request_model_name,
         )
 
-    def exposed_params_model(self) -> type[ExposedParams] | None:
-        """Plain model class with exactly the knobs this deployment exposed.
-
-        One optional field per config field whose ``ExposableParam`` has
-        ``expose=True``: camelCase alias, description-only schema, no admin
-        defaults. Returns ``None`` when nothing is exposed. Consumers subclass
-        the result (or pass it as an extra base to ``create_model``) to graft
-        the knobs onto their own tool-parameter models.
-
-        Example: ``config.exposed_params_model()`` -> ``GoogleExposedParams``.
-        """
-        return derive_exposed_params_model(
-            self,
-            name=type(self)._exposed_params_model_name,
-        )
-
-    def merge(self, overrides: Mapping[str, Any], *, query: str) -> BaseModel:
-        """Deployment defaults + LLM/caller overrides + query -> validated request.
-
-        Defaults: plain fields contribute their value; ``ExposableParam`` knobs
-        contribute ``value`` when not ``None`` (deactivated knobs are dropped);
-        ``engine`` always comes from this config. ``overrides`` win over
-        defaults. Validates into :meth:`request_model`.
-
-        Example: ``config.merge({"date_restrict": "d7"}, query="ai news")``.
-        """
-        merged: dict[str, Any] = self._merge_defaults()
-        merged.update(overrides)
-        merged[QUERY_FIELD] = query
-        merged[ENGINE_FIELD] = self.engine
-        return type(self).request_model().model_validate(merged)
-
-    def _merge_defaults(self) -> dict[str, Any]:
-        """Plain deployment default values (``ExposableParam`` resolved, ``None`` dropped)."""
-        defaults: dict[str, Any] = {}
-        for field_name in type(self).model_fields:
-            if field_name == ENGINE_FIELD:
-                continue
-            raw = getattr(self, field_name)
-            if isinstance(raw, ExposableParam):
-                if raw.value is not None:
-                    defaults[field_name] = raw.value
-            elif raw is not None:
-                defaults[field_name] = raw
-        return defaults
-
     @classmethod
     def provider_query_params(
         cls,

unique_search_proxy_core-2026.36.0.dev2/unique_search_proxy_core/agent_engines/bing/__init__.py

@@ -1,6 +0,0 @@
-from unique_search_proxy_core.agent_engines.bing.schema import (
-    BingAgentConfig,
-    BingAgentSearchRequest,
-)
-
-__all__ = ["BingAgentConfig", "BingAgentSearchRequest"]

unique_search_proxy_core-2026.36.0.dev2/unique_search_proxy_core/agent_engines/bing/schema.py

@@ -1,37 +0,0 @@
-from __future__ import annotations
-
-from typing import Annotated, ClassVar, Literal
-
-from pydantic import Field
-from unique_toolkit._common.pydantic.rjsf_tags import RJSFMetaTag
-
-from unique_search_proxy_core.agent_engines.base import (
-    AgentEngineType,
-    BaseAgentEngineConfig,
-)
-
-
-class BingAgentConfig(BaseAgentEngineConfig[Literal[AgentEngineType.BING]]):
-    """Deployment + request defaults for Bing grounding via Azure AI Projects."""
-
-    _request_model_name: ClassVar[str] = "BingAgentSearchRequest"
-
-    engine: Annotated[
-        Literal[AgentEngineType.BING], RJSFMetaTag.SpecialWidget.hidden()
-    ] = Field(
-        default=AgentEngineType.BING,
-        title="Agent engine",
-        description="Provider discriminator; must be `bing` for this config.",
-    )
-    fetch_size: int = Field(
-        default=5,
-        ge=1,
-        le=50,
-        description="Maximum number of Bing grounding results per query",
-    )
-
-
-BingAgentSearchRequest = BingAgentConfig.request_model()
-
-
-__all__ = ["BingAgentConfig", "BingAgentSearchRequest"]

unique_search_proxy_core-2026.36.0.dev2/unique_search_proxy_core/agent_engines/vertexai/schema.py

@@ -1,45 +0,0 @@
-from __future__ import annotations
-
-from typing import Annotated, ClassVar, Literal
-
-from pydantic import Field
-from unique_toolkit._common.pydantic.rjsf_tags import RJSFMetaTag
-
-from unique_search_proxy_core.agent_engines.base import (
-    AgentEngineType,
-    BaseAgentEngineConfig,
-)
-
-
-class VertexAIAgentConfig(BaseAgentEngineConfig[Literal[AgentEngineType.VERTEXAI]]):
-    """Deployment + request defaults for Vertex AI grounding (Google GenAI)."""
-
-    _request_model_name: ClassVar[str] = "VertexAIAgentSearchRequest"
-
-    engine: Annotated[
-        Literal[AgentEngineType.VERTEXAI], RJSFMetaTag.SpecialWidget.hidden()
-    ] = Field(
-        default=AgentEngineType.VERTEXAI,
-        title="Agent engine",
-        description="Provider discriminator; must be `vertexai` for this config.",
-    )
-    vertexai_model_name: str = Field(
-        default="gemini-3-flash-preview",
-        description="Gemini model name for grounded generation",
-    )
-    enable_enterprise_search: bool = Field(
-        default=False,
-        description=(
-            "When true, ground answers with Vertex AI Enterprise Web Search "
-            "(Agent Platform Search, SEC4-compliant)"
-        ),
-    )
-
-
-VertexAIAgentSearchRequest = VertexAIAgentConfig.request_model()
-
-
-__all__ = [
-    "VertexAIAgentConfig",
-    "VertexAIAgentSearchRequest",
-]