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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-search-proxy-core
-Version: 2026.44.0.dev9
+Version: 2026.44.0.dev11
 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.dev11}/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.dev11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique-search-proxy-core"
-version = "2026.44.0.dev9"
+version = "2026.44.0.dev11"
 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.dev11}/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.dev11}/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.dev11}/unique_search_proxy_core/context.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import json
 import logging
 from collections.abc import Mapping
+from enum import StrEnum
 from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
@@ -13,6 +14,9 @@ COMPANY_ID_HEADER = "x-unique-company-id"
 USER_ID_HEADER = "x-unique-user-id"
 CHAT_ID_HEADER = "x-unique-chat-id"
 USER_METADATA_HEADER = "x-unique-user-metadata"
+ENTRY_POINT_HEADER = "x-unique-entry-point"
+MESSAGE_ID_HEADER = "x-unique-message-id"
+SERVICE_ID_HEADER = "x-service-id"
 
 _CONTEXT_HEADER_FIELDS: tuple[tuple[str, str], ...] = (
     ("company_id", COMPANY_ID_HEADER),
@@ -23,6 +27,23 @@ _CONTEXT_HEADER_FIELDS: tuple[tuple[str, str], ...] = (
 _LOGGER = logging.getLogger(__name__)
 
 
+class EntryPoint(StrEnum):
+    """Service where a search request entered the platform."""
+
+    CHAT_TOOL = "chat_tool"
+    PUBLIC_API = "public_api"
+    CONDUCT = "conduct"
+    UNIQUE_API = "unique_api"
+    GRAPHQL = "graphql"
+    DEEP_RESEARCH = "deep_research"
+    WEB_SEARCH_SERVICE = "web_search_service"
+    UNKNOWN = "unknown"
+
+    @classmethod
+    def _missing_(cls, value: object) -> EntryPoint:
+        return cls.UNKNOWN
+
+
 class RequestContext(BaseModel):
     """Caller identity for search-proxy requests."""
 
@@ -31,8 +52,29 @@ class RequestContext(BaseModel):
     company_id: str
     user_id: str
     chat_id: str
+    entry_point: EntryPoint = EntryPoint.UNKNOWN
+    # Calling service from ``x-service-id``; logged only, never enforced.
+    caller: str = "unknown"
+    # Reserved for analytics; optional until callers send it.
+    message_id: str | None = None
     user_metadata: dict[str, Any] = Field(default_factory=dict)
 
+    @property
+    def invalid_identity_headers(self) -> list[str]:
+        """Identity headers whose value is not a numeric id (``local``, blank, junk)."""
+        return [
+            header_name
+            for header_name, value in (
+                (COMPANY_ID_HEADER, self.company_id),
+                (USER_ID_HEADER, self.user_id),
+            )
+            if not (value.isascii() and value.isdecimal())
+        ]
+
+    @property
+    def is_attributed(self) -> bool:
+        return not self.invalid_identity_headers
+
     def to_headers(self) -> dict[str, str]:
         """Serialize context to the canonical HTTP header names."""
         headers = {
@@ -40,6 +82,10 @@ class RequestContext(BaseModel):
             USER_ID_HEADER: self.user_id,
             CHAT_ID_HEADER: self.chat_id,
         }
+        if self.entry_point is not EntryPoint.UNKNOWN:
+            headers[ENTRY_POINT_HEADER] = self.entry_point.value
+        if self.message_id:
+            headers[MESSAGE_ID_HEADER] = self.message_id
         if self.user_metadata:
             # ``ensure_ascii`` keeps the value latin-1 encodable, which HTTP
             # headers require.
@@ -78,6 +124,13 @@ class RequestContext(BaseModel):
                 values[field_name] = str(raw)
         return cls(
             **values,
+            entry_point=normalized.get(
+                ENTRY_POINT_HEADER.lower(),
+                fallback.entry_point,
+            ),
+            caller=normalized.get(SERVICE_ID_HEADER) or fallback.caller,
+            message_id=str(normalized.get(MESSAGE_ID_HEADER) or "").strip()
+            or fallback.message_id,
             user_metadata=_parse_user_metadata(
                 normalized.get(USER_METADATA_HEADER),
                 fallback=fallback.user_metadata,
@@ -119,8 +172,12 @@ LOCAL_REQUEST_CONTEXT = RequestContext(
 __all__ = [
     "CHAT_ID_HEADER",
     "COMPANY_ID_HEADER",
+    "ENTRY_POINT_HEADER",
+    "EntryPoint",
     "LOCAL_REQUEST_CONTEXT",
+    "MESSAGE_ID_HEADER",
     "RequestContext",
+    "SERVICE_ID_HEADER",
     "USER_ID_HEADER",
     "USER_METADATA_HEADER",
 ]

{unique_search_proxy_core-2026.44.0.dev9 → unique_search_proxy_core-2026.44.0.dev11}/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")
 
 

unique_search_proxy_core-2026.44.0.dev11/unique_search_proxy_core/usage.py

@@ -0,0 +1,45 @@
+"""Per-request usage record emitted as a structured log line."""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from typing import Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+from unique_search_proxy_core.context import EntryPoint
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class UsageRecord(BaseModel):
+    """Who triggered a billable provider operation. Never holds queries or URLs."""
+
+    event: Literal["web_search_usage"] = "web_search_usage"
+    # Unique per usage line, not joinable to other log lines yet. Take the trace id
+    # from unique_toolkit.monitoring.tracing once the proxy adopts tracing.
+    request_id: str = Field(default_factory=lambda: str(uuid4()))
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(UTC))
+    company_id: str
+    user_id: str
+    chat_id: str
+    message_id: str | None = None
+    entry_point: EntryPoint
+    caller: str
+    endpoint: Literal["search", "agent_search", "crawl"]
+    provider: str
+    units: int
+    # Results requested on /v1/search; Google and Brave page, so one unit can be several calls.
+    fetch_size: int | None = None
+    status: Literal["success", "error"]
+    duration_ms: int
+
+
+def record_usage(record: UsageRecord) -> None:
+    """Write ``record`` as one JSON log line."""
+    _LOGGER.info(record.model_dump_json())
+
+
+__all__ = ["UsageRecord", "record_usage"]