cortex-suite-sdk 1.0.2__tar.gz

cortex_suite_sdk-1.0.2/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/

cortex_suite_sdk-1.0.2/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.4
+Name: cortex-suite-sdk
+Version: 1.0.2
+Summary: Cortex SDK — transport client for Python
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: anyio[trio]; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: jsonschema>=4.23; extra == 'dev'
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Cortex SDK for Python
+
+## Install
+
+`pip install cortex-suite-sdk`
+
+## Quick start
+
+```python
+import asyncio
+
+from cortex_sdk import CortexClient
+
+
+def on_message(msg):
+    print(msg["type"], msg["payload"])
+
+
+async def main():
+    client = CortexClient(
+        api_key="your-api-key",
+        # auth_url="https://auth.cortexsuite.app",  # optional override
+        on_message=on_message,
+    )
+    await client.connect()
+    await client.send_message(content="Hello")
+
+
+asyncio.run(main())
+```
+
+## API
+
+See the [full API reference](../docs/04_api_reference.md).
+`auth_url` is optional; if omitted, the SDK uses its default auth base URL.
+
+## Error handling
+
+```python
+from cortex_sdk import CortexClient, CortexError
+
+
+def on_message(msg):
+    if msg["type"] == "system::error":
+        print("Runtime error:", msg["payload"]["code"])
+        if msg["payload"].get("fatal"):
+            pass  # handle unrecoverable session
+
+
+client = CortexClient(
+    api_key="your-api-key",
+    on_message=on_message,
+)
+
+try:
+    await client.connect()
+except CortexError as err:
+    if err.code in ("auth_invalid", "auth_refresh_failed"):
+        pass  # prompt re-authentication
+```

cortex_suite_sdk-1.0.2/README.md

@@ -0,0 +1,60 @@
+# Cortex SDK for Python
+
+## Install
+
+`pip install cortex-suite-sdk`
+
+## Quick start
+
+```python
+import asyncio
+
+from cortex_sdk import CortexClient
+
+
+def on_message(msg):
+    print(msg["type"], msg["payload"])
+
+
+async def main():
+    client = CortexClient(
+        api_key="your-api-key",
+        # auth_url="https://auth.cortexsuite.app",  # optional override
+        on_message=on_message,
+    )
+    await client.connect()
+    await client.send_message(content="Hello")
+
+
+asyncio.run(main())
+```
+
+## API
+
+See the [full API reference](../docs/04_api_reference.md).
+`auth_url` is optional; if omitted, the SDK uses its default auth base URL.
+
+## Error handling
+
+```python
+from cortex_sdk import CortexClient, CortexError
+
+
+def on_message(msg):
+    if msg["type"] == "system::error":
+        print("Runtime error:", msg["payload"]["code"])
+        if msg["payload"].get("fatal"):
+            pass  # handle unrecoverable session
+
+
+client = CortexClient(
+    api_key="your-api-key",
+    on_message=on_message,
+)
+
+try:
+    await client.connect()
+except CortexError as err:
+    if err.code in ("auth_invalid", "auth_refresh_failed"):
+        pass  # prompt re-authentication
+```

cortex_suite_sdk-1.0.2/cortex_sdk/__init__.py

@@ -0,0 +1,4 @@
+from .client import CortexClient
+from .errors import CortexError
+
+__all__ = ["CortexClient", "CortexError"]

cortex_suite_sdk-1.0.2/cortex_sdk/_generated_constants.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+# Generated from shared/constants.json. Do not edit manually.
+
+DEFAULT_AUTH_URL: str = 'https://auth.cortexsuite.app'
+AUTH_TOKEN_PATH: str = '/auth/token'
+AUTH_REFRESH_PATH: str = '/auth/refresh'
+WS_SUBPROTOCOL: str = 'cortex-sdk.v1'
+WS_SUBPROTOCOL_JWT_PREFIX: str = 'cortex-sdk.jwt.'
+SCHEMA_VERSION: str = '1.0'
+
+DEFAULT_CONNECT_TIMEOUT_MS: int = 10000
+DEFAULT_SEND_TIMEOUT_MS: int = 10000
+DEFAULT_RESYNC_TIMEOUT_MS: int = 15000
+DEFAULT_PING_INTERVAL_MS: int = 15000
+DEFAULT_PONG_TIMEOUT_MS: int = 5000
+DEFAULT_STALE_THRESHOLD_MS: int = 45000
+TOKEN_REFRESH_BUFFER_MS: int = 60000
+
+RECONNECT_BACKOFF_MS: tuple[int, ...] = (1000, 2000, 5000, 10000, 20000, 30000,)
+
+# Deprecated compatibility aliases. Prefer DEFAULT_AUTH_URL/AUTH_TOKEN_PATH,
+# DEFAULT_AUTH_URL/AUTH_REFRESH_PATH, and WS_SUBPROTOCOL directly.
+CORTEX_AUTH_URL: str = DEFAULT_AUTH_URL + AUTH_TOKEN_PATH
+CORTEX_REFRESH_URL: str = DEFAULT_AUTH_URL + AUTH_REFRESH_PATH
+WS_SUBPROTOCOL_BASE: str = WS_SUBPROTOCOL

cortex_suite_sdk-1.0.2/cortex_sdk/_generated_errors.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+# Generated from sdk/shared/errors.json. Do not edit manually.
+
+@dataclass(frozen=True)
+class GeneratedErrorEntry:
+    code: str
+    retryable: bool
+    fatal: bool
+
+GENERATED_ERROR_CATALOG: tuple[GeneratedErrorEntry, ...] = (
+    GeneratedErrorEntry('auth_invalid', retryable=False, fatal=True),
+    GeneratedErrorEntry('auth_expired', retryable=True, fatal=False),
+    GeneratedErrorEntry('auth_refresh_failed', retryable=False, fatal=True),
+    GeneratedErrorEntry('transport_connect_timeout', retryable=True, fatal=False),
+    GeneratedErrorEntry('transport_send_timeout', retryable=True, fatal=False),
+    GeneratedErrorEntry('transport_protocol_violation', retryable=False, fatal=True),
+    GeneratedErrorEntry('session_not_found', retryable=False, fatal=True),
+    GeneratedErrorEntry('session_terminal', retryable=False, fatal=True),
+    GeneratedErrorEntry('resync_timeout', retryable=True, fatal=False),
+    GeneratedErrorEntry('replay_unavailable', retryable=True, fatal=False),
+    GeneratedErrorEntry('upload_failed', retryable=True, fatal=False),
+    GeneratedErrorEntry('upload_too_large', retryable=False, fatal=False),
+    GeneratedErrorEntry('upload_type_rejected', retryable=False, fatal=False),
+)

cortex_suite_sdk-1.0.2/cortex_sdk/auth.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import base64
+import json
+import time
+
+import httpx
+
+from .constants import (
+    DEFAULT_AUTH_URL,
+    AUTH_TOKEN_PATH,
+    AUTH_REFRESH_PATH,
+    TOKEN_REFRESH_BUFFER,
+)
+from .errors import make_error
+from .types import AuthTokenResponse
+
+
+def _parse_jwt_exp(token: str) -> float | None:
+    """Extract exp (as Unix timestamp in seconds) from a JWT without verifying signature."""
+    try:
+        parts = token.split(".")
+        if len(parts) != 3:
+            return None
+        # base64url → base64 standard (add padding)
+        payload_b64 = parts[1]
+        # Add padding
+        padding = 4 - len(payload_b64) % 4
+        if padding != 4:
+            payload_b64 += "=" * padding
+        payload_json = base64.urlsafe_b64decode(payload_b64)
+        payload = json.loads(payload_json)
+        exp = payload.get("exp")
+        return float(exp) if isinstance(exp, (int, float)) else None
+    except Exception:
+        return None
+
+
+def is_token_expiring_soon(access_token: str) -> bool:
+    """Return True if the token expires within TOKEN_REFRESH_BUFFER seconds."""
+    exp = _parse_jwt_exp(access_token)
+    if exp is None:
+        return False
+    return time.time() > exp - TOKEN_REFRESH_BUFFER
+
+
+async def exchange_api_key(
+    api_key: str,
+    *,
+    auth_base_url: str = DEFAULT_AUTH_URL,
+) -> AuthTokenResponse:
+    """Exchange an API key for tokens and WS URL."""
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            _build_auth_endpoint(auth_base_url, AUTH_TOKEN_PATH),
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"ApiKey {api_key}",
+            },
+        )
+
+    if not resp.is_success:
+        try:
+            body = resp.json()
+            code = body.get("error", "auth_invalid")
+            message = body.get("message", "API key rejected")
+        except Exception:
+            code, message = "auth_invalid", "API key rejected"
+        raise make_error(str(code), str(message))
+
+    return resp.json()  # type: ignore[no-any-return]
+
+
+async def refresh_access_token(
+    refresh_token: str,
+    *,
+    auth_base_url: str = DEFAULT_AUTH_URL,
+) -> str:
+    """Refresh the access token using the refresh token."""
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            _build_auth_endpoint(auth_base_url, AUTH_REFRESH_PATH),
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {refresh_token}",
+            },
+        )
+
+    if not resp.is_success:
+        raise make_error("auth_refresh_failed", "Refresh token expired or invalid")
+
+    body = resp.json()
+    return str(body["access_token"])
+
+
+def normalize_auth_base_url(auth_url: str) -> str:
+    import warnings
+    normalized = auth_url.rstrip("/")
+    # Guard: consumer may have passed a full endpoint instead of the base URL.
+    # Strip known auth paths and warn so developers catch the misconfiguration early.
+    for known_path in [AUTH_TOKEN_PATH, AUTH_REFRESH_PATH]:
+        if normalized.endswith(known_path):
+            base = normalized[: -len(known_path)]
+            warnings.warn(
+                f"[CortexSDK] auth_url must be a base URL (origin only), not a full endpoint. "
+                f'Received "{auth_url}" — "{known_path}" has been stripped automatically. '
+                f'Pass the base URL only, e.g., "{base}".',
+                UserWarning,
+                stacklevel=3,
+            )
+            normalized = base
+            break
+    return normalized or DEFAULT_AUTH_URL
+
+
+def _build_auth_endpoint(auth_base_url: str, path: str) -> str:
+    return f"{normalize_auth_base_url(auth_base_url)}{path}"

cortex_suite_sdk-1.0.2/cortex_sdk/client.py

@@ -0,0 +1,331 @@
+from __future__ import annotations
+
+import asyncio
+import secrets
+from typing import BinaryIO
+from urllib.parse import urlsplit, urlunsplit
+
+from .auth import (
+    exchange_api_key,
+    refresh_access_token,
+    is_token_expiring_soon,
+    normalize_auth_base_url,
+)
+from .constants import (
+    DEFAULT_AUTH_URL,
+    DEFAULT_CONNECT_TIMEOUT,
+    DEFAULT_SEND_TIMEOUT,
+    DEFAULT_RESYNC_TIMEOUT,
+    DEFAULT_PING_INTERVAL,
+    DEFAULT_PONG_TIMEOUT,
+    DEFAULT_STALE_THRESHOLD,
+    TOKEN_REFRESH_BUFFER,
+    RECONNECT_BACKOFF,
+)
+from .errors import CortexError, make_error
+from .liveness import LivenessMonitor
+from .session import SessionManager
+from .transport import Transport
+from .types import ChannelState, CortexMessage, MessageCallback, SessionState
+from .upload import upload_file
+
+
+class CortexClient:
+    """Cortex SDK client — one instance per session.
+
+    Public API:
+        connect() / disconnect()
+        send_message(content, attachments)
+        upload_attachment(file)
+        stop()
+        session_state / channel_state / session_id  (read-only properties)
+
+    Time options are in **seconds** (not milliseconds).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        on_message: MessageCallback,
+        auth_url: str | None = None,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+        send_timeout: float = DEFAULT_SEND_TIMEOUT,
+        resync_timeout: float = DEFAULT_RESYNC_TIMEOUT,
+        ping_interval: float = DEFAULT_PING_INTERVAL,
+        pong_timeout: float = DEFAULT_PONG_TIMEOUT,
+        stale_threshold: float = DEFAULT_STALE_THRESHOLD,
+        # Private test override — not part of the public API
+        _upload_url: str | None = None,
+    ) -> None:
+        self._api_key = api_key
+        self._on_message_cb = on_message
+        self._auth_url = normalize_auth_base_url(auth_url or DEFAULT_AUTH_URL)
+        self._connect_timeout = connect_timeout
+        self._send_timeout = send_timeout
+        self._resync_timeout = resync_timeout
+        self._ping_interval = ping_interval
+        self._pong_timeout = pong_timeout
+        self._stale_threshold = stale_threshold
+
+        self._upload_url = _upload_url  # None → runtime-side upload URL heuristic
+
+        # Internal state
+        self._channel_state: ChannelState = "CLOSED"
+        self._access_token: str | None = None
+        self._refresh_token: str | None = None
+        self._ws_url: str | None = None
+        self._channel_id: str = f"ch_{secrets.token_hex(4)}"
+        self._reconnect_attempt: int = 0
+        self._disconnect_requested: bool = False
+
+        # Components
+        self._transport = Transport(connect_timeout, send_timeout)
+        self._session = SessionManager(
+            on_message=self._dispatch_message,
+            on_fatal_error=self._handle_fatal_error,
+        )
+        self._liveness: LivenessMonitor | None = None
+        self._reconnect_task: asyncio.Task[None] | None = None
+        self._token_refresh_task: asyncio.Task[None] | None = None
+
+        # Wire transport callbacks
+        self._transport.on_message = self._session.handle_incoming
+        self._transport.on_close = self._handle_close
+        self._transport.on_error = None  # handled via on_close
+
+    # ── public properties ─────────────────────────────────────────────────────
+
+    @property
+    def session_state(self) -> SessionState:
+        return self._session.session_state
+
+    @property
+    def channel_state(self) -> ChannelState:
+        return self._channel_state
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session.session_id
+
+    # ── public methods ────────────────────────────────────────────────────────
+
+    async def connect(self) -> None:
+        """Full bootstrap: auth exchange → WS open → system::init → liveness start."""
+        self._disconnect_requested = False
+        self._reconnect_attempt = 0
+
+        auth = await exchange_api_key(self._api_key, auth_base_url=self._auth_url)
+        self._access_token = auth["access_token"]
+        self._refresh_token = auth["refresh_token"]
+        self._ws_url = auth["ws_url"]
+        if self._upload_url is None:
+            self._upload_url = _derive_upload_url_from_ws_url(self._ws_url)
+
+        await self._open_channel()
+
+        self._session.set_transport(self._transport, self._send_timeout)
+        await self._session.send_init(auth["runtime_bootstrap"])
+
+        self._start_liveness()
+        self._schedule_token_refresh()
+
+    async def disconnect(self) -> None:
+        """Close the session and WebSocket connection cleanly."""
+        self._disconnect_requested = True
+        self._stop_liveness()
+        self._stop_token_refresh()
+
+        if self._reconnect_task and not self._reconnect_task.done():
+            self._reconnect_task.cancel()
+            try:
+                await self._reconnect_task
+            except (asyncio.CancelledError, Exception):
+                pass
+            self._reconnect_task = None
+
+        self._channel_state = "CLOSED"
+        await self._transport.aclose()
+
+    async def send_message(
+        self, content: str, attachments: list[str] | None = None
+    ) -> None:
+        await self._session.send_chat_message(content, attachments)
+
+    async def upload_attachment(self, file: str | bytes | BinaryIO) -> str:
+        if not self._access_token:
+            raise make_error("auth_invalid", "Not connected")
+        url = self._upload_url or "/upload"
+        return await upload_file(file, self._access_token, upload_url=url)
+
+    async def stop(self) -> None:
+        await self._session.send_stop()
+
+    # ── internal helpers ──────────────────────────────────────────────────────
+
+    async def _open_channel(self) -> None:
+        if not self._ws_url or not self._access_token:
+            raise RuntimeError("Auth not completed before _open_channel")
+        self._channel_state = "CONNECTING"
+        await self._transport.open(self._ws_url, self._access_token)
+        self._channel_state = "OPEN"
+        self._reconnect_attempt = 0
+
+    def _start_liveness(self) -> None:
+        self._stop_liveness()
+        self._liveness = LivenessMonitor(
+            transport=self._transport,
+            ping_interval=self._ping_interval,
+            pong_timeout=self._pong_timeout,
+            stale_threshold=self._stale_threshold,
+            on_stale=self._handle_stale,
+            get_session_id=lambda: self._session.session_id,
+            get_channel_id=lambda: self._channel_id,
+        )
+        self._liveness.start()
+
+    def _stop_liveness(self) -> None:
+        if self._liveness:
+            self._liveness.stop()
+            self._liveness = None
+
+    def _schedule_token_refresh(self) -> None:
+        self._stop_token_refresh()
+
+        async def _refresh_loop() -> None:
+            try:
+                while not self._disconnect_requested:
+                    await asyncio.sleep(TOKEN_REFRESH_BUFFER / 2)
+                    if not self._access_token or not self._refresh_token:
+                        continue
+                    if is_token_expiring_soon(self._access_token):
+                        try:
+                            self._access_token = await refresh_access_token(
+                                self._refresh_token,
+                                auth_base_url=self._auth_url,
+                            )
+                        except Exception:
+                            pass  # surfaced at next reconnect
+            except asyncio.CancelledError:
+                pass
+
+        self._token_refresh_task = asyncio.create_task(_refresh_loop())
+
+    def _stop_token_refresh(self) -> None:
+        if self._token_refresh_task and not self._token_refresh_task.done():
+            self._token_refresh_task.cancel()
+        self._token_refresh_task = None
+
+    # ── callbacks from transport / session ────────────────────────────────────
+
+    def _dispatch_message(self, msg: CortexMessage) -> None:
+        # system::pong is internal — route to liveness, not to user callback
+        if msg.get("type") == "system::pong":
+            hb_id = msg["payload"].get("heartbeat_id")
+            if isinstance(hb_id, str) and self._liveness:
+                self._liveness.record_pong(hb_id)
+            return
+        self._on_message_cb(msg)
+
+    def _handle_fatal_error(self, err: CortexError) -> None:
+        self._channel_state = "AUTH_FAILED"
+        self._stop_liveness()
+        self._stop_token_refresh()
+        self._transport.close()
+        # Surface error as a system::error message
+        error_msg: CortexMessage = {
+            "type": "system::error",
+            "schema": "1.0",
+            "session_id": self._session.session_id or "",
+            "payload": {"code": err.code, "message": str(err)},
+            "ts": _now_iso(),
+        }
+        self._on_message_cb(error_msg)
+
+    def _handle_stale(self) -> None:
+        if self._channel_state in ("STALE", "RECONNECTING"):
+            return
+        self._channel_state = "STALE"
+        self._stop_liveness()
+        self._transport.close(1001, "stale")
+        # on_close will trigger reconnect
+
+    def _handle_close(self, code: int, reason: str) -> None:
+        if self._disconnect_requested:
+            return
+        if self._channel_state == "AUTH_FAILED":
+            return
+        if code == 4001:
+            self._channel_state = "AUTH_FAILED"
+            return
+        self._channel_state = "RECONNECTING"
+        self._reconnect_task = asyncio.ensure_future(self._reconnect_loop())
+
+    async def _reconnect_loop(self) -> None:
+        try:
+            while (
+                not self._disconnect_requested
+                and self._channel_state != "AUTH_FAILED"
+            ):
+                idx = min(self._reconnect_attempt, len(RECONNECT_BACKOFF) - 1)
+                backoff = RECONNECT_BACKOFF[idx]
+                self._reconnect_attempt += 1
+
+                await asyncio.sleep(backoff)
+                if self._disconnect_requested:
+                    break
+
+                # Proactively refresh token if needed
+                try:
+                    await self._maybe_refresh_token()
+                except CortexError:
+                    self._channel_state = "AUTH_FAILED"
+                    return
+
+                try:
+                    await self._open_channel()
+                except Exception:
+                    continue  # retry after next backoff
+
+                # Re-attach session to the new transport
+                self._session.set_transport(self._transport, self._send_timeout)
+
+                # Resync with timeout
+                try:
+                    await asyncio.wait_for(
+                        self._session.send_resync(),
+                        timeout=self._resync_timeout,
+                    )
+                except Exception:
+                    self._transport.close()
+                    continue
+
+                # Reconnect successful — restart liveness + token refresh
+                self._start_liveness()
+                self._schedule_token_refresh()
+                return
+        except asyncio.CancelledError:
+            pass
+
+    async def _maybe_refresh_token(self) -> None:
+        if not self._refresh_token:
+            raise make_error("auth_refresh_failed", "No refresh token")
+        if not self._access_token or is_token_expiring_soon(self._access_token):
+            self._access_token = await refresh_access_token(
+                self._refresh_token,
+                auth_base_url=self._auth_url,
+            )
+
+
+def _now_iso() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _derive_upload_url_from_ws_url(ws_url: str | None) -> str:
+    if not ws_url:
+        return "/upload"
+
+    parsed = urlsplit(ws_url)
+    scheme = parsed.scheme.lower()
+    http_scheme = "https" if scheme == "wss" else "http" if scheme == "ws" else scheme
+    return urlunsplit((http_scheme, parsed.netloc, "/upload", "", ""))