centive-sdk 2.2.0.dev6__tar.gz → 2.2.0.dev9__tar.gz

{centive_sdk-2.2.0.dev6 → centive_sdk-2.2.0.dev9}/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project are documented in this file.
 
+## Unreleased
+
+### Added
+
+- **Grounded knowledge search for Aria's client tool.** A new websocket frame,
+  `type: "kb_search"` (`request_id`, `query`, optional `alternate_query`,
+  `user_messages`), is forwarded to Centive's `POST /anam/kb-search`, which
+  searches only this organization's knowledge folders with several phrasings
+  and returns an evidence packet. The server answers with
+  `type: "kb_search_response"` carrying the same `request_id` and either
+  `status: "success", packet` or `status: "error", error` (`INVALID_KB_SEARCH`,
+  `KB_SEARCH_UNAVAILABLE`). In token mode the frame is bound to the connection's
+  user like every other frame. A failed lookup is reported, never guessed.
+- `AsyncSessions.kb_search(KbSearchRequest) -> KbSearchResponse` and
+  `ClientConfig.kb_search_path` (default `/anam/kb-search`).
+- The `kb_search` frame's `session_id` and `user_id` are forwarded to Centive as
+  `session_id` / `external_user_id` on `KbSearchRequest`, so a question the
+  documentation could not answer is logged against the conversation in the
+  organization's knowledge-gap log.
+- The browser's declared `capabilities` (e.g. `["kb_search"]`) on the `user_trigger`
+  frame are validated, remembered for the connection and forwarded on every
+  trigger-session call as `TriggerSessionRequest.capabilities`, so Centive attaches
+  Aria's client search tool only to sessions whose frontend can serve it.
+
+### Changed
+
+- `AsyncSessions.kb_search` makes a single attempt (no retries). Centive spends up to
+  8 s searching, the browser stops waiting at 12 s and Anam's tool times out at 15 s,
+  so a retried 503 could only arrive after everyone had given up. `_make_request`
+  accepts a per-call `max_retries` for this.
+
 ## v2.2.0
 
 Unreleased (branch `feature/user-page-tracking`, merged with the v2.1.0
@@ -40,6 +71,15 @@ Centive batcher and the host callback).
 
 ### Behavior
 
+- **One trigger-session call per connection start.** The connect-time
+  automatic trigger now waits `session_trigger_grace_seconds` (default 0.5)
+  and stands down when the browser SDK has asked for a session itself in the
+  meantime, which it does the moment its socket opens, with the page it has
+  open. Before, both reached Centive within milliseconds: two Anam tokens per
+  connection and an opening prompt built from the page-less request. A request
+  that lands while another trigger for the same connection is in flight waits
+  for it and receives the same frame. Set the grace to 0 for the old behaviour.
+
 - The telemetry queue has its own circuit breaker, so a failing events
   endpoint cannot stop transcript saves (and vice versa).
 - The queue is bounded (`telemetry_max_queue_events`, default 5000); when full

{centive_sdk-2.2.0.dev6 → centive_sdk-2.2.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: centive-sdk
-Version: 2.2.0.dev6
+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.dev6 → centive_sdk-2.2.0.dev9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "centive-sdk"
-version = "2.2.0.dev6"
+version = "2.2.0.dev9"
 description = "Python SDK for Centive backend integration"
 readme = "README.md"
 license = "MIT"

{centive_sdk-2.2.0.dev6 → centive_sdk-2.2.0.dev9}/src/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
@@ -83,6 +84,12 @@ class ClientConfig(BaseModel):
     max_session_id_chars: int = 200
     # Concurrent websocket connections accepted per user.
     max_connections_per_user: int = 5
+    # How long the connect-time session trigger waits for the browser SDK to
+    # ask for a session itself before firing. Browser SDKs since 1.0 ask the
+    # moment the socket opens, and their request is the one that carries the
+    # page the user has open; firing first meant two Centive calls and two Anam
+    # tokens per connection. 0 restores the old immediate trigger.
+    session_trigger_grace_seconds: float = 0.5
 
     # Page-telemetry frames (type="telemetry") from the FE SDK. These mirror the
     # aria-sdk producer's own caps (MAX_EVENTS_PER_FRAME, MAX_FRAME_BYTES,

{centive_sdk-2.2.0.dev6 → centive_sdk-2.2.0.dev9}/src/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-2.2.0.dev6 → centive_sdk-2.2.0.dev9}/src/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-2.2.0.dev6 → centive_sdk-2.2.0.dev9}/src/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-2.2.0.dev6 → centive_sdk-2.2.0.dev9}/src/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-2.2.0.dev6 → centive_sdk-2.2.0.dev9}/src/centive_sdk/resources/websocket_server.py

@@ -1,10 +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
@@ -12,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,
@@ -82,6 +87,18 @@ 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);
+        # a request that lands while another trigger for the same connection is
+        # in flight waits for it and receives the same frame.
+        self._connection_trigger_tasks: Dict[WebSocketServerProtocol, asyncio.Task] = {}
+        self._connection_triggered: set = set()
+        self._connection_trigger_inflight: Dict[WebSocketServerProtocol, asyncio.Future] = {}
         # Every session key touched by a connection, so a disconnect saves all of
         # them rather than only the most recent one.
         self._connection_sessions: Dict[WebSocketServerProtocol, Set[str]] = {}
@@ -569,7 +586,9 @@ class WebSocketServer:
                 {"client": client_info, "user_id": user_id},
             )
 
-            await self._trigger_and_emit(websocket, user_id, None, client_info)
+            self._connection_trigger_tasks[websocket] = asyncio.create_task(
+                self._auto_trigger_after_grace(websocket, user_id, client_info)
+            )
 
         try:
             async for message in websocket:
@@ -599,6 +618,12 @@ 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)
+            if pending_trigger is not None:
+                pending_trigger.cancel()
             self._telemetry_rate.forget(websocket)
             session_keys = self._connection_sessions.pop(websocket, set())
 
@@ -653,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.
@@ -668,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,
@@ -1408,10 +1512,61 @@ 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)
         await self._trigger_and_emit(
             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:
+        """The connect-time session trigger, held back briefly.
+
+        Browser SDKs since 1.0 ask for a token themselves the moment the socket
+        opens, and that request is the one that carries the page the user has
+        open. Firing the automatic trigger first (and before the message loop
+        even started reading) meant two Centive calls and two Anam tokens per
+        connection, with the opening prompt built from the page-less one. Now
+        the automatic trigger waits config.session_trigger_grace_seconds and
+        stands down when the client has asked in the meantime. A client that
+        never asks (older SDKs, custom frontends) still gets its session, half
+        a second later.
+        """
+        try:
+            grace = max(0.0, float(self._config.session_trigger_grace_seconds or 0))
+            if grace:
+                await asyncio.sleep(grace)
+            if websocket in self._connection_triggered or not self._is_live(websocket):
+                safe_log(
+                    self._logger,
+                    "info",
+                    "automatic session trigger stood down",
+                    {"client": client_info, "user_id": user_id,
+                     "reason": "client asked" if websocket in self._connection_triggered else "connection gone"},
+                )
+                return
+            await self._trigger_and_emit(websocket, user_id, None, client_info)
+        except asyncio.CancelledError:
+            return
+        finally:
+            self._connection_trigger_tasks.pop(websocket, None)
+
     def _remember_page(self, websocket: WebSocketServerProtocol, events: Any) -> None:
         """Keeps the newest page_view's page for this connection (see _handle_user_trigger)."""
         if not isinstance(events, list):
@@ -1444,7 +1599,50 @@ class WebSocketServer:
         client_info: str,
         current_page: Optional[dict] = None,
     ) -> None:
-        """calls trigger_session API and emits response to FE."""
+        """calls trigger_session API and emits response to FE.
+
+        Two triggers for the same connection at once (the automatic one mid
+        call when the client's own request lands) share one Centive call: the
+        second waits for the first and re-emits its frame.
+        """
+        inflight = self._connection_trigger_inflight.get(websocket)
+        if inflight is not None:
+            safe_log(
+                self._logger,
+                "info",
+                "session trigger coalesced with one in flight",
+                {"client": client_info, "user_id": user_id},
+            )
+            try:
+                frame = await asyncio.shield(inflight)
+            except Exception:  # noqa: BLE001 - the first caller already reported it
+                frame = None
+            if frame is not None:
+                try:
+                    await websocket.send(frame)
+                except Exception:  # noqa: BLE001
+                    pass
+            return
+
+        done: asyncio.Future = asyncio.get_running_loop().create_future()
+        self._connection_trigger_inflight[websocket] = done
+        emitted: Optional[str] = None
+        try:
+            emitted = await self._trigger_once(websocket, user_id, user_trigger, client_info, current_page)
+        finally:
+            self._connection_trigger_inflight.pop(websocket, None)
+            if not done.done():
+                done.set_result(emitted)
+
+    async def _trigger_once(
+        self,
+        websocket: WebSocketServerProtocol,
+        user_id: str,
+        user_trigger: Optional[bool],
+        client_info: str,
+        current_page: Optional[dict],
+    ) -> Optional[str]:
+        """One trigger-session call. Returns the success frame it sent, if any."""
         safe_log(
             self._logger,
             "info",
@@ -1458,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)
@@ -1481,7 +1680,7 @@ class WebSocketServer:
                     "message": "failed to trigger session",
                     "error": "UPSTREAM_TRIGGER_FAILED",
                 }))
-                return
+                return None
 
             response_data = {
                 "status": response.status,
@@ -1490,7 +1689,8 @@ class WebSocketServer:
                 "time_taken": response.time_taken,
             }
 
-            await websocket.send(json.dumps(response_data))
+            frame = json.dumps(response_data)
+            await websocket.send(frame)
 
             safe_log(
                 self._logger,
@@ -1503,6 +1703,7 @@ class WebSocketServer:
                     "has_session_data": response.session_data is not None,
                 },
             )
+            return frame
 
         except Exception as e:
             # Generic on the wire, detailed in the server's own logs: upstream

centive_sdk-2.2.0.dev9/tests/test_websocket_capabilities.py

@@ -0,0 +1,80 @@
+"""The browser's declared capabilities ride the user_trigger frame and are forwarded on every
+trigger-session call for that connection; malformed tokens are dropped, nothing declared means the
+field is absent so Centive keeps Anam's built-in tools."""
+
+import asyncio
+import json
+
+import httpx
+import pytest
+import respx
+import websockets
+
+from centive_sdk import AsyncCentiveClient
+
+WS_PORT = 18791
+
+
+@pytest.fixture
+def trigger_session_response():
+    return {
+        "status": "success",
+        "message": "Session created successfully",
+        "session_data": {"session_id": "sess_123", "token": "tok_abc"},
+        "time_taken": 0.1,
+    }
+
+
+async def _connect(client, base_url, trigger_session_response, pause_status_not_paused_response):
+    respx.get(f"{base_url}/anam/pause-status/user_123").mock(return_value=httpx.Response(200, json=pause_status_not_paused_response))
+    route = respx.post(f"{base_url}/anam/trigger-session").mock(return_value=httpx.Response(200, json=trigger_session_response))
+    token = await client.initialize_websocket(user_id="user_123", port=WS_PORT)
+    ws = await websockets.connect(f"ws://localhost:{WS_PORT}/ws?token={token}")
+    first = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+    assert first["status"] == "success"  # connect-time session frame
+    return ws, route
+
+
+async def _trigger(ws, frame):
+    await ws.send(json.dumps(frame))
+    for _ in range(5):
+        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+        if data.get("status") == "success" and "session_data" in data:
+            return data
+    raise AssertionError("no session frame received")
+
+
+def _last_body(route):
+    return json.loads(route.calls[-1].request.content)
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_declared_capabilities_are_forwarded_and_remembered(base_url, api_key, trigger_session_response, pause_status_not_paused_response):
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    ws, route = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    try:
+        assert "capabilities" not in _last_body(route)  # the automatic connect-time trigger declared nothing
+        await _trigger(ws, {"user_trigger": True, "user_id": "user_123", "capabilities": ["kb_search", "Bad Token!", 42, "kb_search"]})
+        assert _last_body(route)["capabilities"] == ["kb_search"]
+        # A later trigger on the same connection (a token refresh) keeps the declaration.
+        await _trigger(ws, {"user_trigger": True, "user_id": "user_123"})
+        assert _last_body(route)["capabilities"] == ["kb_search"]
+    finally:
+        await ws.close()
+        await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_nothing_usable_declared_means_no_capabilities_field(base_url, api_key, trigger_session_response, pause_status_not_paused_response):
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    ws, route = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    try:
+        await _trigger(ws, {"user_trigger": True, "user_id": "user_123", "capabilities": ["Not A Token"]})
+        assert "capabilities" not in _last_body(route)
+        await _trigger(ws, {"user_trigger": True, "user_id": "user_123", "capabilities": "kb_search"})  # wrong shape
+        assert "capabilities" not in _last_body(route)
+    finally:
+        await ws.close()
+        await client.aclose()

centive_sdk-2.2.0.dev9/tests/test_websocket_kb_search.py

@@ -0,0 +1,145 @@
+"""kb_search frames: served from Centive's /anam/kb-search, scoped to the connection's user,
+and reported as an error frame (never a guess) when the lookup fails."""
+
+import asyncio
+import json
+
+import httpx
+import pytest
+import respx
+import websockets
+
+from centive_sdk import AsyncCentiveClient
+
+WS_PORT = 18790
+
+
+@pytest.fixture
+def trigger_session_response():
+    return {
+        "status": "success",
+        "message": "Session created successfully",
+        "session_data": {"session_id": "sess_123", "token": "tok_abc"},
+        "time_taken": 0.1,
+    }
+
+
+def ws_url(token):
+    return f"ws://localhost:{WS_PORT}/ws?token={token}"
+
+
+PACKET = {
+    "status": "sources_found",
+    "document_passages": [{"document_id": "d1", "chunk_index": 0, "folder_id": "f", "filename": "faqs.md",
+                           "content": "Invite them from Team, Invite Member.", "score": 0.7, "sha256": "h"}],
+    "user_messages": [{"turn_index": 0, "text": "how do I invite", "origin": "user_message", "verified_by_document": False}],
+    "answer_rules": "rules", "source_policy": "policy", "queries": ["how do I invite", "invite"],
+}
+
+
+async def _connect(client, base_url, trigger_session_response, pause_status_not_paused_response):
+    respx.get(f"{base_url}/anam/pause-status/user_123").mock(return_value=httpx.Response(200, json=pause_status_not_paused_response))
+    respx.post(f"{base_url}/anam/trigger-session").mock(return_value=httpx.Response(200, json=trigger_session_response))
+    token = await client.initialize_websocket(user_id="user_123", port=WS_PORT)
+    ws = await websockets.connect(ws_url(token))
+    first = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+    assert first["status"] == "success"  # connect-time session frame
+    return ws
+
+
+async def _recv_type(ws, frame_type):
+    for _ in range(5):
+        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+        if data.get("type") == frame_type:
+            return data
+    raise AssertionError(f"no {frame_type} frame received")
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_kb_search_frame_is_served_from_centive(base_url, api_key, trigger_session_response, pause_status_not_paused_response):
+    route = respx.post(f"{base_url}/anam/kb-search").mock(return_value=httpx.Response(200, json=PACKET))
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    ws = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    try:
+        await ws.send(json.dumps({"type": "kb_search", "request_id": "r1", "user_id": "user_123", "session_id": "sess_123",
+                                  "query": "how do I invite", "alternate_query": "invite member", "user_messages": ["how do I invite"]}))
+        frame = await _recv_type(ws, "kb_search_response")
+        assert frame["status"] == "success" and frame["request_id"] == "r1"
+        assert frame["packet"]["document_passages"][0]["document_id"] == "d1"
+        sent = json.loads(route.calls[0].request.content)
+        assert sent == {"query": "how do I invite", "alternate_query": "invite member", "user_messages": ["how do I invite"],
+                        "session_id": "sess_123", "external_user_id": "user_123"}
+        assert route.calls[0].request.headers["X-API-Key"] == api_key
+    finally:
+        await ws.close()
+        await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_kb_search_failure_is_an_error_frame_after_a_single_attempt(base_url, api_key, trigger_session_response, pause_status_not_paused_response):
+    """A 503 from Centive is not retried: the browser stops waiting at 12 s and Anam at 15 s,
+    so the error frame must arrive at once rather than after three back-offs."""
+    route = respx.post(f"{base_url}/anam/kb-search").mock(return_value=httpx.Response(503, json={"detail": "Knowledge search is unavailable"}))
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)  # default retry policy (3) must not apply here
+    ws = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    try:
+        await ws.send(json.dumps({"type": "kb_search", "request_id": "r2", "user_id": "user_123", "query": "anything"}))
+        frame = await asyncio.wait_for(_recv_type(ws, "kb_search_response"), timeout=3.0)
+        assert frame == {"type": "kb_search_response", "request_id": "r2", "status": "error",
+                         "error": "KB_SEARCH_UNAVAILABLE", "message": "knowledge search is unavailable"}
+        assert route.call_count == 1
+    finally:
+        await ws.close()
+        await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_kb_search_rejects_bad_frames_and_foreign_identity(base_url, api_key, trigger_session_response, pause_status_not_paused_response):
+    route = respx.post(f"{base_url}/anam/kb-search").mock(return_value=httpx.Response(200, json=PACKET))
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    ws = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    try:
+        await ws.send(json.dumps({"type": "kb_search", "request_id": "r3", "query": ""}))
+        frame = await _recv_type(ws, "kb_search_response")
+        assert frame["status"] == "error" and frame["error"] == "INVALID_KB_SEARCH" and frame["request_id"] == "r3"
+
+        await ws.send(json.dumps({"type": "kb_search", "request_id": "r4", "user_id": "someone_else", "query": "ok"}))
+        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+        assert data["status"] == "error" and data["error"] == "IDENTITY_MISMATCH"
+        assert route.call_count == 0
+    finally:
+        await ws.close()
+        await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_long_chat_message_and_followup_pass_through_without_truncation(
+    base_url, api_key, trigger_session_response, pause_status_not_paused_response,
+):
+    route = respx.post(f"{base_url}/anam/kb-search").mock(return_value=httpx.Response(200, json=PACKET))
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    ws = await _connect(client, base_url, trigger_session_response, pause_status_not_paused_response)
+    question = "q" * 4000
+    history = [question]
+    try:
+        for index, query in enumerate([question, "download invoice"]):
+            if index:
+                history.append(query)
+            await ws.send(json.dumps({
+                "type": "kb_search", "request_id": f"long-{index}", "user_id": "user_123",
+                "query": query, "user_messages": history,
+            }))
+            frame = await _recv_type(ws, "kb_search_response")
+            assert frame["status"] == "success"
+            sent = json.loads(route.calls[index].request.content)
+            assert sent["query"] == query and sent["user_messages"] == history
+        await ws.send(json.dumps({"type": "kb_search", "request_id": "too-long", "query": "q" * 4001}))
+        assert (await _recv_type(ws, "kb_search_response"))["error"] == "INVALID_KB_SEARCH"
+        assert route.call_count == 2
+    finally:
+        await ws.close()
+        await client.aclose()

{centive_sdk-2.2.0.dev6 → centive_sdk-2.2.0.dev9}/tests/test_websocket_server.py

@@ -127,31 +127,134 @@ async def test_user_trigger_forwards_the_browsers_page(base_url, api_key, ws_por
     client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
     token = await client.initialize_websocket(user_id="user_123", port=ws_port)
 
-    async with websockets.connect(ws_url(ws_port, token)) as ws:
-        await ws.recv()  # auto-trigger on connect: no page known yet
-        assert "current_page" not in json.loads(route.calls.last.request.content)
+    try:
+        async with websockets.connect(ws_url(ws_port, token)) as ws:
+            await ws.recv()  # auto-trigger on connect: no page known yet
+            assert "current_page" not in json.loads(route.calls.last.request.content)
+
+            await ws.send(json.dumps({
+                "user_trigger": True,
+                "page": {"path": "/billing/42", "pattern": "/billing/:id", "title": "Invoices",
+                         "referrer_path": "/home", "junk": "ignored"},
+            }))
+            data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert data["status"] == "success"
+
+            body = json.loads(route.calls.last.request.content)
+            assert body["external_user_id"] == "user_123"
+            assert body["current_page"] == {
+                "path": "/billing/42", "pattern": "/billing/:id", "title": "Invoices", "referrer_path": "/home",
+            }
+
+            # A malformed hint costs nothing: the session is still triggered, without it.
+            await ws.send(json.dumps({"user_trigger": True, "page": {"pattern": 7}}))
+            data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert data["status"] == "success"
+            assert "current_page" not in json.loads(route.calls.last.request.content)
+
+    finally:
+        await client.aclose()
 
-        await ws.send(json.dumps({
-            "user_trigger": True,
-            "page": {"path": "/billing/42", "pattern": "/billing/:id", "title": "Invoices",
-                     "referrer_path": "/home", "junk": "ignored"},
-        }))
-        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
-        assert data["status"] == "success"
 
-        body = json.loads(route.calls.last.request.content)
-        assert body["external_user_id"] == "user_123"
-        assert body["current_page"] == {
-            "path": "/billing/42", "pattern": "/billing/:id", "title": "Invoices", "referrer_path": "/home",
-        }
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_client_that_asks_for_its_session_replaces_the_automatic_trigger(
+    base_url, api_key, ws_port, trigger_session_response, pause_status_not_paused_response
+):
+    """One Centive call per connection start, carrying the page.
 
-        # A malformed hint costs nothing: the session is still triggered, without it.
-        await ws.send(json.dumps({"user_trigger": True, "page": {"pattern": 7}}))
-        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
-        assert data["status"] == "success"
+    Seen on dev: the connect-time automatic trigger and the browser SDK's own
+    request (sent the moment the socket opens) both reached Centive within
+    milliseconds, two Anam tokens per connection, and the opening prompt was
+    built from the page-less one.
+    """
+    respx.get(f"{base_url}/anam/pause-status/user_123").mock(
+        return_value=httpx.Response(200, json=pause_status_not_paused_response)
+    )
+    route = respx.post(f"{base_url}/anam/trigger-session").mock(
+        return_value=httpx.Response(200, json=trigger_session_response)
+    )
+
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    token = await client.initialize_websocket(user_id="user_123", port=ws_port)
+
+    try:
+        async with websockets.connect(ws_url(ws_port, token)) as ws:
+            await ws.send(json.dumps({"user_trigger": True, "page": {"path": "/dashboard", "pattern": "/dashboard"}}))
+            data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert data["status"] == "success"
+
+            # Past the grace period nothing else arrives: the automatic trigger stood down.
+            with pytest.raises(asyncio.TimeoutError):
+                await asyncio.wait_for(ws.recv(), timeout=client.config.session_trigger_grace_seconds + 0.7)
+
+        assert route.call_count == 1
+        assert json.loads(route.calls.last.request.content)["current_page"]["path"] == "/dashboard"
+    finally:
+        await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_a_silent_client_still_gets_the_automatic_trigger(
+    base_url, api_key, ws_port, trigger_session_response, pause_status_not_paused_response
+):
+    """Older browser SDKs and custom frontends never ask; they get their session
+    after the grace period, from exactly one call."""
+    respx.get(f"{base_url}/anam/pause-status/user_123").mock(
+        return_value=httpx.Response(200, json=pause_status_not_paused_response)
+    )
+    route = respx.post(f"{base_url}/anam/trigger-session").mock(
+        return_value=httpx.Response(200, json=trigger_session_response)
+    )
+
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    token = await client.initialize_websocket(user_id="user_123", port=ws_port)
+
+    try:
+        async with websockets.connect(ws_url(ws_port, token)) as ws:
+            data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert data["status"] == "success"
+            assert data["session_data"]["token"] == trigger_session_response["session_data"]["token"]
+
+        assert route.call_count == 1
         assert "current_page" not in json.loads(route.calls.last.request.content)
+    finally:
+        await client.aclose()
 
-    await client.aclose()
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_concurrent_triggers_on_one_connection_share_a_call(
+    base_url, api_key, ws_port, trigger_session_response, pause_status_not_paused_response
+):
+    """A request that lands while another trigger for the connection is in
+    flight waits for it and receives the same frame; Centive is called once."""
+    respx.get(f"{base_url}/anam/pause-status/user_123").mock(
+        return_value=httpx.Response(200, json=pause_status_not_paused_response)
+    )
+
+    async def slow(request):
+        await asyncio.sleep(0.4)
+        return httpx.Response(200, json=trigger_session_response)
+
+    route = respx.post(f"{base_url}/anam/trigger-session").mock(side_effect=slow)
+
+    client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
+    client.config.session_trigger_grace_seconds = 0  # automatic trigger fires at once
+    token = await client.initialize_websocket(user_id="user_123", port=ws_port)
+
+    try:
+        async with websockets.connect(ws_url(ws_port, token)) as ws:
+            await ws.send(json.dumps({"user_trigger": True}))  # lands while the automatic call is in flight
+            first = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            second = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert first["status"] == second["status"] == "success"
+            assert first["session_data"] == second["session_data"]
+
+        assert route.call_count == 1
+    finally:
+        await client.aclose()
 
 
 @pytest.mark.asyncio
@@ -174,23 +277,25 @@ async def test_user_trigger_falls_back_to_the_last_page_view_seen(
     client = AsyncCentiveClient(api_key=api_key, base_url=base_url)
     token = await client.initialize_websocket(user_id="user_123", port=ws_port)
 
-    async with websockets.connect(ws_url(ws_port, token)) as ws:
-        await ws.recv()
-        frame = dict(telemetry_event_data)
-        await ws.send(json.dumps(frame))
-        ack = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
-        assert ack["type"] == "telemetry_ack"
-
-        await ws.send(json.dumps({"user_trigger": True}))
-        data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
-        assert data["status"] == "success"
-
-        body = json.loads(route.calls.last.request.content)
-        latest_view = [e for e in frame["events"] if e["event_type"] == "page_view"][-1]["page"]
-        assert body["current_page"]["path"] == latest_view["path"]
-        assert body["current_page"]["pattern"] == latest_view["pattern"]
-
-    await client.aclose()
+    try:
+        async with websockets.connect(ws_url(ws_port, token)) as ws:
+            await ws.recv()
+            frame = dict(telemetry_event_data)
+            await ws.send(json.dumps(frame))
+            ack = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert ack["type"] == "telemetry_ack"
+
+            await ws.send(json.dumps({"user_trigger": True}))
+            data = json.loads(await asyncio.wait_for(ws.recv(), timeout=5.0))
+            assert data["status"] == "success"
+
+            body = json.loads(route.calls.last.request.content)
+            latest_view = [e for e in frame["events"] if e["event_type"] == "page_view"][-1]["page"]
+            assert body["current_page"]["path"] == latest_view["path"]
+            assert body["current_page"]["pattern"] == latest_view["pattern"]
+
+    finally:
+        await client.aclose()
 
 
 @pytest.mark.asyncio