unique-search-proxy-core 2026.44.0.dev9__tar.gz → 2026.44.0.dev10__tar.gz

{unique_search_proxy_core-2026.44.0.dev9 → unique_search_proxy_core-2026.44.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-search-proxy-core
-Version: 2026.44.0.dev9
+Version: 2026.44.0.dev10
 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.44.0.dev9,<2026.44.0rc0
+Requires-Dist: unique-toolkit[monitoring]>=2026.44.0.dev10,<2026.44.0rc0
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 
@@ -150,7 +150,7 @@ flowchart TB
 
 | Module | Responsibility |
 |--------|----------------|
-| `schema.py` | Shared API models: `SearchResponse`, `AgentSearchResponse`, `CrawlResponse`, `WebSearchResult`, `ErrorResponse`, SSE events |
+| `schema.py` | Shared API models: `SearchResponse`, `AgentSearchResponse` (+ `AnswerSpanCitation`), `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 |

{unique_search_proxy_core-2026.44.0.dev9 → unique_search_proxy_core-2026.44.0.dev10}/README.md

@@ -136,7 +136,7 @@ flowchart TB
 
 | Module | Responsibility |
 |--------|----------------|
-| `schema.py` | Shared API models: `SearchResponse`, `AgentSearchResponse`, `CrawlResponse`, `WebSearchResult`, `ErrorResponse`, SSE events |
+| `schema.py` | Shared API models: `SearchResponse`, `AgentSearchResponse` (+ `AnswerSpanCitation`), `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 |

{unique_search_proxy_core-2026.44.0.dev9 → unique_search_proxy_core-2026.44.0.dev10}/pyproject.toml

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

{unique_search_proxy_core-2026.44.0.dev9 → unique_search_proxy_core-2026.44.0.dev10}/unique_search_proxy_core/__init__.py

@@ -19,6 +19,8 @@ from unique_search_proxy_core.errors import (
     ValidationProxyError,
 )
 from unique_search_proxy_core.schema import (
+    AgentSearchResponse,
+    AnswerSpanCitation,
     CrawlResponse,
     ErrorDetail,
     ErrorResponse,
@@ -35,6 +37,8 @@ __all__ = [
     "RequestContext",
     "USER_ID_HEADER",
     "BadRequestProxyError",
+    "AgentSearchResponse",
+    "AnswerSpanCitation",
     "CrawlResponse",
     "EmptySearchResultsError",
     "EngineNotConfiguredError",

{unique_search_proxy_core-2026.44.0.dev9 → unique_search_proxy_core-2026.44.0.dev10}/unique_search_proxy_core/agent_engines/base.py

@@ -112,8 +112,9 @@ class AgentSearchEngine(ABC, Generic[AgentRequestT]):
     """Agent (grounded) search engine contract for v1 providers.
 
     Implementations call the upstream agent/grounding provider and return opaque
-    ``answer`` text plus ``raw`` provider payload. Content resolution is left to
-    consumers; this layer stays provider-egress only.
+    ``answer`` text, the ``citations`` the provider attached to it, and ``raw``
+    provider payload. Content resolution is left to consumers; this layer stays
+    provider-egress only.
     """
 
     engine_id: str

{unique_search_proxy_core-2026.44.0.dev9 → unique_search_proxy_core-2026.44.0.dev10}/unique_search_proxy_core/schema.py

@@ -186,11 +186,42 @@ class SearchResponse(BaseModel):
     curated: list[WebSearchResult]
 
 
+class AnswerSpanCitation(BaseModel):
+    """A source cited at a specific span of the answer text.
+
+    Grounding with Bing Search reports these as ``url_citation`` annotations:
+    the agent writes a marker such as ``【4:0†source】`` into its answer, and
+    Foundry attaches the source to that marker's character span.
+    """
+
+    model_config = camelized_model_config
+
+    url: str = Field(description="URL of the cited source")
+    title: str | None = Field(
+        default=None,
+        description="Title of the cited source",
+    )
+    marker: str = Field(
+        description="Answer text between start_index and end_index",
+    )
+    start_index: int = Field(
+        description="Character offset in the answer where the marker starts",
+    )
+    end_index: int = Field(
+        description="Character offset in the answer just past the marker",
+    )
+    output_item_id: str | None = Field(
+        default=None,
+        description="Output item the citation is attached to, if the provider reports one",
+    )
+
+
 class AgentSearchResponse(BaseModel):
     """Result of an agent-based (grounded) search.
 
-    Thin egress contract: opaque ``answer`` text from the provider plus ``raw``
-    for debugging. Consumers interpret ``answer`` (JSON parsing, citations, etc.).
+    Thin egress contract: opaque ``answer`` text from the provider, the
+    citations the provider attached to it, and ``raw`` for debugging. Consumers
+    interpret ``answer`` (JSON parsing, mapping citations, etc.).
     """
 
     model_config = camelized_model_config
@@ -201,6 +232,13 @@ class AgentSearchResponse(BaseModel):
         default="",
         description="Agent response text as returned by the provider (opaque to the proxy)",
     )
+    citations: list[AnswerSpanCitation] = Field(
+        default_factory=list,
+        description=(
+            "Sources cited in the answer. Only Grounding with Bing Search "
+            "reports citations; other engines return an empty list."
+        ),
+    )
     raw: Any = Field(default=None, description="Opaque provider payload")