centive-sdk 2.1.0.dev3__py3-none-any.whl → 2.2.0.dev4__py3-none-any.whl

centive_sdk/__init__.py

@@ -14,21 +14,27 @@ from .exceptions import (
 from .models.requests import (
     MessageHistoryEvent,
     MessageStreamEvent,
+    ProductEventBatchRequest,
     SaveMessagesRequest,
     SessionEndEvent,
     SessionMessage,
     SessionMetadata,
     StreamMessage,
+    TelemetryEvent,
+    TelemetryFrame,
+    TelemetryUserBatch,
     ToolMappingRequest,
     TriggerSessionRequest,
 )
 from .models.responses import (
     PauseStatusResponse,
+    ProductEventIngestResponse,
     SaveMessagesResponse,
     ToolMappingResponse,
     TriggerSessionResponse,
 )
 from .resources.message_accumulator import MessageAccumulator
+from .resources.telemetry_batcher import TelemetryBatcher
 from .resources.websocket_server import WebSocketServer
 
 try:
@@ -52,14 +58,20 @@ __all__ = [
     "MessageHistoryEvent",
     "MessageStreamEvent",
     "SessionEndEvent",
+    "TelemetryEvent",
+    "TelemetryFrame",
+    "TelemetryUserBatch",
+    "ProductEventBatchRequest",
     # Response Models
     "ToolMappingResponse",
     "TriggerSessionResponse",
     "SaveMessagesResponse",
     "PauseStatusResponse",
+    "ProductEventIngestResponse",
     # Resources
     "WebSocketServer",
     "MessageAccumulator",
+    "TelemetryBatcher",
     # Exceptions
     "CentiveError",
     "AuthError",

centive_sdk/_logging.py

@@ -72,6 +72,11 @@ def redact_request_data(data: dict) -> dict:
     if "company_name" in redacted:
         redacted["company_name"] = mask_string(str(redacted["company_name"]))
 
+    # Page paths and titles can carry identifiers from the customer's app.
+    for path_field in ("page_path", "page_title", "path", "title", "referrer_path"):
+        if path_field in redacted:
+            redacted[path_field] = mask_string(str(redacted[path_field]))
+
     for secret_field in ("api_key", "token", "connection_token", "ws_handshake_secret"):
         if secret_field in redacted:
             redacted[secret_field] = "[REDACTED]"

centive_sdk/async_client.py

@@ -7,6 +7,8 @@ from ._logging import safe_log
 from .config import ClientConfig
 from .models.responses import PauseStatusResponse
 from .resources.async_sessions import AsyncSessions
+from .resources.async_telemetry import AsyncTelemetry
+from .resources.telemetry_batcher import TelemetryBatcher
 from .resources.websocket_server import WebSocketServer
 
 
@@ -43,8 +45,10 @@ class AsyncCentiveClient:
 
         Pass on_telemetry=<callable> to receive page-telemetry frames from the FE
         SDK: on_telemetry(user_id: str, frame: dict), sync or async, with the
-        events at frame["events"]. The SDK does not store them — without a
-        callback they are acknowledged and dropped.
+        events at frame["events"]. By default the SDK also forwards these
+        events to Centive (POST /anam/events); the callback is an additional
+        sink. With telemetry_enabled=False and no callback, frames are
+        acknowledged and dropped.
         """
         if api_key is not None:
             options["api_key"] = api_key
@@ -57,6 +61,10 @@ class AsyncCentiveClient:
         # **options and is read out here. ClientConfig ignores unknown keys.
         self._on_telemetry = options.get("on_telemetry")
         self.sessions = AsyncSessions(self._http_client, self.config, self._logger)
+        self._telemetry_batcher = TelemetryBatcher(
+            send=self.sessions.send_events, config=self.config, logger=self._logger
+        )
+        self.telemetry = AsyncTelemetry(self._telemetry_batcher, self._logger)
         self._ws_server: Optional[WebSocketServer] = None
         self._last_pause_status: Optional[PauseStatusResponse] = None
         # One process serves many users; serialize server startup so concurrent
@@ -136,15 +144,38 @@ class AsyncCentiveClient:
                     sessions=self.sessions,
                     config=self.config,
                     logger=self._logger,
+                    telemetry=self._telemetry_batcher,
                     on_telemetry=self._on_telemetry,
                 )
                 # Publish only after a successful bind, so a failed start does
                 # not leave a dead server in place and wedge every later call.
                 await server.start(host=ws_host, port=ws_port, **ws_options)
                 self._ws_server = server
+                self._telemetry_batcher.on_context = self._relay_live_context
+                self._telemetry_batcher.start()
 
         return self._ws_server.register_user(user_id)
 
+    async def _relay_live_context(self, user_id: str, entry: dict) -> int:
+        """Pushes a Centive context entry to the user's browser as a C4 frame.
+
+        The browser SDK calls anamClient.addContext with it; Anam has no
+        server-side way to inform a running session. Only the connection bound
+        to this user receives it (send_to_user), never a broadcast.
+        """
+        server = self._ws_server
+        if server is None or not server.is_running:
+            return 0
+        frame = {
+            "type": "context",
+            "schema": 1,
+            "content": str(entry.get("content", ""))[:1000],
+            "source": "centive",
+        }
+        if entry.get("expires_at"):
+            frame["expires_at"] = entry["expires_at"]
+        return await server.send_to_user(user_id, frame)
+
     async def get_aria_status(self, user_id: str) -> PauseStatusResponse:
         """Checks if Aria is paused for a user (for UI display purposes).
 
@@ -179,6 +210,9 @@ class AsyncCentiveClient:
             await self._ws_server.stop()
             self._ws_server = None
 
+        # Flush queued page events before the HTTP client goes away.
+        await self._telemetry_batcher.stop()
+
         await self._http_client.aclose()
 
     async def __aenter__(self) -> "AsyncCentiveClient":

centive_sdk/config.py

@@ -38,6 +38,7 @@ class ClientConfig(BaseModel):
     trigger_session_path: str = "/anam/trigger-session"
     save_messages_path: str = "/anam/save-messages"
     pause_status_path: str = "/anam/pause-status"
+    events_path: str = "/anam/events"
     timeout_seconds: float = 10.0
     max_retries: int = 3
     initial_retry_delay: float = 0.5
@@ -98,6 +99,19 @@ class ClientConfig(BaseModel):
     # False to fail closed and withhold connections instead.
     pause_check_fail_open: bool = True
 
+    # Product events (page tracking) forwarded from FE "telemetry" frames to
+    # POST /anam/events. Contract: CentiveAI docs/product-events/CONTRACTS.md.
+    telemetry_enabled: bool = True
+    # Flush when this many events are queued, or after the interval, whichever first.
+    telemetry_flush_max_events: int = 50
+    telemetry_flush_interval_seconds: float = 2.0
+    # Bounded in-memory queue; oldest events are dropped (and counted) when full.
+    telemetry_max_queue_events: int = 5000
+    # Per-frame caps (C1 limits) live above as max_telemetry_* — they are
+    # shared with the validation the host-callback path uses.
+    # Telemetry frames accepted per websocket connection per minute (0 disables).
+    telemetry_rate_per_connection_per_minute: int = 120
+
     incremental_save_enabled: bool = Field(
         default=False,
         description="enable incremental message saving (sends messages to API immediately as they arrive)"

centive_sdk/models/__init__.py

@@ -1,10 +1,27 @@
-from .requests import ToolMappingRequest, TriggerSessionRequest
-from .responses import PauseStatusResponse, ToolMappingResponse, TriggerSessionResponse
+from .requests import (
+    ProductEventBatchRequest,
+    TelemetryEvent,
+    TelemetryFrame,
+    TelemetryUserBatch,
+    ToolMappingRequest,
+    TriggerSessionRequest,
+)
+from .responses import (
+    PauseStatusResponse,
+    ProductEventIngestResponse,
+    ToolMappingResponse,
+    TriggerSessionResponse,
+)
 
 __all__ = [
     "ToolMappingRequest",
     "TriggerSessionRequest",
+    "TelemetryEvent",
+    "TelemetryFrame",
+    "TelemetryUserBatch",
+    "ProductEventBatchRequest",
     "ToolMappingResponse",
     "TriggerSessionResponse",
     "PauseStatusResponse",
+    "ProductEventIngestResponse",
 ]

centive_sdk/models/requests.py

@@ -1,6 +1,6 @@
-from typing import List, Literal, Optional
+from typing import Any, Dict, List, Literal, Optional
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 
 class ToolMappingRequest(BaseModel):
@@ -86,3 +86,79 @@ class SessionEndEvent(BaseModel):
     type: Literal["session_end"] = "session_end"
     session_id: str = Field(..., description="session ID")
     user_id: str = Field(..., description="user ID")
+
+
+# ---------------------------------------------------------------------------
+# Product events (page tracking). Contract: CentiveAI docs/product-events/CONTRACTS.md
+# ---------------------------------------------------------------------------
+
+TELEMETRY_MAX_PROPERTIES_BYTES = 4 * 1024
+TELEMETRY_MAX_PATH_CHARS = 2048
+
+
+class TelemetryPage(BaseModel):
+    """page fields of a C1 event."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    path: str = Field(..., min_length=1, max_length=TELEMETRY_MAX_PATH_CHARS)
+    pattern: Optional[str] = Field(default=None, max_length=TELEMETRY_MAX_PATH_CHARS)
+    title: Optional[str] = Field(default=None, max_length=512)
+    referrer_path: Optional[str] = Field(default=None, max_length=TELEMETRY_MAX_PATH_CHARS)
+
+
+class TelemetryEvent(BaseModel):
+    """one C1 event as produced by the browser SDK; forwarded to Centive unchanged."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    client_event_id: str = Field(..., min_length=1, max_length=64)
+    event_type: str = Field(..., min_length=1, max_length=64)
+    occurred_at: str = Field(..., description="iso 8601 timestamp with timezone")
+    browser_session_id: Optional[str] = Field(default=None, max_length=64)
+    page: Optional[TelemetryPage] = None
+    duration_ms: Optional[int] = Field(default=None, ge=0)
+    detection: Optional[str] = Field(default=None, max_length=32)
+    properties: Dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator("properties")
+    @classmethod
+    def _bound_properties(cls, value: Dict[str, Any]) -> Dict[str, Any]:
+        import json
+
+        if len(json.dumps(value, separators=(",", ":"), default=str)) > TELEMETRY_MAX_PROPERTIES_BYTES:
+            raise ValueError("properties_too_large")
+        return value
+
+
+class TelemetryFrame(BaseModel):
+    """event payload for type="telemetry" from FE SDK (C1)."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    type: Literal["telemetry"] = "telemetry"
+    schema_version: int = Field(default=1, alias="schema")
+    user_id: Optional[str] = Field(default=None, max_length=255)
+    sdk: Optional[str] = Field(default=None, max_length=64)
+    events: List[TelemetryEvent] = Field(..., min_length=1)
+
+
+class TelemetryUserBatch(BaseModel):
+    """events for one end user inside a C2 request."""
+
+    external_user_id: str = Field(..., min_length=1, max_length=255)
+    client_sdk: Optional[str] = Field(default=None, max_length=64)
+    events: List[TelemetryEvent] = Field(..., min_length=1)
+
+
+class ProductEventBatchRequest(BaseModel):
+    """request payload for POST /anam/events (C2)."""
+
+    schema_version: int = Field(default=1, serialization_alias="schema")
+    sdk_version: Optional[str] = None
+    batches: List[TelemetryUserBatch]
+    idempotency_key: Optional[str] = Field(default=None, exclude=True)
+
+    @property
+    def total_events(self) -> int:
+        return sum(len(b.events) for b in self.batches)

centive_sdk/models/responses.py

@@ -59,3 +59,16 @@ class SaveMessagesResponse(BaseModel):
     time_taken: float = 0.0
     error: Optional[str] = None
     raw: Optional[Dict[str, Any]] = None
+
+
+class ProductEventIngestResponse(BaseModel):
+    """response from POST /anam/events (202)."""
+
+    accepted: int = 0
+    rejected: int = 0
+    rejections: list = Field(default_factory=list)
+    # Context for users with a live Aria session; relayed to the browser as a
+    # "context" frame (C4) for anamClient.addContext. Entries look like
+    # {"external_user_id", "content", "expires_at"}.
+    context: list = Field(default_factory=list)
+    raw: Optional[Dict[str, Any]] = None

centive_sdk/resources/async_sessions.py

@@ -8,9 +8,15 @@ from .._logging import safe_log
 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 SaveMessagesRequest, ToolMappingRequest, TriggerSessionRequest
+from ..models.requests import (
+    ProductEventBatchRequest,
+    SaveMessagesRequest,
+    ToolMappingRequest,
+    TriggerSessionRequest,
+)
 from ..models.responses import (
     PauseStatusResponse,
+    ProductEventIngestResponse,
     SaveMessagesResponse,
     ToolMappingResponse,
     TriggerSessionResponse,
@@ -191,6 +197,35 @@ class AsyncSessions:
             raw=data,
         )
 
+    async def send_events(self, input: ProductEventBatchRequest) -> ProductEventIngestResponse:
+        """Sends a batch of product events (page views) to Centive.
+
+        Contract C2 in CentiveAI docs/product-events/CONTRACTS.md. A 202 is
+        final: the ``rejections`` in the response are not retryable. 429 and
+        5xx are retried with backoff like every other call; 400/413/422 raise
+        ``ValidationError`` and 401 raises ``AuthError``.
+        """
+        url = join_url(self._config.base_url, self._config.events_path)
+        headers = build_headers(self._config.api_key, idempotency_key=input.idempotency_key)
+        payload = input.model_dump(mode="json", by_alias=True)
+        if payload.get("sdk_version") is None:
+            from .. import __version__
+
+            payload["sdk_version"] = f"python/{__version__}"
+
+        response = await self._make_request(url, headers, payload)
+        try:
+            data = response.json()
+        except ValueError:
+            data = {}
+        return ProductEventIngestResponse(
+            accepted=int(data.get("accepted", 0)),
+            rejected=int(data.get("rejected", 0)),
+            rejections=list(data.get("rejections", []) or []),
+            context=list(data.get("context", []) or []),
+            raw=data,
+        )
+
     async def get_pause_status(self, user_id: str) -> PauseStatusResponse:
         """Checks if Aria is paused for a specific user.
 
@@ -381,7 +416,9 @@ class AsyncSessions:
                     error_detail = self._extract_error_message(response)
                     raise AuthError(f"Authentication failed: {error_detail}", request_id=request_id)
 
-                elif response.status_code in [400, 422]:
+                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.
                     error_detail = self._extract_error_message(response)
                     raise ValidationError(
                         f"Validation error: {error_detail}", request_id=request_id

centive_sdk/resources/async_telemetry.py

@@ -0,0 +1,65 @@
+"""Server-side entry point for product events.
+
+Most events arrive from the browser through the websocket ``telemetry`` frame.
+This resource lets the customer's backend emit its own events (for example
+``invoice_paid``) into the same queue, and exposes queue statistics.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Dict, Optional
+
+from .._logging import safe_log
+from ..models.requests import TelemetryEvent
+from .telemetry_batcher import TelemetryBatcher
+
+
+class AsyncTelemetry:
+    def __init__(self, batcher: TelemetryBatcher, logger: Optional[Any] = None):
+        self._batcher = batcher
+        self._logger = logger
+
+    def track(
+        self,
+        user_id: str,
+        event_type: str,
+        properties: Optional[Dict[str, Any]] = None,
+        *,
+        occurred_at: Optional[datetime] = None,
+        client_event_id: Optional[str] = None,
+        page_path: Optional[str] = None,
+    ) -> bool:
+        """Queues one server-side event for ``user_id``.
+
+        ``user_id`` must come from your own authentication, exactly like
+        ``tool_mapping``. Events for users Centive cannot link to an account are
+        dropped by the API, not stored. Returns False if the event was dropped
+        locally (telemetry disabled or queue full).
+        """
+        when = occurred_at or datetime.now(timezone.utc)
+        if when.tzinfo is None:
+            when = when.replace(tzinfo=timezone.utc)
+        event = TelemetryEvent(
+            client_event_id=client_event_id or str(uuid.uuid4()),
+            event_type=event_type,
+            occurred_at=when.isoformat(),
+            page={"path": page_path} if page_path else None,
+            detection="manual",
+            properties=properties or {},
+        )
+        accepted, dropped = self._batcher.enqueue(user_id, "python/server", [event])
+        if dropped:
+            safe_log(self._logger, "debug", "server-side telemetry event dropped", {"event_type": event_type})
+        return accepted > 0 and dropped == 0
+
+    async def flush(self) -> None:
+        """Sends everything queued right now. Normally not needed; the batcher
+        flushes every ``telemetry_flush_interval_seconds``."""
+        if not self._batcher.is_running:
+            self._batcher.start()
+        await self._batcher.flush()
+
+    def stats(self) -> Dict[str, Any]:
+        return self._batcher.stats()

centive_sdk/resources/telemetry_batcher.py

@@ -0,0 +1,341 @@
+"""Buffers product events (page views) from FE connections and forwards them to
+Centive in batches.
+
+Contract: CentiveAI ``docs/product-events/CONTRACTS.md`` (C1 in, C2 out).
+
+Design points:
+- Bounded queue. When full, the oldest events are dropped and counted; the
+  websocket handler is never blocked.
+- Flush on ``telemetry_flush_max_events`` or every
+  ``telemetry_flush_interval_seconds``, whichever comes first.
+- Own ``CircuitBreaker``: a flaky events endpoint must not trip the breaker
+  that guards transcript saves, and vice versa.
+- ``Idempotency-Key`` per flush; the API dedupes on ``client_event_id`` so a
+  retried flush can never double count.
+- Retryable failures (429 / 5xx / network) re-queue the batch at the front,
+  bounded by the same queue cap. Non-retryable failures (400 / 401 / 413 / 422)
+  drop the batch and are counted.
+- A 202 is final: its ``rejections`` are recorded in stats, never retried.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Deque, Dict, List, Optional, Tuple
+
+from .._logging import safe_log
+from ..config import ClientConfig
+from ..exceptions import AuthError, NetworkError, RateLimitError, ServerError, ValidationError
+from ..models.requests import ProductEventBatchRequest, TelemetryEvent, TelemetryUserBatch
+from ..models.responses import ProductEventIngestResponse
+from .message_accumulator import CircuitBreaker
+
+SendCallable = Callable[[ProductEventBatchRequest], Awaitable[ProductEventIngestResponse]]
+# (external_user_id, context entry dict) -> awaitable; set by the client to
+# relay live-session context to the user's browser (C4 frame).
+ContextCallable = Callable[[str, Dict[str, Any]], Awaitable[Any]]
+
+# (external_user_id, client_sdk, event)
+_Queued = Tuple[str, Optional[str], TelemetryEvent]
+
+
+@dataclass
+class TelemetryStats:
+    enqueued: int = 0
+    dropped_queue_full: int = 0
+    sent: int = 0
+    accepted: int = 0
+    rejected: int = 0
+    dropped_non_retryable: int = 0
+    flush_failures: int = 0
+    rejections_by_reason: Dict[str, int] = field(default_factory=dict)
+    last_error: Optional[str] = None
+    context_received: int = 0
+    context_delivered: int = 0
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "enqueued": self.enqueued,
+            "dropped_queue_full": self.dropped_queue_full,
+            "sent": self.sent,
+            "accepted": self.accepted,
+            "rejected": self.rejected,
+            "dropped_non_retryable": self.dropped_non_retryable,
+            "flush_failures": self.flush_failures,
+            "rejections_by_reason": dict(self.rejections_by_reason),
+            "last_error": self.last_error,
+            "context_received": self.context_received,
+            "context_delivered": self.context_delivered,
+        }
+
+
+class TelemetryBatcher:
+    def __init__(
+        self,
+        send: SendCallable,
+        config: ClientConfig,
+        logger: Optional[Any] = None,
+    ):
+        self._send = send
+        self._config = config
+        self._logger = logger
+        self._queue: Deque[_Queued] = deque()
+        self._stats = TelemetryStats()
+        self._breaker = CircuitBreaker(
+            failure_threshold=config.circuit_breaker_threshold,
+            recovery_timeout_seconds=config.circuit_breaker_recovery_seconds,
+            logger=logger,
+        )
+        self._flush_task: Optional[asyncio.Task] = None
+        self._flush_lock = asyncio.Lock()
+        self._wake = asyncio.Event()
+        self._running = False
+        self._auth_error_logged = False
+        self.on_context: Optional[ContextCallable] = None
+
+    # ------------------------------------------------------------------ state
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
+    @property
+    def queue_depth(self) -> int:
+        return len(self._queue)
+
+    @property
+    def circuit_breaker(self) -> CircuitBreaker:
+        return self._breaker
+
+    def stats(self) -> Dict[str, Any]:
+        data = self._stats.as_dict()
+        data["queue_depth"] = len(self._queue)
+        data["circuit_breaker"] = self._breaker.state
+        return data
+
+    # -------------------------------------------------------------- lifecycle
+
+    def start(self) -> None:
+        if self._running:
+            return
+        self._running = True
+        self._flush_task = asyncio.create_task(self._flush_loop())
+
+    async def stop(self) -> None:
+        """Stops the flush loop and sends whatever is still queued."""
+        if not self._running:
+            return
+        self._running = False
+        self._wake.set()
+        if self._flush_task is not None:
+            self._flush_task.cancel()
+            try:
+                await self._flush_task
+            except (asyncio.CancelledError, Exception):
+                pass
+            self._flush_task = None
+        try:
+            await self.flush()
+        except Exception as e:  # never let shutdown raise because of telemetry
+            safe_log(self._logger, "warning", f"telemetry flush on stop failed: {e}")
+
+    # ---------------------------------------------------------------- enqueue
+
+    def enqueue(
+        self, external_user_id: str, client_sdk: Optional[str], events: List[TelemetryEvent]
+    ) -> Tuple[int, int]:
+        """Queues events for the given user. Returns (accepted, dropped).
+
+        Never blocks. Drops the *oldest* queued events when the cap is hit so
+        the newest navigation is the one that survives.
+        """
+        if not self._config.telemetry_enabled:
+            return 0, len(events)
+        cap = self._config.telemetry_max_queue_events
+        dropped = 0
+        for event in events:
+            if len(self._queue) >= cap:
+                self._queue.popleft()
+                dropped += 1
+            self._queue.append((external_user_id, client_sdk, event))
+        self._stats.enqueued += len(events)
+        self._stats.dropped_queue_full += dropped
+        if dropped:
+            safe_log(
+                self._logger,
+                "warning",
+                "telemetry queue full, dropped oldest events",
+                {"dropped": dropped, "cap": cap},
+            )
+        if len(self._queue) >= self._config.telemetry_flush_max_events:
+            self._wake.set()
+        return len(events), dropped
+
+    # ------------------------------------------------------------------ flush
+
+    async def _flush_loop(self) -> None:
+        interval = self._config.telemetry_flush_interval_seconds
+        while self._running:
+            try:
+                await asyncio.wait_for(self._wake.wait(), timeout=interval)
+            except asyncio.TimeoutError:
+                pass
+            self._wake.clear()
+            if not self._running:
+                break
+            try:
+                await self.flush()
+            except Exception as e:  # the loop must survive anything
+                safe_log(self._logger, "error", f"telemetry flush loop error: {e}")
+
+    async def flush(self) -> None:
+        """Sends queued events, one request per ``telemetry_flush_max_events``."""
+        async with self._flush_lock:
+            while self._queue:
+                if self._breaker.is_open:
+                    safe_log(
+                        self._logger,
+                        "debug",
+                        "telemetry circuit breaker open, holding queue",
+                        {"queue_depth": len(self._queue)},
+                    )
+                    return
+                batch: List[_Queued] = []
+                limit = self._config.telemetry_flush_max_events
+                while self._queue and len(batch) < limit:
+                    batch.append(self._queue.popleft())
+                if not await self._send_batch(batch):
+                    return
+
+    async def _send_batch(self, batch: List[_Queued]) -> bool:
+        """Returns True to keep flushing, False to stop for now."""
+        grouped: Dict[Tuple[str, Optional[str]], List[TelemetryEvent]] = {}
+        for user_id, client_sdk, event in batch:
+            grouped.setdefault((user_id, client_sdk), []).append(event)
+        request = ProductEventBatchRequest(
+            batches=[
+                TelemetryUserBatch(external_user_id=uid, client_sdk=sdk, events=events)
+                for (uid, sdk), events in grouped.items()
+            ],
+            idempotency_key=str(uuid.uuid4()),
+        )
+        try:
+            response = await self._send(request)
+        except (RateLimitError, ServerError, NetworkError) as e:
+            # Retryable: put the batch back at the front and back off via the breaker.
+            self._breaker.record_failure()
+            self._stats.flush_failures += 1
+            self._stats.last_error = type(e).__name__
+            self._requeue_front(batch)
+            safe_log(
+                self._logger,
+                "warning",
+                f"telemetry flush failed, will retry: {type(e).__name__}",
+                {"events": len(batch), "queue_depth": len(self._queue)},
+            )
+            return False
+        except AuthError as e:
+            self._stats.dropped_non_retryable += len(batch)
+            self._stats.last_error = "AuthError"
+            if not self._auth_error_logged:
+                self._auth_error_logged = True
+                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.
+            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)},
+            )
+            return True
+        except Exception as e:  # unknown: treat as retryable but bounded by the breaker
+            self._breaker.record_failure()
+            self._stats.flush_failures += 1
+            self._stats.last_error = type(e).__name__
+            self._requeue_front(batch)
+            safe_log(self._logger, "error", f"telemetry flush unexpected error: {e}")
+            return False
+
+        self._breaker.record_success()
+        await self._relay_context(response)
+        self._stats.sent += len(batch)
+        self._stats.accepted += response.accepted
+        self._stats.rejected += response.rejected
+        for rejection in response.rejections:
+            reason = rejection.get("reason", "unknown")
+            self._stats.rejections_by_reason[reason] = (
+                self._stats.rejections_by_reason.get(reason, 0) + int(rejection.get("count", 0))
+            )
+        if response.rejected:
+            safe_log(
+                self._logger,
+                "debug",
+                "telemetry events rejected by API (final, not retried)",
+                {
+                    "accepted": response.accepted,
+                    "rejected": response.rejected,
+                    "reasons": sorted({r.get("reason") for r in response.rejections}),
+                },
+            )
+        return True
+
+    async def _relay_context(self, response: ProductEventIngestResponse) -> None:
+        """Hands live-session context entries to the client's relay (C4)."""
+        entries = getattr(response, "context", None) or []
+        if not entries:
+            return
+        self._stats.context_received += len(entries)
+        if self.on_context is None:
+            return
+        for entry in entries:
+            user_id = entry.get("external_user_id") if isinstance(entry, dict) else None
+            if not user_id or not entry.get("content"):
+                continue
+            try:
+                delivered = await self.on_context(user_id, entry)
+                if delivered:
+                    self._stats.context_delivered += 1
+            except Exception as e:  # relay problems must never break flushing
+                safe_log(self._logger, "debug", f"context relay failed: {e}")
+
+    def _requeue_front(self, batch: List[_Queued]) -> None:
+        cap = self._config.telemetry_max_queue_events
+        for item in reversed(batch):
+            if len(self._queue) >= cap:
+                # Queue filled while we were sending; the batch is older than
+                # what is queued, so it is the part that gives way.
+                self._stats.dropped_queue_full += 1
+                continue
+            self._queue.appendleft(item)
+
+
+class ConnectionRateLimiter:
+    """Token bucket per websocket connection for telemetry frames."""
+
+    def __init__(self, per_minute: int):
+        self._per_minute = per_minute
+        self._buckets: Dict[Any, Tuple[float, float]] = {}  # key -> (tokens, updated)
+
+    def allow(self, key: Any, now: Optional[float] = None) -> bool:
+        if self._per_minute <= 0:
+            return True
+        now = time.monotonic() if now is None else now
+        rate = self._per_minute / 60.0
+        tokens, updated = self._buckets.get(key, (float(self._per_minute), now))
+        tokens = min(float(self._per_minute), tokens + max(0.0, now - updated) * rate)
+        if tokens >= 1.0:
+            self._buckets[key] = (tokens - 1.0, now)
+            return True
+        self._buckets[key] = (tokens, now)
+        return False
+
+    def forget(self, key: Any) -> None:
+        self._buckets.pop(key, None)

centive_sdk/resources/websocket_server.py

@@ -16,6 +16,7 @@ from ..models.requests import (
     SaveMessagesRequest,
     SessionMessage,
     SessionMetadata,
+    TelemetryEvent,
     TriggerSessionRequest,
 )
 
@@ -23,6 +24,7 @@ if TYPE_CHECKING:
     from .async_sessions import AsyncSessions
 
 from .message_accumulator import MessageAccumulator
+from .telemetry_batcher import ConnectionRateLimiter, TelemetryBatcher
 
 # Short identifier fields on a telemetry event. Not a config knob: the frame
 # byte cap already bounds the whole payload, this only stops one field from
@@ -53,15 +55,20 @@ class WebSocketServer:
         sessions: "AsyncSessions",
         config: ClientConfig,
         logger: Optional[Any] = None,
+        telemetry: Optional[TelemetryBatcher] = None,
         on_telemetry: Optional[Callable[[str, dict], Any]] = None,
     ):
         self._sessions = sessions
         self._config = config
         self._logger = logger
-        # Host sink for page-telemetry frames. The SDK relays and forgets them:
-        # there is no Centive telemetry endpoint and nothing is stored here.
-        # Called as on_telemetry(user_id, frame); may be sync or async. See
-        # _handle_telemetry.
+        # Product-event sinks for page-telemetry frames. `telemetry` is the
+        # Centive batcher (owned by the client, forwards to POST /anam/events);
+        # `on_telemetry(user_id, frame)` is an optional host callback, sync or
+        # async, that receives the validated frame as well. See _handle_telemetry.
+        self._telemetry = telemetry
+        self._telemetry_rate = ConnectionRateLimiter(
+            config.telemetry_rate_per_connection_per_minute
+        )
         self._on_telemetry = on_telemetry
         self._server: Optional[websockets.WebSocketServer] = None
         self._clients: Set[WebSocketServerProtocol] = set()
@@ -585,6 +592,7 @@ class WebSocketServer:
             # immediately after a drop).
             self._clients.discard(websocket)
             self._connection_users.pop(websocket, None)
+            self._telemetry_rate.forget(websocket)
             session_keys = self._connection_sessions.pop(websocket, set())
 
             safe_log(
@@ -953,9 +961,12 @@ class WebSocketServer:
     ) -> None:
         """handles a page-telemetry frame from the FE SDK.
 
-        The SDK is a relay here, not a store: a validated frame goes to the
-        host's on_telemetry callback and is forgotten. There is no Centive
-        telemetry endpoint, and nothing is buffered.
+        A validated frame feeds up to two sinks: the Centive batcher (which
+        forwards the events to POST /anam/events in batches) and, when set,
+        the host's on_telemetry callback, which receives the whole frame.
+        When the batcher is active its enqueue result is what the ack reports;
+        a callback failure is then logged but does not change the ack, because
+        the events were still accepted for Centive.
 
         Telemetry frames carry a browser_session_id (a client tab, rolled over
         on idle) rather than the chat session_id, so identity is enforced with
@@ -1001,6 +1012,12 @@ class WebSocketServer:
         # still dropped in full, this 0 is just an uncounted one, not a bug.
         event_count = len(events) if isinstance(events, list) else 0
 
+        # Flow control before validation: a chatty producer gets a reasoned
+        # ack it understands, and the socket is never closed for it.
+        if not self._telemetry_rate.allow(websocket):
+            await ack(0, event_count, "rate_limited")
+            return
+
         failure = self._validate_telemetry(data, raw_message)
         if failure is not None:
             kind, code = failure
@@ -1016,11 +1033,31 @@ class WebSocketServer:
                 }))
             return
 
-        if self._on_telemetry is None:
+        batcher_active = self._telemetry is not None and self._config.telemetry_enabled
+        enqueued = 0
+        queue_dropped = 0
+        if batcher_active:
+            # The connection-bound user is authoritative; the frame's own
+            # user_id was already proven absent or equal.
+            parsed = []
+            for event in data["events"]:
+                try:
+                    parsed.append(TelemetryEvent.model_validate(event))
+                except Exception:
+                    queue_dropped += 1  # _validate_telemetry makes this rare
+            enqueued, dropped = self._telemetry.enqueue(user_id, data.get("sdk"), parsed)
+            queue_dropped += dropped
+
+        if self._on_telemetry is None and not batcher_active:
             # Acked rather than errored: the frame was fine, this deployment
             # simply has nowhere to put it. The producer does not retry on a
             # non-zero `dropped`, which is what we want.
-            await ack(0, event_count, "no_telemetry_handler")
+            reason = "telemetry_disabled" if not self._config.telemetry_enabled else "no_telemetry_handler"
+            await ack(0, event_count, reason)
+            return
+
+        if self._on_telemetry is None:
+            await ack(enqueued, event_count - enqueued, "queue_full" if queue_dropped else None)
             return
 
         try:
@@ -1049,7 +1086,12 @@ class WebSocketServer:
                 "on_telemetry callback failed, dropping frame",
                 {"client": client_info, "user_id": user_id, "error": type(e).__name__},
             )
-            await ack(0, event_count, "handler_error")
+            if batcher_active:
+                # The events were still accepted for Centive; the callback
+                # failure is the host's problem, not the producer's.
+                await ack(enqueued, event_count - enqueued, "queue_full" if queue_dropped else None)
+            else:
+                await ack(0, event_count, "handler_error")
             return
 
         # Counts only: page paths, titles and properties are navigation data
@@ -1061,7 +1103,10 @@ class WebSocketServer:
             {"client": client_info, "user_id": user_id, "event_count": event_count},
         )
 
-        await ack(event_count, 0)
+        if batcher_active:
+            await ack(enqueued, event_count - enqueued, "queue_full" if queue_dropped else None)
+        else:
+            await ack(event_count, 0)
 
     async def _save_disconnected_sessions(
         self,

{centive_sdk-2.1.0.dev3.dist-info → centive_sdk-2.2.0.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: centive-sdk
-Version: 2.1.0.dev3
+Version: 2.2.0.dev4
 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
@@ -195,6 +195,11 @@ an expired connection token.
 | `ws_host`             | `str`           | `0.0.0.0`                               | websocket bind address (`127.0.0.1` behind a proxy) |
 | `ws_port`             | `int`           | `8765`                                  | websocket server port                 |
 | `ws_auth_mode`        | `"token" \| "open"` | `"token"`                           | connection identity binding (see Security) |
+| `telemetry_enabled`   | `bool`        | `True`                              | accept `telemetry` frames and forward page events |
+| `telemetry_flush_interval_seconds` | `float` | `2.0`                     | max time an event waits before being sent |
+| `telemetry_flush_max_events` | `int`  | `50`                                | send when this many events are queued |
+| `telemetry_max_queue_events` | `int`  | `5000`                              | bounded queue; oldest dropped when full |
+| `telemetry_rate_per_connection_per_minute` | `int` | `120`               | telemetry frames accepted per socket per minute |
 | `ws_token_ttl_seconds`| `float`         | `3600.0`                                | how long a connection token stays valid |
 | `ws_allowed_origins`  | `list[str]`     | `None`                                  | allow-list of Origin headers for WS handshakes |
 | `ws_handshake_secret` | `str`           | `None`                                  | static shared secret (legacy `"open"` mode only) |
@@ -518,6 +523,54 @@ client = AsyncCentiveClient(
 
 For details on WebSocket event formats, see `websocket_messages.md`.
 
+## Page Tracking (Product Events)
+
+From v2.2.0 the websocket server also accepts `type: "telemetry"` frames from
+the browser SDK. These carry page views and page leaves for the connected end
+user. The SDK validates each frame, queues the events, and forwards them to
+Centive in batches (every 2 seconds or 50 events, whichever comes first).
+
+Nothing is required from your code beyond what you already do for the avatar:
+`initialize_websocket()` starts the queue and `aclose()` flushes it.
+
+```python
+# Optional: emit your own server-side events into the same pipe.
+client.telemetry.track(user_id, "invoice_paid", {"amount": 120})
+
+# Optional: inspect the queue.
+client.telemetry.stats()
+# {'enqueued': 412, 'sent': 410, 'accepted': 398, 'rejected': 12,
+#  'rejections_by_reason': {'user_not_mapped_to_account': 12}, 'queue_depth': 2, ...}
+```
+
+Context back to Aria: when a user has a live Aria session, Centive answers the
+events call with short context lines ("The user just opened the Invoices
+page."). The SDK pushes each one to that user's browser as a `context` frame
+and the browser SDK hands it to the avatar with `anamClient.addContext`. This
+is why page tracking exists: Aria knows where the user is while they talk.
+
+What Centive keeps: only events for end users that `tool_mapping` linked to an
+account in your organization. Events for other users come back in the `202`
+response as `rejected` with reason `user_not_mapped_to_account`; they are
+counted in `stats()` and never retried. If that number is high, the
+`company_name` you pass to `tool_mapping` does not match the account names in
+Centive.
+
+Safety properties:
+
+- The browser cannot spoof identity: the frame's `user_id` must match the user
+  bound to the socket, exactly like transcript frames.
+- Frames over 100 events or 64 KB, and more than 120 frames per minute per
+  connection, are dropped with a reasoned ack. The socket is never closed for
+  a telemetry violation.
+- The queue is bounded (`telemetry_max_queue_events`, default 5000). When full,
+  the oldest events are dropped and counted. The websocket handler never blocks.
+- Telemetry has its own circuit breaker; a failing events endpoint cannot stop
+  transcript saves.
+- Set `telemetry_enabled=False` to turn the feature off entirely.
+
+Wire contract: `docs/product-events/CONTRACTS.md` in the CentiveAI repository.
+
 ## Page Telemetry
 
 The FE SDK (`@centive/aria-sdk` 1.1.0+) sends page-view and page-leave events over

centive_sdk-2.2.0.dev4.dist-info/RECORD

@@ -0,0 +1,23 @@
+centive_sdk/__init__.py,sha256=JK6YZh1ZNQC1Wxoxot1cDZtP_Ulb20HmIB5Qnz7hiFc,2145
+centive_sdk/_http.py,sha256=hJlHSov6Wvj2ok3R_EczTS3KgIIUv7QE3Kj9yHIfyyc,1056
+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/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/responses.py,sha256=zCYPB0aL2DXn-z0Febkuxo3DdZ_5sdpdGy2Jtf8Ubs8,2519
+centive_sdk/resources/__init__.py,sha256=GLutz38X4F4FwPfSZy35EkWTV7l7t9RgcBKwXmz2X_Y,179
+centive_sdk/resources/async_sessions.py,sha256=P7BDnkTKKU26kSCK5p91R593FurOHCHH0iF8PcTU1ZQ,20691
+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=Oiysy_TsvxZU26H0vUjlWB5sH8M5krSuL9RjZgwDQiw,13537
+centive_sdk/resources/websocket_server.py,sha256=iGS48oB4myV-sI0nArlBE3Y0fe_GlfBClFtVAPzrvdU,59760
+centive_sdk-2.2.0.dev4.dist-info/METADATA,sha256=TAMEhgIrXDXIyl_E-T8tCqJNEZS9ZumpFUpPYTKgZic,36427
+centive_sdk-2.2.0.dev4.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+centive_sdk-2.2.0.dev4.dist-info/licenses/LICENSE,sha256=9dFibPr7z9srhWwd35lQL2MX1Kx2qivEZdVQb9L8Q-Q,1064
+centive_sdk-2.2.0.dev4.dist-info/RECORD,,

centive_sdk-2.1.0.dev3.dist-info/RECORD

@@ -1,21 +0,0 @@
-centive_sdk/__init__.py,sha256=k7XAv5O8EVnFfe7VAFGmBeQRcrstn030LcKEW2wWllY,1801
-centive_sdk/_http.py,sha256=hJlHSov6Wvj2ok3R_EczTS3KgIIUv7QE3Kj9yHIfyyc,1056
-centive_sdk/_logging.py,sha256=GRNnqzNY_9SFP2mk3wSIfoyHwVZfNAHY3uTZ9vv1ihQ,3248
-centive_sdk/_retry.py,sha256=Q1cIFZyimj0RS4x14FEOseqpORCSydvJyzGiIPfDn7E,1755
-centive_sdk/async_client.py,sha256=NF8FGac3vXHqaqWyH5XQuznn_uGO-GDgcY-R_p8LL3Q,7776
-centive_sdk/client.py,sha256=Evtsng8cqqRSoV54MI2IKbEW1q0vPOkxlz9zM0evH7k,3249
-centive_sdk/config.py,sha256=uUDpYOeZYBAf24HmyNZiTqj_nQdbaFKQ2BLqwtFMQjQ,5379
-centive_sdk/exceptions.py,sha256=wFy-hU0TJ0dHa6TEDI7FIQu9Lbg5aMeWxW9E-IMMUbI,1841
-centive_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-centive_sdk/models/__init__.py,sha256=-O7bQ0j1-QabhMqvI4AK8Aj5RHLFUbilKY08zJlnxYM,306
-centive_sdk/models/requests.py,sha256=XD6b6Dh1mSvDK-J5Q5JEOUCIQ7ozaaNK7NAYhC_Vt78,4195
-centive_sdk/models/responses.py,sha256=kPph7xXh2pVbY9EAGSdFXss-51Z0CwpaUisDFtnXUQU,2035
-centive_sdk/resources/__init__.py,sha256=GLutz38X4F4FwPfSZy35EkWTV7l7t9RgcBKwXmz2X_Y,179
-centive_sdk/resources/async_sessions.py,sha256=bFQSkRSGwB4yd1O-fUaTuEFdL3MLz6Z3G-HmtAZQgGw,19145
-centive_sdk/resources/message_accumulator.py,sha256=Or3sMGkXG9upeQ9sm8YWL_V5vvsxtnE9tu52VBUUGgY,19261
-centive_sdk/resources/sessions.py,sha256=Ipg4bpmpejA5WoALbT49ah0c3I7x4OgPn9tSmfW8JAw,16741
-centive_sdk/resources/websocket_server.py,sha256=uR8-rVD_nwe2-mLGvp_R6_oUltDhnUcCDGnBJLz_iDs,57440
-centive_sdk-2.1.0.dev3.dist-info/METADATA,sha256=O7o_1odgUD5xaXGjDlvmntKSYesessg5AS9lEqQX92s,33454
-centive_sdk-2.1.0.dev3.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-centive_sdk-2.1.0.dev3.dist-info/licenses/LICENSE,sha256=9dFibPr7z9srhWwd35lQL2MX1Kx2qivEZdVQb9L8Q-Q,1064
-centive_sdk-2.1.0.dev3.dist-info/RECORD,,