centive-sdk 2.2.0.dev8__py3-none-any.whl → 2.2.0.dev9__py3-none-any.whl

centive_sdk/config.py

@@ -39,6 +39,7 @@ class ClientConfig(BaseModel):
     save_messages_path: str = "/anam/save-messages"
     pause_status_path: str = "/anam/pause-status"
     events_path: str = "/anam/events"
+    kb_search_path: str = "/anam/kb-search"
     timeout_seconds: float = 10.0
     max_retries: int = 3
     initial_retry_delay: float = 0.5

centive_sdk/models/__init__.py

@@ -1,4 +1,6 @@
 from .requests import (
+    KbSearchFrame,
+    KbSearchRequest,
     ProductEventBatchRequest,
     TelemetryEvent,
     TelemetryFrame,
@@ -7,6 +9,7 @@ from .requests import (
     TriggerSessionRequest,
 )
 from .responses import (
+    KbSearchResponse,
     PauseStatusResponse,
     ProductEventIngestResponse,
     ToolMappingResponse,
@@ -14,6 +17,9 @@ from .responses import (
 )
 
 __all__ = [
+    "KbSearchRequest",
+    "KbSearchFrame",
+    "KbSearchResponse",
     "ToolMappingRequest",
     "TriggerSessionRequest",
     "TelemetryEvent",

centive_sdk/models/requests.py

@@ -1,3 +1,4 @@
+import re
 from typing import Any, Dict, List, Literal, Optional
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
@@ -28,6 +29,23 @@ class TriggerSessionRequest(BaseModel):
     current_page: Optional["TelemetryPage"] = Field(
         None, description="page the browser reports having open when it asks for a session"
     )
+    # What the browser SDK can serve in this session ("kb_search" for Aria's awaited
+    # knowledge-search tool). Centive attaches that tool only to sessions that
+    # declare it, so a customer on an older frontend never gets a tool nobody
+    # answers. Omitted when the browser declared nothing.
+    capabilities: Optional[List[str]] = Field(
+        None, max_length=16, description="capabilities the browser SDK declared for this session"
+    )
+
+    @field_validator("capabilities")
+    @classmethod
+    def _capability_tokens(cls, capabilities: Optional[List[str]]) -> Optional[List[str]]:
+        if capabilities is None:
+            return None
+        for capability in capabilities:
+            if not re.fullmatch(r"[a-z0-9_]{1,32}", capability):
+                raise ValueError("capabilities must be lowercase tokens of at most 32 characters")
+        return list(dict.fromkeys(capabilities))
 
 
 class SessionMessage(BaseModel):
@@ -96,6 +114,33 @@ class SessionEndEvent(BaseModel):
     user_id: str = Field(..., description="user ID")
 
 
+class KbSearchRequest(BaseModel):
+    """request payload for POST /anam/kb-search: grounded evidence for Aria's client search tool."""
+
+    query: str = Field(..., min_length=1, max_length=4000, description="the user's sentence or the model's query")
+    alternate_query: Optional[str] = Field(None, max_length=4000, description="optional second phrasing")
+    user_messages: List[str] = Field(default_factory=list, max_length=10, description="the user's turns so far")
+    session_id: Optional[str] = Field(None, max_length=255, description="Anam session id, so unanswered questions tie to the conversation")
+    external_user_id: Optional[str] = Field(None, max_length=255, description="end-user id, for the knowledge-gap log")
+
+    @field_validator("user_messages")
+    @classmethod
+    def _bounded_user_messages(cls, messages: List[str]) -> List[str]:
+        for message in messages:
+            if len(message) > 4000:
+                raise ValueError("user message longer than 4000 characters")
+        return messages
+
+
+class KbSearchFrame(KbSearchRequest):
+    """kb_search frame from FE SDK; answered with a kb_search_response frame carrying request_id."""
+
+    type: Literal["kb_search"] = "kb_search"
+    request_id: str = Field(..., min_length=1, max_length=128, description="client-chosen id echoed in the response")
+    session_id: Optional[str] = Field(None, description="Anam session id when known")
+    user_id: Optional[str] = Field(None, description="user id (checked against the connection identity)")
+
+
 # ---------------------------------------------------------------------------
 # Product events (page tracking). Contract: CentiveAI docs/product-events/CONTRACTS.md
 # ---------------------------------------------------------------------------

centive_sdk/models/responses.py

@@ -72,3 +72,18 @@ class ProductEventIngestResponse(BaseModel):
     # {"external_user_id", "content", "expires_at"}.
     context: list = Field(default_factory=list)
     raw: Optional[Dict[str, Any]] = None
+
+
+class KbSearchResponse(BaseModel):
+    """evidence packet from POST /anam/kb-search (see CentiveAI kb_grounded_search_service)."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    status: str
+    document_passages: list = Field(default_factory=list)
+    user_messages: list = Field(default_factory=list)
+    answer_rules: str = ""
+    source_policy: str = ""
+    queries: list = Field(default_factory=list)
+    no_evidence_policy: Optional[str] = None
+    raw: Optional[Dict[str, Any]] = None

centive_sdk/resources/async_sessions.py

@@ -9,12 +9,14 @@ from .._retry import calculate_backoff, extract_retry_after, should_retry
 from ..config import ClientConfig
 from ..exceptions import AuthError, NetworkError, RateLimitError, ServerError, ValidationError
 from ..models.requests import (
+    KbSearchRequest,
     ProductEventBatchRequest,
     SaveMessagesRequest,
     ToolMappingRequest,
     TriggerSessionRequest,
 )
 from ..models.responses import (
+    KbSearchResponse,
     PauseStatusResponse,
     ProductEventIngestResponse,
     SaveMessagesResponse,
@@ -197,6 +199,23 @@ class AsyncSessions:
             raw=data,
         )
 
+    async def kb_search(self, input: KbSearchRequest) -> KbSearchResponse:
+        """Fetches a grounded evidence packet for Aria's client search tool.
+
+        Centive searches the organization's own knowledge folders with several
+        phrasings and validates provenance server-side. Raises the usual SDK
+        errors; the caller reports failure to the persona rather than guessing.
+        """
+        url = join_url(self._config.base_url, self._config.kb_search_path)
+        headers = build_headers(self._config.api_key)
+        # One attempt, no retries: the browser stops waiting for this answer after
+        # 12 s and Anam's tool times out at 15 s, while Centive already spends up
+        # to 8 s searching. A retried 503 would arrive after both have given up.
+        # Chain: Centive 8 s < this timeout (10 s, one attempt) < frontend 12 s < Anam 15 s.
+        response = await self._make_request(url, headers, input.model_dump(exclude_none=True), max_retries=0)
+        data = response.json()
+        return KbSearchResponse(**{key: value for key, value in data.items() if key != "raw"}, raw=data)
+
     async def send_events(self, input: ProductEventBatchRequest) -> ProductEventIngestResponse:
         """Sends a batch of product events (page views) to Centive.
 
@@ -394,12 +413,17 @@ class AsyncSessions:
         ) from last_exception
 
     async def _make_request(
-        self, url: str, headers: dict, payload: dict
+        self, url: str, headers: dict, payload: dict, max_retries: Optional[int] = None
     ) -> httpx.Response:
-        """Makes an HTTP POST request with retry logic and error handling."""
+        """Makes an HTTP POST request with retry logic and error handling.
+
+        ``max_retries`` overrides the configured retry count for calls whose
+        caller has its own deadline (``kb_search`` passes 0).
+        """
         last_exception = None
+        retries = self._config.max_retries if max_retries is None else max_retries
 
-        for attempt in range(self._config.max_retries + 1):
+        for attempt in range(retries + 1):
             try:
                 response = await self._client.post(
                     url,
@@ -440,7 +464,7 @@ class AsyncSessions:
                 elif response.status_code == 429:
                     retry_after = extract_retry_after(response.headers)
 
-                    if should_retry(429, attempt, self._config.max_retries):
+                    if should_retry(429, attempt, retries):
                         delay = (
                             retry_after
                             if retry_after is not None
@@ -467,7 +491,7 @@ class AsyncSessions:
                     )
 
                 elif response.status_code >= 500:
-                    if should_retry(response.status_code, attempt, self._config.max_retries):
+                    if should_retry(response.status_code, attempt, retries):
                         delay = calculate_backoff(
                             attempt, self._config.initial_retry_delay, self._config.max_retry_delay
                         )
@@ -503,7 +527,7 @@ class AsyncSessions:
             except (httpx.TimeoutException, httpx.ConnectError, httpx.NetworkError) as e:
                 last_exception = e
 
-                if attempt < self._config.max_retries:
+                if attempt < retries:
                     delay = calculate_backoff(
                         attempt, self._config.initial_retry_delay, self._config.max_retry_delay
                     )
@@ -517,7 +541,7 @@ class AsyncSessions:
                     continue
 
         raise NetworkError(
-            f"Network error after {self._config.max_retries} retries: {str(last_exception)}"
+            f"Network error after {retries} retries: {str(last_exception)}"
         ) from last_exception
 
     def _extract_error_message(self, response: httpx.Response) -> str:

centive_sdk/resources/websocket_server.py

@@ -1,11 +1,12 @@
 import asyncio
 import inspect
 import json
+import re
 import secrets
 import time
 import warnings
 from collections import deque
-from typing import TYPE_CHECKING, Any, Callable, Deque, Dict, Optional, Set, Tuple
+from typing import TYPE_CHECKING, Any, Callable, Deque, Dict, List, Optional, Set, Tuple
 from urllib.parse import parse_qs, urlparse
 
 import websockets
@@ -13,7 +14,10 @@ from websockets.server import WebSocketServerProtocol
 
 from .._logging import safe_log, transport_logger
 from ..config import ClientConfig
+from ..exceptions import CentiveError
 from ..models.requests import (
+    KbSearchFrame,
+    KbSearchRequest,
     SaveMessagesRequest,
     SessionMessage,
     SessionMetadata,
@@ -83,6 +87,10 @@ class WebSocketServer:
         # current_page when the FE's user_trigger frame carries no page of its
         # own (older browser SDKs). Bounded by the number of live connections.
         self._connection_last_page: Dict[WebSocketServerProtocol, dict] = {}
+        # What each browser declared it can serve (e.g. "kb_search"), taken from its
+        # user_trigger frame and forwarded on every trigger-session call for the
+        # connection, so Centive attaches Aria's client tool only where it works.
+        self._connection_capabilities: Dict[WebSocketServerProtocol, List[str]] = {}
         # One Centive trigger-session call per connection start, not two: the
         # connect-time automatic trigger is held back for a grace period and
         # stands down when the client asked itself (_auto_trigger_after_grace);
@@ -610,6 +618,7 @@ class WebSocketServer:
             self._clients.discard(websocket)
             self._connection_users.pop(websocket, None)
             self._connection_last_page.pop(websocket, None)
+            self._connection_capabilities.pop(websocket, None)
             self._connection_triggered.discard(websocket)
             self._connection_trigger_inflight.pop(websocket, None)
             pending_trigger = self._connection_trigger_tasks.pop(websocket, None)
@@ -669,6 +678,10 @@ class WebSocketServer:
             await self._handle_session_end(websocket, data, client_info)
             return
 
+        if msg_type == "kb_search":
+            await self._handle_kb_search(websocket, data, client_info)
+            return
+
         if msg_type == "telemetry":
             # The raw message goes along: the frame byte cap is on what was
             # actually sent, and re-serializing `data` would not reproduce it.
@@ -684,6 +697,81 @@ class WebSocketServer:
             "message": "message received",
         }))
 
+    async def _handle_kb_search(
+        self,
+        websocket: WebSocketServerProtocol,
+        data: dict,
+        client_info: str,
+    ) -> None:
+        """serves Aria's awaited knowledge-search tool.
+
+        The FE SDK sends the user's sentence (prefetch) or the model's own query;
+        Centive answers with an evidence packet scoped to this organization. A
+        failed lookup is reported as an error frame so the persona says that
+        verification failed instead of answering from nothing.
+        """
+        request_id = data.get("request_id") if isinstance(data.get("request_id"), str) else None
+        try:
+            frame = KbSearchFrame.model_validate(data)
+        except Exception as e:  # pydantic ValidationError or wrong shape
+            await websocket.send(json.dumps({
+                "type": "kb_search_response",
+                "request_id": request_id,
+                "status": "error",
+                "error": "INVALID_KB_SEARCH",
+                "message": f"invalid kb_search frame: {str(e)[:200]}",
+            }))
+            return
+
+        if self._config.ws_auth_mode != "open":
+            if await self._enforce_frame_identity(websocket, data, frame.session_id, client_info) is None:
+                return
+
+        request = KbSearchRequest(
+            query=frame.query,
+            alternate_query=frame.alternate_query,
+            user_messages=frame.user_messages,
+            session_id=frame.session_id,
+            external_user_id=frame.user_id,
+        )
+        started = time.monotonic()
+        try:
+            response = await self._sessions.kb_search(request)
+        except CentiveError as e:
+            safe_log(
+                self._logger,
+                "warning",
+                "kb_search failed",
+                {"client": client_info, "request_id": request_id, "error": str(e)[:200]},
+            )
+            await websocket.send(json.dumps({
+                "type": "kb_search_response",
+                "request_id": frame.request_id,
+                "status": "error",
+                "error": "KB_SEARCH_UNAVAILABLE",
+                "message": "knowledge search is unavailable",
+            }))
+            return
+
+        packet = response.raw if response.raw is not None else response.model_dump(exclude={"raw"})
+        safe_log(
+            self._logger,
+            "info",
+            "kb_search served",
+            {
+                "client": client_info,
+                "request_id": frame.request_id,
+                "passages": len(packet.get("document_passages", [])),
+                "seconds": round(time.monotonic() - started, 3),
+            },
+        )
+        await websocket.send(json.dumps({
+            "type": "kb_search_response",
+            "request_id": frame.request_id,
+            "status": "success",
+            "packet": packet,
+        }))
+
     async def _enforce_frame_identity(
         self,
         websocket: WebSocketServerProtocol,
@@ -1424,6 +1512,9 @@ class WebSocketServer:
         # batcher. The frame's own page wins; the last page_view seen on this
         # connection stands in for browser SDKs that predate the field.
         current_page = self._coerce_page(data.get("page")) or self._connection_last_page.get(websocket)
+        declared = self._coerce_capabilities(data.get("capabilities"))
+        if declared:
+            self._connection_capabilities[websocket] = declared
         # The client asked itself, so the connect-time automatic trigger, if it
         # is still waiting out its grace period, has nothing left to do.
         self._connection_triggered.add(websocket)
@@ -1431,6 +1522,17 @@ class WebSocketServer:
             websocket, user_id, user_trigger, client_info, current_page=current_page
         )
 
+    @staticmethod
+    def _coerce_capabilities(value: object) -> Optional[List[str]]:
+        """Bounded list of capability tokens from a frame, or None when nothing usable was declared."""
+        if not isinstance(value, list):
+            return None
+        tokens: List[str] = []
+        for item in value[:16]:
+            if isinstance(item, str) and re.fullmatch(r"[a-z0-9_]{1,32}", item) and item not in tokens:
+                tokens.append(item)
+        return tokens or None
+
     async def _auto_trigger_after_grace(
         self, websocket: WebSocketServerProtocol, user_id: str, client_info: str
     ) -> None:
@@ -1554,6 +1656,7 @@ class WebSocketServer:
                 user_id=user_id,
                 user_trigger=user_trigger,
                 current_page=current_page,
+                capabilities=self._connection_capabilities.get(websocket),
             )
 
             response = await self._sessions.trigger_session(request)

{centive_sdk-2.2.0.dev8.dist-info → centive_sdk-2.2.0.dev9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: centive-sdk
-Version: 2.2.0.dev8
+Version: 2.2.0.dev9
 Summary: Python SDK for Centive backend integration
 Project-URL: Homepage, https://github.com/TheAgenticAI/centive-backend-sdk
 Project-URL: Repository, https://github.com/TheAgenticAI/centive-backend-sdk

{centive_sdk-2.2.0.dev8.dist-info → centive_sdk-2.2.0.dev9.dist-info}/RECORD

@@ -4,20 +4,20 @@ centive_sdk/_logging.py,sha256=z8Kdi4vJdko0nkMeySGSHwPkEB2E7ucklc9FeJCbyOw,3518
 centive_sdk/_retry.py,sha256=Q1cIFZyimj0RS4x14FEOseqpORCSydvJyzGiIPfDn7E,1755
 centive_sdk/async_client.py,sha256=RRoCJrvdeLwQz5UJv2EjmlgTq7vntSV9ELMWHyNwJ5I,9355
 centive_sdk/client.py,sha256=Evtsng8cqqRSoV54MI2IKbEW1q0vPOkxlz9zM0evH7k,3249
-centive_sdk/config.py,sha256=1GoHkwJebL1HknSa-y4oFhxDAaG0boq0JY0csNV-pfE,6612
+centive_sdk/config.py,sha256=V1ZZN6_oZyilR-JUBglT776AcIy4hZQvLBnH7gpvN-o,6656
 centive_sdk/exceptions.py,sha256=wFy-hU0TJ0dHa6TEDI7FIQu9Lbg5aMeWxW9E-IMMUbI,1841
 centive_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-centive_sdk/models/__init__.py,sha256=-ledNpbOi1Q14ELhvlDbGPF37N3yv5XJ-QsH2I6UMVQ,598
-centive_sdk/models/requests.py,sha256=_SqXf-8wejbAVQOMf6Lk3W0q3F3yu401mFvB8dMhwp4,7736
-centive_sdk/models/responses.py,sha256=zCYPB0aL2DXn-z0Febkuxo3DdZ_5sdpdGy2Jtf8Ubs8,2519
+centive_sdk/models/__init__.py,sha256=kvQ8WmLSdbLHOlJ95H7ZSm4Fe_E9NN7LK34BHl4_Z_4,728
+centive_sdk/models/requests.py,sha256=O1MnGWNj7-vdvu95Km1WrK7Z0TF6KHTeBZO1I9tCChc,10179
+centive_sdk/models/responses.py,sha256=T8xpw6N6Ap-UplXyBCxCtdXbBV0H8UjV9ZdxmxhXOAs,3039
 centive_sdk/resources/__init__.py,sha256=GLutz38X4F4FwPfSZy35EkWTV7l7t9RgcBKwXmz2X_Y,179
-centive_sdk/resources/async_sessions.py,sha256=m0_gj2wLabs3BTe6rZuo9WGgSwEMJLmdKW8_s4T7KRM,21500
+centive_sdk/resources/async_sessions.py,sha256=bdscJFj_nlqe0FZD3rXjai4IwlfH5I6VFFk4kXIzRwI,22841
 centive_sdk/resources/async_telemetry.py,sha256=wT12g9rG2dp_ml5YpAYCxobLlhfcsyy-LHty4bwwFZI,2431
 centive_sdk/resources/message_accumulator.py,sha256=Or3sMGkXG9upeQ9sm8YWL_V5vvsxtnE9tu52VBUUGgY,19261
 centive_sdk/resources/sessions.py,sha256=Ipg4bpmpejA5WoALbT49ah0c3I7x4OgPn9tSmfW8JAw,16741
 centive_sdk/resources/telemetry_batcher.py,sha256=OkOv2Iir6E_9mdtAKvelol3RaveGSlH-ckIoE2cQYCc,14629
-centive_sdk/resources/websocket_server.py,sha256=RTkM1YyD7afNWs4KpoboCo-NI2TFgk8IkzaH0KAKR5A,66518
-centive_sdk-2.2.0.dev8.dist-info/METADATA,sha256=5DM9IFShg7CIqzt5jQ8goRocZXmOCJtELTUWVUgVSZY,36427
-centive_sdk-2.2.0.dev8.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-centive_sdk-2.2.0.dev8.dist-info/licenses/LICENSE,sha256=9dFibPr7z9srhWwd35lQL2MX1Kx2qivEZdVQb9L8Q-Q,1064
-centive_sdk-2.2.0.dev8.dist-info/RECORD,,
+centive_sdk/resources/websocket_server.py,sha256=_U_PPeB-_fLyxQVPC0SlV5V0AD8ECULYdbeCkLLSyy0,70723
+centive_sdk-2.2.0.dev9.dist-info/METADATA,sha256=cDNuDwvyAHMVPJML42egvWLSwOUyCvPsOYz_pMMKj6o,36427
+centive_sdk-2.2.0.dev9.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+centive_sdk-2.2.0.dev9.dist-info/licenses/LICENSE,sha256=9dFibPr7z9srhWwd35lQL2MX1Kx2qivEZdVQb9L8Q-Q,1064
+centive_sdk-2.2.0.dev9.dist-info/RECORD,,

{centive_sdk-2.2.0.dev8.dist-info → centive_sdk-2.2.0.dev9.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.0
+Generator: hatchling 1.32.3
 Root-Is-Purelib: true
 Tag: py3-none-any