causilo-client 0.8.13__py3-none-any.whl

causilo_client/__init__.py

@@ -0,0 +1,39 @@
+"""Radix inference API client.
+
+    from radix import Radix
+
+    r = Radix(key_file="radix-key.json")
+    pred = r.predict(context_df, query_df, target="label", model="radix-a-clf")
+
+Handles authentication, Parquet encoding, multipart assembly, token refresh
+and retries. Callers pass two DataFrames and nothing else.
+"""
+
+from .client import (
+    MODELS,
+    Causilo,
+    RadixAuthError,
+    RadixError,
+    RadixOverloaded,
+    RadixQuotaExceeded,
+    RadixTimeout,
+    RadixTooLarge,
+    RadixUnavailable,
+    RadixValidationError,
+    to_batch_parquet,
+)
+
+__all__ = [
+    "Causilo",
+    "RadixError",
+    "RadixValidationError",
+    "RadixTooLarge",
+    "RadixUnavailable",
+    "RadixQuotaExceeded",
+    "RadixOverloaded",
+    "RadixTimeout",
+    "RadixAuthError",
+    "MODELS",
+    "to_batch_parquet",
+]
+__version__ = "0.8.13"

causilo_client/client.py

@@ -0,0 +1,774 @@
+"""Causilo inference API client.
+
+Import name is causilo_client, not causilo: that one is the model package on
+PyPI, and a customer may well have both installed.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import os
+import threading
+import time
+import uuid
+from datetime import timezone
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+import requests
+
+# Checked before a request is sent, so a stale copy of this list refuses keys
+# the server would have served. radix-b-clf and radix-b-reg were served until
+# 2026-09-11 and are gone; causilo-clf and causilo-reg replace them. A customer
+# running an older build of this client will be refused locally on a causilo
+# key -- the fix is a client release, not a server change.
+MODELS = ("radix-a-clf", "radix-a-reg", "causilo-clf", "causilo-reg")
+
+# Where an operator-issued token rides on top of Authorization. SageMaker's
+# front end consumes the SigV4 Authorization header and does not pass it to the
+# container, so a token sent only there arrives nowhere and the call is billed
+# to nobody. This header is the one AWS documents as passed through, capped at
+# 1024 ASCII characters. The pair form leaves room for anything else that wants
+# the field -- a trace identifier, say -- which a bare token would not.
+#
+# Sent on every call once a token= is configured, not only against SageMaker: a
+# client cannot tell the two platforms apart from the endpoint alone, and the
+# server treats the same token in both headers as one identity rather than two.
+# A caller on the key_file= path sends nothing here. A Google ID token is not
+# ours to check, it usually exceeds 1024 characters, and Cloud Run IAM has
+# already established who they are.
+_CUSTOM_ATTRIBUTES_HEADER = "X-Amzn-SageMaker-Custom-Attributes"
+_TOKEN_ATTRIBUTE = "radix-token"
+
+# Sent with every prediction and again with a cancel. Ours to choose, because a
+# call that times out never sees the server's request id and still has to name
+# what it is giving up on. Neither Cloud Run nor SageMaker tells the server when
+# a caller hangs up, so without this the server finishes the work, bills it and
+# logs it as served.
+_CANCEL_KEY_HEADER = "X-Radix-Cancel-Key"
+
+# Retry when the server marks the error retryable=true, or when it answers with
+# one of these status codes.
+# 504 and 502 are deliberately absent. Cloud Run answers 504 when the request
+# passed its own timeout and 502 when the container died mid-request; either
+# way the server took the work and charged for it, and in the 502 case the
+# process that would have refunded it is the one that died. Retrying pays for
+# it again -- four times over, which is the shape the server-side refunds were
+# written to close.
+_RETRY_STATUS = frozenset({429, 500, 503})
+_MAX_RETRIES = 3
+_BACKOFF_S = (1.0, 3.0, 8.0)
+# Cap on a server-sent Retry-After, so one bad header cannot hang the caller.
+_MAX_RETRY_AFTER_S = 30.0
+
+# Refresh the ID token this many seconds before it expires. A large table can
+# spend minutes in a single call, and a token that lapses in flight comes back
+# as a 401 after the work has already been paid for.
+_TOKEN_MARGIN_S = 300
+
+
+class RadixError(Exception):
+    """An error returned by the server.
+
+    `request_id` identifies the failing call in the operator's logs. It is
+    appended to the message rather than left on the attribute alone, because
+    what reaches a support request is whatever the traceback printed, and
+    nobody reads attributes off an exception they did not expect. Empty when
+    the refusal came from the platform in front of the service rather than
+    from the service itself.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        error_code: str = "",
+        request_id: str = "",
+    ) -> None:
+        if request_id:
+            message = f"{message} (request {request_id})"
+        super().__init__(message)
+        self.status = status
+        self.error_code = error_code
+        self.request_id = request_id
+
+
+class RadixValidationError(RadixError):
+    """The request was invalid (422). Fix it and send again."""
+
+
+class RadixTooLarge(RadixError):
+    """The table is too large (413). Reduce rows or columns."""
+
+
+class RadixUnavailable(RadixError):
+    """Temporarily unavailable (503). Retrying may succeed."""
+
+
+class RadixTimeout(RadixError):
+    """No response within the client's timeout.
+
+    `refunded` is the number of cells the server gave back when this client
+    told it the call was abandoned, 0 if there was nothing to give back, and
+    None if the cancel itself could not be delivered -- in which case the
+    charge may stand and the message says so.
+
+    Deliberately not a subclass of RadixUnavailable: the request reached the
+    server, which is very likely still computing it, so this is the one
+    failure that must not be retried automatically. Every retry is charged
+    against the monthly quota for work that will complete regardless, and the
+    server has nothing to refund because nothing failed there.
+    """
+
+    refunded: int | None = None
+
+
+class RadixAuthError(RadixError):
+    """The credential was rejected (401) or is not permitted (403).
+
+    403 is what an unfinished setup looks like: the service account exists and
+    the token is valid, but it has not been granted the invoker role on this
+    service, or the key belongs to another project.
+    """
+
+
+class RadixQuotaExceeded(RadixError):
+    """The monthly usage quota is spent (429). Resets on the 1st, UTC.
+
+    Retrying will not help before the reset. Ask for a higher cap, or send
+    less.
+
+    `scope` says which of the two caps refused: "caller" is this one API key,
+    "tenant" is everything the account holds together. The fixes differ, so it
+    is worth branching on. A key that is spent while the account has room
+    means another key still works; an account that is spent means none of them
+    do.
+
+    Empty against a server older than 0.8.2, which refused without saying
+    which cap. Treat "" as "unknown", not as "caller" -- guessing the cheaper
+    of the two sends the customer to buy a second key that will not work.
+    """
+
+    def __init__(self, message: str, *, status: int = 0, error_code: str = "",
+                 request_id: str = "", scope: str = "") -> None:
+        super().__init__(
+            message, status=status, error_code=error_code, request_id=request_id
+        )
+        self.scope = scope
+
+
+class RadixOverloaded(RadixError):
+    """The service had no free capacity in time (429).
+
+    Not the same 429 as RadixQuotaExceeded, and the difference matters: this
+    one says the request waited for an instance longer than Cloud Run is
+    willing to hold it, so it never reached the model at all. Nothing was
+    charged against the monthly quota, and calling again once the queue drains
+    succeeds. A caller that reads this as "we are out of quota" goes looking
+    for a limit increase that would change nothing.
+
+    The two are told apart by the body: our own 429 carries an error_code,
+    the one Cloud Run generates does not.
+    """
+
+
+class Causilo:
+    """A client bound to one inference endpoint.
+
+    Authentication, pick one:
+
+        key_file   Path to a service account key JSON. The standard route when
+                   calling from outside GCP. Requires ``google-auth``.
+        token      A bearer token issued by the operator. Use this when the
+                   caller cannot reach ``oauth2.googleapis.com``, and on
+                   SageMaker, where it is also what the usage records are
+                   attributed to.
+        (neither)  No authentication. Local testing only.
+
+    A ``token`` travels in ``Authorization`` and in
+    ``X-Amzn-SageMaker-Custom-Attributes`` both, because the SageMaker front
+    end passes on only the second. Callers who invoke the endpoint through
+    boto3 rather than this client send the same string themselves:
+    ``invoke_endpoint(..., CustomAttributes="radix-token=<token>")``.
+
+    ``endpoint`` falls back to the ``RADIX_ENDPOINT`` environment variable.
+    """
+
+    def __init__(
+        self,
+        endpoint: str | None = None,
+        *,
+        key_file: str | Path | None = None,
+        token: str | None = None,
+        timeout: float = 900.0,
+        session: requests.Session | None = None,
+    ) -> None:
+        endpoint = endpoint or os.environ.get("RADIX_ENDPOINT", "")
+        if not endpoint:
+            raise ValueError(
+                "endpoint is required. Pass it directly or set RADIX_ENDPOINT."
+            )
+        # Require https. A bearer token and the whole table go in the request;
+        # over http they travel in clear. A typo'd http:// endpoint would still
+        # "work" (Cloud Run redirects to https), so nothing would flag the leak
+        # -- reject it here instead. localhost is exempt for local testing.
+        from urllib.parse import urlparse
+
+        parsed = urlparse(endpoint)
+        if parsed.scheme != "https" and parsed.hostname not in (
+            "localhost",
+            "127.0.0.1",
+        ):
+            raise ValueError(
+                f"endpoint must use https (got {parsed.scheme or 'no scheme'}). "
+                "The token and data are sent in the request body."
+            )
+        # A comma would split the token in half inside the custom attributes
+        # header, and a non-ASCII one cannot travel in an HTTP field value at
+        # all. Neither can be a token we issued -- the server reads its list
+        # from a comma-separated variable -- so this catches a typo or a
+        # pasted-in credential from somewhere else, here rather than as a 401
+        # against a live endpoint.
+        if token is not None and ("," in token or not token.isascii()):
+            raise ValueError(
+                "token must be ASCII and cannot contain a comma. Check that "
+                "the whole token was copied, and only the token."
+            )
+        self.endpoint = endpoint.rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+        self._static_token = token
+        self._key_file = Path(key_file) if key_file else None
+        self._credentials = None
+        self._token_cache: tuple[str, float] | None = None
+        self._token_lock = threading.Lock()
+
+    def __getstate__(self) -> dict:
+        """Let a Radix cross a process boundary.
+
+        multiprocessing and joblib pickle whatever the worker function closes
+        over, and a lock, a requests.Session and a credentials object are none
+        of them picklable -- so building the client once and mapping over
+        chunks, which is the obvious way to use this, used to fail with
+        "cannot pickle '_thread.lock' object" before a single call went out.
+        Those are dropped and rebuilt on the other side, along with any minted
+        ID token: each process mints its own.
+
+        The session's transport settings are carried across by value, because
+        losing them is silent and only in the workers. A caller who configures
+        a corporate CA bundle or an explicit proxy, watches one call succeed,
+        then fans out would otherwise have every worker fail TLS with a
+        message about the endpoint being unreachable.
+
+        A ``token=`` credential IS in the pickle, in clear text -- it is the
+        only way the worker can authenticate at all. joblib writes pickles to
+        temporary files, so treat a pickled client as the credential itself.
+        """
+        state = self.__dict__.copy()
+        for field in ("_token_lock", "_session", "_credentials", "_token_cache"):
+            state.pop(field, None)
+        session = self._session
+        state["_session_settings"] = {
+            "verify": session.verify,
+            "proxies": dict(session.proxies),
+            "cert": session.cert,
+            "trust_env": session.trust_env,
+            "headers": dict(session.headers),
+        }
+        return state
+
+    def __setstate__(self, state: dict) -> None:
+        settings = state.pop("_session_settings", {})
+        self.__dict__.update(state)
+        self._token_lock = threading.Lock()
+        self._session = requests.Session()
+        for name, value in settings.items():
+            if name == "headers":
+                self._session.headers.update(value)
+            else:
+                setattr(self._session, name, value)
+        self._credentials = None
+        self._token_cache = None
+
+    # --- Public API -------------------------------------------------------
+
+    def predict(
+        self,
+        context: pd.DataFrame,
+        query: pd.DataFrame,
+        *,
+        target: str,
+        model: str,
+        output_type: str | None = None,
+        quantiles: list[float] | None = None,
+    ):
+        """Return the prediction only.
+
+        ``context`` includes the target column; ``query`` does not. Feature
+        columns must match in name and order across both frames.
+        """
+        prediction, _ = self.predict_with_metadata(
+            context,
+            query,
+            target=target,
+            model=model,
+            output_type=output_type,
+            quantiles=quantiles,
+        )
+        return prediction
+
+    def predict_with_metadata(
+        self,
+        context: pd.DataFrame,
+        query: pd.DataFrame,
+        *,
+        target: str,
+        model: str,
+        output_type: str | None = None,
+        quantiles: list[float] | None = None,
+    ) -> tuple[Any, dict]:
+        """Return ``(prediction, metadata)``.
+
+        ``metadata`` carries the settings the server applied and any warning.
+        For classification, ``metadata["classes"]`` gives the column order of
+        the probability matrix.
+        """
+        if model not in MODELS:
+            raise ValueError(f"model must be one of: {', '.join(MODELS)}.")
+
+        params: dict[str, Any] = {"model": model, "target": target}
+        if output_type:
+            params["output_type"] = output_type
+        if quantiles:
+            params["quantiles"] = list(quantiles)
+
+        body, content_type = _multipart(context, query, params)
+        response = self._post(body, content_type, accept="application/json")
+        doc = response.json()
+        return doc["prediction"], doc.get("metadata", {})
+
+    def health(self) -> bool:
+        """Whether the model is loaded and ready to serve."""
+        try:
+            r = self._session.get(
+                f"{self.endpoint}/ping", headers=self._headers(), timeout=30
+            )
+        except requests.RequestException:
+            return False
+        return r.status_code == 200
+
+    def wake(self, timeout: float = 120.0) -> bool:
+        """Warm the instance up ahead of time.
+
+        With no traffic the service scales to zero, and coming back takes
+        on the order of ten seconds. Call this while preparing a large table
+        so the two overlap.
+        """
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            if self.health():
+                return True
+            time.sleep(2.0)
+        return False
+
+    def usage(self) -> dict:
+        """This month's consumption for the credential this client holds.
+
+        Returns the body of ``GET /usage``. Always has ``caller`` and
+        ``metered``; the figures are present only when ``metered`` is true.
+
+            u = rx.usage()
+            if u["metered"] and u["remaining"] < 1_000_000:
+                ...
+
+        ``metered`` is false both when no cap applies and when the ledger could
+        not be read, and those are not distinguished on purpose. Treat it as
+        "no figure available", never as zero -- a client that defaults to zero
+        reports full remaining quota during an outage of the thing that counts
+        it.
+
+        Scoped to this credential. There is no argument for whose usage to
+        fetch, because the credential is the answer.
+        """
+        r = self._session.get(
+            f"{self.endpoint}/usage", headers=self._headers(), timeout=30
+        )
+        if r.status_code != 200:
+            raise _to_error(r)
+        return r.json()
+
+    # --- Internals --------------------------------------------------------
+
+    def _post(self, body: bytes, content_type: str, accept: str) -> requests.Response:
+        last: RadixError | None = None
+        cancel_key = uuid.uuid4().hex
+        for attempt in range(_MAX_RETRIES + 1):
+            # Reset per attempt. A connection error on attempt 0 leaves response
+            # unbound, and a stale response from an earlier attempt must not feed
+            # _sleep_for a stale Retry-After.
+            response: requests.Response | None = None
+            headers = {**self._headers(), _CANCEL_KEY_HEADER: cancel_key}
+            headers["Content-Type"] = content_type
+            headers["Accept"] = accept
+            try:
+                response = self._session.post(
+                    f"{self.endpoint}/invocations",
+                    data=body,
+                    headers=headers,
+                    timeout=self.timeout,
+                )
+            except requests.exceptions.ReadTimeout as exc:
+                refunded = self._cancel(cancel_key)
+                # The request was delivered and the server is still working on
+                # it. Retrying charges the month again for a call that will
+                # finish anyway, and the server cannot refund it -- nothing
+                # failed on its side. This is the same 4x shape the server-side
+                # refunds were written to close, on the half of the wire they
+                # cannot reach.
+                # Tell the server we gave up. It cannot see the hang-up itself
+                # -- neither platform passes one to the container -- so this is
+                # the only way the charge for work nobody will receive comes
+                # back. Best effort: a cancel that fails leaves things as they
+                # were before it existed, and the message says which happened.
+                if refunded:
+                    released = f" The server released the charge ({refunded:,} cells)."
+                elif refunded == 0:
+                    released = " Nothing was pending to release."
+                else:
+                    released = (
+                        " The cancel could not be delivered, so the charge may "
+                        "stand; quote the time of the call if you dispute it."
+                    )
+                err = RadixTimeout(
+                    f"No response within {self.timeout:.0f}s, and the server is "
+                    "probably still computing. The call was not retried, "
+                    "because a retry is charged again. Raise timeout= or send "
+                    f"a smaller table. ({exc}){released}"
+                )
+                err.refunded = refunded
+                raise err from None
+            except requests.exceptions.SSLError as exc:
+                # A CA bundle problem, which is what a corporate TLS proxy
+                # looks like. No number of retries fixes it.
+                raise RadixError(
+                    f"TLS verification failed: {exc}. If the network inspects "
+                    "TLS, point requests at the corporate CA bundle "
+                    "(REQUESTS_CA_BUNDLE, or session=)."
+                ) from None
+            except requests.RequestException as exc:
+                last = RadixUnavailable(f"Could not reach the endpoint: {exc}")
+            else:
+                if response.status_code == 200:
+                    return response
+                last = _to_error(response)
+                # A 401 mid-run is usually a token that lapsed in flight, so
+                # drop the cache and let the next attempt mint a fresh one
+                # rather than failing a call the GPU has already been paid for.
+                # Only worth doing when there is something to refresh from: a
+                # static token cannot change, so retrying it just makes a wrong
+                # credential take three backoffs to report.
+                if last.status == 401 and self._key_file and attempt < _MAX_RETRIES:
+                    self._token_cache = None
+                elif not _retryable(response, last):
+                    raise last
+
+            if attempt < _MAX_RETRIES:
+                time.sleep(_sleep_for(response, attempt))
+
+        raise last if last else RadixError("The request failed.")
+
+    def _cancel(self, cancel_key: str) -> int | None:
+        """Tell the server a call was abandoned. Best effort, never raises.
+
+        Returns cells refunded, 0 if nothing was pending, None if the cancel
+        could not be delivered. Ten seconds is generous for a request that
+        does no inference; a cancel that hangs must not extend a timeout the
+        caller has already waited through.
+        """
+        try:
+            r = self._session.post(
+                f"{self.endpoint}/cancel",
+                headers={**self._headers(), _CANCEL_KEY_HEADER: cancel_key},
+                timeout=10,
+            )
+            if r.status_code != 200:
+                return None
+            return int(r.json().get("refunded", 0))
+        except (requests.RequestException, ValueError):
+            return None
+
+    def _headers(self) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        token = self._bearer()
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        if self._static_token:
+            headers[_CUSTOM_ATTRIBUTES_HEADER] = (
+                f"{_TOKEN_ATTRIBUTE}={self._static_token}"
+            )
+        return headers
+
+    def _bearer(self) -> str | None:
+        if self._static_token:
+            return self._static_token
+        if not self._key_file:
+            return None
+
+        now = time.time()
+        if self._token_cache and self._token_cache[1] - _TOKEN_MARGIN_S > now:
+            return self._token_cache[0]
+
+        # Serialise the mint. Threads that all start on a cold cache otherwise
+        # build IDTokenCredentials from the same file at once and refresh the
+        # shared object concurrently; some of them read self._credentials.token
+        # while another refresh is mid-flight and send an empty Authorization
+        # header, which Cloud Run answers with 403. Measured on 2026-08-27:
+        # six threads sharing one Radix, four came back 403. Under the lock the
+        # first thread fills the cache and the rest take the fast path above.
+        with self._token_lock:
+            now = time.time()
+            if self._token_cache and self._token_cache[1] - _TOKEN_MARGIN_S > now:
+                return self._token_cache[0]
+            return self._mint_token(now)
+
+    def _mint_token(self, now: float) -> str:
+        try:
+            import google.auth.transport.requests
+            from google.oauth2 import service_account
+        except ImportError:
+            raise RadixError(
+                "Using a service account key requires google-auth: "
+                "pip install google-auth"
+            ) from None
+
+        # Everything google-auth raises here -- a key file that is not a service
+        # account key, a clock too far off, a network that cannot reach
+        # oauth2.googleapis.com -- would otherwise surface as a library
+        # exception the caller has no reason to have imported, and the last of
+        # those is the likeliest failure on a corporate network. Name the two
+        # things worth checking.
+        try:
+            if self._credentials is None:
+                self._credentials = (
+                    service_account.IDTokenCredentials.from_service_account_file(
+                        str(self._key_file), target_audience=self.endpoint
+                    )
+                )
+            self._credentials.refresh(google.auth.transport.requests.Request())
+        except Exception as exc:
+            self._credentials = None
+            raise RadixError(
+                f"Could not get a token for {self._key_file}: "
+                f"{type(exc).__name__}: {exc}. Check that the file is a service "
+                "account key in JSON, and that this machine can reach "
+                "oauth2.googleapis.com."
+            ) from None
+        expiry = self._credentials.expiry
+        # google-auth returns expiry as a naive UTC datetime. Calling
+        # .timestamp() on a naive datetime interprets it in local time, which in
+        # a UTC-negative zone reads the token as valid hours past its real
+        # expiry -- so the client keeps sending a lapsed token and every call
+        # 401s. Attach UTC before converting.
+        if expiry is not None:
+            expiry_ts = expiry.replace(tzinfo=timezone.utc).timestamp()
+        else:
+            expiry_ts = now + 3600
+        self._token_cache = (self._credentials.token, expiry_ts)
+        return self._token_cache[0]
+
+
+def _sleep_for(response, attempt: int) -> float:
+    """How long to wait before the next attempt.
+
+    A server-sent Retry-After wins over the local backoff schedule: it is the
+    only party that knows when capacity frees up. Capped so a bad value cannot
+    stall the caller for minutes.
+    """
+    if response is not None:
+        raw = response.headers.get("Retry-After", "")
+        if raw.isdigit():
+            return min(float(raw), _MAX_RETRY_AFTER_S)
+    return _BACKOFF_S[min(attempt, len(_BACKOFF_S) - 1)]
+
+
+# --- Request assembly --------------------------------------------------------
+
+
+def _to_parquet(frame: pd.DataFrame) -> bytes:
+    buf = io.BytesIO()
+    frame.to_parquet(buf, index=False, compression="zstd")
+    return buf.getvalue()
+
+
+def _multipart(
+    context: pd.DataFrame, query: pd.DataFrame, params: dict
+) -> tuple[bytes, str]:
+    boundary = uuid.uuid4().hex
+    chunks: list[bytes] = []
+    for name, frame in (("context", context), ("query", query)):
+        chunks.append(
+            f"--{boundary}\r\n"
+            f'Content-Disposition: form-data; name="{name}"; '
+            f'filename="{name}.parquet"\r\n'
+            f"Content-Type: application/vnd.apache.parquet\r\n\r\n".encode()
+            + _to_parquet(frame)
+            + b"\r\n"
+        )
+    chunks.append(
+        f"--{boundary}\r\n"
+        f'Content-Disposition: form-data; name="params"\r\n'
+        f"Content-Type: application/json\r\n\r\n"
+        f"{json.dumps(params)}\r\n".encode()
+    )
+    chunks.append(f"--{boundary}--\r\n".encode())
+    return b"".join(chunks), f"multipart/form-data; boundary={boundary}"
+
+
+def to_batch_parquet(
+    frame: pd.DataFrame,
+    *,
+    target: str,
+    model: str,
+    path: str | Path,
+    output_type: str | None = None,
+) -> Path:
+    """Write a single Parquet file for batch transform.
+
+    **Rows with a blank target become the query**; filled rows are the
+    context. Parameters go into the Parquet schema metadata because batch
+    transform cannot carry headers.
+    """
+    import pyarrow as pa
+    import pyarrow.parquet as pq
+
+    if target not in frame.columns:
+        raise ValueError(f"Table has no target column {target!r}.")
+    if not frame[target].isna().any():
+        raise ValueError(
+            f"Target column {target!r} has no blank values. "
+            "Leave the target empty on the rows you want predicted."
+        )
+
+    params: dict[str, Any] = {"model": model, "target": target}
+    if output_type:
+        params["output_type"] = output_type
+
+    table = pa.Table.from_pandas(frame, preserve_index=False)
+    table = table.replace_schema_metadata(
+        {b"radix-params": json.dumps(params).encode("utf-8")}
+    )
+    path = Path(path)
+    pq.write_table(table, path, compression="zstd")
+    return path
+
+
+# --- Response handling -------------------------------------------------------
+
+
+def _to_error(response: requests.Response) -> RadixError:
+    """Turn a failed response into the right exception class.
+
+    The status inside the RFC 9457 body wins over the HTTP status. SageMaker
+    rewrites every 4xx and 5xx a container returns into a 424 ModelError, so
+    on that path the HTTP status says nothing about what went wrong. RFC 9457
+    keeps the original in the `status` member for exactly this case.
+    """
+    try:
+        doc = response.json()
+    except ValueError:
+        doc = {}
+
+    status = doc.get("status")
+    if not isinstance(status, int):
+        status = response.status_code
+
+    code = doc.get("code") or doc.get("error_code", "")
+    message = (
+        doc.get("detail")
+        or doc.get("message")
+        or response.reason
+        or "The request failed."
+    )
+    if status == 502:
+        return RadixUnavailable(
+            "The service dropped this request (502). It was charged and was "
+            "not retried automatically, because a retry is charged again. Try "
+            "once more, and send a smaller table if it repeats.",
+            status=status,
+            error_code=code,
+        )
+    if status == 504:
+        return RadixTimeout(
+            "The service did not finish this request within its own timeout "
+            "(504). It was charged and is probably still running, so the call "
+            "was not retried. Send a smaller table.",
+            status=status,
+            error_code=code,
+        )
+    cls = {
+        400: RadixValidationError,
+        401: RadixAuthError,
+        403: RadixAuthError,
+        406: RadixValidationError,
+        413: RadixTooLarge,
+        422: RadixValidationError,
+        429: RadixQuotaExceeded,
+        503: RadixUnavailable,
+    }.get(status, RadixError)
+    # Cloud Run rejects an unauthorized call before the container sees it, so
+    # the body is HTML and `message` above falls back to the reason phrase --
+    # "Forbidden", by itself, for the single likeliest failure on install day.
+    # Say what to check instead.
+    if cls is RadixAuthError and not code:
+        message = (
+            "The service rejected this credential (403 Forbidden). Check that "
+            "the service account in the key file has been granted the Cloud "
+            "Run invoker role on this service, and that the key belongs to the "
+            "right project."
+            if status == 403
+            else "The service did not accept this credential (401 "
+            "Unauthorized). The token may have expired, or the key file may "
+            "not match this endpoint."
+        )
+    # Two different things answer 429. Ours carries `code` in an RFC 9457 body;
+    # the one Cloud Run returns when no instance came free in time is a plain
+    # HTML page with no code at all. Reporting both as "quota exhausted" sends
+    # the caller after a limit increase for what is really a queue that was
+    # busy for a moment.
+    if cls is RadixQuotaExceeded and code != "quota_exceeded":
+        cls = RadixOverloaded
+    # Header first: it arrives even when the body is not ours to read. Both
+    # copies exist because SageMaker strips the header, so neither alone is
+    # enough.
+    request_id = str(
+        response.headers.get("X-Request-Id", "") or doc.get("request_id", "")
+    )
+    if cls is RadixQuotaExceeded:
+        return cls(message, status=status, error_code=code,
+                   request_id=request_id, scope=str(doc.get("scope", "")))
+    return cls(message or "No instance was free in time.", status=status,
+               error_code=code, request_id=request_id)
+
+
+def _retryable(response: requests.Response, error: RadixError) -> bool:
+    """Trust the server's own retryable flag first; fall back to the status code.
+
+    The server knows whether the failure was transient -- a 500 from a busy
+    engine is worth another attempt, one from a malformed table never is. The
+    status code is only a guess, so it decides only when the flag is absent.
+    """
+    try:
+        doc = response.json()
+    except ValueError:
+        doc = {}
+    flag = doc.get("retryable")
+    if isinstance(flag, bool):
+        return flag
+    status = doc.get("status")
+    if not isinstance(status, int):
+        status = response.status_code
+    return status in _RETRY_STATUS
+

causilo_client-0.8.13.dist-info/METADATA

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: causilo-client
+Version: 0.8.13
+Summary: Python client for the Causilo inference API
+License: Proprietary
+Project-URL: Homepage, https://nums.world
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=15
+Requires-Dist: requests>=2.32
+Requires-Dist: google-auth>=2.28
+
+# causilo-client
+
+Python client for the Causilo inference API. Send a table with the answers
+filled in and a table with them blank; get a prediction for every blank row.
+
+## Install
+
+```bash
+pip install -U causilo-client
+```
+
+Python 3.11 or newer. `pandas`, `pyarrow`, `requests` and `google-auth` are
+pulled in automatically.
+
+The import name is `causilo_client`. `causilo` on PyPI is the model package,
+and the two can be installed side by side. Code written against the earlier
+`radix` name changes one import line: `from causilo_client import Causilo`.
+
+## Use
+
+```python
+import os
+
+from causilo_client import Causilo
+
+cx = Causilo(
+    os.environ["CAUSILO_ENDPOINT"],
+    key_file=os.environ["CAUSILO_KEY_FILE"],
+)
+
+pred = cx.predict(context_df, query_df, target="churned", model="causilo-clf")
+```
+
+`context_df` holds the target column; `query_df` does not. The feature columns
+must match in name and order across the two. The endpoint URL and the
+credential are issued to you at handover; neither is published here.
+
+Authentication takes either a service account key file (`key_file=`) or a
+bearer token issued by the operator (`token=`). Which one applies is agreed
+before handover.
+
+The integration guide covers the call arguments, the input rules, the response
+metadata, what each error means, and what the client does on your behalf when a
+call times out.

causilo_client-0.8.13.dist-info/RECORD

@@ -0,0 +1,6 @@
+causilo_client/__init__.py,sha256=HyUmmAIzNwnRfbcaB6xidkd2qqmAodD02cjM0PmkITE,833
+causilo_client/client.py,sha256=2Q8KEmF2btVEEz654ISWq2bSp8g1D7_tH4wSg7Gh04E,32124
+causilo_client-0.8.13.dist-info/METADATA,sha256=3pkwV8niLpB5i4r-0apOAy-F3BHli2w9J8HSi9hLXko,1724
+causilo_client-0.8.13.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+causilo_client-0.8.13.dist-info/top_level.txt,sha256=jXX4_JiFj_wxrC0ksiWZiBTEpmBtE-UJqY58gOrA0eY,15
+causilo_client-0.8.13.dist-info/RECORD,,

causilo_client-0.8.13.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

causilo_client-0.8.13.dist-info/top_level.txt

@@ -0,0 +1 @@
+causilo_client