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

{unique_search_proxy_core-2026.44.0.dev10 → 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.dev10
+Version: 2026.44.0.dev11
 Summary: Shared Pydantic types for the Unique Search Proxy API
 Author: ThePhilAz
 Author-email: ThePhilAz <rami.azouz@philico.com>

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

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

{unique_search_proxy_core-2026.44.0.dev10 → 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.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"]