cubic-sdk 0.3.2__py3-none-any.whl

cubic/__init__.py

@@ -0,0 +1,91 @@
+"""Cubic Python SDK.
+
+Quickstart::
+
+    from cubic import Cubic
+
+    client = Cubic(api_key="mxk_...")
+    result = client.completions.create(
+        cube_id="cbe_a1B2c3D4e5F6g7",
+        variables={"customer_name": "Ada"},
+    )
+    print(result.content)
+"""
+
+from . import webhooks
+from ._async_client import AsyncCubic
+from ._client import Cubic
+from ._exceptions import (
+    APIConnectionError,
+    APITimeoutError,
+    AuthenticationError,
+    CompletionError,
+    CompletionNotFoundError,
+    CompletionTimeoutError,
+    CubeNotFoundError,
+    CubicError,
+    InsufficientCreditsError,
+    InternalServerError,
+    InvalidRequestError,
+    MissingVariableError,
+    ModelNotFoundError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProviderError,
+    RateLimitError,
+    VersionNotFoundError,
+    WaitTimeoutError,
+    WebhookSignatureError,
+)
+from ._version import __version__
+from .types import (
+    AttemptError,
+    CompletionRecord,
+    CompletionResult,
+    Cube,
+    CubeModel,
+    Metrics,
+    Model,
+    PolycubeResult,
+    Segment,
+    SingleCompletion,
+)
+
+__all__ = [
+    "Cubic",
+    "AsyncCubic",
+    "webhooks",
+    "__version__",
+    # exceptions
+    "CubicError",
+    "APIConnectionError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "PermissionDeniedError",
+    "NotFoundError",
+    "ModelNotFoundError",
+    "CubeNotFoundError",
+    "VersionNotFoundError",
+    "CompletionNotFoundError",
+    "InvalidRequestError",
+    "InsufficientCreditsError",
+    "RateLimitError",
+    "CompletionTimeoutError",
+    "InternalServerError",
+    "CompletionError",
+    "MissingVariableError",
+    "ProviderError",
+    "WaitTimeoutError",
+    "WebhookSignatureError",
+    # types
+    "AttemptError",
+    "Metrics",
+    "SingleCompletion",
+    "CompletionResult",
+    "PolycubeResult",
+    "Segment",
+    "CompletionRecord",
+    "Cube",
+    "CubeModel",
+    "Model",
+]

cubic/_async_client.py

@@ -0,0 +1,130 @@
+"""The asynchronous Cubic client — same surface as :class:`cubic.Cubic`, awaitable."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from typing import Any
+
+import httpx
+
+from . import _exceptions as err
+from ._client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    classify_retry,
+    error_from_response,
+    next_delay,
+)
+from ._version import __version__
+
+
+class AsyncCubic:
+    """Asynchronous client for the Cubic API.
+
+    Accepts the same arguments as :class:`cubic.Cubic`; every resource method
+    is a coroutine. Use it as an async context manager or call ``aclose()``.
+
+    Args:
+        api_key: A ``mxk_…`` API key. Falls back to the ``CUBIC_API_KEY``
+            environment variable.
+        base_url: API origin. Falls back to ``CUBIC_BASE_URL``, then the
+            hosted API (https://api.cubic.zone).
+        timeout: httpx timeout for all requests.
+        max_retries: Automatic retries for transient failures (connection
+            errors, capacity 429s, and — when the request is idempotent —
+            5xx responses).
+        http_client: Bring your own ``httpx.AsyncClient`` (proxies, custom
+            transports, testing). The SDK will not close it for you.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: httpx.Timeout | float | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.AsyncClient | None = None,
+        backoff_base: float = 0.5,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("CUBIC_API_KEY")
+        if not self.api_key:
+            raise err.CubicError(
+                "No API key provided. Pass api_key=... or set the CUBIC_API_KEY "
+                "environment variable. Keys are created in the Cubic dashboard "
+                "and start with 'mxk_'."
+            )
+        self.base_url = (base_url or os.environ.get("CUBIC_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max_retries
+        self._backoff_base = backoff_base
+        self._own_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(
+            timeout=timeout if timeout is not None else DEFAULT_TIMEOUT
+        )
+        self._kind_cache: dict[str, str] = {}
+
+        from .resources.completions import AsyncCompletions
+        from .resources.cubes import AsyncCubes
+        from .resources.models import AsyncModels
+
+        self.completions = AsyncCompletions(self)
+        self.cubes = AsyncCubes(self)
+        self.models = AsyncModels(self)
+
+    # ---- lifecycle ----
+    async def aclose(self) -> None:
+        if self._own_http:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncCubic":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    # ---- transport ----
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict | None = None,
+        params: dict | None = None,
+        idempotent: bool = False,
+    ) -> httpx.Response:
+        url = f"{self.base_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"cubic-python/{__version__}",
+        }
+        attempt = 0
+        while True:
+            retry_after: float | None = None
+            try:
+                response = await self._http.request(
+                    method, url, json=json_body, params=params, headers=headers
+                )
+            except (httpx.ConnectError, httpx.ConnectTimeout) as e:
+                # The request never reached the server — always safe to retry.
+                exc: err.CubicError = err.APIConnectionError(f"Could not reach {self.base_url}: {e}")
+                retryable = True
+            except httpx.TimeoutException as e:
+                exc = err.APITimeoutError(f"Request timed out: {e}")
+                retryable = idempotent
+            except httpx.TransportError as e:
+                exc = err.APIConnectionError(f"Transport error: {e}")
+                retryable = idempotent
+            else:
+                if response.status_code < 400:
+                    return response
+                exc = error_from_response(response)
+                retryable, retry_after = classify_retry(response, exc, idempotent)
+
+            if not retryable or attempt >= self.max_retries:
+                raise exc
+            attempt += 1
+            delay = next_delay(attempt, retry_after, self._backoff_base)
+            if delay > 0:
+                await asyncio.sleep(delay)

cubic/_client.py

@@ -0,0 +1,247 @@
+"""The synchronous Cubic client: transport, auth, retries, and error mapping."""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from typing import Any
+
+import httpx
+
+from . import _exceptions as err
+from ._version import __version__
+
+# The hosted Cubic API. Point CUBIC_BASE_URL or base_url= at another deployment
+# (e.g. http://localhost:8010 for local development).
+DEFAULT_BASE_URL = "https://api.cubic.zone"
+
+# Completions can legitimately run for minutes (the server's own execution
+# deadline is ~150s), so the read timeout is generous.
+DEFAULT_TIMEOUT = httpx.Timeout(180.0, connect=5.0)
+DEFAULT_MAX_RETRIES = 2
+
+# Statuses safe to retry only when the request carries an idempotency key
+# (client_request_id): the server may or may not have started executing.
+_RETRY_STATUSES_IDEMPOTENT = {500, 502, 503}
+
+
+def classify_retry(
+    response: httpx.Response, exc: err.CubicError, idempotent: bool
+) -> tuple[bool, float | None]:
+    """Decide whether a failed response may be retried, and any server-directed delay."""
+    status = response.status_code
+    if status == 429:
+        # Capacity load-shedding has no error_code and is always safe to
+        # retry (the request was never admitted). Credit/quota 429s are
+        # caller errors — never retry those.
+        if isinstance(exc, err.RateLimitError) and exc.error_code is None:
+            return True, exc.retry_after
+        return False, None
+    if status in _RETRY_STATUSES_IDEMPOTENT and idempotent:
+        return True, None
+    return False, None
+
+
+def next_delay(attempt: int, retry_after: float | None, base: float) -> float:
+    if retry_after is not None:
+        return retry_after
+    delay = min(base * (2 ** (attempt - 1)), 8.0)
+    return delay + random.uniform(0, delay / 4)
+
+
+class Cubic:
+    """Synchronous client for the Cubic API.
+
+    Args:
+        api_key: A ``mxk_…`` API key. Falls back to the ``CUBIC_API_KEY``
+            environment variable.
+        base_url: API origin. Falls back to ``CUBIC_BASE_URL``, then the
+            hosted API (https://api.cubic.zone).
+        timeout: httpx timeout for all requests.
+        max_retries: Automatic retries for transient failures (connection
+            errors, capacity 429s, and — when the request is idempotent —
+            5xx responses).
+        http_client: Bring your own ``httpx.Client`` (proxies, custom
+            transports, testing). The SDK will not close it for you.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        timeout: httpx.Timeout | float | None = None,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        http_client: httpx.Client | None = None,
+        backoff_base: float = 0.5,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("CUBIC_API_KEY")
+        if not self.api_key:
+            raise err.CubicError(
+                "No API key provided. Pass api_key=... or set the CUBIC_API_KEY "
+                "environment variable. Keys are created in the Cubic dashboard "
+                "and start with 'mxk_'."
+            )
+        self.base_url = (base_url or os.environ.get("CUBIC_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max_retries
+        self._backoff_base = backoff_base
+        self._own_http = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout if timeout is not None else DEFAULT_TIMEOUT)
+        # Remembers which public IDs turned out to be polycubes, so we stop
+        # attaching fields the chain path rejects (e.g. client_request_id).
+        self._kind_cache: dict[str, str] = {}
+
+        from .resources.completions import Completions
+        from .resources.cubes import Cubes
+        from .resources.models import Models
+
+        self.completions = Completions(self)
+        self.cubes = Cubes(self)
+        self.models = Models(self)
+
+    # ---- lifecycle ----
+    def close(self) -> None:
+        if self._own_http:
+            self._http.close()
+
+    def __enter__(self) -> "Cubic":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    # ---- transport ----
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict | None = None,
+        params: dict | None = None,
+        idempotent: bool = False,
+    ) -> httpx.Response:
+        url = f"{self.base_url}{path}"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "User-Agent": f"cubic-python/{__version__}",
+        }
+        attempt = 0
+        while True:
+            retry_after: float | None = None
+            try:
+                response = self._http.request(method, url, json=json_body, params=params, headers=headers)
+            except (httpx.ConnectError, httpx.ConnectTimeout) as e:
+                # The request never reached the server — always safe to retry.
+                exc: err.CubicError = err.APIConnectionError(f"Could not reach {self.base_url}: {e}")
+                retryable = True
+            except httpx.TimeoutException as e:
+                exc = err.APITimeoutError(f"Request timed out: {e}")
+                retryable = idempotent
+            except httpx.TransportError as e:
+                exc = err.APIConnectionError(f"Transport error: {e}")
+                retryable = idempotent
+            else:
+                if response.status_code < 400:
+                    return response
+                exc = error_from_response(response)
+                retryable, retry_after = classify_retry(response, exc, idempotent)
+
+            if not retryable or attempt >= self.max_retries:
+                raise exc
+            attempt += 1
+            delay = next_delay(attempt, retry_after, self._backoff_base)
+            if delay > 0:
+                time.sleep(delay)
+
+
+def _flatten_validation_detail(detail: list[Any]) -> str:
+    """Flatten FastAPI's 422 detail array into one readable message."""
+    parts = []
+    for item in detail:
+        if not isinstance(item, dict):
+            parts.append(str(item))
+            continue
+        loc = item.get("loc") or []
+        # drop the leading "body" segment — callers think in field names
+        field = ".".join(str(x) for x in loc[1:] if x != "__root__") or ".".join(map(str, loc))
+        msg = item.get("msg", "invalid")
+        parts.append(f"{field}: {msg}" if field else msg)
+    return "; ".join(parts) or "Invalid request"
+
+
+def error_from_response(response: httpx.Response) -> err.CubicError:
+    """Map a non-2xx API response onto the SDK exception hierarchy.
+
+    Dispatch is by ``error_code`` first, HTTP status second — the API surfaces
+    e.g. insufficient credits under more than one status.
+    """
+    status = response.status_code
+    request_id = response.headers.get("X-Request-ID")
+    try:
+        body = response.json()
+    except Exception:
+        body = None
+    detail = body.get("detail") if isinstance(body, dict) else None
+    error_code = body.get("error_code") if isinstance(body, dict) else None
+    common: dict[str, Any] = {
+        "error_code": error_code,
+        "status_code": status,
+        "request_id": request_id,
+        "body": body,
+    }
+
+    # Pydantic validation errors arrive as a list of field errors.
+    if isinstance(detail, list):
+        return err.InvalidRequestError(_flatten_validation_detail(detail), **common)
+
+    message = detail if isinstance(detail, str) else f"HTTP {status} from Cubic API"
+
+    if error_code == "insufficient_credits" or status == 402:
+        g = body if isinstance(body, dict) else {}
+        return err.InsufficientCreditsError(
+            message,
+            required=g.get("required"),
+            balance=g.get("balance"),
+            grace=g.get("grace"),
+            topup_allowed=g.get("topup_allowed"),
+            **common,
+        )
+    if status == 401:
+        return err.AuthenticationError(message, **common)
+    if status == 403:
+        return err.PermissionDeniedError(message, **common)
+    if status == 404:
+        if error_code == "version_not_found":
+            return err.VersionNotFoundError(message, **common)
+        if error_code in ("cube_not_found", "chain_not_found", "prompt_not_found"):
+            return err.CubeNotFoundError(
+                message + " (the ID may not exist, or your key may not own it — "
+                "marketplace cube definitions are not readable by subscribers)",
+                **common,
+            )
+        if error_code == "completion_not_found":
+            return err.CompletionNotFoundError(message, **common)
+        return err.NotFoundError(message, **common)
+    if status == 422:
+        return err.InvalidRequestError(message, **common)
+    if status == 429:
+        retry_after_header = response.headers.get("Retry-After")
+        try:
+            retry_after = float(retry_after_header) if retry_after_header else None
+        except ValueError:
+            retry_after = None
+        return err.RateLimitError(message, retry_after=retry_after, **common)
+    if status == 504:
+        # The deadline response is a CompletionResponse envelope, not the
+        # standard error shape — pull the human message out of attempt_errors.
+        if isinstance(body, dict):
+            for ae in body.get("attempt_errors") or []:
+                if isinstance(ae, dict) and ae.get("message"):
+                    message = ae["message"]
+                    common["error_code"] = ae.get("error_code")
+                    break
+        return err.CompletionTimeoutError(message, **common)
+    if status >= 500:
+        return err.InternalServerError(message, **common)
+    return err.CubicError(message, **common)

cubic/_exceptions.py

@@ -0,0 +1,171 @@
+"""Exception hierarchy for the Cubic SDK.
+
+Every exception carries ``error_code`` (the API's machine-readable code),
+``status_code`` (HTTP, when the error came from a non-2xx response),
+``request_id`` (the ``X-Request-ID`` correlation header — quote it in support
+requests), and ``body`` (the raw parsed response body, when available).
+
+Pipeline failures — where the API returns HTTP 200 with ``status: "error"`` —
+are raised as :class:`CompletionError` subclasses and additionally carry the
+parsed result object on ``.result``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class CubicError(Exception):
+    """Base class for every error raised by the Cubic SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        error_code: str | None = None,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        body: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.error_code = error_code
+        self.status_code = status_code
+        self.request_id = request_id
+        self.body = body
+
+
+class APIConnectionError(CubicError):
+    """The SDK could not reach the Cubic API (DNS, refused connection, TLS…)."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The HTTP request timed out client-side before a response arrived."""
+
+
+class AuthenticationError(CubicError):
+    """401 — the API key is missing, invalid, revoked, or expired."""
+
+
+class PermissionDeniedError(CubicError):
+    """403 — e.g. ``marketplace_subscription_required`` or ``override_forbidden``."""
+
+
+class NotFoundError(CubicError):
+    """404 — the referenced resource does not exist (or is not yours)."""
+
+
+class CubeNotFoundError(NotFoundError):
+    """The cube/polycube ID could not be resolved.
+
+    The API deliberately returns the same response for an unknown ID and for a
+    cube your key does not own, so foreign IDs cannot be probed. Note that
+    marketplace subscribers can *run* a listed cube but cannot read its
+    definition, and ``cubes.retrieve`` does not (yet) serve polycube IDs.
+    """
+
+
+class VersionNotFoundError(CubeNotFoundError):
+    """The cube exists but the pinned ``version`` does not."""
+
+
+class CompletionNotFoundError(NotFoundError):
+    """No completion record exists for the given ``request_id``."""
+
+
+class ModelNotFoundError(NotFoundError):
+    """No catalog model matches the given name (client-side lookup against
+    ``models.list()``). The message includes close-match suggestions."""
+
+
+class InvalidRequestError(CubicError):
+    """422 — the request body failed validation (unknown fields, bad types,
+    out-of-range parameters, or fields not applicable to a polycube)."""
+
+
+class InsufficientCreditsError(CubicError):
+    """The credit gate rejected the request. Not retryable — top up first."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        required: int | None = None,
+        balance: int | None = None,
+        grace: int | None = None,
+        topup_allowed: bool | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.required = required
+        self.balance = balance
+        self.grace = grace
+        self.topup_allowed = topup_allowed
+
+
+class RateLimitError(CubicError):
+    """429 — the server is at capacity or a quota was exceeded.
+
+    Capacity 429s are retried automatically; if you see this, retries were
+    exhausted. ``retry_after`` echoes the server's ``Retry-After`` header.
+    """
+
+    def __init__(self, message: str, *, retry_after: float | None = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class CompletionTimeoutError(CubicError):
+    """504 — the completion exceeded the server's execution deadline."""
+
+
+class InternalServerError(CubicError):
+    """5xx — an unexpected server-side failure."""
+
+
+class WaitTimeoutError(CubicError):
+    """``wait()`` gave up before the queued completion's result was persisted.
+
+    The run may still complete server-side — the ``request_id`` stays valid for
+    ``completions.retrieve`` and the callback delivery is unaffected.
+    """
+
+
+class WebhookSignatureError(CubicError):
+    """The callback payload's ``X-Maxwell-Signature`` header is missing or does
+    not match the payload — treat the delivery as unauthenticated."""
+
+
+class CompletionError(CubicError):
+    """The request was accepted but the completion pipeline failed
+    (HTTP 200 with ``status: "error"``).
+
+    ``result`` holds the fully parsed response — including ``attempt_errors``
+    and, for polycubes, per-node ``segments`` — for inspection.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        result: Any = None,
+        attempt_errors: list[Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, **kwargs)
+        self.result = result
+        self.attempt_errors = attempt_errors or []
+
+
+class MissingVariableError(CompletionError):
+    """A required template variable was not provided (or failed coercion)."""
+
+    def __init__(self, message: str, *, variable_name: str | None = None, **kwargs: Any) -> None:
+        super().__init__(message, **kwargs)
+        self.variable_name = variable_name
+
+
+class ProviderError(CompletionError):
+    """Every model attempt failed at the provider stage (rate limits, outages,
+    circuit breaker open, missing provider credential…). Check
+    ``attempt_errors`` for the per-attempt detail, including ``is_retryable``."""

cubic/_version.py

@@ -0,0 +1 @@
+__version__ = "0.3.2"