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

centive_sdk/config.py

@@ -83,6 +83,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/models/requests.py

@@ -20,6 +20,14 @@ class TriggerSessionRequest(BaseModel):
     user_trigger: Optional[bool] = Field(
         None, description="optional trigger to force session creation"
     )
+    # The page the browser has open at the moment of the request. Centive builds
+    # the opening prompt from it instead of from stored page views, which travel
+    # through the telemetry batcher and were measured arriving 1.3 s after this
+    # call. Optional: an older browser SDK sends none, and the websocket server
+    # then falls back to the last page_view it saw on the connection.
+    current_page: Optional["TelemetryPage"] = Field(
+        None, description="page the browser reports having open when it asks for a session"
+    )
 
 
 class SessionMessage(BaseModel):
@@ -107,6 +115,9 @@ class TelemetryPage(BaseModel):
     referrer_path: Optional[str] = Field(default=None, max_length=TELEMETRY_MAX_PATH_CHARS)
 
 
+TriggerSessionRequest.model_rebuild()
+
+
 class TelemetryEvent(BaseModel):
     """one C1 event as produced by the browser SDK; forwarded to Centive unchanged."""
 

centive_sdk/resources/websocket_server.py

@@ -1,3 +1,4 @@
+import asyncio
 import inspect
 import json
 import secrets
@@ -17,6 +18,7 @@ from ..models.requests import (
     SessionMessage,
     SessionMetadata,
     TelemetryEvent,
+    TelemetryPage,
     TriggerSessionRequest,
 )
 
@@ -77,6 +79,18 @@ class WebSocketServer:
         self._pending_users: Deque[str] = deque()  # legacy "open" mode only
         self._connection_tokens: Dict[str, Tuple[str, float]] = {}  # token -> (user_id, expiry)
         self._connection_users: Dict[WebSocketServerProtocol, str] = {}
+        # Last page_view seen on each connection, forwarded as trigger-session's
+        # 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] = {}
+        # 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]] = {}
@@ -340,6 +354,7 @@ class WebSocketServer:
         stale = [ws for ws in self._connection_users if not self._is_live(ws)]
         for ws in stale:
             self._connection_users.pop(ws, None)
+            self._connection_last_page.pop(ws, None)
             self._clients.discard(ws)
 
         return sum(1 for bound in self._connection_users.values() if bound == user_id)
@@ -563,7 +578,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:
@@ -592,6 +609,12 @@ class WebSocketServer:
             # immediately after a drop).
             self._clients.discard(websocket)
             self._connection_users.pop(websocket, None)
+            self._connection_last_page.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())
 
@@ -1033,6 +1056,8 @@ class WebSocketServer:
                 }))
             return
 
+        self._remember_page(websocket, data["events"])
+
         batcher_active = self._telemetry is not None and self._config.telemetry_enabled
         enqueued = 0
         queue_dropped = 0
@@ -1394,7 +1419,75 @@ class WebSocketServer:
             return
 
         user_trigger = data.get("user_trigger")
-        await self._trigger_and_emit(websocket, user_id, user_trigger, client_info)
+        # The page the browser has open right now, so Centive's opening prompt
+        # starts from it rather than from a page_view still waiting in the
+        # 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)
+        # 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
+        )
+
+    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):
+            return
+        for event in reversed(events):
+            if isinstance(event, dict) and event.get("event_type") == "page_view":
+                page = self._coerce_page(event.get("page"))
+                if page is not None:
+                    self._connection_last_page[websocket] = page
+                return
+
+    @staticmethod
+    def _coerce_page(value: Any) -> Optional[dict]:
+        """A C1 page object reduced to the fields Centive accepts, or None.
+
+        Never raises: a malformed hint must not cost the user their session.
+        """
+        if not isinstance(value, dict):
+            return None
+        try:
+            return TelemetryPage.model_validate(value).model_dump(exclude_none=True)
+        except Exception:
+            return None
 
     async def _trigger_and_emit(
         self,
@@ -1402,19 +1495,65 @@ class WebSocketServer:
         user_id: str,
         user_trigger: Optional[bool],
         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",
             "triggering session",
-            {"client": client_info, "user_id": user_id, "user_trigger": user_trigger},
+            {"client": client_info, "user_id": user_id, "user_trigger": user_trigger,
+             "has_page": current_page is not None},
         )
 
         try:
             request = TriggerSessionRequest(
                 user_id=user_id,
                 user_trigger=user_trigger,
+                current_page=current_page,
             )
 
             response = await self._sessions.trigger_session(request)
@@ -1438,7 +1577,7 @@ class WebSocketServer:
                     "message": "failed to trigger session",
                     "error": "UPSTREAM_TRIGGER_FAILED",
                 }))
-                return
+                return None
 
             response_data = {
                 "status": response.status,
@@ -1447,7 +1586,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,
@@ -1460,6 +1600,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.dev5.dist-info → centive_sdk-2.2.0.dev8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: centive-sdk
-Version: 2.2.0.dev5
+Version: 2.2.0.dev8
 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.dev5.dist-info → centive_sdk-2.2.0.dev8.dist-info}/RECORD

@@ -4,11 +4,11 @@ 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=HX0N7UCu9QLS5bICW_iME1LeBBG83Za2-cYoV-9VgLA,6187
+centive_sdk/config.py,sha256=1GoHkwJebL1HknSa-y4oFhxDAaG0boq0JY0csNV-pfE,6612
 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=6KW5KEjyMAy-DAppTssu5b-LSf1doKtMnOfng5O3tNc,7153
+centive_sdk/models/requests.py,sha256=_SqXf-8wejbAVQOMf6Lk3W0q3F3yu401mFvB8dMhwp4,7736
 centive_sdk/models/responses.py,sha256=zCYPB0aL2DXn-z0Febkuxo3DdZ_5sdpdGy2Jtf8Ubs8,2519
 centive_sdk/resources/__init__.py,sha256=GLutz38X4F4FwPfSZy35EkWTV7l7t9RgcBKwXmz2X_Y,179
 centive_sdk/resources/async_sessions.py,sha256=m0_gj2wLabs3BTe6rZuo9WGgSwEMJLmdKW8_s4T7KRM,21500
@@ -16,8 +16,8 @@ centive_sdk/resources/async_telemetry.py,sha256=wT12g9rG2dp_ml5YpAYCxobLlhfcsyy-
 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=iGS48oB4myV-sI0nArlBE3Y0fe_GlfBClFtVAPzrvdU,59760
-centive_sdk-2.2.0.dev5.dist-info/METADATA,sha256=6hTQ3pohxlZnB5dEEwBLq5vngFLK5LhX7NXgPMp9HOM,36427
-centive_sdk-2.2.0.dev5.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-centive_sdk-2.2.0.dev5.dist-info/licenses/LICENSE,sha256=9dFibPr7z9srhWwd35lQL2MX1Kx2qivEZdVQb9L8Q-Q,1064
-centive_sdk-2.2.0.dev5.dist-info/RECORD,,
+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,,