tabapi 0.1.0__py3-none-any.whl

tabapi/__init__.py

@@ -0,0 +1,7 @@
+"""TabAPI: scikit-learn-style client for tabular foundation models served over HTTP."""
+
+from tabapi.classifier import TabAPIClassifier
+from tabapi.client import TabAPIClient
+
+__all__ = ["TabAPIClassifier", "TabAPIClient"]
+__version__ = "0.1.0"

tabapi/_base.py

@@ -0,0 +1,59 @@
+"""Base class for the scikit-learn estimators backed by the TabICL API."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from sklearn.base import BaseEstimator
+from sklearn.utils.validation import check_is_fitted
+
+from tabapi.client import TabAPIClient
+
+
+class _TabAPIEstimator(BaseEstimator):
+    """Fit and predict on a remote TabICL server, whatever the task.
+
+    Subclasses set ``_task`` and list every parameter in their ``__init__``
+    (scikit-learn reads them from its signature). The connection parameters
+    are ``base_url``, ``timeout``, ``token``, ``max_retries`` and
+    ``backoff_factor``. The model parameters shared by all tasks are
+    ``n_estimators``, ``random_state`` and ``target_name``.
+    """
+
+    _task: str
+
+    def __repr__(self) -> str:
+        """Like the sklearn repr, but never show the token."""
+        text = super().__repr__()
+        if self.token:
+            text = text.replace(repr(self.token), "'***'")
+        return text
+
+    def __sklearn_is_fitted__(self) -> bool:
+        return hasattr(self, "_model_id")
+
+    def _fit_remote(self, X, y, **config) -> None:
+        """Fit a model on the server, with ``config`` as the task-specific parameters."""
+        self._client = TabAPIClient(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            token=self.token,
+            max_retries=self.max_retries,
+            backoff_factor=self.backoff_factor,
+        )
+        self._model_id = self._client.fit(
+            pd.DataFrame(X),
+            y if isinstance(y, pd.Series) else pd.Series(y),
+            task=self._task,
+            target_name=self.target_name,
+            n_estimators=self.n_estimators,
+            random_state=self.random_state,
+            **config,
+        )
+
+    def _predict_remote(self, X, output_type: str) -> np.ndarray:
+        check_is_fitted(self)
+        prediction = self._client.predict(
+            self._model_id, pd.DataFrame(X), task=self._task, output_type=output_type
+        )
+        return np.asarray(prediction)

tabapi/classifier.py

@@ -0,0 +1,133 @@
+"""TabAPIClassifier: scikit-learn-style classifier that calls the TabICL API."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+from sklearn.base import ClassifierMixin
+
+from tabapi._base import _TabAPIEstimator
+
+
+class TabAPIClassifier(ClassifierMixin, _TabAPIEstimator):
+    """
+    Scikit-learn-style classifier that fits and predicts via the TabICL API.
+
+    This estimator does not run TabICL locally; it sends data to a remote
+    server (e.g. deployed via the tabapi Docker image) and uses the returned
+    model_id for subsequent predictions.
+
+    Parameters
+    ----------
+    base_url : str
+        Base URL of the TabICL API (e.g. "http://localhost:8000").
+    timeout : float
+        Request timeout in seconds for fit and predict.
+    token : str or None
+        Bearer token sent as "Authorization: Bearer <token>" when the server
+        requires auth. If None, the TABAPI_API_TOKEN environment variable is
+        read at request time. Prefer the environment variable: an explicit
+        token is an estimator parameter, so it is kept when the estimator is
+        pickled (e.g. saved to a skore project).
+    max_retries : int
+        How many times a request the server could not take (busy, or no
+        healthy backend behind the proxy) is retried. 0 disables retries.
+    backoff_factor : float
+        Base wait between retries, in seconds; doubled after each retry
+        unless the server sends Retry-After.
+    n_estimators : int or None
+        Passed to the server at fit time (TabICL ensemble size).
+    random_state : int or None
+        Passed to the server at fit time.
+    softmax_temperature : float or None
+        Passed to the server at fit time.
+    target_name : str
+        Name the target column is given in the payload sent to the server. Only
+        matters for the server-side schema; predictions are made by model_id.
+        Change it if X already has a feature column named "target", otherwise
+        the client refuses to overwrite that column.
+    """
+
+    _task = "classification"
+
+    def __init__(
+        self,
+        *,
+        base_url: str = "http://localhost:8000",
+        timeout: float = 300.0,
+        token: str | None = None,
+        max_retries: int = 3,
+        backoff_factor: float = 1.0,
+        n_estimators: int | None = None,
+        random_state: int | None = None,
+        softmax_temperature: float | None = None,
+        target_name: str = "target",
+    ):
+        self.base_url = base_url
+        self.timeout = timeout
+        self.token = token
+        self.max_retries = max_retries
+        self.backoff_factor = backoff_factor
+        self.n_estimators = n_estimators
+        self.random_state = random_state
+        self.softmax_temperature = softmax_temperature
+        self.target_name = target_name
+
+    def fit(self, X: pd.DataFrame | np.ndarray, y: pd.Series | np.ndarray) -> TabAPIClassifier:
+        """
+        Fit a model on the server using (X, y).
+
+        Parameters
+        ----------
+        X : DataFrame or ndarray
+            Feature matrix. Converted to DataFrame if ndarray.
+        y : Series or ndarray
+            Target labels.
+
+        Returns
+        -------
+        self
+        """
+        self._fit_remote(X, y, softmax_temperature=self.softmax_temperature)
+        self.classes_ = np.unique(y)
+        return self
+
+    def predict(self, X: pd.DataFrame | np.ndarray) -> np.ndarray:
+        """
+        Predict class labels for X using the model fitted on the server.
+
+        Parameters
+        ----------
+        X : DataFrame or ndarray
+            Feature matrix. Must have same columns as training data.
+
+        Returns
+        -------
+        ndarray of shape (n_samples,) with class labels.
+
+        Raises
+        ------
+        sklearn.exceptions.NotFittedError
+            If called before ``fit``.
+        """
+        return self._predict_remote(X, output_type="preds")
+
+    def predict_proba(self, X: pd.DataFrame | np.ndarray) -> np.ndarray:
+        """
+        Predict class probabilities for X using the model fitted on the server.
+
+        Parameters
+        ----------
+        X : DataFrame or ndarray
+            Feature matrix.
+
+        Returns
+        -------
+        ndarray of shape (n_samples, n_classes) with class probabilities.
+
+        Raises
+        ------
+        sklearn.exceptions.NotFittedError
+            If called before ``fit``.
+        """
+        return self._predict_remote(X, output_type="probas")

tabapi/client.py

@@ -0,0 +1,306 @@
+"""Low-level HTTP client for the TabICL API (fit and predict)."""
+
+from __future__ import annotations
+
+import io
+import json
+import logging
+import os
+import random
+import time
+from collections.abc import Callable
+from typing import Any
+
+import pandas as pd
+import requests
+
+TOKEN_ENV_VAR = "TABAPI_API_TOKEN"
+
+logger = logging.getLogger(__name__)
+
+# 503 means the request was not processed: either the server had no free
+# compute slot (it says so with "retryable": true), or the reverse proxy had
+# no healthy backend to forward it to. Safe to retry for every endpoint.
+_RETRY_ALWAYS = frozenset({503})
+# 502/504 may come back after the server started (or even finished) the work.
+# Retrying is only safe for idempotent calls: predict, not fit (a retried fit
+# would train, and keep in server memory, a second model).
+_RETRY_IF_IDEMPOTENT = frozenset({502, 503, 504})
+# Upper bound on one wait, whatever the server's Retry-After says.
+_MAX_RETRY_DELAY = 60.0
+
+
+def _resolve_token(token: str | None) -> str | None:
+    """Token to send: explicit value, else TABAPI_API_TOKEN.
+
+    Whitespace is stripped, and for a comma-separated list (the server-side
+    format of TABAPI_API_TOKEN) the first non-empty entry is used.
+    """
+    raw = token if token is not None else os.environ.get(TOKEN_ENV_VAR)
+    if not raw:
+        return None
+    for part in raw.split(","):
+        if part.strip():
+            return part.strip()
+    return None
+
+
+class TabAPIClient:
+    """Client for the TabICL API (POST /v1/fit and POST /v1/predict).
+
+    If the server requires bearer auth, pass ``token`` (or set the
+    TABAPI_API_TOKEN environment variable); it is sent as
+    "Authorization: Bearer <token>". The environment variable is read at
+    request time and never stored on the client, so it is not persisted
+    when a fitted estimator is pickled.
+
+    Requests the server could not take (busy server, or proxy with no healthy
+    backend) are retried up to ``max_retries`` times with exponential backoff
+    (``backoff_factor`` * 1, 2, 4, ... seconds, or the server's Retry-After).
+    fit is retried only on 503 and on errors marked ``"retryable": true``;
+    predict, which is idempotent, also on 502 and 504. Set ``max_retries=0``
+    to disable retries.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000",
+        timeout: float = 300.0,
+        token: str | None = None,
+        max_retries: int = 3,
+        backoff_factor: float = 1.0,
+    ):
+        if max_retries < 0:
+            raise ValueError(f"max_retries must be >= 0, got {max_retries}")
+        if backoff_factor < 0:
+            raise ValueError(f"backoff_factor must be >= 0, got {backoff_factor}")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.token = token
+        self.max_retries = max_retries
+        self.backoff_factor = backoff_factor
+
+    def _headers(self) -> dict[str, str]:
+        token = _resolve_token(self.token)
+        if token:
+            return {"Authorization": f"Bearer {token}"}
+        return {}
+
+    @staticmethod
+    def _check_response(r: requests.Response) -> None:
+        """Raise requests.HTTPError, including the server's error detail if present."""
+        if r.ok:
+            return
+        try:
+            body = r.json()
+        except ValueError:
+            body = None
+        if isinstance(body, dict):
+            detail = body.get("detail", r.text)
+        else:
+            # Non-dict JSON (bare string, list, ...) or non-JSON body: fall back to text.
+            detail = r.text if body is None else str(body)
+        if isinstance(detail, dict):
+            detail = detail.get("detail") or detail.get("code") or str(detail)
+        raise requests.HTTPError(
+            f"{r.status_code} {r.reason} for {r.url}: {detail}",
+            response=r,
+        )
+
+    @staticmethod
+    def _marked_retryable(r: requests.Response) -> bool:
+        """True if the server's structured error says ``"retryable": true``."""
+        try:
+            body = r.json()
+        except ValueError:
+            return False
+        detail = body.get("detail") if isinstance(body, dict) else None
+        return isinstance(detail, dict) and detail.get("retryable") is True
+
+    def _should_retry(self, r: requests.Response, idempotent: bool) -> bool:
+        if r.ok:
+            return False
+        if r.status_code in _RETRY_ALWAYS:
+            return True
+        if idempotent and r.status_code in _RETRY_IF_IDEMPOTENT:
+            return True
+        return self._marked_retryable(r)
+
+    def _retry_delay(self, r: requests.Response, attempt: int) -> float:
+        """Server's Retry-After (in seconds) if given, else exponential backoff.
+
+        Stretched by a random 0-50% so clients turned away together do not all
+        come back at the same instant and collide again.
+        """
+        retry_after = r.headers.get("Retry-After")
+        try:
+            delay = float(retry_after) if retry_after is not None else None
+        except ValueError:
+            delay = None  # HTTP-date form: fall back to backoff
+        if delay is None or delay < 0:
+            delay = self.backoff_factor * (2**attempt)
+        delay *= random.uniform(1.0, 1.5)
+        return min(delay, _MAX_RETRY_DELAY)
+
+    def _post(
+        self,
+        path: str,
+        make_files: Callable[[], dict[str, Any]],
+        *,
+        idempotent: bool,
+    ) -> requests.Response:
+        """POST with retries; ``make_files`` builds fresh upload buffers per attempt."""
+        url = f"{self.base_url}{path}"
+        attempt = 0
+        while True:
+            r = requests.post(
+                url,
+                files=make_files(),
+                headers=self._headers(),
+                timeout=self.timeout,
+            )
+            if attempt >= self.max_retries or not self._should_retry(r, idempotent):
+                self._check_response(r)
+                return r
+            delay = self._retry_delay(r, attempt)
+            attempt += 1
+            logger.warning(
+                "%s returned %s; retrying in %.1fs (attempt %d/%d)",
+                path,
+                r.status_code,
+                delay,
+                attempt,
+                self.max_retries,
+            )
+            time.sleep(delay)
+
+    def fit(
+        self,
+        X: pd.DataFrame,
+        y: pd.Series,
+        *,
+        task: str = "classification",
+        target_name: str = "target",
+        n_estimators: int | None = None,
+        random_state: int | None = None,
+        softmax_temperature: float | None = None,
+    ) -> str:
+        """
+        Fit a model on the server. Returns the model_id for use in predict.
+
+        Parameters
+        ----------
+        X : DataFrame
+            Feature matrix.
+        y : Series
+            Target labels.
+        task : str
+            Task the server fits the model for.
+        target_name : str
+            Name of the target column (used in the API schema).
+        n_estimators, random_state, softmax_temperature
+            Optional server-side TabICL config.
+
+        Returns
+        -------
+        model_id : str
+            UUID of the fitted model on the server.
+
+        Raises
+        ------
+        ValueError
+            If ``target_name`` is already a column of ``X``.
+        """
+        if target_name in X.columns:
+            raise ValueError(
+                f"target_name {target_name!r} is already a column in X; "
+                "rename that feature or pass a different target_name"
+            )
+        df = X.copy()
+        df[target_name] = y
+        buf = io.BytesIO()
+        df.to_csv(buf, index=False)
+        csv_bytes = buf.getvalue()
+
+        payload: dict[str, Any] = {
+            "task": task,
+            "schema": {"target": target_name},
+        }
+        config: dict[str, Any] = {}
+        if n_estimators is not None:
+            config["n_estimators"] = n_estimators
+        if random_state is not None:
+            config["random_state"] = random_state
+        if softmax_temperature is not None:
+            config["softmax_temperature"] = softmax_temperature
+        if config:
+            payload["config"] = config
+        data_field = json.dumps(payload)
+
+        r = self._post(
+            "/v1/fit",
+            lambda: {
+                "data": (None, data_field, "application/json"),
+                "dataset_file": ("train.csv", io.BytesIO(csv_bytes), "text/csv"),
+            },
+            idempotent=False,
+        )
+        data = r.json()
+        return data["model_id"]
+
+    def predict(
+        self,
+        model_id: str,
+        X: pd.DataFrame,
+        *,
+        task: str = "classification",
+        output_type: str = "preds",
+    ) -> Any:
+        """
+        Run predictions on the server.
+
+        Parameters
+        ----------
+        model_id : str
+            Model ID returned by fit().
+        X : DataFrame
+            Feature matrix (same columns as training).
+        task : str
+            Task the model was fitted for.
+        output_type : str
+            "preds" for class labels, "probas" for probability arrays.
+
+        Returns
+        -------
+        If output_type == "preds": list of class labels.
+        If output_type == "probas": list of lists (probability per class).
+        """
+        buf = io.BytesIO()
+        X.to_csv(buf, index=False)
+        csv_bytes = buf.getvalue()
+
+        payload = {
+            "model_id": model_id,
+            "task": task,
+            "output_type": output_type,
+        }
+        data_field = json.dumps(payload)
+
+        r = self._post(
+            "/v1/predict",
+            lambda: {
+                "data": (None, data_field, "application/json"),
+                "file": ("predict.csv", io.BytesIO(csv_bytes), "text/csv"),
+            },
+            idempotent=True,
+        )
+        data = r.json()
+        return data["prediction"]
+
+    def health(self) -> bool:
+        """Return True if the server is reachable."""
+        try:
+            r = requests.get(f"{self.base_url}/health", timeout=5.0)
+            return r.status_code == 200
+        except Exception:
+            return False

tabapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: tabapi
+Version: 0.1.0
+Summary: scikit-learn-style Python client for tabular foundation models (TabICL) served over HTTP
+Project-URL: Homepage, https://probabl.ai
+Author: Probabl
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: api-client,foundation-model,in-context-learning,scikit-learn,tabicl,tabular
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: scikit-learn>=1.3.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# tabapi
+
+A scikit-learn-style Python client for tabular foundation models (TFMs) such as
+[TabICL](https://github.com/soda-inria/tabicl), served over HTTP.
+
+TFMs predict by in-context learning: there is no training loop on your machine.
+`tabapi` sends your labelled rows to a TabAPI server, which runs the model, and
+gives you back predictions through the familiar `fit` / `predict` /
+`predict_proba` interface. You don't need torch or a GPU locally.
+
+> **Status: alpha.** The API may change between minor versions. You need access
+> to a running TabAPI server.
+
+## Install
+
+```bash
+pip install tabapi
+```
+
+Requires Python 3.10+.
+
+## Quickstart
+
+```python
+from sklearn.datasets import load_breast_cancer
+from sklearn.model_selection import train_test_split
+from tabapi import TabAPIClassifier
+
+X, y = load_breast_cancer(return_X_y=True, as_frame=True)
+X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=0)
+
+clf = TabAPIClassifier(base_url="https://your-tabapi-server.example.com")
+clf.fit(X_train, y_train)          # uploads the training context, gets a model id
+y_pred = clf.predict(X_test)
+proba = clf.predict_proba(X_test)
+print(clf.score(X_test, y_test))
+```
+
+`TabAPIClassifier` is a regular scikit-learn estimator, so it works with
+`cross_val_score`, `Pipeline`, `clone`, and so on.
+
+## Authentication
+
+If the server requires a bearer token, pass `token=...` or set the
+`TABAPI_API_TOKEN` environment variable. The environment variable is read at
+request time and is never stored on the estimator, so it does not end up in a
+pickled model.
+
+## Retries
+
+Requests the server could not take (busy server, proxy with no healthy backend)
+are retried with exponential backoff, honouring `Retry-After`. Tune this with
+`max_retries` and `backoff_factor`, or turn it off with `max_retries=0`.
+
+## Low-level client
+
+`TabAPIClient` exposes the raw HTTP calls (`fit`, `predict`, `health`) if you
+don't want the scikit-learn wrapper.
+
+## License
+
+BSD-3-Clause.

tabapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+tabapi/__init__.py,sha256=1CXIF99E1z7TUnz0piwGJS5mVXqJBjZYEm_fXggdDxQ,245
+tabapi/_base.py,sha256=u_TB3g8ScBgrymHWL5V4szgBOQeqxU4kLSg0Pep6zJw,2061
+tabapi/classifier.py,sha256=mLhyPX7Gy6WeDiBka6mMFEiszRr8_m9w6UNViXPdeBw,4482
+tabapi/client.py,sha256=a4AnoWsHlE0lyich9iZgo-JnHnDaG050q7UB711MW-k,10155
+tabapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tabapi-0.1.0.dist-info/METADATA,sha256=-OwG9-vSKj_dpOGaY0MiduEaMElUF9BhRKvkXheMx2A,3168
+tabapi-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+tabapi-0.1.0.dist-info/licenses/LICENSE,sha256=p5FMhe5GUbgQ_RZASK7inMy3EB_i58z0O6YuI2wVLtA,1494
+tabapi-0.1.0.dist-info/RECORD,,

tabapi-0.1.0.dist-info/WHEEL

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

tabapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Probabl
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.