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

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

@@ -25,6 +25,12 @@ Centive batcher and the host callback).
   `stats()` as `context_received` / `context_delivered`. Anam has no
   server-side way to inform a running session, so this is the only path.
 - `AsyncSessions.send_events(ProductEventBatchRequest)`.
+- **The session request carries the current page.** `TriggerSessionRequest.current_page`
+  (a `TelemetryPage`). The websocket server fills it from the `page` the browser
+  SDK puts in its `user_trigger` frame, or, for older browser SDKs, from the last
+  `page_view` seen on that connection. Centive builds the opening prompt from it:
+  measured on dev, trigger-session landed 1.3 s before the batched page_view, so
+  the assistant used to open on the page the previous visit had ended on.
 - Models: `TelemetryEvent`, `TelemetryFrame`, `TelemetryUserBatch`,
   `ProductEventBatchRequest`, `ProductEventIngestResponse`.
 - Config: `events_path`, `telemetry_enabled`, `telemetry_flush_max_events`,
@@ -46,6 +52,14 @@ Centive batcher and the host callback).
   `ServerError`) for every request, since retrying the same body cannot help.
 - Log redaction now masks `page_path`, `page_title`, `path`, `title` and
   `referrer_path`.
+- **A 404 is no longer retried.** It is not a transient failure: the route is
+  absent on that deployment. This is the shape of a Centive backend older than
+  the SDK — `/anam/events` does not exist before page tracking — and of a
+  `trigger-session` for a user with no session in the organization. Previously
+  both were retried three times and then opened a circuit breaker to reach the
+  same answer. Telemetry now drops the batch, says once that the deployment has
+  no product-events endpoint, and keeps everything else working; a rolling
+  upgrade that brings the endpoint up is picked up by the next batch.
 
 ## v2.1.0
 

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

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

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

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

@@ -416,6 +416,19 @@ class AsyncSessions:
                     error_detail = self._extract_error_message(response)
                     raise AuthError(f"Authentication failed: {error_detail}", request_id=request_id)
 
+                elif response.status_code == 404:
+                    # Not transient, so it must not be retried: the route is
+                    # absent on this deployment. That is the shape of a Centive
+                    # backend older than the SDK — /anam/events does not exist
+                    # before page tracking — and of a trigger-session for a user
+                    # with no session in this org. Retrying either one three
+                    # times, then opening a circuit breaker, spends requests and
+                    # fills logs to reach the same answer.
+                    error_detail = self._extract_error_message(response)
+                    raise ValidationError(
+                        f"Not found (404): {error_detail}", request_id=request_id
+                    )
+
                 elif response.status_code in [400, 413, 422]:
                     # 413 is "payload over the API's size caps": retrying the
                     # same body cannot succeed, so it is a validation failure.

{centive_sdk-2.2.0.dev4 → centive_sdk-2.2.0.dev6}/src/centive_sdk/resources/telemetry_batcher.py

@@ -95,6 +95,7 @@ class TelemetryBatcher:
         self._wake = asyncio.Event()
         self._running = False
         self._auth_error_logged = False
+        self._missing_endpoint_logged = False
         self.on_context: Optional[ContextCallable] = None
 
     # ------------------------------------------------------------------ state
@@ -246,15 +247,33 @@ class TelemetryBatcher:
                 safe_log(self._logger, "error", f"telemetry rejected: invalid API key ({e})")
             return False
         except ValidationError as e:
-            # 400 / 413 / 422: our payload was wrong; retrying cannot help.
+            # 400 / 404 / 413 / 422: the payload or the route was wrong, and
+            # retrying cannot change either.
             self._stats.dropped_non_retryable += len(batch)
             self._stats.last_error = "ValidationError"
-            safe_log(
-                self._logger,
-                "warning",
-                f"telemetry batch rejected by API, dropped: {e}",
-                {"events": len(batch)},
-            )
+            if "(404)" in str(e):
+                # A Centive deployment older than this SDK: page tracking has
+                # no endpoint to reach there. Said once, plainly, because the
+                # fix is a backend upgrade and not something a retry reaches.
+                # Not fatal: everything else the SDK does still works, and a
+                # rolling upgrade can bring the endpoint up under us, so later
+                # batches keep trying quietly.
+                if not self._missing_endpoint_logged:
+                    self._missing_endpoint_logged = True
+                    safe_log(
+                        self._logger,
+                        "warning",
+                        "this Centive deployment has no product-events endpoint; page "
+                        "events are being discarded. Everything else is unaffected. "
+                        "Set telemetry_enabled=False to stop sending them.",
+                    )
+            else:
+                safe_log(
+                    self._logger,
+                    "warning",
+                    f"telemetry batch rejected by API, dropped: {e}",
+                    {"events": len(batch)},
+                )
             return True
         except Exception as e:  # unknown: treat as retryable but bounded by the breaker
             self._breaker.record_failure()

{centive_sdk-2.2.0.dev4 → centive_sdk-2.2.0.dev6}/src/centive_sdk/resources/websocket_server.py

@@ -17,6 +17,7 @@ from ..models.requests import (
     SessionMessage,
     SessionMetadata,
     TelemetryEvent,
+    TelemetryPage,
     TriggerSessionRequest,
 )
 
@@ -77,6 +78,10 @@ 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] = {}
         # 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 +345,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)
@@ -592,6 +598,7 @@ class WebSocketServer:
             # immediately after a drop).
             self._clients.discard(websocket)
             self._connection_users.pop(websocket, None)
+            self._connection_last_page.pop(websocket, None)
             self._telemetry_rate.forget(websocket)
             session_keys = self._connection_sessions.pop(websocket, set())
 
@@ -1033,6 +1040,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 +1403,38 @@ 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)
+        await self._trigger_and_emit(
+            websocket, user_id, user_trigger, client_info, current_page=current_page
+        )
+
+    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 +1442,22 @@ 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."""
         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)

{centive_sdk-2.2.0.dev4 → centive_sdk-2.2.0.dev6}/tests/test_telemetry_batcher.py

@@ -265,3 +265,56 @@ async def test_context_relay_failure_does_not_break_flush():
     assert batcher.queue_depth == 0
     assert batcher.stats()["accepted"] == 1
     assert batcher.circuit_breaker.state == "closed"
+
+
+@pytest.mark.asyncio
+async def test_missing_endpoint_drops_without_retrying_or_tripping_the_breaker():
+    """A Centive deployment older than this SDK has no /anam/events.
+
+    This is the rollout shape that matters: the SDK ships ahead of the backend
+    for a couple of weeks. A 404 must cost the page events and nothing else —
+    no retry storm, no circuit breaker, no effect on transcript saves.
+    """
+    logged: list[str] = []
+
+    class Recorder:
+        def warning(self, message, *args, **kwargs):
+            logged.append(str(message))
+
+        def __getattr__(self, _name):
+            return lambda *a, **k: None
+
+    sender = RecordingSender([ValidationError("Not found (404): Not Found")])
+    batcher = TelemetryBatcher(sender, make_config(telemetry_flush_max_events=10), logger=Recorder())
+    batcher.enqueue("alice", None, [make_event(), make_event()])
+
+    await batcher.flush()
+
+    assert batcher.queue_depth == 0  # dropped, not requeued
+    assert batcher.circuit_breaker.state == "closed"
+    assert batcher.stats()["dropped_non_retryable"] == 2
+    assert len(sender.requests) == 1  # not retried
+    assert any("no product-events endpoint" in line for line in logged)
+
+
+@pytest.mark.asyncio
+async def test_the_missing_endpoint_is_reported_once_not_per_batch():
+    logged: list[str] = []
+
+    class Recorder:
+        def warning(self, message, *args, **kwargs):
+            logged.append(str(message))
+
+        def __getattr__(self, _name):
+            return lambda *a, **k: None
+
+    sender = RecordingSender(
+        [ValidationError("Not found (404): Not Found"), ValidationError("Not found (404): Not Found")]
+    )
+    batcher = TelemetryBatcher(sender, make_config(telemetry_flush_max_events=1), logger=Recorder())
+    batcher.enqueue("alice", None, [make_event(), make_event()])
+
+    await batcher.flush()
+
+    assert len(sender.requests) == 2
+    assert sum("no product-events endpoint" in line for line in logged) == 1

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

@@ -109,6 +109,90 @@ async def test_user_trigger_message(base_url, api_key, ws_port, trigger_session_
     await client.aclose()
 
 
+@pytest.mark.asyncio
+@respx.mock
+async def test_user_trigger_forwards_the_browsers_page(base_url, api_key, ws_port, trigger_session_response, pause_status_not_paused_response):
+    """The page in the FE's user_trigger frame reaches trigger-session as current_page.
+
+    Measured on dev: trigger-session landed 1.3 s before the batched page_view,
+    so Centive built the opening prompt from the previous visit's last page.
+    """
+    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)
+
+    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)
+
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_user_trigger_falls_back_to_the_last_page_view_seen(
+    base_url, api_key, ws_port, trigger_session_response, pause_status_not_paused_response, telemetry_event_data
+):
+    """A browser SDK that predates the `page` field still gets the right opening
+    page: the last page_view on the connection stands in."""
+    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)
+    )
+    respx.post(f"{base_url}/anam/events").mock(
+        return_value=httpx.Response(202, json={"accepted": 2, "rejected": 0, "rejections": [], "context": []})
+    )
+
+    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()
+
+
 @pytest.mark.asyncio
 @respx.mock
 async def test_connection_without_token_rejected(base_url, api_key, ws_port):