splx-proxy-sdk 1.0.9__py3-none-any.whl

splx_proxy_sdk/__init__.py

@@ -0,0 +1,58 @@
+"""
+A SDK for building proxy servers for integration between user applications and SplxAI Platform.
+"""
+
+from splx_proxy_sdk.error import (
+    BadRequestException,
+    ExceptionCode,
+    ForbiddenException,
+    InternalServerErrorException,
+    NotFoundException,
+    ProxyException,
+    ProxyExceptionConfig,
+    SessionClosedException,
+    TooManyRequestsException,
+    UnauthorizedException,
+)
+from splx_proxy_sdk.logging import LoggingConfig
+from splx_proxy_sdk.model import (
+    CloseSessionRequest,
+    CloseSessionResponse,
+    MultiModal,
+    MultiModalAudio,
+    MultiModalImage,
+    MultiModalType,
+    OpenSessionRequest,
+    OpenSessionResponse,
+    SendMessageRequest,
+    SendMessageResponse,
+)
+from splx_proxy_sdk.server import Server
+from splx_proxy_sdk.version import VERSION
+
+__version__ = VERSION
+
+__all__ = [
+    "ExceptionCode",
+    "ProxyException",
+    "UnauthorizedException",
+    "BadRequestException",
+    "NotFoundException",
+    "ForbiddenException",
+    "TooManyRequestsException",
+    "InternalServerErrorException",
+    "SessionClosedException",
+    "ProxyExceptionConfig",
+    "MultiModalType",
+    "MultiModal",
+    "MultiModalImage",
+    "MultiModalAudio",
+    "SendMessageRequest",
+    "SendMessageResponse",
+    "OpenSessionRequest",
+    "OpenSessionResponse",
+    "CloseSessionRequest",
+    "CloseSessionResponse",
+    "Server",
+    "LoggingConfig",
+]

splx_proxy_sdk/auth.py

@@ -0,0 +1,34 @@
+"""
+Authentication middleware and configuration.
+"""
+
+from dataclasses import dataclass
+from typing import Callable
+
+from fastapi import Security
+
+from splx_proxy_sdk.error import ExceptionCode, UnauthorizedException
+
+
+@dataclass
+class Config:
+    """Configuration for the authentication middleware."""
+
+    secret: str
+    """
+    The secret with which the value should be compared with.
+    """
+    security: Callable
+    """
+    The security function to use for extracting the secret from the request.
+    More details are in the [FastAPI docs](https://fastapi.tiangolo.com/tutorial/security/).
+    """
+
+
+def _auth_func(api_key: str, base: Callable):
+    async def _f(key: str = Security(base)):
+        if key != api_key:
+            raise UnauthorizedException("Invalid API key", ExceptionCode.UNAUTHORIZED)
+        return None
+
+    return _f

splx_proxy_sdk/error.py

@@ -0,0 +1,279 @@
+"""Error definitions and error handling."""
+
+import math
+from dataclasses import dataclass, replace
+from datetime import timedelta
+from enum import Enum
+
+from fastapi import Request
+from pydantic import BaseModel
+from starlette.exceptions import HTTPException
+from starlette.responses import JSONResponse
+
+SESSION_STATUS_HEADER = "X-Splx-Session-Status"
+SESSION_STATUS_OPEN = "open"
+SESSION_STATUS_CLOSED = "closed"
+
+
+@dataclass(slots=True)
+class ProxyExceptionConfig:
+    """Structured exception config used when building proxy exceptions."""
+
+    session_closed: bool | None = None
+    retry_after: timedelta | None = None
+    headers: dict[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        if self.headers is not None:
+            # Copy to avoid mutating caller-provided dictionaries.
+            self.headers = dict(self.headers)
+
+    def to_headers(self) -> dict[str, str]:
+        """Build the headers that should accompany the error response."""
+        headers: dict[str, str] = dict(self.headers or {})
+
+        if self.session_closed is not None:
+            headers[SESSION_STATUS_HEADER] = (
+                SESSION_STATUS_CLOSED if self.session_closed else SESSION_STATUS_OPEN
+            )
+
+        if self.retry_after is not None:
+            headers["Retry-After"] = str(math.ceil(self.retry_after.total_seconds()))
+
+        return headers
+
+
+class ProxyHTTPStatusCode(int, Enum):
+    """
+    HTTP status codes used in the proxy.
+    """
+
+    SESSION_CLOSED = 452
+
+
+class ExceptionCode(str, Enum):
+    """
+    Exception codes that can be generated from the proxy.
+    These are used so the SplxAI Platform can do error handling for some
+    common use cases.
+    """
+
+    UNKNOWN = "UNKNOWN"
+
+    BAD_REQUEST = "BAD_REQUEST"
+    FORBIDDEN = "FORBIDDEN"
+    NOT_FOUND = "NOT_FOUND"
+    TOO_MANY_REQUESTS = "TOO_MANY_REQUESTS"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR"
+    SESSION_CLOSED = "SESSION_CLOSED"
+
+
+class ProxyException(HTTPException):
+    """
+    A custom exception implementation that includes the `ExceptionCode`.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        details: str,
+        code: ExceptionCode,
+        *,
+        config: ProxyExceptionConfig | None = None,
+    ):
+        """
+        Args:
+            status_code: the status code that should be returned in the result
+            details: details about the exception
+            code: the `ExceptionCode` of the error
+            response: metadata describing proxy-specific response headers
+        """
+        super().__init__(status_code, details)
+        self.code = code
+        self._config = config or ProxyExceptionConfig()
+
+    def get_headers(self) -> dict[str, str] | None:
+        """
+        Function returning Probe supported headers formatted as dictionary
+        """
+        headers = self._config.to_headers()
+        return headers or None
+
+
+class BadRequestException(ProxyException):
+    """
+    Specialized instance of the `ProxyException` that returns `Bad Request`.
+    """
+
+    def __init__(
+        self,
+        details: str,
+        code: ExceptionCode = ExceptionCode.BAD_REQUEST,
+        *,
+        config: ProxyExceptionConfig | None = None,
+    ):
+        super().__init__(
+            400,
+            details,
+            code,
+            config=config,
+        )
+
+
+class UnauthorizedException(ProxyException):
+    """
+    Specialized instance of the `ProxyException` that returns `Unauthorized`.
+    """
+
+    def __init__(
+        self,
+        details: str,
+        code: ExceptionCode = ExceptionCode.UNAUTHORIZED,
+        *,
+        config: ProxyExceptionConfig | None = None,
+    ):
+        super().__init__(
+            401,
+            details,
+            code,
+            config=config,
+        )
+
+
+class ForbiddenException(ProxyException):
+    """
+    Specialized instance of the `ProxyException` that returns `Forbidden`.
+    """
+
+    def __init__(
+        self,
+        details: str,
+        code: ExceptionCode = ExceptionCode.FORBIDDEN,
+        *,
+        config: ProxyExceptionConfig | None = None,
+    ):
+        super().__init__(
+            403,
+            details,
+            code,
+            config=config,
+        )
+
+
+class NotFoundException(ProxyException):
+    """
+    Specialized instance of the `ProxyException` that returns `Not Found`.
+    """
+
+    def __init__(
+        self,
+        details: str,
+        code: ExceptionCode = ExceptionCode.NOT_FOUND,
+        *,
+        config: ProxyExceptionConfig | None = None,
+    ):
+        super().__init__(
+            404,
+            details,
+            code,
+            config=config,
+        )
+
+
+class SessionClosedException(ProxyException):
+    """
+    Specialized instance of the `ProxyException` that informs the Probe that the session is closed.
+    """
+
+    def __init__(
+        self,
+        details: str,
+        code: ExceptionCode = ExceptionCode.SESSION_CLOSED,
+        *,
+        config: ProxyExceptionConfig | None = None,
+    ):
+        config = (
+            replace(config, session_closed=True)
+            if config
+            else ProxyExceptionConfig(session_closed=True)
+        )
+        super().__init__(
+            ProxyHTTPStatusCode.SESSION_CLOSED,
+            details,
+            code,
+            config=config,
+        )
+
+
+class TooManyRequestsException(ProxyException):
+    """
+    Specialized instance of the `ProxyException` that returns `Too Many Requests`.
+    """
+
+    def __init__(
+        self,
+        details: str,
+        code: ExceptionCode = ExceptionCode.TOO_MANY_REQUESTS,
+        *,
+        config: ProxyExceptionConfig | None = None,
+    ):
+        """
+        Args:
+            details: details about the exception
+            code: the `ExceptionCode` of the error (default is TOO_MANY_REQUESTS)
+            config: optional exception config controlling headers returned
+        """
+        super().__init__(
+            429,
+            details,
+            code,
+            config=config,
+        )
+
+
+class InternalServerErrorException(ProxyException):
+    """
+    Specialized instance of the `ProxyException` that returns `Internal Server Error`.
+    """
+
+    def __init__(
+        self,
+        details: str,
+        code: ExceptionCode = ExceptionCode.INTERNAL_SERVER_ERROR,
+        *,
+        config: ProxyExceptionConfig | None = None,
+    ):
+        super().__init__(
+            500,
+            details,
+            code,
+            config=config,
+        )
+
+
+class ExceptionResult(BaseModel):
+    """
+    The resulting model for the exception response.
+
+    Args:
+        message: the message that should be returned in the result
+        code: the `ExceptionCode` of the error
+    """
+
+    message: str
+    code: ExceptionCode
+
+
+def _exception_handler(_: Request, exc: HTTPException):
+    code = ExceptionCode.UNKNOWN
+    headers = exc.headers
+    if isinstance(exc, ProxyException):
+        code = exc.code
+        headers = exc.get_headers()
+
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=ExceptionResult(message=exc.detail, code=code).model_dump(),
+        headers=headers,
+    )

splx_proxy_sdk/logging.py

@@ -0,0 +1,345 @@
+"""
+Logging utilities for the SplxAI proxy.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, AsyncIterator, Iterable, Mapping
+
+from fastapi import Request
+from loguru import logger
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import Response
+from starlette.types import ASGIApp
+
+DEFAULT_REDACTED = "***REDACTED***"
+
+
+def _utc_now_iso() -> str:
+    """
+    Return the current UTC time in ISO-8601 format with a trailing Z for readability.
+    """
+
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _parse_bool(value: str | None, default: bool) -> bool:
+    if value is None:
+        return default
+    value_lower = value.strip().lower()
+    if value_lower in {"1", "true", "t", "yes", "y", "on"}:
+        return True
+    if value_lower in {"0", "false", "f", "no", "n", "off"}:
+        return False
+    return default
+
+
+def _parse_csv(value: str | None, *, default: Iterable[str]) -> tuple[str, ...]:
+    if not value:
+        return tuple(default)
+    return tuple(part.strip() for part in value.split(",") if part.strip())
+
+
+@dataclass
+class LoggingConfig:
+    """
+    Configuration options for the structured logging middleware.
+    """
+
+    enabled: bool = True
+    log_request_body: bool = True
+    log_response_body: bool = True
+    max_body_length: int = 4096
+    redact_headers: tuple[str, ...] = field(default_factory=lambda: ("x-api-key",))
+    redact_fields: tuple[str, ...] = field(
+        default_factory=lambda: (
+            "api_key",
+            "access_token",
+            "refresh_token",
+            "token",
+            "secret",
+            "password",
+            "authorization",
+        )
+    )
+
+    @classmethod
+    def from_env(cls) -> "LoggingConfig":
+        """
+        Build a logging configuration instance from environment variables.
+        """
+
+        enabled = _parse_bool(os.getenv("SPLX_PROXY_LOG_ENABLED"), default=True)
+        log_request_body = _parse_bool(
+            os.getenv("SPLX_PROXY_LOG_REQUEST_BODY"), default=True
+        )
+        log_response_body = _parse_bool(
+            os.getenv("SPLX_PROXY_LOG_RESPONSE_BODY"), default=True
+        )
+
+        max_body_length_raw = os.getenv("SPLX_PROXY_LOG_MAX_BODY_LENGTH")
+        max_body_length = 4096
+        if max_body_length_raw:
+            try:
+                max_body_length = max(0, int(max_body_length_raw))
+            except ValueError:
+                max_body_length = 4096
+
+        redact_headers = _parse_csv(
+            os.getenv("SPLX_PROXY_LOG_REDACT_HEADERS"),
+            default=cls().redact_headers,
+        )
+        redact_fields = _parse_csv(
+            os.getenv("SPLX_PROXY_LOG_REDACT_FIELDS"),
+            default=cls().redact_fields,
+        )
+
+        return cls(
+            enabled=enabled,
+            log_request_body=log_request_body,
+            log_response_body=log_response_body,
+            max_body_length=max_body_length,
+            redact_headers=tuple(header.lower() for header in redact_headers),
+            redact_fields=tuple(field.lower() for field in redact_fields),
+        )
+
+    def __post_init__(self) -> None:
+        self.redact_headers = tuple(header.lower() for header in self.redact_headers)
+        self.redact_fields = tuple(field.lower() for field in self.redact_fields)
+
+
+# pylint: disable=too-few-public-methods
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    """
+    FastAPI middleware emitting structured request/response logs via Loguru.
+    """
+
+    def __init__(self, app: ASGIApp, config: LoggingConfig):
+        super().__init__(app)
+        logger.remove()
+        logger.add(
+            sink=sys.stdout,
+            serialize=True,
+            backtrace=False,
+            diagnose=False,
+            enqueue=True,
+        )
+
+        self._context_logger = logger.opt(record=False, raw=True)
+
+        self._config = config
+
+    async def dispatch(self, request: Request, call_next):
+        if not self._config.enabled:
+            return await call_next(request)
+
+        started_at_iso = _utc_now_iso()
+        request_id = str(uuid.uuid4())
+        start_time = time.perf_counter()
+
+        client_host = request.client.host if request.client else None
+        client_port = request.client.port if request.client else None
+
+        client_info: dict[str, int | str] | None = None
+        if client_host or client_port:
+            client_info = {}
+            if client_host:
+                client_info["ip"] = client_host
+            if client_port:
+                client_info["port"] = client_port
+
+        log_context: dict[str, Any] = {
+            "request_id": request_id,
+            "started_at": started_at_iso,
+            "start_time": start_time,
+            "client_info": client_info,
+        }
+
+        request_payload, _ = await self._create_request_payload(request, log_context)
+
+        self._context_logger.info("Request logged.", payload=request_payload)
+
+        response = await call_next(request)  # type: ignore
+
+        response_payload, response_body_bytes = await self._create_response_payload(
+            request,
+            response,
+            log_context,
+        )
+
+        self._context_logger.info("Response logged.", payload=response_payload)
+
+        if response_body_bytes is not None:
+            return Response(
+                content=response_body_bytes,  # type: ignore[attr-defined]
+                status_code=response.status_code,
+                headers=dict(response.headers),
+                media_type=response.media_type,
+            )
+
+        return response
+
+    async def _create_request_payload(
+        self,
+        request: Request,
+        context: Mapping[str, Any],
+    ) -> tuple[dict[str, Any], bytes | None]:
+        request_id: str = context["request_id"]
+        started_at_iso = context.get("started_at") or _utc_now_iso()
+        client_info = context.get("client_info")
+        sanitized_headers = self._sanitize_headers(request.headers)
+        request_content_length: int | str | None = None
+        request_content_length_raw = request.headers.get("content-length")
+        if request_content_length_raw is not None:
+            try:
+                request_content_length = int(request_content_length_raw)
+            except ValueError:
+                request_content_length = request_content_length_raw
+
+        request_body_bytes: bytes | None = None
+        request_body = None
+        request_body_length = None
+        if self._config.log_request_body:
+            request_body_bytes = await request.body()
+            request_body_length = len(request_body_bytes)
+            request_body = self._format_body(
+                request_body_bytes, request.headers.get("content-type")
+            )
+
+        request_payload: dict[str, Any] = {
+            "event": "request",
+            "request_id": request_id,
+            "method": request.method,
+            "url": str(request.url),
+            "scheme": request.url.scheme,
+            "host": request.url.hostname,
+            "path": request.url.path,
+            "query": request.url.query or None,
+            "http_version": request.scope.get("http_version"),
+            "headers": sanitized_headers,
+            "started_at": started_at_iso,
+        }
+        if client_info:
+            request_payload["client"] = client_info
+        if request_content_length is not None:
+            request_payload["content_length"] = request_content_length
+        if request_body_length is not None:
+            request_payload["body_length"] = request_body_length
+        if request_body is not None:
+            request_payload["body"] = request_body
+
+        return request_payload, request_body_bytes
+
+    async def _create_response_payload(
+        self,
+        request: Request,
+        response: Response,
+        context: Mapping[str, Any],
+    ) -> tuple[dict[str, Any], bytes | None]:
+        start_time = context.get("start_time", time.perf_counter())
+        client_info = context.get("client_info")
+        response_body = None
+        response_body_bytes: bytes | None = None
+
+        if self._config.log_response_body and hasattr(response, "body_iterator"):
+            response_body_bytes = await self._read_bytes(response.body_iterator)  # type: ignore
+            response_body = self._format_body(
+                response_body_bytes, response.headers.get("content-type")
+            )
+
+        completed_at_iso = _utc_now_iso()
+        duration_ms = (time.perf_counter() - start_time) * 1000
+        response_body_length = len(response_body_bytes) if response_body_bytes else None
+        response_content_length: int | str | None = None
+        response_content_length_raw = response.headers.get("content-length")
+        if response_content_length_raw is not None:
+            try:
+                response_content_length = int(response_content_length_raw)
+            except ValueError:
+                response_content_length = response_content_length_raw
+        response_headers = self._sanitize_headers(response.headers)
+
+        response_payload: dict[str, Any] = {
+            "event": "response",
+            "request_id": context["request_id"],
+            "method": request.method,
+            "url": str(request.url),
+            "path": request.url.path,
+            "status_code": response.status_code,
+            "duration_ms": round(duration_ms, 3),
+            "completed_at": completed_at_iso,
+            "headers": response_headers,
+        }
+        if client_info:
+            response_payload["client"] = client_info
+        if response_content_length is not None:
+            response_payload["content_length"] = response_content_length
+        if response_body_length is not None:
+            response_payload["body_length"] = response_body_length
+        if response_body is not None:
+            response_payload["body"] = response_body
+
+        return response_payload, response_body_bytes
+
+    def _sanitize_headers(self, headers: Mapping[str, str]) -> dict[str, str]:
+        sanitized: dict[str, str] = {}
+        for key, value in headers.items():
+            key_lower = key.lower()
+            if key_lower in self._config.redact_headers:
+                sanitized[key] = DEFAULT_REDACTED
+            else:
+                sanitized[key] = value
+        return sanitized
+
+    def _format_body(self, body: bytes, content_type: str | None) -> Any:
+        if not body:
+            return None
+
+        length = len(body)
+        if self._config.max_body_length and length > self._config.max_body_length:
+            return {"length": length, "truncated": True}
+
+        if content_type and "json" in content_type.lower():
+            try:
+                parsed = json.loads(body)
+            except (json.JSONDecodeError, UnicodeDecodeError):
+                pass
+            else:
+                return self._sanitize_data(parsed)
+
+        decoded = body.decode("utf-8", errors="replace")
+        if self._config.max_body_length and len(decoded) > self._config.max_body_length:
+            return {
+                "length": len(decoded),
+                "truncated": True,
+            }
+        return decoded
+
+    def _sanitize_data(self, data: Any) -> Any:
+        if isinstance(data, dict):
+            return {
+                key: (
+                    DEFAULT_REDACTED
+                    if key.lower() in self._config.redact_fields
+                    else self._sanitize_data(value)
+                )
+                for key, value in data.items()
+            }
+        if isinstance(data, list):
+            return [self._sanitize_data(value) for value in data]
+        if isinstance(data, tuple):
+            return tuple(self._sanitize_data(value) for value in data)
+        return data
+
+    async def _read_bytes(self, generator: AsyncIterator[bytes]) -> bytes:
+        body = b""
+        async for data in generator:
+            body += data
+        return body

splx_proxy_sdk/model.py

@@ -0,0 +1,127 @@
+"""
+Model definitions.
+"""
+
+from enum import Enum
+from typing import Dict, Generic, Optional, TypeVar, Union
+
+from pydantic import BaseModel
+
+ExtraArgsT = TypeVar("ExtraArgsT")
+
+# Base64 encoded image or audio
+MultiModalImage = str
+MultiModalAudio = str
+
+
+class MultiModalType(str, Enum):
+    """
+    The type of multimodal content.
+
+    Supported types:
+        - `image`
+        - `audio`
+
+    """
+
+    IMAGE = "image"
+    AUDIO = "audio"
+
+
+class MultiModal(BaseModel):
+    """
+    A multimodal content value.
+
+    Args:
+        type: the type of multimodal content
+        content: the encoded multimodal content
+    """
+
+    type: MultiModalType
+    content: Union[MultiModalImage, MultiModalAudio]
+
+
+class OpenSessionRequest(BaseModel, Generic[ExtraArgsT]):
+    """
+    The request to open a new session.
+
+    Args:
+        session_id: the session id to use.
+            If not provided, a new session should be generated from the server.
+        extra_args: any extra static attributes or data you want to
+            include in the request. Default is None.
+    """
+
+    session_id: Optional[str] = None
+
+    extra_args: Optional[ExtraArgsT] = None
+
+
+class OpenSessionResponse(BaseModel):
+    """
+    The response of opening a new session.
+
+    Args:
+        session_id: the session id that should be used for the session
+    """
+
+    session_id: str
+
+
+class SendMessageRequest(BaseModel, Generic[ExtraArgsT]):
+    """
+    The request to send a message to the session.
+
+    Args:
+        session_id: the session id to use
+        message: the message to send
+        multimodal: the multimodal content to send.
+            The key of the dictionary is the name of the multimodal content,
+            and the value is the `MultiModal` message.
+        extra_args: any extra static attributes or data you want to
+            include in the request. Default is None.
+    """
+
+    session_id: str
+    message: str
+    multimodal: Optional[Dict[str, MultiModal]] = None
+
+    extra_args: Optional[ExtraArgsT] = None
+
+
+class SendMessageResponse(BaseModel):
+    """
+    The response of sending a message to the session.
+
+    Args:
+        session_id: the session id that is used for the session
+        message: the message received
+        multimodal: the multimodal content received.
+            The key of the dictionary is the name of the multimodal content,
+            and the value is the `MultiModal` message.
+    """
+
+    session_id: str
+    message: str
+    multimodal: Optional[Dict[str, MultiModal]] = None
+
+
+class CloseSessionRequest(BaseModel, Generic[ExtraArgsT]):
+    """
+    The request to close a session.
+
+    Args:
+        session_id: the session id to close
+        extra_args: any extra static attributes or data you want to
+            include in the request. Default is None.
+    """
+
+    session_id: str
+
+    extra_args: Optional[ExtraArgsT] = None
+
+
+class CloseSessionResponse(BaseModel):
+    """
+    The response of closing a session.
+    """

splx_proxy_sdk/server.py

@@ -0,0 +1,165 @@
+"""
+Server definition that the user should extend.
+"""
+
+import os
+from abc import ABC, abstractmethod
+from typing import Mapping
+
+from fastapi import APIRouter, Depends, FastAPI, Request
+from fastapi.security.api_key import APIKeyHeader
+from starlette.exceptions import HTTPException
+
+from splx_proxy_sdk.auth import _auth_func
+from splx_proxy_sdk.error import _exception_handler
+from splx_proxy_sdk.logging import LoggingConfig, RequestLoggingMiddleware
+from splx_proxy_sdk.model import (
+    CloseSessionRequest,
+    CloseSessionResponse,
+    OpenSessionRequest,
+    OpenSessionResponse,
+    SendMessageRequest,
+    SendMessageResponse,
+)
+
+API_KEY_ENV_VAR = "SPLX_PROXY_API_KEY"
+API_KEY_HEADER_NAME = "x-api-key"
+
+
+class Server(FastAPI, ABC):
+    """
+    The server that handles the proxy requests.
+    This class should be extended to implement the actual server.
+    It also supports all `FastAPI` features.
+
+    **Example:**
+    ```python
+    from proxy import Server
+    from proxy import (
+            OpenSessionRequest,
+            OpenSessionResponse,
+            CloseSessionRequest,
+            CloseSessionResponse,
+            SendMessageRequest,
+            SendMessageResponse
+        )
+
+    class MyServer(Server):
+        def __init__(self, **kwargs):
+            super().__init__(**kwargs)
+            # some other initialization code
+
+        async def open_session(
+            self, request: OpenSessionRequest, raw: Request
+        ) -> OpenSessionResponse:
+            return OpenSessionResponse(session_id="my-session-id")
+        async def close_session(
+            self, request: CloseSessionRequest, raw: Request
+        ) -> CloseSessionResponse:
+            return CloseSessionResponse()
+        async def send_message(
+            self, request: SendMessageRequest, raw: Request
+        ) -> SendMessageResponse:
+            return SendMessageResponse(session_id="my-session-id", message="Hello, world!")
+    ```
+    You can find more examples in the
+    [examples](https://github.com/splx-ai/proxy/tree/main/examples) directory.
+    """
+
+    def __init__(self, logging_config=None, **kwargs):
+        """
+        The init method of the server.
+        It uses the `FastAPI` constructor and adds the routes for the proxy requests.
+        Additionally, it adds the authentication middleware with the API key loaded
+        from the `SPLX_PROXY_API_KEY` environment variable.
+
+        Args:
+            logging_config: The logging configuration or mapping.
+            **kwargs: Additional keyword arguments for the FastAPI constructor.
+        """
+
+        if logging_config is None:
+            logging_config = LoggingConfig.from_env()
+        elif isinstance(logging_config, Mapping):
+            logging_config = LoggingConfig(**logging_config)
+        elif not isinstance(logging_config, LoggingConfig):
+            raise TypeError("logging_config must be a LoggingConfig or mapping")
+
+        api_key = os.getenv(API_KEY_ENV_VAR)
+        if not api_key:
+            raise RuntimeError(
+                (
+                    "SPLX_PROXY_API_KEY environment variable ",
+                    "must be set before starting the proxy server.",
+                )
+            )
+
+        super().__init__(**kwargs)
+        if logging_config.enabled:
+            self.add_middleware(RequestLoggingMiddleware, config=logging_config)
+
+        security = APIKeyHeader(name=API_KEY_HEADER_NAME, auto_error=True)
+        dependencies = [Depends(_auth_func(api_key, security))]
+
+        router = APIRouter(dependencies=dependencies)
+
+        router.add_api_route(
+            "/open-session",
+            self.open_session,
+            methods=["POST"],
+        )
+        router.add_api_route(
+            "/close-session",
+            self.close_session,
+            methods=["POST"],
+        )
+        router.add_api_route(
+            "/send-message",
+            self.send_message,
+            methods=["POST"],
+        )
+
+        self.include_router(router)
+        self.exception_handler(HTTPException)(_exception_handler)
+
+    @abstractmethod
+    async def open_session(
+        self, request: OpenSessionRequest, raw: Request
+    ) -> OpenSessionResponse:
+        """
+        The method that handles the `/open-session` request.
+        It should return an `OpenSessionResponse` object with the session ID.
+
+        Args:
+            request: The request object.
+            raw: The raw request object so you can access the headers, query parameters, etc.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def close_session(
+        self, request: CloseSessionRequest, raw: Request
+    ) -> CloseSessionResponse:
+        """
+        The method that handles the `/close-session` request.
+        It should return a `CloseSessionResponse` object.
+
+        Args:
+            request: The request object.
+            raw: The raw request object so you can access the headers, query parameters, etc.
+        """
+        raise NotImplementedError
+
+    @abstractmethod
+    async def send_message(
+        self, request: SendMessageRequest, raw: Request
+    ) -> SendMessageResponse:
+        """
+        The method that handles the `/send-message` request.
+        It should return a `SendMessageResponse` object with the session ID and the message.
+
+        Args:
+            request: The request object.
+            raw: The raw request object so you can access the headers, query parameters, etc.
+        """
+        raise NotImplementedError

splx_proxy_sdk/version.py

@@ -0,0 +1,8 @@
+"""
+The version of the SplxAI Proxy package.
+"""
+
+__all__ = ["VERSION"]
+
+VERSION = "1.0.9"
+"""The version of the SplxAI Proxy package."""

splx_proxy_sdk-1.0.9.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 SplxAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

splx_proxy_sdk-1.0.9.dist-info/METADATA

@@ -0,0 +1,283 @@
+Metadata-Version: 2.1
+Name: splx-proxy-sdk
+Version: 1.0.9
+Summary: SDK for building proxy servers for integration between user applications and the SPLX Platform
+License: MIT
+Author: Luka Simac
+Author-email: luka.simac@splx.ai
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: fastapi (>=0.116.1,<0.117.0)
+Requires-Dist: loguru (>=0.7.2,<0.8.0)
+Requires-Dist: pydantic (>=2.11.7,<3.0.0)
+Description-Content-Type: text/markdown
+
+# SPLX AI Proxy
+
+The SPLX AI Proxy is a lightweight and easy-to-use interface for creating and managing API proxies for integration with the SPLX Platform.
+
+## Getting Started
+
+1. **Configure package source**
+
+```bash
+# poetry
+poetry config repositories.splxai https://splxai-851725337651.d.codeartifact.eu-central-1.amazonaws.com/pypi/pypi/
+
+# pip
+pip config set global.extra-index-url https://splxai-851725337651.d.codeartifact.eu-central-1.amazonaws.com/pypi/pypi/
+pip config set global.trusted-host splxai-851725337651.d.codeartifact.eu-central-1.amazonaws.com
+```
+
+Alternatively, add the repository directly in `pyproject.toml`:
+
+```toml
+[[tool.poetry.source]]
+name = "splxai"
+url = "https://splxai-851725337651.d.codeartifact.eu-central-1.amazonaws.com/pypi/pypi/simple"
+priority = "secondary"
+```
+
+2. **Install the SDK**
+
+```bash
+# poetry
+poetry add splxai-proxy
+
+# pip
+pip install splxai-proxy
+```
+
+3. **Implement your proxy server**
+
+```python
+from fastapi import Request
+from pydantic import BaseModel
+
+from splx_proxy_sdk import (
+    CloseSessionRequest,
+    CloseSessionResponse,
+    OpenSessionRequest,
+    OpenSessionResponse,
+    SendMessageRequest,
+    SendMessageResponse,
+    Server,
+)
+
+
+class ExtraArgs(BaseModel):
+    tone: str
+    token_count: int
+
+
+class SimpleServer(Server):
+    async def open_session(
+        self, request: OpenSessionRequest, raw: Request
+    ) -> OpenSessionResponse:
+        raise NotImplementedError("Implement the open_session method")
+
+    async def close_session(
+        self, request: CloseSessionRequest, raw: Request
+    ) -> CloseSessionResponse:
+        raise NotImplementedError("Implement the close_session method")
+
+    async def send_message(
+        self, request: SendMessageRequest[ExtraArgs], raw: Request
+    ) -> SendMessageResponse:
+        if request.extra_args:
+            print("Response tone:", request.extra_args.tone)
+            print("Response token count:", request.extra_args.token_count)
+
+        return SendMessageResponse(
+            session_id="test", message="Hello, how may I help you?"
+        )
+
+
+# Ensure SPLX_PROXY_API_KEY env. variable is set before instantiating the server
+app = SimpleServer()
+```
+
+4. **Run the service**
+
+```bash
+gunicorn -w 1 -k uvicorn.workers.UvicornWorker main:app --bind 0.0.0.0:8000
+```
+
+The SPLX Platform must be able to reach the host and port you expose.
+
+See [examples/simple_server](examples/simple_server/main.py) for a sample project, including `.env` placeholders for SPLX credentials.
+
+## Features
+
+### Authentication
+
+Proxy SDK requires authentication using the `x-api-key` header. To set the secret, you need to set the `SPLX_PROXY_API_KEY` environment variable.
+
+### Extra arguments
+
+If you want to use some extra arguments in any of the endpoints, you can parametrize any of the Request classes (OpenSessionRequest, SendMessageRequest, CloseSessionRequest). To do that, define your own class and use it as in the [example](examples/simple_server/main.py) code. This approach provides simple customization together with type safety.
+
+### Logging
+
+By default, all requests and responses are logged in JSON format.
+
+```json
+{
+  "text": "Request logged.",
+  "record": {
+    "elapsed": { "repr": "0:00:01.259405", "seconds": 1.259405 },
+    "exception": null,
+    "extra": {
+      "payload": {
+        "event": "request",
+        "request_id": "1f8c1f39-e2c3-471e-b567-d69b2d58337f",
+        "method": "POST",
+        "url": "http://127.0.0.1:8000/send-message",
+        "scheme": "http",
+        "host": "127.0.0.1",
+        "path": "/send-message",
+        "query": null,
+        "http_version": "1.1",
+        "headers": {
+          "host": "127.0.0.1:8000",
+          "connection": "keep-alive",
+          "content-length": "342",
+          "sec-ch-ua-platform": "\"macOS\"",
+          "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36",
+          "accept": "application/json",
+          "sec-ch-ua": "\"Chromium\";v=\"142\", \"Brave\";v=\"142\", \"Not_A Brand\";v=\"99\"",
+          "content-type": "application/json",
+          "x-api-key": "***REDACTED***",
+          "sec-ch-ua-mobile": "?0",
+          "sec-gpc": "1",
+          "accept-language": "en-US,en;q=0.8",
+          "origin": "http://127.0.0.1:8000",
+          "sec-fetch-site": "same-origin",
+          "sec-fetch-mode": "cors",
+          "sec-fetch-dest": "empty",
+          "referer": "http://127.0.0.1:8000/docs",
+          "accept-encoding": "gzip, deflate, br, zstd"
+        },
+        "started_at": "2025-11-03T09:29:18.151146Z",
+        "client": { "ip": "127.0.0.1", "port": 60711 },
+        "content_length": 342,
+        "body_length": 342,
+        "body": {
+          "session_id": "string",
+          "message": "string",
+          "multimodal": {
+            "additionalProp1": { "type": "image", "content": "string" },
+            "additionalProp2": { "type": "image", "content": "string" },
+            "additionalProp3": { "type": "image", "content": "string" }
+          },
+          "extra_args": "string"
+        }
+      }
+    },
+    "file": {
+      "name": "logging.py",
+      "path": "/Users/ivanvlahov/Desktop/SPLX/splx-proxy-sdk/splx_proxy_sdk/logging.py"
+    },
+    "function": "dispatch",
+    "level": { "icon": "ℹ️", "name": "INFO", "no": 20 },
+    "line": 169,
+    "message": "Request logged.",
+    "module": "logging",
+    "name": "splx_proxy_sdk.logging",
+    "process": { "id": 49939, "name": "SpawnProcess-1" },
+    "thread": { "id": 8591597888, "name": "MainThread" },
+    "time": {
+      "repr": "2025-11-03 10:29:18.151469+01:00",
+      "timestamp": 1762162158.151469
+    }
+  }
+}
+INFO:     127.0.0.1:60711 - "POST /send-message HTTP/1.1" 200 OK
+{
+  "text": "Response logged.",
+  "record": {
+    "elapsed": { "repr": "0:00:01.262576", "seconds": 1.262576 },
+    "exception": null,
+    "extra": {
+      "payload": {
+        "event": "response",
+        "request_id": "1f8c1f39-e2c3-471e-b567-d69b2d58337f",
+        "method": "POST",
+        "url": "http://127.0.0.1:8000/send-message",
+        "path": "/send-message",
+        "status_code": 200,
+        "duration_ms": 3.394,
+        "completed_at": "2025-11-03T09:29:18.154589Z",
+        "headers": {
+          "content-length": "65",
+          "content-type": "application/json"
+        },
+        "client": { "ip": "127.0.0.1", "port": 60711 },
+        "content_length": 65,
+        "body_length": 65,
+        "body": {
+          "session_id": "test",
+          "message": "Hello, world!",
+          "multimodal": null
+        }
+      }
+    },
+    "file": {
+      "name": "logging.py",
+      "path": "/Users/ivanvlahov/Desktop/SPLX/splx-proxy-sdk/splx_proxy_sdk/logging.py"
+    },
+    "function": "dispatch",
+    "level": { "icon": "ℹ️", "name": "INFO", "no": 20 },
+    "line": 179,
+    "message": "Response logged.",
+    "module": "logging",
+    "name": "splx_proxy_sdk.logging",
+    "process": { "id": 49939, "name": "SpawnProcess-1" },
+    "thread": { "id": 8591597888, "name": "MainThread" },
+    "time": {
+      "repr": "2025-11-03 10:29:18.154640+01:00",
+      "timestamp": 1762162158.15464
+    }
+  }
+}
+```
+
+You can use the `LoggingConfig` class to configure the logging in your server’s constructor. Alternatively, you can use environment variables:
+
+- `SPLX_PROXY_LOG_ENABLED` - defaults to `True`
+- `SPLX_PROXY_LOG_REQUEST_BODY` - defaults to `True`
+- `SPLX_PROXY_LOG_RESPONSE_BODY` - defaults to `True`
+- `SPLX_PROXY_LOG_MAX_BODY_LENGTH` - defaults to `4096`
+- `SPLX_PROXY_LOG_REDACT_HEADERS` - defaults to `x-api-key`
+- `SPLX_PROXY_LOG_REDACT_FIELDS` - defaults to `api_key`, `access_token`, `refresh_token`, `token`, `secret`, `password`, `authorization`
+
+### Exception Catalogue
+
+Proxy SDK exposes multiple exception classes:
+
+- `BadRequestException`
+- `UnauthorizedException`
+- `ForbiddenException`
+- `NotFoundException`
+- `SessionClosedException` - error code 452
+- `TooManyRequestsException`
+- `InternalServerErrorException`
+
+Each of these exceptions can be raised with the following parameters:
+
+- `details: str` - details of the exception
+- `code: ExceptionCode` - each exception has a default enum value
+- `config: ProxyExceptionConfig | None = None` - an exception config object that sets the headers
+  - `session_closed: bool | None = None` - tells Probe whether the session was closed as a result of this exception, uses a X-Splx-Session-Status header internally
+  - `retry_after: timedelta | None = None` - tells Probe when to retry the request, if needed, uses a Retry-After header internally
+  - `headers: dict[str, str]` - any additional headers you want to include in the exception
+
+## Useful links
+
+- TODO: Link to public documentation
+- TODO: Link to package repository
+

splx_proxy_sdk-1.0.9.dist-info/RECORD

@@ -0,0 +1,11 @@
+splx_proxy_sdk/__init__.py,sha256=qh9iYi13R7HmbmBaWiBOWpR7kW3xv0fgxswNlhE7nZM,1391
+splx_proxy_sdk/auth.py,sha256=g8LxkmxrVs_FtAegx_JGiAnqBOOLqczYqOFYAT55f-A,848
+splx_proxy_sdk/error.py,sha256=0jDL4bLZSj_d3BdyUwMfq4XE3_5_9diDHTs6J6jj2Qk,7173
+splx_proxy_sdk/logging.py,sha256=Nu3Higjv1IYWGxA20mcQGLlKE7bIJOJFPMANd4QVfI4,12083
+splx_proxy_sdk/model.py,sha256=9Cks_tZjx8NugXQsBreyFGjYm1Xe8G0HtgzGWb_f4rQ,2969
+splx_proxy_sdk/server.py,sha256=ZOMj4srn7rUYnFpODkjJdp7xMSY3nzXDBGksj5DlWAM,5495
+splx_proxy_sdk/version.py,sha256=EytKkFXdMsbzzQ4fkmmIFSUypsJPFNRpZKxS8B_LOkw,138
+splx_proxy_sdk-1.0.9.dist-info/LICENSE,sha256=oadOuOQAGm5-LFNdhERvtu9GPus1DRgU0zJtphW17jk,1063
+splx_proxy_sdk-1.0.9.dist-info/METADATA,sha256=cIQqbrhSW4T00jw-m37vdUzOF0Ir8zi3Ragw-TWlTFE,9447
+splx_proxy_sdk-1.0.9.dist-info/WHEEL,sha256=Nq82e9rUAnEjt98J6MlVmMCZb-t9cYE2Ir1kpBmnWfs,88
+splx_proxy_sdk-1.0.9.dist-info/RECORD,,

splx_proxy_sdk-1.0.9.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 1.9.1
+Root-Is-Purelib: true
+Tag: py3-none-any