slen 0.4.0__py3-none-any.whl

slen/__init__.py

@@ -0,0 +1,160 @@
+"""The Slen Python SDK: run flows and read their outcome, keep end customers and their credits, check webhooks."""
+
+from slen._client import AsyncSlen, Slen
+from slen._errors import (
+    AuthenticationError,
+    BudgetExceededError,
+    ConcurrencyLimitError,
+    ConnectionError,
+    CustomerBlockedError,
+    CustomerNotFoundError,
+    FlowRuntimeError,
+    IdempotencyConflictError,
+    InsufficientCreditsError,
+    InvalidRequestError,
+    InvalidResponseError,
+    OperationLimitExceededError,
+    OperationUncertainError,
+    OverrunApprovalRequiredError,
+    OverrunStoppedError,
+    PolicyDeniedError,
+    ProviderError,
+    RateLimitError,
+    ServiceUnavailableError,
+    SlenError,
+    SpendRefusedError,
+    TimeoutError,
+    WebhookSignatureError,
+    WebhookSignatureReason,
+)
+from slen._health import Health
+from slen._idempotency import generate_idempotency_key, idempotency_key_for_job
+from slen._logger import LOG_EVENTS, SlenLogger
+from slen._modules.customers._async import AsyncCustomers
+from slen._modules.customers._sync import Customers
+from slen._modules.customers._types import (
+    CreditEntry,
+    CreditEntryType,
+    CreditPrice,
+    CreditPriceList,
+    Customer,
+    CustomerAccount,
+    CustomerStatus,
+)
+from slen._modules.executions._async import AsyncExecutions
+from slen._modules.executions._sync import Executions
+from slen._modules.executions._types import (
+    AttemptSummary,
+    ExecutionCache,
+    ExecutionCost,
+    ExecutionError,
+    ExecutionStatus,
+    ExecutionStatusView,
+    ExecutionTrace,
+    FlowExecutionEvent,
+    FlowExecutionNode,
+    WaitingOn,
+)
+from slen._modules.executions._wait import AsyncPollErrorListener, PollErrorListener
+from slen._modules.operations._async import AsyncOperations
+from slen._modules.operations._calls import ContextValue
+from slen._modules.operations._sync import Operations
+from slen._modules.operations._types import ExecutionResult
+from slen._modules.webhooks._types import (
+    ApprovalDecidedEvent,
+    ApprovalDecidedEventData,
+    ApprovalRequestedEvent,
+    ApprovalRequestedEventData,
+    CustomerBalanceLowEvent,
+    CustomerBalanceLowEventData,
+    ExecutionFinishedEvent,
+    ExecutionFinishedEventData,
+    UnknownWebhookEvent,
+    WebhookEvent,
+    WebhookEventType,
+    WebhookPayload,
+)
+from slen._modules.webhooks._webhooks import Webhooks
+from slen._observability._recorders import LoggerSpanRecorder, SpanRecorder
+from slen._observability._span import SlenSpan
+from slen._page import Page
+from slen._version import __version__
+
+__all__ = (
+    "LOG_EVENTS",
+    "ApprovalDecidedEvent",
+    "ApprovalDecidedEventData",
+    "ApprovalRequestedEvent",
+    "ApprovalRequestedEventData",
+    "AsyncCustomers",
+    "AsyncExecutions",
+    "AsyncOperations",
+    "AsyncPollErrorListener",
+    "AsyncSlen",
+    "AttemptSummary",
+    "AuthenticationError",
+    "BudgetExceededError",
+    "ConcurrencyLimitError",
+    "ConnectionError",
+    "ContextValue",
+    "CreditEntry",
+    "CreditEntryType",
+    "CreditPrice",
+    "CreditPriceList",
+    "Customer",
+    "CustomerAccount",
+    "CustomerBalanceLowEvent",
+    "CustomerBalanceLowEventData",
+    "CustomerBlockedError",
+    "CustomerNotFoundError",
+    "CustomerStatus",
+    "Customers",
+    "ExecutionCache",
+    "ExecutionCost",
+    "ExecutionError",
+    "ExecutionFinishedEvent",
+    "ExecutionFinishedEventData",
+    "ExecutionResult",
+    "ExecutionStatus",
+    "ExecutionStatusView",
+    "ExecutionTrace",
+    "Executions",
+    "FlowExecutionEvent",
+    "FlowExecutionNode",
+    "FlowRuntimeError",
+    "Health",
+    "IdempotencyConflictError",
+    "InsufficientCreditsError",
+    "InvalidRequestError",
+    "InvalidResponseError",
+    "LoggerSpanRecorder",
+    "OperationLimitExceededError",
+    "OperationUncertainError",
+    "Operations",
+    "OverrunApprovalRequiredError",
+    "OverrunStoppedError",
+    "Page",
+    "PolicyDeniedError",
+    "PollErrorListener",
+    "ProviderError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "Slen",
+    "SlenError",
+    "SlenLogger",
+    "SlenSpan",
+    "SpanRecorder",
+    "SpendRefusedError",
+    "TimeoutError",
+    "UnknownWebhookEvent",
+    "WaitingOn",
+    "WebhookEvent",
+    "WebhookEventType",
+    "WebhookPayload",
+    "WebhookSignatureError",
+    "WebhookSignatureReason",
+    "Webhooks",
+    "__version__",
+    "generate_idempotency_key",
+    "idempotency_key_for_job",
+)

slen/_client.py

@@ -0,0 +1,244 @@
+import dataclasses
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Generic, NoReturn, Self, TypeVar
+
+import httpx
+
+from slen._config import DEFAULT_BASE_URL, ClientConfig, ClientOptions, logger_of, resolve_config
+from slen._health import Health, health_call
+from slen._http import _clock, _pool
+from slen._http._async import AsyncTransport
+from slen._http._clock import Clock
+from slen._http._request import Sending
+from slen._http._sync import SyncTransport
+from slen._logger import SlenLogger
+from slen._modules._context import AsyncContext, SyncContext
+from slen._modules.customers._async import AsyncCustomers
+from slen._modules.customers._sync import Customers
+from slen._modules.executions._async import AsyncExecutions
+from slen._modules.executions._sync import Executions
+from slen._modules.operations._async import AsyncOperations
+from slen._modules.operations._sync import Operations
+from slen._modules.webhooks._webhooks import Webhooks
+from slen._observability._recorders import NullSpanRecorder, SpanRecorder
+
+C = TypeVar("C", httpx.Client, httpx.AsyncClient)
+
+
+# What one client is made of; a copy made by with_logger() shares all of it but the logger, and owns no pool.
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Parts(Generic[C]):
+    config: ClientConfig
+    http: C
+    owns: bool
+    spans: SpanRecorder
+    clock: Clock
+
+
+def recorder_of(given: SpanRecorder | None) -> SpanRecorder:
+    if given is not None and not callable(getattr(given, "record", None)):
+        raise TypeError("Slen: span_recorder has a record(span) method.")
+
+    return NullSpanRecorder() if given is None else given
+
+
+def webhooks_of(config: ClientConfig) -> Webhooks:
+    return Webhooks(
+        secret=config.webhook_secret,
+        tolerance_seconds=config.webhook_tolerance_seconds,
+        logger=config.logger,
+    )
+
+
+def refuse_to_travel() -> NoReturn:
+    raise TypeError(
+        "Slen: a client holds connections and cannot be pickled or copied; build a client in each process, "
+        "and use with_logger() for a copy within one."
+    )
+
+
+class Slen:
+    """The Slen client: runs flows, reads their runs, keeps end customers and their credits."""
+
+    __slots__ = ("_parts", "_transport", "customers", "executions", "operations", "webhooks")
+
+    operations: Operations
+    executions: Executions
+    customers: Customers
+    webhooks: Webhooks
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        timeout: float = 65.0,
+        connect_timeout: float = 5.0,
+        retries: int = 2,
+        logger: SlenLogger | None = None,
+        span_recorder: SpanRecorder | None = None,
+        webhook_secret: str | None = None,
+        webhook_tolerance_seconds: int = 300,
+        http_client: httpx.Client | None = None,
+        headers: Mapping[str, str] | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> None:
+        options = ClientOptions(
+            api_key=api_key,
+            timeout=timeout,
+            connect_timeout=connect_timeout,
+            retries=retries,
+            logger=logger,
+            webhook_secret=webhook_secret,
+            webhook_tolerance_seconds=webhook_tolerance_seconds,
+            headers=headers,
+            base_url=base_url,
+        )
+        config = resolve_config(options)
+        spans = recorder_of(span_recorder)
+
+        if http_client is not None and not isinstance(http_client, httpx.Client):
+            raise TypeError("Slen: http_client is an httpx.Client; AsyncSlen takes an httpx.AsyncClient.")
+
+        http = _pool.sync_pool(config) if http_client is None else http_client
+        self._build(Parts(config=config, http=http, owns=http_client is None, spans=spans, clock=_clock.SYSTEM_CLOCK))
+
+    def _build(self, parts: Parts[httpx.Client]) -> None:
+        self._parts = parts
+        self._transport = SyncTransport(parts.config, parts.http, parts.clock)
+        context = SyncContext(self._transport, parts.spans)
+        self.operations = Operations(context)
+        self.executions = Executions(context)
+        self.customers = Customers(context)
+        self.webhooks = webhooks_of(parts.config)
+
+    def with_logger(self, logger: SlenLogger) -> "Slen":
+        """A client like this one that writes its journal to logger, over the same connections and span recorder."""
+        parts = self._parts
+        copy = type(self).__new__(type(self))
+        config = dataclasses.replace(parts.config, logger=logger_of(logger))
+        copy._build(dataclasses.replace(parts, config=config, owns=False))
+
+        return copy
+
+    def health(
+        self,
+        *,
+        timeout: float | None = None,
+        retries: int | None = None,
+        request_id: str | None = None,
+    ) -> Health:
+        """Liveness of the API: a dependency that is down is named in the body, not in the status."""
+        sending = Sending(timeout=timeout, retries=retries, request_id=request_id)
+
+        return self._transport.call(health_call(sending))
+
+    def close(self) -> None:
+        """Closes the connections of the HTTP client the SDK built; one passed as http_client is left to its owner."""
+        if self._parts.owns:
+            self._parts.http.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"Slen(timeout={self._parts.config.timeout!r}, retries={self._parts.config.retries!r})"
+
+    def __reduce__(self) -> NoReturn:
+        refuse_to_travel()
+
+
+class AsyncSlen:
+    """The Slen client for asyncio: runs flows, reads their runs, keeps end customers and their credits."""
+
+    __slots__ = ("_parts", "_transport", "customers", "executions", "operations", "webhooks")
+
+    operations: AsyncOperations
+    executions: AsyncExecutions
+    customers: AsyncCustomers
+    webhooks: Webhooks
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        timeout: float = 65.0,
+        connect_timeout: float = 5.0,
+        retries: int = 2,
+        logger: SlenLogger | None = None,
+        span_recorder: SpanRecorder | None = None,
+        webhook_secret: str | None = None,
+        webhook_tolerance_seconds: int = 300,
+        http_client: httpx.AsyncClient | None = None,
+        headers: Mapping[str, str] | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+    ) -> None:
+        options = ClientOptions(
+            api_key=api_key,
+            timeout=timeout,
+            connect_timeout=connect_timeout,
+            retries=retries,
+            logger=logger,
+            webhook_secret=webhook_secret,
+            webhook_tolerance_seconds=webhook_tolerance_seconds,
+            headers=headers,
+            base_url=base_url,
+        )
+        config = resolve_config(options)
+        spans = recorder_of(span_recorder)
+
+        if http_client is not None and not isinstance(http_client, httpx.AsyncClient):
+            raise TypeError("Slen: http_client is an httpx.AsyncClient; Slen takes an httpx.Client.")
+
+        http = _pool.async_pool(config) if http_client is None else http_client
+        self._build(Parts(config=config, http=http, owns=http_client is None, spans=spans, clock=_clock.SYSTEM_CLOCK))
+
+    def _build(self, parts: Parts[httpx.AsyncClient]) -> None:
+        self._parts = parts
+        self._transport = AsyncTransport(parts.config, parts.http, parts.clock)
+        context = AsyncContext(self._transport, parts.spans)
+        self.operations = AsyncOperations(context)
+        self.executions = AsyncExecutions(context)
+        self.customers = AsyncCustomers(context)
+        self.webhooks = webhooks_of(parts.config)
+
+    def with_logger(self, logger: SlenLogger) -> "AsyncSlen":
+        """A client like this one that writes its journal to logger, over the same connections and span recorder."""
+        parts = self._parts
+        copy = type(self).__new__(type(self))
+        config = dataclasses.replace(parts.config, logger=logger_of(logger))
+        copy._build(dataclasses.replace(parts, config=config, owns=False))
+
+        return copy
+
+    async def health(
+        self,
+        *,
+        timeout: float | None = None,
+        retries: int | None = None,
+        request_id: str | None = None,
+    ) -> Health:
+        """Liveness of the API: a dependency that is down is named in the body, not in the status."""
+        sending = Sending(timeout=timeout, retries=retries, request_id=request_id)
+
+        return await self._transport.call(health_call(sending))
+
+    async def close(self) -> None:
+        """Closes the connections of the HTTP client the SDK built; one passed as http_client is left to its owner."""
+        if self._parts.owns:
+            await self._parts.http.aclose()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"AsyncSlen(timeout={self._parts.config.timeout!r}, retries={self._parts.config.retries!r})"
+
+    def __reduce__(self) -> NoReturn:
+        refuse_to_travel()

slen/_config.py

@@ -0,0 +1,117 @@
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from types import MappingProxyType
+from typing import Final
+
+from slen._logger import SlenLogger, default_logger, is_logger
+
+# The hosted API, `servers[0]` of the spec. Another address is for tests and a local stack only.
+DEFAULT_BASE_URL: Final = "https://api.slen.ai"
+
+# The one variable the SDK reads.
+KEY_VARIABLE: Final = "SLEN_API_KEY"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ClientOptions:
+    api_key: str | None = field(repr=False)
+    timeout: float
+    connect_timeout: float
+    retries: int
+    logger: SlenLogger | None
+    webhook_secret: str | None = field(repr=False)
+    webhook_tolerance_seconds: int
+    headers: Mapping[str, str] | None
+    base_url: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ClientConfig:
+    api_key: str = field(repr=False)
+    base_url: str
+    timeout: float
+    connect_timeout: float
+    retries: int
+    headers: Mapping[str, str]
+    logger: SlenLogger
+    webhook_secret: str | None = field(repr=False)
+    webhook_tolerance_seconds: int
+
+
+def resolve_config(options: ClientOptions) -> ClientConfig:
+    return ClientConfig(
+        api_key=api_key_of(options.api_key),
+        base_url=base_url_of(options.base_url),
+        timeout=seconds_of("timeout", options.timeout),
+        connect_timeout=seconds_of("connect_timeout", options.connect_timeout),
+        retries=whole("retries", options.retries, 0),
+        headers=headers_of(options.headers),
+        logger=logger_of(options.logger),
+        webhook_secret=secret_of(options.webhook_secret),
+        webhook_tolerance_seconds=whole("webhook_tolerance_seconds", options.webhook_tolerance_seconds, 1),
+    )
+
+
+def api_key_of(given: str | None) -> str:
+    key: object = os.environ.get(KEY_VARIABLE) if given is None else given
+
+    if key is not None and not isinstance(key, str):
+        raise TypeError("Slen: api_key is a string.")
+
+    if key is None or not key.strip():
+        raise ValueError(f"Slen: an api_key is required (pass api_key or set {KEY_VARIABLE}).")
+
+    return key
+
+
+def base_url_of(given: str) -> str:
+    if not isinstance(given, str) or not given.strip():
+        raise ValueError("Slen: the address of the API is a URL that is not empty.")
+
+    return given.rstrip("/")
+
+
+def seconds_of(name: str, value: object) -> float:
+    if not isinstance(value, int | float) or isinstance(value, bool):
+        raise TypeError(f"Slen: {name} is a number of seconds, got {type(value).__name__}.")
+
+    # Negated on purpose: NaN is not above 0 either.
+    if not value > 0:
+        raise ValueError(f"Slen: {name} must be a number above 0, got {value!r}.")
+
+    return float(value)
+
+
+def whole(name: str, value: object, least: int) -> int:
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise TypeError(f"Slen: {name} is an integer, got {type(value).__name__}.")
+
+    if value < least:
+        raise ValueError(f"Slen: {name} must be an integer of at least {least}, got {value!r}.")
+
+    return value
+
+
+def headers_of(given: Mapping[str, str] | None) -> Mapping[str, str]:
+    headers = dict(given or {})
+
+    if not all(isinstance(name, str) and isinstance(value, str) for name, value in headers.items()):
+        raise TypeError("Slen: headers is a mapping of strings to strings.")
+
+    return MappingProxyType(headers)
+
+
+def logger_of(given: SlenLogger | None) -> SlenLogger:
+    if given is not None and not is_logger(given):
+        raise TypeError("Slen: logger has debug, info, warning and error, as logging.Logger has.")
+
+    return default_logger() if given is None else given
+
+
+# An empty or blank secret is a variable that was not set, not a secret.
+def secret_of(given: str | None) -> str | None:
+    if given is not None and not isinstance(given, str):
+        raise TypeError("Slen: webhook_secret is a string.")
+
+    return None if given is None or not given.strip() else given

slen/_errors.py

@@ -0,0 +1,176 @@
+import builtins
+from collections.abc import Callable, Mapping
+from types import MappingProxyType
+from typing import Any, Final, Literal, TypeAlias
+
+INVALID_REQUEST: Final = "invalid_request"
+INVALID_RESPONSE: Final = "invalid_response"
+WEBHOOK_SIGNATURE_INVALID: Final = "webhook_signature_invalid"
+WEBHOOK_PAYLOAD_INVALID: Final = "webhook_payload_invalid"
+
+WebhookSignatureReason: TypeAlias = Literal[
+    "missing_header", "malformed_header", "outside_tolerance", "no_matching_signature"
+]
+
+_STATE: Final = ("code", "status", "details", "request_id", "retry_after_seconds")
+
+
+class SlenError(Exception):
+    """The root of every error the SDK raises."""
+
+    code: str | None
+    status: int | None
+    details: Mapping[str, Any]
+    request_id: str | None
+    retry_after_seconds: int | None
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        status: int | None = None,
+        details: Mapping[str, Any] | None = None,
+        request_id: str | None = None,
+        retry_after_seconds: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.status = status
+        self.details = MappingProxyType(dict(details or {}))
+        self.request_id = request_id
+        self.retry_after_seconds = retry_after_seconds
+
+    def __reduce__(self) -> tuple[Callable[..., "SlenError"], tuple[object, ...]]:
+        state = {name: getattr(self, name) for name in _STATE}
+        state["details"] = dict(self.details)
+        state.update({name: value for name, value in vars(self).items() if name not in _STATE})
+
+        return _rebuilt, (type(self), str(self), state)
+
+
+def _rebuilt(kind: type[SlenError], message: str, state: dict[str, Any]) -> SlenError:
+    error = kind.__new__(kind, message)
+    Exception.__init__(error, message)
+    vars(error).update({**state, "details": MappingProxyType(dict(state["details"]))})
+
+    return error
+
+
+class AuthenticationError(SlenError):
+    """401 or 403: the key, its scope or the tenant."""
+
+
+class InvalidRequestError(SlenError):
+    """The request was refused for its shape: 422, an unknown code of a 4xx, or a check before the wire."""
+
+
+class SpendRefusedError(SlenError):
+    """Money said no (402); each ceiling has a subtype."""
+
+
+class BudgetExceededError(SpendRefusedError):
+    """The project's or the organization's budget."""
+
+
+class InsufficientCreditsError(SpendRefusedError):
+    """The end customer is out of credits."""
+
+
+class OverrunStoppedError(SpendRefusedError):
+    """An overrun of a budget that stops the run."""
+
+
+class OverrunApprovalRequiredError(SpendRefusedError):
+    """An overrun of a budget that waits for somebody to approve it."""
+
+
+class OperationLimitExceededError(SpendRefusedError):
+    """One operation would cost more than a per-operation budget allows."""
+
+
+class ConcurrencyLimitError(SpendRefusedError):
+    """A concurrency budget has every slot taken; passes when one is freed."""
+
+
+class CustomerNotFoundError(SlenError):
+    """The project has never seen this end customer."""
+
+
+class RateLimitError(SlenError):
+    """429: the key sent more requests than its rate limit allows."""
+
+
+class PolicyDeniedError(SlenError):
+    """A policy of the project refused the run."""
+
+
+class CustomerBlockedError(PolicyDeniedError):
+    """The end customer of the run is blocked, so its new runs are refused; nothing ran."""
+
+
+class IdempotencyConflictError(SlenError):
+    """The idempotency key was used with another body, or its first request is still running."""
+
+
+class ProviderError(SlenError):
+    """A model provider failed or could not be called; any 5xx without a known code lands here too — read code."""
+
+
+class TimeoutError(SlenError, builtins.TimeoutError):
+    """No answer in time (no code), or a run that ran out of time on the server."""
+
+
+class OperationUncertainError(SlenError):
+    """A provider was called and nobody knows what became of the call: the money may be spent."""
+
+
+class ServiceUnavailableError(SlenError):
+    """503 from Slen itself: nothing was done, the request may be sent again."""
+
+
+class FlowRuntimeError(SlenError):
+    """The flow broke while it was walked; the model calls before the break were paid for."""
+
+
+class ConnectionError(SlenError, builtins.ConnectionError):
+    """Slen could not be reached, or the connection broke before the answer was read; no code, no status."""
+
+
+class InvalidResponseError(SlenError):
+    """A 2xx whose body cannot be read as the answer; the call may have gone through."""
+
+
+class WebhookSignatureError(SlenError):
+    """A webhook whose Slen-Signature was not accepted: do not act on its body; reason says why."""
+
+    reason: WebhookSignatureReason
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        reason: WebhookSignatureReason,
+        code: str | None = WEBHOOK_SIGNATURE_INVALID,
+        status: int | None = None,
+        details: Mapping[str, Any] | None = None,
+        request_id: str | None = None,
+        retry_after_seconds: int | None = None,
+    ) -> None:
+        super().__init__(
+            message,
+            code=code,
+            status=status,
+            details=details,
+            request_id=request_id,
+            retry_after_seconds=retry_after_seconds,
+        )
+        self.reason = reason
+
+
+def contract_type_of(error: SlenError) -> str:
+    return type(error).__name__.removesuffix("Error")
+
+
+def refused(message: str) -> InvalidRequestError:
+    return InvalidRequestError(message, code=INVALID_REQUEST)