centive-sdk 2.0.0__py3-none-any.whl

centive_sdk/__init__.py

@@ -0,0 +1,62 @@
+from .async_client import AsyncCentiveClient
+from .client import CentiveClient
+from .exceptions import (
+    AuthError,
+    CentiveError,
+    NetworkError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from .models.requests import (
+    MessageHistoryEvent,
+    MessageStreamEvent,
+    SaveMessagesRequest,
+    SessionEndEvent,
+    SessionMessage,
+    SessionMetadata,
+    StreamMessage,
+    ToolMappingRequest,
+    TriggerSessionRequest,
+)
+from .models.responses import (
+    PauseStatusResponse,
+    SaveMessagesResponse,
+    ToolMappingResponse,
+    TriggerSessionResponse,
+)
+from .resources.message_accumulator import MessageAccumulator
+from .resources.websocket_server import WebSocketServer
+
+__version__ = "2.0.0"
+
+__all__ = [
+    # Clients
+    "CentiveClient",
+    "AsyncCentiveClient",
+    # Request Models
+    "ToolMappingRequest",
+    "TriggerSessionRequest",
+    "SaveMessagesRequest",
+    "SessionMessage",
+    "SessionMetadata",
+    "StreamMessage",
+    "MessageHistoryEvent",
+    "MessageStreamEvent",
+    "SessionEndEvent",
+    # Response Models
+    "ToolMappingResponse",
+    "TriggerSessionResponse",
+    "SaveMessagesResponse",
+    "PauseStatusResponse",
+    # Resources
+    "WebSocketServer",
+    "MessageAccumulator",
+    # Exceptions
+    "CentiveError",
+    "AuthError",
+    "ValidationError",
+    "RateLimitError",
+    "ServerError",
+    "NetworkError",
+]

centive_sdk/_http.py

@@ -0,0 +1,34 @@
+from typing import Optional
+
+
+def join_url(base: str, path: str) -> str:
+    """Safely joins a base URL with a path, avoiding double slashes.
+
+    Ensures exactly one slash between base and path components,
+    preventing malformed URLs from trailing/leading slash mismatches.
+
+    Examples:
+        join_url("https://api.test", "/path") -> "https://api.test/path"
+        join_url("https://api.test/", "/path") -> "https://api.test/path"
+        join_url("https://api.test", "path") -> "https://api.test/path"
+    """
+    base = base.rstrip("/")
+    path = path.lstrip("/")
+    return f"{base}/{path}"
+
+
+def build_headers(api_key: str, idempotency_key: Optional[str] = None) -> dict:
+    """Builds HTTP headers for Centive API requests.
+
+    Includes X-API-Key header for authentication and optional
+    Idempotency-Key header for safe request retries.
+    """
+    headers = {
+        "X-API-Key": api_key,
+        "Content-Type": "application/json",
+    }
+
+    if idempotency_key:
+        headers["Idempotency-Key"] = idempotency_key
+
+    return headers

centive_sdk/_logging.py

@@ -0,0 +1,98 @@
+import logging
+import re
+from copy import deepcopy
+from typing import Any, Optional
+
+# Connection tokens travel in the websocket URL's query string, so the transport
+# layer's own debug logging would otherwise write them to the host application's
+# log files verbatim.
+_TOKEN_IN_URL = re.compile(r"(token=)[^&\s\"'>]+")
+
+
+def _scrub(value: Any) -> Any:
+    if isinstance(value, str) and "token=" in value:
+        return _TOKEN_IN_URL.sub(r"\1[REDACTED]", value)
+    return value
+
+
+class TokenRedactingFilter(logging.Filter):
+    """Strips connection tokens out of log records before they are emitted."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        record.msg = _scrub(record.msg)
+        if record.args:
+            if isinstance(record.args, dict):
+                record.args = {k: _scrub(v) for k, v in record.args.items()}
+            elif isinstance(record.args, tuple):
+                record.args = tuple(_scrub(a) for a in record.args)
+        return True
+
+
+def transport_logger(parent: Optional[Any] = None) -> logging.Logger:
+    """Returns the logger handed to the websocket transport, with token redaction.
+
+    Child of the caller's logger when one is supplied, so the host application's
+    handlers and level still apply, but never carries raw tokens.
+    """
+    if isinstance(parent, logging.Logger):
+        logger = parent.getChild("centive_ws")
+    else:
+        logger = logging.getLogger("centive_sdk.websocket")
+
+    if not any(isinstance(f, TokenRedactingFilter) for f in logger.filters):
+        logger.addFilter(TokenRedactingFilter())
+    return logger
+
+
+def mask_string(s: str) -> str:
+    """Masks a string by showing only the first 2 characters followed by ***.
+
+    Examples:
+        "Harrison" -> "Ha***"
+        "TheAgentic" -> "Th***"
+        "AB" -> "AB***"
+        "A" -> "A***"
+    """
+    if len(s) <= 2:
+        return f"{s}***"
+    return f"{s[:2]}***"
+
+
+def redact_request_data(data: dict) -> dict:
+    """Deep copies a dictionary and redacts sensitive fields.
+
+    Masks user_name and company_name, completely redacts api_key.
+    Preserves the structure of the original dictionary.
+    """
+    redacted = deepcopy(data)
+
+    if "user_name" in redacted:
+        redacted["user_name"] = mask_string(str(redacted["user_name"]))
+
+    if "company_name" in redacted:
+        redacted["company_name"] = mask_string(str(redacted["company_name"]))
+
+    for secret_field in ("api_key", "token", "connection_token", "ws_handshake_secret"):
+        if secret_field in redacted:
+            redacted[secret_field] = "[REDACTED]"
+
+    return redacted
+
+
+def safe_log(logger: Optional[Any], level: str, message: str, extra: Optional[dict] = None) -> None:
+    """Safely logs a message with automatic PII redaction.
+
+    Only logs if a logger is provided. Applies redaction to any extra
+    data before logging to prevent accidental exposure of secrets or PII.
+    """
+    if logger is None:
+        return
+
+    redacted_extra = redact_request_data(extra) if extra else {}
+
+    log_method = getattr(logger, level.lower(), None)
+    if log_method and callable(log_method):
+        if redacted_extra:
+            log_method(f"{message} {redacted_extra}")
+        else:
+            log_method(message)

centive_sdk/_retry.py

@@ -0,0 +1,57 @@
+import random
+from datetime import datetime
+from typing import Optional
+
+
+def should_retry(status_code: int, attempt: int, max_retries: int) -> bool:
+    """Determines if a request should be retried based on status code and attempt count.
+
+    Retries are allowed for:
+    - 429 (rate limit)
+    - 5xx (server errors)
+    - Network errors (handled separately)
+
+    Returns False if max_retries has been reached.
+    """
+    if attempt >= max_retries:
+        return False
+
+    return status_code == 429 or status_code >= 500
+
+
+def calculate_backoff(attempt: int, initial: float, max_delay: float) -> float:
+    """Calculates exponential backoff with jitter for retry delays.
+
+    Uses exponential backoff (initial * 2^attempt) capped at max_delay,
+    with added random jitter to prevent thundering herd.
+
+    Formula: min(max_delay, initial * 2^attempt) + random(0, 1)
+    """
+    delay = min(max_delay, initial * (2**attempt))
+    jitter = random.uniform(0, 1)
+    return delay + jitter
+
+
+def extract_retry_after(headers: dict) -> Optional[int]:
+    """Extracts Retry-After header value in seconds.
+
+    Supports both:
+    - Integer seconds: "Retry-After: 120"
+    - HTTP date format: "Retry-After: Wed, 21 Oct 2015 07:28:00 GMT"
+
+    Returns None if header is missing or cannot be parsed.
+    """
+    retry_after = headers.get("Retry-After") or headers.get("retry-after")
+
+    if not retry_after:
+        return None
+
+    try:
+        return int(retry_after)
+    except ValueError:
+        try:
+            retry_date = datetime.strptime(retry_after, "%a, %d %b %Y %H:%M:%S %Z")
+            delta = retry_date - datetime.utcnow()
+            return max(0, int(delta.total_seconds()))
+        except (ValueError, OverflowError):
+            return None

centive_sdk/async_client.py

@@ -0,0 +1,179 @@
+import asyncio
+from typing import Optional
+
+import httpx
+
+from ._logging import safe_log
+from .config import ClientConfig
+from .models.responses import PauseStatusResponse
+from .resources.async_sessions import AsyncSessions
+from .resources.websocket_server import WebSocketServer
+
+
+class AsyncCentiveClient:
+    """Asynchronous client for the Centive API.
+
+    Flow:
+    1. At login: call sessions.tool_mapping()
+    2. From an authenticated endpoint: call initialize_websocket(user_id)
+       -> returns a connection token bound to that user
+    3. SDK internally checks if Aria is paused
+    4. If paused: WebSocket is NOT started and no token is issued
+    5. If not paused: WebSocket starts; return the token to your frontend as
+       part of its websocket URL (wss://your-host/ws?token=<value>) and the
+       FE SDK connects with it
+
+    Example:
+        client = AsyncCentiveClient(api_key="sk_live_...")
+
+        # At login (user comes from YOUR authentication, e.g. session/JWT)
+        await client.sessions.tool_mapping(ToolMappingRequest(...))
+
+        @app.post("/api/login")
+        async def login(user = Depends(get_current_user)):
+            token = await client.initialize_websocket(user_id=user.id)
+            return {"aria_websocket_url": f"wss://your-host/ws?token={token}" if token else None}
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, **options):
+        """Initializes the async Centive client.
+
+        api_key and base_url fall back to the CENTIVE_API_KEY and CENTIVE_BASE_URL
+        environment variables when not passed explicitly.
+        """
+        if api_key is not None:
+            options["api_key"] = api_key
+        if base_url is not None:
+            options["base_url"] = base_url
+        self.config = ClientConfig(**options)
+        self._http_client = httpx.AsyncClient()
+        self._logger = options.get("logger")
+        self.sessions = AsyncSessions(self._http_client, self.config, 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
+        # first logins cannot race to bind the same port.
+        self._ws_lock = asyncio.Lock()
+
+    async def initialize_websocket(
+        self,
+        user_id: str,
+        host: Optional[str] = None,
+        port: Optional[int] = None,
+        **ws_options,
+    ) -> Optional[str]:
+        """Initializes WebSocket for real-time FE SDK communication.
+
+        Internally checks if Aria is paused for this user:
+        - If paused: no WebSocket server starts. FE cannot connect, so the
+          avatar button stays hidden.
+        - If active: WebSocket starts, FE connects, session triggered.
+
+        Args:
+            user_id: ID of the user (from your existing authentication — never
+                from an unauthenticated request parameter)
+            host: WebSocket server host (default from config)
+            port: WebSocket server port (default from config)
+
+        Returns:
+            The connection token for this user (default ws_auth_mode="token").
+            Include it in the websocket URL your frontend passes to the FE SDK,
+            e.g. wss://your-host/ws?token=<value>. The connection is bound to
+            this user and the token expires after ws_token_ttl_seconds.
+            Returns None when Aria is paused or in legacy ws_auth_mode="open".
+        """
+        try:
+            pause_status = await self.sessions.get_pause_status(user_id)
+            self._last_pause_status = pause_status
+
+            if pause_status.is_paused:
+                safe_log(
+                    self._logger,
+                    "info",
+                    "Aria is paused for this user, withholding access",
+                    {
+                        "user_id": user_id,
+                        "pause_source": pause_status.pause_source,
+                        "paused_until": pause_status.paused_until,
+                    },
+                )
+                # Affect only this user: revoke their tokens and close their
+                # sockets. The server is shared, so stopping it would disconnect
+                # every other user mid-conversation.
+                if self._ws_server is not None and self._ws_server.is_running:
+                    await self._ws_server.disconnect_user(user_id, reason="aria paused")
+                return None
+        except Exception as e:
+            if not self.config.pause_check_fail_open:
+                safe_log(
+                    self._logger,
+                    "error",
+                    f"Pause status check failed and fail-open is disabled: {e}",
+                    {"user_id": user_id},
+                )
+                return None
+            safe_log(
+                self._logger,
+                "warning",
+                f"Failed to check pause status, proceeding as active: {e}",
+                {"user_id": user_id},
+            )
+
+        ws_host = host or self.config.ws_host
+        ws_port = port or self.config.ws_port
+
+        async with self._ws_lock:
+            if self._ws_server is None or not self._ws_server.is_running:
+                server = WebSocketServer(
+                    sessions=self.sessions,
+                    config=self.config,
+                    logger=self._logger,
+                )
+                # 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
+
+        return self._ws_server.register_user(user_id)
+
+    async def get_aria_status(self, user_id: str) -> PauseStatusResponse:
+        """Checks if Aria is paused for a user (for UI display purposes).
+
+        Use this if you want to show pause status in your UI. Otherwise,
+        initialize_websocket() handles everything automatically.
+
+        Args:
+            user_id: External user ID to check
+
+        Returns:
+            PauseStatusResponse with is_paused, pause_source, message, etc.
+        """
+        return await self.sessions.get_pause_status(user_id)
+
+    @property
+    def last_pause_status(self) -> Optional[PauseStatusResponse]:
+        """Returns the pause status from the last initialize_websocket() call.
+
+        Useful if you want to check the status after calling initialize_websocket()
+        without making another API call.
+        """
+        return self._last_pause_status
+
+    @property
+    def websocket_server(self) -> Optional[WebSocketServer]:
+        """Returns the WebSocket server instance if initialized."""
+        return self._ws_server
+
+    async def aclose(self) -> None:
+        """Closes the async HTTP client, WebSocket server, and releases resources."""
+        if self._ws_server is not None:
+            await self._ws_server.stop()
+            self._ws_server = None
+
+        await self._http_client.aclose()
+
+    async def __aenter__(self) -> "AsyncCentiveClient":
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.aclose()

centive_sdk/client.py

@@ -0,0 +1,87 @@
+from typing import Optional
+
+import httpx
+
+from .config import ClientConfig
+from .models.responses import PauseStatusResponse
+from .resources.sessions import Sessions
+
+
+class CentiveClient:
+    """Synchronous client for the Centive API.
+
+    Provides a high-level interface for interacting with Centive services,
+    including tool mapping, session triggering, and pause status checking.
+    Note that WebSocket functionality is only available in the async client.
+
+    Example:
+        client = CentiveClient(api_key="sk_live_...")
+
+        # Map user to tool at login
+        result = client.sessions.tool_mapping(ToolMappingRequest(...))
+
+        # Check if Aria is paused
+        status = client.get_aria_status("user_123")
+        if not status.is_paused:
+            # Trigger session when needed
+            session = client.sessions.trigger_session(TriggerSessionRequest(...))
+
+        client.close()
+
+        # Or using context manager:
+        with CentiveClient(api_key="sk_live_...") as client:
+            client.sessions.tool_mapping(...)
+    """
+
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, **options):
+        """Initializes the Centive client.
+
+        Args:
+            api_key: API key for authentication (falls back to the
+                CENTIVE_API_KEY environment variable)
+            base_url: Base URL for the Centive API (falls back to CENTIVE_BASE_URL,
+                then to Centive production)
+            **options: Additional configuration options including:
+                - tool_mapping_path: Custom path for tool mapping endpoint
+                - trigger_session_path: Custom path for trigger session endpoint
+                - pause_status_path: Custom path for pause status endpoint
+                - timeout_seconds: HTTP request timeout
+                - max_retries: Maximum retry attempts
+                - initial_retry_delay: Initial delay between retries
+                - max_retry_delay: Maximum delay between retries
+                - logger: Custom logger instance
+        """
+        if api_key is not None:
+            options["api_key"] = api_key
+        if base_url is not None:
+            options["base_url"] = base_url
+        self.config = ClientConfig(**options)
+        self._http_client = httpx.Client()
+        self._logger = options.get("logger")
+        self.sessions = Sessions(self._http_client, self.config, self._logger)
+
+    def get_aria_status(self, user_id: str) -> PauseStatusResponse:
+        """Checks if Aria is paused for a user.
+
+        Use this to check Aria's availability before triggering sessions
+        or to display pause status in your UI.
+
+        Args:
+            user_id: External user ID to check
+
+        Returns:
+            PauseStatusResponse with is_paused, pause_source, message, etc.
+        """
+        return self.sessions.get_pause_status(user_id)
+
+    def close(self) -> None:
+        """Closes the HTTP client and releases resources."""
+        self._http_client.close()
+
+    def __enter__(self) -> "CentiveClient":
+        """Enters the context manager."""
+        return self
+
+    def __exit__(self, *args) -> None:
+        """Exits the context manager and closes the client."""
+        self.close()

centive_sdk/config.py

@@ -0,0 +1,114 @@
+import os
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+# Known Centive API environments. Selection precedence for the base URL:
+#   base_url param > CENTIVE_BASE_URL env > environment param > CENTIVE_ENVIRONMENT env > "prod"
+ENVIRONMENT_URLS = {
+    "prod": "https://centive-prod-api.theagentic.ai/api",
+    "dev": "https://centive-api.theagentic.ai/api",
+}
+
+
+def _env_environment() -> str:
+    return os.environ.get("CENTIVE_ENVIRONMENT", "prod")
+
+
+def _env_base_url() -> Optional[str]:
+    return os.environ.get("CENTIVE_BASE_URL")
+
+
+def _env_api_key() -> str:
+    return os.environ.get("CENTIVE_API_KEY", "")
+
+
+class ClientConfig(BaseModel):
+    """configuration for the Centive SDK client with API, websocket, and accumulator settings.
+
+    api_key falls back to the CENTIVE_API_KEY environment variable. The target
+    API is chosen via environment ("prod" / "dev", or the CENTIVE_ENVIRONMENT
+    env var); an explicit base_url or CENTIVE_BASE_URL overrides it.
+    """
+
+    environment: Literal["prod", "dev"] = Field(default_factory=_env_environment)
+    base_url: Optional[str] = Field(default_factory=_env_base_url)
+    api_key: str = Field(default_factory=_env_api_key, validate_default=True)
+    tool_mapping_path: str = "/anam/tool-mapping"
+    trigger_session_path: str = "/anam/trigger-session"
+    save_messages_path: str = "/anam/save-messages"
+    pause_status_path: str = "/anam/pause-status"
+    timeout_seconds: float = 10.0
+    max_retries: int = 3
+    initial_retry_delay: float = 0.5
+    max_retry_delay: float = 8.0
+
+    ws_host: str = "0.0.0.0"  # bind address; set 127.0.0.1 when fronted by a proxy
+    ws_port: int = 8765
+    ws_path: str = "/ws"
+    # Identity binding for FE connections:
+    #   "token" (default): register_user() issues a per-user connection token; the FE
+    #     must connect with ?token=<value> and the socket is bound to that user only.
+    #   "open" (deprecated): legacy pre-2.0 behavior — first socket to connect is
+    #     assigned the next registered user and client frames are trusted. Insecure;
+    #     kept only as a migration escape hatch.
+    ws_auth_mode: Literal["token", "open"] = "token"
+    # How long an issued connection token stays valid. Tokens are reusable within
+    # their TTL so the FE SDK's automatic reconnect keeps working mid-conversation.
+    ws_token_ttl_seconds: float = 3600.0
+    # When set, the server rejects WS handshakes whose Origin is not allow-listed.
+    ws_allowed_origins: Optional[list[str]] = None
+    # Static shared secret checked as ?token= on the handshake. Only honored in
+    # ws_auth_mode="open"; in "token" mode the per-user token replaces it.
+    ws_handshake_secret: Optional[str] = None
+    ws_ping_interval: float = 20.0
+    ws_ping_timeout: float = 20.0
+    ws_close_timeout: float = 10.0
+    ws_max_size: int = 1048576
+    ws_compression: Optional[str] = "deflate"
+
+    auto_save_interval_seconds: float = 300.0
+    circuit_breaker_threshold: int = 5
+    circuit_breaker_recovery_seconds: float = 60.0
+
+    # Memory and abuse bounds so no single end-user can exhaust the host process.
+    max_sessions_per_user: int = 10
+    max_stream_messages_per_session: int = 10000
+    # Accumulated message bytes retained per session. Counts actual content, not
+    # message count, so a few very large frames cannot blow past the limit.
+    max_session_bytes: int = 2_000_000
+    # Longest single message accepted. Frames above this are rejected outright.
+    max_message_content_chars: int = 32_768
+    max_session_id_chars: int = 200
+    # Concurrent websocket connections accepted per user.
+    max_connections_per_user: int = 5
+
+    # When the pause-status check fails (upstream 5xx, rate limit, network), the
+    # SDK proceeds as active so a Centive outage does not hide every avatar. Set
+    # False to fail closed and withhold connections instead.
+    pause_check_fail_open: bool = True
+
+    incremental_save_enabled: bool = Field(
+        default=False,
+        description="enable incremental message saving (sends messages to API immediately as they arrive)"
+    )
+    incremental_save_mode: str = Field(
+        default="immediate",
+        description="mode for incremental saves: 'immediate' sends each message right away"
+    )
+
+    @field_validator("api_key")
+    @classmethod
+    def _api_key_required(cls, v: str) -> str:
+        if not v:
+            raise ValueError(
+                "api_key is required: pass api_key=... or set the CENTIVE_API_KEY "
+                "environment variable"
+            )
+        return v
+
+    @model_validator(mode="after")
+    def _resolve_base_url(self) -> "ClientConfig":
+        if not self.base_url:
+            self.base_url = ENVIRONMENT_URLS[self.environment]
+        return self