unique-search-proxy-core 2026.30.0.dev0__tar.gz → 2026.30.0.dev2__tar.gz

{unique_search_proxy_core-2026.30.0.dev0 → unique_search_proxy_core-2026.30.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-search-proxy-core
-Version: 2026.30.0.dev0
+Version: 2026.30.0.dev2
 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.30.0.dev0,<2026.30.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.30.0.dev10,<2026.30.0rc0
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 
@@ -46,17 +46,15 @@ flowchart TB
 
     subgraph core["unique_search_proxy_core"]
         Contracts["Response & error models"]
-        Config["*Config deployment models"]
-        Project["Schema projection & merge"]
+        Config["*Config deployment models\n(request_model / exposed_params_model / merge)"]
     end
 
     AC --> Config
-    AC --> Project
     Client --> Contracts
     Client --> Config
     SDK --> Contracts
-    Project -->|"flat request body"| SDK
-    Project -->|"flat request body"| Client
+    Config -->|"flat request body"| SDK
+    Config -->|"flat request body"| Client
 ```
 
 System overview → [../README.md](../README.md)
@@ -65,81 +63,63 @@ System overview → [../README.md](../README.md)
 
 ## 3. Key concepts
 
-Core uses **three different config patterns** depending on provider kind. Only search engines use `ExposableParam` and the full projection pipeline.
+**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 Three provider patterns (search vs agent vs crawl)
+### 3.1 Config-owned API (search engines)
 
-| Kind | Config → request | `ExposableParam` | LLM call schema | Config/invocation merge |
-|------|------------------|------------------|-----------------|-------------------------|
-| **Search engines** | `GoogleConfig` → `GoogleSearchRequest` via `projection.build_request_model` | Yes | `build_llm_call_model` + `call_schema.resolve_*` | `merge_config_and_invocation` |
-| **Agent engines** | `BingAgentConfig` → `BingAgentSearchRequest` via `agent_engines/projection.build_agent_request_model` | No (plain fields) | Not implemented in core | Not implemented in core |
-| **Crawlers** | `BasicConfig` → `BasicCrawlRequest` via `crawlers/projection.build_crawl_request_model` | No | Not implemented in core | `merge_crawler_config_and_invocation` |
-
-```mermaid
-flowchart TB
-    subgraph search["Search engines only"]
-        GC["GoogleConfig\n(ExposableParam knobs)"]
-        Proj["projection.py\nbuild_request_model\nbuild_llm_call_model"]
-        GSR["GoogleSearchRequest"]
-        LLM["LLM call schema"]
-        GC --> Proj
-        Proj --> GSR
-        Proj --> LLM
-    end
-
-    subgraph agent["Agent engines"]
-        BC["BingAgentConfig\n(plain fields)"]
-        AProj["agent_engines/projection.py\nbuild_agent_request_model"]
-        BSR["BingAgentSearchRequest"]
-        BC --> AProj
-        AProj -->|"via model_derivation"| BSR
-    end
-
-    subgraph crawl["Crawlers"]
-        BCrawl["BasicConfig\n(no urls)"]
-        CProj["crawlers/projection.py\nbuild_crawl_request_model"]
-        BCR["BasicCrawlRequest\n(urls injected)"]
-        BCrawl --> CProj
-        CProj -->|"via model_derivation"| BCR
-    end
+```
+Admin JSON → GoogleConfig {expose, value}
+  ├─ GoogleConfig.request_model()            → GoogleSearchRequest (HTTP body, query required)
+  ├─ config.exposed_params_model()           → GoogleExposedParams (LLM knobs; tool inherits it)
+  ├─ config.merge(llm_args, query=…)         → validated GoogleSearchRequest
+  └─ GoogleConfig.provider_query_params(req) → upstream provider dict
 ```
 
-### 3.2 Search engines — three surfaces from one config
-
-Search is the only kind where a single `*Config` fans out into three derived surfaces:
-
-| Surface | Audience | Example |
-|---------|----------|---------|
-| **Deployment config** | Admin / deployment UI | `{ "engine": "google", "gl": { "expose": true, "value": "de" }, … }` |
-| **LLM call schema** | Tool manifest shown to the model | `{ "query", "gl" }` — only fields where `expose: true` |
-| **HTTP request body** | `POST /v1/search` wire format | `{ "engine": "google", "query": "…", "gl": "de", "fetchSize": 10 }` |
+| 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 |
+| `provider_query_params(request)` (classmethod) | search only | request serialized for the upstream provider, minus `_provider_param_exclude_fields` (Google adds `search_engine_id`) |
 
-`projection.py` and `search_engines/params.py` derive the latter two from the first. Agent and crawl use `model_derivation.derive_request_model` via per-kind projection modules to inject `query` or `urls`.
+Agent engines (`BingAgentConfig`, …) and crawlers (`BasicConfig`, …) only implement `request_model()`; crawlers additionally keep `merge_crawler_config_and_invocation`.
 
-### 3.3 ExposableParam — search-engine only
+### 3.2 ExposableParam — search-engine only
 
 Optional **search** parameters use `ExposableParam[T]`:
 
 - **`value`** — admin default merged into every request (`null` = deactivated)
-- **`expose`** — when `true`, the parameter appears on the LLM call schema
+- **`expose`** — when `true`, the parameter appears on the LLM-facing exposed-params model
 
 ```python
 gl: ExposableParam[str | None] = ExposableParam(expose=False, value="de")  # admin-fixed
 gl: ExposableParam[str | None] = ExposableParam(expose=True, value=None)   # LLM-overridable
 ```
 
-No agent or crawler schema imports `ExposableParam` today.
+Bare scalars are **not** coerced — deployment JSON must use the explicit `{"expose": …, "value": …}` shape.
+
+### 3.3 ExposedParams — the LLM tool-schema contract
 
-### 3.4 merge_config_and_invocation — search-engine only
+`config.exposed_params_model()` returns a plain Pydantic model class. Tool-parameter models graft the knobs on by **ordinary inheritance** — no field-def plumbing, no stamped attributes:
 
 ```python
-from unique_search_proxy_core.search_engines import merge_config_and_invocation
+Exposed = config.exposed_params_model()          # GoogleExposedParams | None
+class ToolParams(ToolParamsBase, Exposed): ...   # or create_model(__base__=(...))
+
+ToolParams.model_json_schema()   # camelCase knobs, no title/default noise
+Exposed.model_fields             # the exposed field names
+```
+
+The shared `ExposedParams` base owns the single JSON-schema concern: its `model_json_schema` strips Pydantic's auto-`title` and `default` noise, so admin defaults never leak into what the LLM sees.
 
-request = merge_config_and_invocation(google_config, {"query": "EU AI Act"})
+### 3.4 merge — deployment defaults + LLM overrides
+
+```python
+request = google_config.merge({"gl": "de"}, query="EU AI Act")
 # → validated GoogleSearchRequest ready for POST /v1/search
 ```
 
-The proxy receives a flat body; it does not resolve deployment config over HTTP.
+Deactivated knobs (`value=None`) are dropped, overrides win over admin defaults, `engine` always comes from the config. The proxy receives a flat body; it does not resolve deployment config over HTTP.
 
 ### 3.5 merge_crawler_config_and_invocation — crawler only
 
@@ -159,25 +139,16 @@ flowchart TB
     subgraph core_pkg["unique_search_proxy_core"]
         Schema["schema.py"]
         Errors["errors.py"]
-        MD["model_derivation/"]
-        PP["param_policy/"]
-        Proj["projection.py\n(search + LLM projection)"]
-        AProj["agent_engines/projection.py"]
-        CProj["crawlers/projection.py"]
+        PP["param_policy/\nExposableParam · ExposedParams\nrequest bases · derive"]
         Prov["providers/schema.py"]
         SE["search_engines/"]
         AE["agent_engines/"]
         CR["crawlers/"]
     end
 
-    PP --> Proj
     PP --> SE
-    MD --> Proj
-    MD --> AProj
-    MD --> CProj
-    Proj --> SE
-    AProj --> AE
-    CProj --> CR
+    PP --> AE
+    PP --> CR
     Prov --> SE
     Prov --> CR
     SE --> Schema
@@ -190,15 +161,15 @@ flowchart TB
 |--------|----------------|
 | `schema.py` | Shared API models: `SearchResponse`, `AgentSearchResponse`, `CrawlResponse`, `WebSearchResult`, `ErrorResponse`, SSE events |
 | `errors.py` | `ProxyError` hierarchy and stable `ProxyErrorCode` enum |
-| `model_derivation/` | Shared `derive_request_model` + field/annotation helpers used by all three provider kinds |
-| `param_policy/` | `ExposableParam` — used by **search engine** config models only |
-| `projection.py` | Search-only: `build_request_model`, `build_llm_call_model`, `project_call_schema` |
-| `agent_engines/projection.py` | Agent-only: `build_agent_request_model` (injects `query`; excludes `output_schema`) |
-| `crawlers/projection.py` | Crawler-only: `build_crawl_request_model` (injects `urls`) |
+| `param_policy/exposable_param.py` | `ExposableParam` value object, factory-default merge, type introspection, OpenAPI naming |
+| `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, request union, `merge_config_and_invocation`, call-schema resolution |
-| `agent_engines/` | Agent config/request models, output schema |
-| `crawlers/` | `*Config` deployment models + derived `*CrawlRequest` HTTP bodies |
+| `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 |
+| `crawlers/` | `*Config` deployment models + derived `*CrawlRequest` bodies, `merge_crawler_config_and_invocation` |
 
 ---
 
@@ -230,21 +201,19 @@ schema = provider_config_json_schema("search_engine", "google")
 defaults = provider_default_config("search_engine", "google")
 ```
 
-### Tool manifest — LLM call schema
+### Tool manifest — exposed LLM knobs
 
 ```python
-from unique_search_proxy_core.search_engines.call_schema import resolve_search_call_schema
-
-descriptor = resolve_search_call_schema("google", config=google_config, strict=False)
-# descriptor.call_schema → JSON Schema for the LLM tool
+Exposed = google_config.exposed_params_model()   # GoogleExposedParams | None
+class ToolParams(ToolParamsBase, Exposed): ...   # graft knobs by inheritance
+ToolParams.model_json_schema()                   # camelCase, no title/default noise
 ```
 
 ### Runtime — build flat request before HTTP call
 
 ```python
-from unique_search_proxy_core.search_engines import merge_config_and_invocation
-
-body = merge_config_and_invocation(config, llm_invocation_dict)
+request = google_config.merge(llm_invocation_dict, query="EU AI Act")
+body = GoogleConfig.provider_query_params(request)  # upstream provider dict
 ```
 
 ### Shared types and errors
@@ -263,9 +232,9 @@ from unique_search_proxy_core import (
 ## 7. Features summary
 
 - Discriminated provider configs (`engine`, `crawler` Literal discriminators)
-- **Search-only:** `ExposableParam` policy, three-surface projection, LLM call schema, `merge_config_and_invocation`
-- **Agent:** config → request derivation via `model_derivation` + `build_agent_request_model`
-- **Crawl:** `*Config` + `build_crawl_request_model` (injects `urls`); `merge_crawler_config_and_invocation`
+- **Search-only:** `ExposableParam` policy; config-owned `request_model` / `exposed_params_model` / `merge` / `provider_query_params`
+- **Agent:** `BingAgentConfig.request_model()` (injects `query`; excludes `output_schema`)
+- **Crawl:** `BasicConfig.request_model()` (injects `urls`); `merge_crawler_config_and_invocation`
 - CamelCase JSON aliases on all models
 - Zero server dependencies (import-linter enforced in the client package)
 

{unique_search_proxy_core-2026.30.0.dev0 → unique_search_proxy_core-2026.30.0.dev2}/README.md

@@ -32,17 +32,15 @@ flowchart TB
 
     subgraph core["unique_search_proxy_core"]
         Contracts["Response & error models"]
-        Config["*Config deployment models"]
-        Project["Schema projection & merge"]
+        Config["*Config deployment models\n(request_model / exposed_params_model / merge)"]
     end
 
     AC --> Config
-    AC --> Project
     Client --> Contracts
     Client --> Config
     SDK --> Contracts
-    Project -->|"flat request body"| SDK
-    Project -->|"flat request body"| Client
+    Config -->|"flat request body"| SDK
+    Config -->|"flat request body"| Client
 ```
 
 System overview → [../README.md](../README.md)
@@ -51,81 +49,63 @@ System overview → [../README.md](../README.md)
 
 ## 3. Key concepts
 
-Core uses **three different config patterns** depending on provider kind. Only search engines use `ExposableParam` and the full projection pipeline.
+**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 Three provider patterns (search vs agent vs crawl)
+### 3.1 Config-owned API (search engines)
 
-| Kind | Config → request | `ExposableParam` | LLM call schema | Config/invocation merge |
-|------|------------------|------------------|-----------------|-------------------------|
-| **Search engines** | `GoogleConfig` → `GoogleSearchRequest` via `projection.build_request_model` | Yes | `build_llm_call_model` + `call_schema.resolve_*` | `merge_config_and_invocation` |
-| **Agent engines** | `BingAgentConfig` → `BingAgentSearchRequest` via `agent_engines/projection.build_agent_request_model` | No (plain fields) | Not implemented in core | Not implemented in core |
-| **Crawlers** | `BasicConfig` → `BasicCrawlRequest` via `crawlers/projection.build_crawl_request_model` | No | Not implemented in core | `merge_crawler_config_and_invocation` |
-
-```mermaid
-flowchart TB
-    subgraph search["Search engines only"]
-        GC["GoogleConfig\n(ExposableParam knobs)"]
-        Proj["projection.py\nbuild_request_model\nbuild_llm_call_model"]
-        GSR["GoogleSearchRequest"]
-        LLM["LLM call schema"]
-        GC --> Proj
-        Proj --> GSR
-        Proj --> LLM
-    end
-
-    subgraph agent["Agent engines"]
-        BC["BingAgentConfig\n(plain fields)"]
-        AProj["agent_engines/projection.py\nbuild_agent_request_model"]
-        BSR["BingAgentSearchRequest"]
-        BC --> AProj
-        AProj -->|"via model_derivation"| BSR
-    end
-
-    subgraph crawl["Crawlers"]
-        BCrawl["BasicConfig\n(no urls)"]
-        CProj["crawlers/projection.py\nbuild_crawl_request_model"]
-        BCR["BasicCrawlRequest\n(urls injected)"]
-        BCrawl --> CProj
-        CProj -->|"via model_derivation"| BCR
-    end
+```
+Admin JSON → GoogleConfig {expose, value}
+  ├─ GoogleConfig.request_model()            → GoogleSearchRequest (HTTP body, query required)
+  ├─ config.exposed_params_model()           → GoogleExposedParams (LLM knobs; tool inherits it)
+  ├─ config.merge(llm_args, query=…)         → validated GoogleSearchRequest
+  └─ GoogleConfig.provider_query_params(req) → upstream provider dict
 ```
 
-### 3.2 Search engines — three surfaces from one config
-
-Search is the only kind where a single `*Config` fans out into three derived surfaces:
-
-| Surface | Audience | Example |
-|---------|----------|---------|
-| **Deployment config** | Admin / deployment UI | `{ "engine": "google", "gl": { "expose": true, "value": "de" }, … }` |
-| **LLM call schema** | Tool manifest shown to the model | `{ "query", "gl" }` — only fields where `expose: true` |
-| **HTTP request body** | `POST /v1/search` wire format | `{ "engine": "google", "query": "…", "gl": "de", "fetchSize": 10 }` |
+| 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 |
+| `provider_query_params(request)` (classmethod) | search only | request serialized for the upstream provider, minus `_provider_param_exclude_fields` (Google adds `search_engine_id`) |
 
-`projection.py` and `search_engines/params.py` derive the latter two from the first. Agent and crawl use `model_derivation.derive_request_model` via per-kind projection modules to inject `query` or `urls`.
+Agent engines (`BingAgentConfig`, …) and crawlers (`BasicConfig`, …) only implement `request_model()`; crawlers additionally keep `merge_crawler_config_and_invocation`.
 
-### 3.3 ExposableParam — search-engine only
+### 3.2 ExposableParam — search-engine only
 
 Optional **search** parameters use `ExposableParam[T]`:
 
 - **`value`** — admin default merged into every request (`null` = deactivated)
-- **`expose`** — when `true`, the parameter appears on the LLM call schema
+- **`expose`** — when `true`, the parameter appears on the LLM-facing exposed-params model
 
 ```python
 gl: ExposableParam[str | None] = ExposableParam(expose=False, value="de")  # admin-fixed
 gl: ExposableParam[str | None] = ExposableParam(expose=True, value=None)   # LLM-overridable
 ```
 
-No agent or crawler schema imports `ExposableParam` today.
+Bare scalars are **not** coerced — deployment JSON must use the explicit `{"expose": …, "value": …}` shape.
+
+### 3.3 ExposedParams — the LLM tool-schema contract
 
-### 3.4 merge_config_and_invocation — search-engine only
+`config.exposed_params_model()` returns a plain Pydantic model class. Tool-parameter models graft the knobs on by **ordinary inheritance** — no field-def plumbing, no stamped attributes:
 
 ```python
-from unique_search_proxy_core.search_engines import merge_config_and_invocation
+Exposed = config.exposed_params_model()          # GoogleExposedParams | None
+class ToolParams(ToolParamsBase, Exposed): ...   # or create_model(__base__=(...))
+
+ToolParams.model_json_schema()   # camelCase knobs, no title/default noise
+Exposed.model_fields             # the exposed field names
+```
+
+The shared `ExposedParams` base owns the single JSON-schema concern: its `model_json_schema` strips Pydantic's auto-`title` and `default` noise, so admin defaults never leak into what the LLM sees.
 
-request = merge_config_and_invocation(google_config, {"query": "EU AI Act"})
+### 3.4 merge — deployment defaults + LLM overrides
+
+```python
+request = google_config.merge({"gl": "de"}, query="EU AI Act")
 # → validated GoogleSearchRequest ready for POST /v1/search
 ```
 
-The proxy receives a flat body; it does not resolve deployment config over HTTP.
+Deactivated knobs (`value=None`) are dropped, overrides win over admin defaults, `engine` always comes from the config. The proxy receives a flat body; it does not resolve deployment config over HTTP.
 
 ### 3.5 merge_crawler_config_and_invocation — crawler only
 
@@ -145,25 +125,16 @@ flowchart TB
     subgraph core_pkg["unique_search_proxy_core"]
         Schema["schema.py"]
         Errors["errors.py"]
-        MD["model_derivation/"]
-        PP["param_policy/"]
-        Proj["projection.py\n(search + LLM projection)"]
-        AProj["agent_engines/projection.py"]
-        CProj["crawlers/projection.py"]
+        PP["param_policy/\nExposableParam · ExposedParams\nrequest bases · derive"]
         Prov["providers/schema.py"]
         SE["search_engines/"]
         AE["agent_engines/"]
         CR["crawlers/"]
     end
 
-    PP --> Proj
     PP --> SE
-    MD --> Proj
-    MD --> AProj
-    MD --> CProj
-    Proj --> SE
-    AProj --> AE
-    CProj --> CR
+    PP --> AE
+    PP --> CR
     Prov --> SE
     Prov --> CR
     SE --> Schema
@@ -176,15 +147,15 @@ flowchart TB
 |--------|----------------|
 | `schema.py` | Shared API models: `SearchResponse`, `AgentSearchResponse`, `CrawlResponse`, `WebSearchResult`, `ErrorResponse`, SSE events |
 | `errors.py` | `ProxyError` hierarchy and stable `ProxyErrorCode` enum |
-| `model_derivation/` | Shared `derive_request_model` + field/annotation helpers used by all three provider kinds |
-| `param_policy/` | `ExposableParam` — used by **search engine** config models only |
-| `projection.py` | Search-only: `build_request_model`, `build_llm_call_model`, `project_call_schema` |
-| `agent_engines/projection.py` | Agent-only: `build_agent_request_model` (injects `query`; excludes `output_schema`) |
-| `crawlers/projection.py` | Crawler-only: `build_crawl_request_model` (injects `urls`) |
+| `param_policy/exposable_param.py` | `ExposableParam` value object, factory-default merge, type introspection, OpenAPI naming |
+| `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, request union, `merge_config_and_invocation`, call-schema resolution |
-| `agent_engines/` | Agent config/request models, output schema |
-| `crawlers/` | `*Config` deployment models + derived `*CrawlRequest` HTTP bodies |
+| `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 |
+| `crawlers/` | `*Config` deployment models + derived `*CrawlRequest` bodies, `merge_crawler_config_and_invocation` |
 
 ---
 
@@ -216,21 +187,19 @@ schema = provider_config_json_schema("search_engine", "google")
 defaults = provider_default_config("search_engine", "google")
 ```
 
-### Tool manifest — LLM call schema
+### Tool manifest — exposed LLM knobs
 
 ```python
-from unique_search_proxy_core.search_engines.call_schema import resolve_search_call_schema
-
-descriptor = resolve_search_call_schema("google", config=google_config, strict=False)
-# descriptor.call_schema → JSON Schema for the LLM tool
+Exposed = google_config.exposed_params_model()   # GoogleExposedParams | None
+class ToolParams(ToolParamsBase, Exposed): ...   # graft knobs by inheritance
+ToolParams.model_json_schema()                   # camelCase, no title/default noise
 ```
 
 ### Runtime — build flat request before HTTP call
 
 ```python
-from unique_search_proxy_core.search_engines import merge_config_and_invocation
-
-body = merge_config_and_invocation(config, llm_invocation_dict)
+request = google_config.merge(llm_invocation_dict, query="EU AI Act")
+body = GoogleConfig.provider_query_params(request)  # upstream provider dict
 ```
 
 ### Shared types and errors
@@ -249,9 +218,9 @@ from unique_search_proxy_core import (
 ## 7. Features summary
 
 - Discriminated provider configs (`engine`, `crawler` Literal discriminators)
-- **Search-only:** `ExposableParam` policy, three-surface projection, LLM call schema, `merge_config_and_invocation`
-- **Agent:** config → request derivation via `model_derivation` + `build_agent_request_model`
-- **Crawl:** `*Config` + `build_crawl_request_model` (injects `urls`); `merge_crawler_config_and_invocation`
+- **Search-only:** `ExposableParam` policy; config-owned `request_model` / `exposed_params_model` / `merge` / `provider_query_params`
+- **Agent:** `BingAgentConfig.request_model()` (injects `query`; excludes `output_schema`)
+- **Crawl:** `BasicConfig.request_model()` (injects `urls`); `merge_crawler_config_and_invocation`
 - CamelCase JSON aliases on all models
 - Zero server dependencies (import-linter enforced in the client package)
 

{unique_search_proxy_core-2026.30.0.dev0 → unique_search_proxy_core-2026.30.0.dev2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique-search-proxy-core"
-version = "2026.30.0.dev0"
+version = "2026.30.0.dev2"
 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.30.0.dev0,<2026.30.0rc0",
+    "unique-toolkit[monitoring]>=2026.30.0.dev10,<2026.30.0rc0",
 
 ]
 

{unique_search_proxy_core-2026.30.0.dev0 → unique_search_proxy_core-2026.30.0.dev2}/unique_search_proxy_core/agent_engines/base.py

@@ -2,13 +2,15 @@ from __future__ import annotations
 
 from abc import ABC, abstractmethod
 from enum import StrEnum
-from typing import TYPE_CHECKING, Annotated, AsyncIterator, Generic, TypeVar
+from typing import TYPE_CHECKING, Annotated, AsyncIterator, ClassVar, Generic, TypeVar
 
 from pydantic import BaseModel, Field
 from pydantic.json_schema import SkipJsonSchema
 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.request_base import AgentRequestBase
 from unique_search_proxy_core.schema import (
     AgentSearchResponse,
     AgentSearchStreamEvent,
@@ -42,11 +44,34 @@ class AgentEngineType(StrEnum):
     VERTEXAI = "vertexai"
 
 
+#: Config fields not accepted on the agent-search request body.
+_AGENT_REQUEST_EXCLUDED_FIELDS = frozenset({"output_schema"})
+
+
 class BaseAgentEngineConfig(BaseModel, Generic[T]):
     """Shared agent-engine config; each engine narrows ``engine`` with a Literal."""
 
     model_config = camelized_model_config
 
+    #: Name of the derived request model; set by every concrete agent config.
+    _request_model_name: ClassVar[str]
+
+    @classmethod
+    def request_model(cls) -> type[BaseModel]:
+        """HTTP request body model, cached per config class.
+
+        :class:`AgentRequestBase` (required ``query``) + this config's fields,
+        excluding ``output_schema`` (server-side concern, not a request knob).
+
+        Example: ``BingAgentConfig.request_model()`` -> ``BingAgentSearchRequest``.
+        """
+        return derive_request_model(
+            cls,
+            base=AgentRequestBase,
+            name=cls._request_model_name,
+            exclude=_AGENT_REQUEST_EXCLUDED_FIELDS,
+        )
+
     engine: T
     generation_instructions: Annotated[
         str,

{unique_search_proxy_core-2026.30.0.dev0 → unique_search_proxy_core-2026.30.0.dev2}/unique_search_proxy_core/agent_engines/bing/schema.py

@@ -1,20 +1,21 @@
 from __future__ import annotations
 
-from typing import Annotated, Literal
+from typing import Annotated, ClassVar, Literal
 
-from pydantic import BaseModel, Field
+from pydantic import Field
 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.projection import build_agent_request_model
 
 
 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(
@@ -37,11 +38,7 @@ class BingAgentConfig(BaseAgentEngineConfig[Literal[AgentEngineType.BING]]):
     )
 
 
-def bing_agent_request_model() -> type[BaseModel]:
-    return build_agent_request_model(BingAgentConfig)
-
-
-BingAgentSearchRequest = bing_agent_request_model()
+BingAgentSearchRequest = BingAgentConfig.request_model()
 
 
-__all__ = ["BingAgentConfig", "BingAgentSearchRequest", "bing_agent_request_model"]
+__all__ = ["BingAgentConfig", "BingAgentSearchRequest"]

{unique_search_proxy_core-2026.30.0.dev0 → unique_search_proxy_core-2026.30.0.dev2}/unique_search_proxy_core/agent_engines/config_types.py

@@ -11,7 +11,6 @@ from unique_search_proxy_core.agent_engines.base import (
     BaseAgentEngineConfig,
 )
 from unique_search_proxy_core.agent_engines.bing.schema import BingAgentConfig
-from unique_search_proxy_core.agent_engines.projection import build_agent_request_model
 from unique_search_proxy_core.agent_engines.vertexai.schema import VertexAIAgentConfig
 
 AgentEngineConfigTypes: TypeAlias = BingAgentConfig | VertexAIAgentConfig
@@ -48,17 +47,15 @@ def get_agent_engine_config_types_from_names(
 
 
 def _union_members_from_mapping(
-    mapping: Mapping[str, type[BaseModel]],
-) -> tuple[type[BaseModel], ...]:
+    mapping: Mapping[str, type[BaseAgentEngineConfig]],
+) -> tuple[type[BaseAgentEngineConfig], ...]:
     return tuple(mapping.values())
 
 
 def build_agent_search_request_union() -> Any:
     """Discriminated union of flat ``POST /v1/agent-search`` bodies."""
     members = _union_members_from_mapping(ENGINE_NAME_TO_CONFIG)
-    request_models = tuple(
-        build_agent_request_model(config_cls) for config_cls in members
-    )
+    request_models = tuple(config_cls.request_model() for config_cls in members)
     if len(request_models) == 1:
         return request_models[0]
     return Annotated[