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

{unique_search_proxy_core-2026.44.0.dev8 → 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.dev8
+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.dev8 → 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.dev8 → unique_search_proxy_core-2026.44.0.dev10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique-search-proxy-core"
-version = "2026.44.0.dev8"
+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.dev8 → 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.dev8 → 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.dev8 → unique_search_proxy_core-2026.44.0.dev10}/unique_search_proxy_core/http_client/__init__.py

@@ -19,6 +19,7 @@ from unique_search_proxy_core.http_client.credentials import (
 )
 from unique_search_proxy_core.http_client.response_cap import (
     MAX_RESPONSE_BYTES_EXTENSION,
+    ByteBudget,
     install_response_size_cap,
     read_capped_body,
     response_size_cap_hook,
@@ -36,6 +37,7 @@ from unique_search_proxy_core.http_client.settings import (
 
 __all__ = [
     "MAX_RESPONSE_BYTES_EXTENSION",
+    "ByteBudget",
     "DirectRoute",
     "EgressRoute",
     "HttpClientRegistry",

{unique_search_proxy_core-2026.44.0.dev8 → unique_search_proxy_core-2026.44.0.dev10}/unique_search_proxy_core/http_client/response_cap.py

@@ -115,10 +115,45 @@ def install_response_size_cap(
     return client
 
 
+class ByteBudget:
+    """Shared allowance of decoded body bytes across several responses.
+
+    Bounds what one caller keeps in memory at once, e.g. every page of a crawl
+    request, which a per-response limit alone cannot do. Not thread-safe; share
+    it only between tasks of one event loop.
+    """
+
+    def __init__(self, max_bytes: int) -> None:
+        self._max_bytes = max_bytes
+        self._used = 0
+
+    @property
+    def exhausted(self) -> bool:
+        return self._used >= self._max_bytes
+
+    def consume(self, num_bytes: int) -> None:
+        """Reserve bytes, raising once the budget is exceeded.
+
+        Raises:
+            ResponseTooLargeError: When the reservation exceeds the budget.
+        """
+        self._used += num_bytes
+        if self._used > self._max_bytes:
+            raise ResponseTooLargeError(
+                f"Combined upstream responses exceeded the {self._max_bytes} "
+                "byte budget",
+            )
+
+    def release(self, num_bytes: int) -> None:
+        """Return bytes from a body that was discarded."""
+        self._used = max(0, self._used - num_bytes)
+
+
 async def read_capped_body(
     response: httpx.Response,
     *,
     max_bytes: int | None,
+    budget: ByteBudget | None = None,
 ) -> bytes:
     """Read a streamed response body, limiting its decompressed size.
 
@@ -129,25 +164,38 @@ async def read_capped_body(
         response (httpx.Response): Response opened with ``stream=True``.
         max_bytes (int | None): Largest decoded body allowed. ``None`` reads
             the whole body.
+        budget (ByteBudget | None): Shared budget the body is charged against.
+            Bytes are returned to it when the read fails.
 
     Returns:
         bytes: The decoded response body.
 
     Raises:
-        ResponseTooLargeError: When the decoded body exceeds ``max_bytes``.
+        ResponseTooLargeError: When the decoded body exceeds ``max_bytes`` or
+            the shared budget.
     """
     chunks: list[bytes] = []
     received = 0
-    async for chunk in response.aiter_bytes():
-        received += len(chunk)
-        if max_bytes is not None and received > max_bytes:
-            raise ResponseTooLargeError.for_limit(max_bytes)
-        chunks.append(chunk)
+    charged = 0
+    try:
+        async for chunk in response.aiter_bytes():
+            received += len(chunk)
+            if max_bytes is not None and received > max_bytes:
+                raise ResponseTooLargeError.for_limit(max_bytes)
+            if budget is not None:
+                charged += len(chunk)
+                budget.consume(len(chunk))
+            chunks.append(chunk)
+    except BaseException:
+        if budget is not None:
+            budget.release(charged)
+        raise
     return b"".join(chunks)
 
 
 __all__ = [
     "MAX_RESPONSE_BYTES_EXTENSION",
+    "ByteBudget",
     "ResponseHook",
     "install_response_size_cap",
     "read_capped_body",

{unique_search_proxy_core-2026.44.0.dev8 → 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")