From f62cc786ede9bf9b5c2dd283e3cc18a99b9f608f Mon Sep 17 00:00:00 2001
From: Tyler Riccardi <247895347+tylrcc@users.noreply.github.com>
Date: Wed, 11 Nov 2026 22:35:20 +0000
Subject: [PATCH 1/2] docs: add executable quickstart notebook with Colab
badges
examples/quickstart.ipynb runs the quickstart end to end with its
outputs kept: install tabctx[standalone,tabicl,client], start
python -m tabctx.serve in the background (TABCTX_BACKEND=tabicl),
fit credit-g with TabctxClassifier and predict, fit a regressor and
show predict_quantiles, then list and delete the contexts and stop
the server.
An Open in Colab badge linking to the notebook is added to the
README Quickstart section and to docs/getting-started/quickstart.md.
---
README.md | 6 +-
docs/getting-started/quickstart.md | 6 +-
examples/quickstart.ipynb | 457 +++++++++++++++++++++++++++++
3 files changed, 467 insertions(+), 2 deletions(-)
create mode 100644 examples/quickstart.ipynb
diff --git a/README.md b/README.md
index f002986..d74d67e 100644
--- a/README.md
+++ b/README.md
@@ -72,7 +72,11 @@ own GPUs.
## Quickstart
-Run a server on your laptop (CPU works; it uses the GPU if there is one):
+[](https://colab.research.google.com/github/VectorInstitute/tabctx/blob/main/examples/quickstart.ipynb)
+
+Run the whole quickstart in your browser with the
+[notebook](examples/quickstart.ipynb), or on your laptop (CPU works; it
+uses the GPU if there is one):
```bash
pip install "tabctx[standalone,tabicl,client]"
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index f619dc5..45cbcfa 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -1,8 +1,12 @@
# Quickstart
+[](https://colab.research.google.com/github/VectorInstitute/tabctx/blob/main/examples/quickstart.ipynb)
+
Run a tabctx server on your laptop, fit a real dataset and predict
against it. A CPU is enough; the server uses a GPU if it finds one.
-tabctx needs Python 3.12 or newer.
+tabctx needs Python 3.12 or newer. Prefer a notebook? The
+[quickstart notebook](https://github.com/VectorInstitute/tabctx/blob/main/examples/quickstart.ipynb)
+runs this whole page end to end.
## 1. Install and start a server
diff --git a/examples/quickstart.ipynb b/examples/quickstart.ipynb
new file mode 100644
index 0000000..d0b4e50
--- /dev/null
+++ b/examples/quickstart.ipynb
@@ -0,0 +1,457 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "cfe05809",
+ "metadata": {},
+ "source": [
+ "# tabctx quickstart\n",
+ "\n",
+ "Fit a table once, keep it as a cached *context* on a server, and predict against it with a scikit-learn-style API. This notebook runs the whole flow end to end: install, start a server (CPU is fine), classify, regress with prediction quantiles, and manage contexts."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4eb6943b",
+ "metadata": {},
+ "source": [
+ "## 1. Install"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "ac7b3069",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-11T22:32:10.461627Z",
+ "iopub.status.busy": "2026-11-11T22:32:10.461448Z",
+ "iopub.status.idle": "2026-11-11T22:32:14.363213Z",
+ "shell.execute_reply": "2026-11-11T22:32:14.362009Z"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "!pip install -q \"tabctx[standalone,tabicl,client]\""
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "409f9924",
+ "metadata": {},
+ "source": [
+ "## 2. Start a server\n",
+ "\n",
+ "The server hosts the TabICL model. The first start downloads the TabICLv2 weights (BSD-3, no account needed). We start it in the background and wait until it answers."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "069dd645",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-11T22:32:14.366317Z",
+ "iopub.status.busy": "2026-11-11T22:32:14.366064Z",
+ "iopub.status.idle": "2026-11-11T22:33:44.642958Z",
+ "shell.execute_reply": "2026-11-11T22:33:44.642469Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "{'data': [{'id': 'tabicl-v2', 'object': 'model', 'default': True}]}"
+ ]
+ },
+ "execution_count": 2,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "import json\n",
+ "import os\n",
+ "import subprocess\n",
+ "import sys\n",
+ "import time\n",
+ "import urllib.request\n",
+ "\n",
+ "env = {**os.environ, \"TABCTX_BACKEND\": \"tabicl\"}\n",
+ "server = subprocess.Popen(\n",
+ " [sys.executable, \"-m\", \"tabctx.serve\"],\n",
+ " env=env,\n",
+ " stdout=subprocess.DEVNULL,\n",
+ " stderr=subprocess.DEVNULL,\n",
+ ")\n",
+ "\n",
+ "models = None\n",
+ "for _ in range(180):\n",
+ " try:\n",
+ " with urllib.request.urlopen(\"http://127.0.0.1:8000/v1/models\", timeout=2) as resp:\n",
+ " models = json.load(resp)\n",
+ " break\n",
+ " except Exception:\n",
+ " time.sleep(5)\n",
+ "\n",
+ "assert models is not None, \"server did not come up\"\n",
+ "models"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "2b5d87c9",
+ "metadata": {},
+ "source": [
+ "## 3. Fit once, predict many (classification)\n",
+ "\n",
+ "`fit` sends the table to the server, which encodes it into a cached context. Every later `predict` / `predict_proba` reuses that context."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "f2c406ce",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-11T22:33:44.728917Z",
+ "iopub.status.busy": "2026-11-11T22:33:44.728571Z",
+ "iopub.status.idle": "2026-11-11T22:34:44.680054Z",
+ "shell.execute_reply": "2026-11-11T22:34:44.678987Z"
+ }
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "context id: sklearn-93906881b2b76a20dd1a638b8bf37862\n"
+ ]
+ }
+ ],
+ "source": [
+ "from sklearn.datasets import fetch_openml\n",
+ "from sklearn.model_selection import train_test_split\n",
+ "\n",
+ "from tabctx import TabctxClassifier, TabctxClient\n",
+ "\n",
+ "X, y = fetch_openml(\"credit-g\", version=1, as_frame=True, return_X_y=True)\n",
+ "X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=0)\n",
+ "\n",
+ "client = TabctxClient(\"http://127.0.0.1:8000\")\n",
+ "clf = TabctxClassifier(client=client)\n",
+ "clf.fit(X_train, y_train)\n",
+ "print(\"context id:\", clf.dataset_id_)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "fde60009",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-11T22:34:44.699083Z",
+ "iopub.status.busy": "2026-11-11T22:34:44.698816Z",
+ "iopub.status.idle": "2026-11-11T22:34:52.212283Z",
+ "shell.execute_reply": "2026-11-11T22:34:52.210403Z"
+ }
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "accuracy: 0.772\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "array([[0.7023325 , 0.29766747],\n",
+ " [0.05054151, 0.94945848],\n",
+ " [0.04760469, 0.95239532],\n",
+ " [0.26294938, 0.73705065],\n",
+ " [0.39968097, 0.60031903]])"
+ ]
+ },
+ "execution_count": 4,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "print(\"accuracy:\", clf.score(X_test, y_test))\n",
+ "clf.predict_proba(X_test[:5])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9d7973c2",
+ "metadata": {},
+ "source": [
+ "## 4. Regression with prediction quantiles\n",
+ "\n",
+ "`TabctxRegressor.predict_quantiles` returns predictive quantiles for each row, not just a point estimate. (The diabetes dataset ships with scikit-learn, so this cell needs no download.)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "06969f36",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-11T22:34:52.215051Z",
+ "iopub.status.busy": "2026-11-11T22:34:52.214816Z",
+ "iopub.status.idle": "2026-11-11T22:35:02.351567Z",
+ "shell.execute_reply": "2026-11-11T22:35:02.350755Z"
+ }
+ },
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "context id: sklearn-aea702693a87d2751cc473edb459f246\n"
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "array([164.15979004, 143.35258484, 152.58087158, 130.20314026,\n",
+ " 195.56369019])"
+ ]
+ },
+ "execution_count": 5,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "from sklearn.datasets import load_diabetes\n",
+ "\n",
+ "from tabctx import TabctxRegressor\n",
+ "\n",
+ "data = load_diabetes(as_frame=True)\n",
+ "Xr, yr = data.data, data.target\n",
+ "Xr_train, Xr_test = Xr.iloc[:-100], Xr.iloc[-100:]\n",
+ "yr_train, yr_test = yr.iloc[:-100], yr.iloc[-100:]\n",
+ "\n",
+ "reg = TabctxRegressor(client=client)\n",
+ "reg.fit(Xr_train, yr_train)\n",
+ "print(\"context id:\", reg.dataset_id_)\n",
+ "reg.predict(Xr_test[:5])"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "id": "a01752e5",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-11T22:35:02.353893Z",
+ "iopub.status.busy": "2026-11-11T22:35:02.353630Z",
+ "iopub.status.idle": "2026-11-11T22:35:02.958799Z",
+ "shell.execute_reply": "2026-11-11T22:35:02.957944Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "
\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " q5 | \n",
+ " q50 | \n",
+ " q95 | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " 69.302078 | \n",
+ " 160.332001 | \n",
+ " 269.507080 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " 55.275356 | \n",
+ " 138.298859 | \n",
+ " 248.152664 | \n",
+ "
\n",
+ " \n",
+ " | 2 | \n",
+ " 62.262737 | \n",
+ " 149.525345 | \n",
+ " 253.321518 | \n",
+ "
\n",
+ " \n",
+ " | 3 | \n",
+ " 52.836693 | \n",
+ " 122.921402 | \n",
+ " 230.515656 | \n",
+ "
\n",
+ " \n",
+ " | 4 | \n",
+ " 94.553528 | \n",
+ " 195.324875 | \n",
+ " 295.893463 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
"
+ ],
+ "text/plain": [
+ " q5 q50 q95\n",
+ "0 69.302078 160.332001 269.507080\n",
+ "1 55.275356 138.298859 248.152664\n",
+ "2 62.262737 149.525345 253.321518\n",
+ "3 52.836693 122.921402 230.515656\n",
+ "4 94.553528 195.324875 295.893463"
+ ]
+ },
+ "execution_count": 6,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "import pandas as pd\n",
+ "\n",
+ "quantiles = (0.05, 0.5, 0.95)\n",
+ "q = reg.predict_quantiles(Xr_test[:5], quantiles=quantiles)\n",
+ "pd.DataFrame(q, columns=[f\"q{int(q_ * 100)}\" for q_ in quantiles])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "9cca4507",
+ "metadata": {},
+ "source": [
+ "## 5. List and delete contexts\n",
+ "\n",
+ "Contexts live on the server until they are evicted or deleted. `client.datasets()` lists them; `client.delete(...)` removes one."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 7,
+ "id": "594bd733",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-11T22:35:02.961580Z",
+ "iopub.status.busy": "2026-11-11T22:35:02.961337Z",
+ "iopub.status.idle": "2026-11-11T22:35:03.012973Z",
+ "shell.execute_reply": "2026-11-11T22:35:03.011921Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "['sklearn-93906881b2b76a20dd1a638b8bf37862',\n",
+ " 'sklearn-aea702693a87d2751cc473edb459f246']"
+ ]
+ },
+ "execution_count": 7,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "[d[\"dataset_id\"] for d in client.datasets()]"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "id": "3d377819",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-11T22:35:03.015000Z",
+ "iopub.status.busy": "2026-11-11T22:35:03.014784Z",
+ "iopub.status.idle": "2026-11-11T22:35:03.112360Z",
+ "shell.execute_reply": "2026-11-11T22:35:03.110732Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "[]"
+ ]
+ },
+ "execution_count": 8,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "client.delete(clf.dataset_id_)\n",
+ "client.delete(reg.dataset_id_)\n",
+ "client.datasets()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "bcdb5901",
+ "metadata": {},
+ "source": [
+ "## 6. Shut the server down"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 9,
+ "id": "14664151",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-11-11T22:35:03.114866Z",
+ "iopub.status.busy": "2026-11-11T22:35:03.114610Z",
+ "iopub.status.idle": "2026-11-11T22:35:03.209491Z",
+ "shell.execute_reply": "2026-11-11T22:35:03.200252Z"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "server.terminate()"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.12.3"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
From 26453f9898f66457833f133dd2b3db46907fe032 Mon Sep 17 00:00:00 2001
From: Amrit Krishnan
Date: Wed, 18 Nov 2026 08:04:33 -0500
Subject: [PATCH 2/2] docs: harden quickstart notebook from review
- Start the server on a free port in its own session, log to a file,
stop waiting when it exits and show the log tail; poll via
TabctxClient (no hard-coded URL twice); TABCTX_COMPILE=0 for a fast
start on GPU runtimes; %pip installs into the kernel's interpreter.
- Regression uses train_test_split and checks interval coverage on
held-out rows; quantile labels no longer truncate.
- Note that estimators re-fit a deleted context on their next predict.
- Re-executed against tabctx 0.21.0; execution timestamps dropped.
- ruff-format the notebook and run code checks on .ipynb changes.
- README links the Colab notebook by absolute URL (PyPI); docs say
what the notebook covers.
- python-multipart floor 0.0.13 (the server imports python_multipart).
- CHANGELOG entry.
Co-Authored-By: Claude Opus 5.5
---
.github/workflows/code_checks.yml | 2 +
CHANGELOG.md | 4 +
README.md | 7 +-
docs/getting-started/quickstart.md | 3 +-
examples/quickstart.ipynb | 264 +++++++++++++----------------
pyproject.toml | 8 +-
uv.lock | 8 +-
7 files changed, 138 insertions(+), 158 deletions(-)
diff --git a/.github/workflows/code_checks.yml b/.github/workflows/code_checks.yml
index 97287d1..70465b0 100644
--- a/.github/workflows/code_checks.yml
+++ b/.github/workflows/code_checks.yml
@@ -14,6 +14,7 @@ on:
- .pre-commit-config.yaml
- .github/workflows/code_checks.yml
- '**.py'
+ - '**.ipynb'
- uv.lock
- pyproject.toml
- 'deploy/**'
@@ -23,6 +24,7 @@ on:
- .pre-commit-config.yaml
- .github/workflows/code_checks.yml
- '**.py'
+ - '**.ipynb'
- uv.lock
- pyproject.toml
- 'deploy/**'
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ca9dfa7..a85d5fc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,10 @@
# Changelog
## [Unreleased]
+### Added
+- **A quickstart notebook you can run in Colab** (`examples/quickstart.ipynb`, #113): install, start a server, classify, regress with prediction quantiles checked on held-out rows, and list and delete contexts. Colab badges in the README and the docs quickstart. (From @tylrcc in #134.)
+### Fixed
+- The `python-multipart` floor is now 0.0.13: the server imports `python_multipart`, which older releases don't have, so an environment that already had one failed at startup.
## [0.21.0] - 2026-11-13
### Added
diff --git a/README.md b/README.md
index 9ae2c91..68dc9a4 100644
--- a/README.md
+++ b/README.md
@@ -75,9 +75,10 @@ own GPUs.
[](https://colab.research.google.com/github/VectorInstitute/tabctx/blob/main/examples/quickstart.ipynb)
-Run the whole quickstart in your browser with the
-[notebook](examples/quickstart.ipynb), or on your laptop (CPU works; it
-uses the GPU if there is one):
+Try the Python quickstart in your browser with the
+[Colab notebook](https://colab.research.google.com/github/VectorInstitute/tabctx/blob/main/examples/quickstart.ipynb),
+or run a server on your laptop (CPU works; it uses the GPU if there is
+one):
```bash
pip install "tabctx[standalone,tabicl,client]"
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index d3f268b..e66666b 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -6,7 +6,8 @@ Run a tabctx server on your laptop, fit a real dataset and predict
against it. A CPU is enough; the server uses a GPU if it finds one.
tabctx needs Python 3.12 or newer. Prefer a notebook? The
[quickstart notebook](https://github.com/VectorInstitute/tabctx/blob/main/examples/quickstart.ipynb)
-runs this whole page end to end.
+runs the Python steps of this page end to end: install, server,
+classification, regression with quantiles, and managing contexts.
## 1. Install and start a server
diff --git a/examples/quickstart.ipynb b/examples/quickstart.ipynb
index d0b4e50..5f367ed 100644
--- a/examples/quickstart.ipynb
+++ b/examples/quickstart.ipynb
@@ -7,7 +7,7 @@
"source": [
"# tabctx quickstart\n",
"\n",
- "Fit a table once, keep it as a cached *context* on a server, and predict against it with a scikit-learn-style API. This notebook runs the whole flow end to end: install, start a server (CPU is fine), classify, regress with prediction quantiles, and manage contexts."
+ "Fit a table once, keep it as a cached *context* on a server, and predict against it with a scikit-learn-style API. This notebook runs the Python quickstart end to end: install, start a server (CPU is fine), classify, regress with prediction quantiles, and manage contexts. tabctx needs Python 3.12 or newer."
]
},
{
@@ -22,17 +22,18 @@
"cell_type": "code",
"execution_count": 1,
"id": "ac7b3069",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-11-11T22:32:10.461627Z",
- "iopub.status.busy": "2026-11-11T22:32:10.461448Z",
- "iopub.status.idle": "2026-11-11T22:32:14.363213Z",
- "shell.execute_reply": "2026-11-11T22:32:14.362009Z"
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "Note: you may need to restart the kernel to use updated packages.\n"
+ ]
}
- },
- "outputs": [],
+ ],
"source": [
- "!pip install -q \"tabctx[standalone,tabicl,client]\""
+ "%pip install -q \"tabctx[standalone,tabicl,client]\""
]
},
{
@@ -42,60 +43,67 @@
"source": [
"## 2. Start a server\n",
"\n",
- "The server hosts the TabICL model. The first start downloads the TabICLv2 weights (BSD-3, no account needed). We start it in the background and wait until it answers."
+ "The server hosts the TabICL model. The first start downloads the TabICLv2 weights (BSD-3, no account needed). We start it in the background on a free port and wait until it answers. Its log goes to `tabctx-server.log`; if it exits, the cell shows the end of the log."
]
},
{
"cell_type": "code",
"execution_count": 2,
"id": "069dd645",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-11-11T22:32:14.366317Z",
- "iopub.status.busy": "2026-11-11T22:32:14.366064Z",
- "iopub.status.idle": "2026-11-11T22:33:44.642958Z",
- "shell.execute_reply": "2026-11-11T22:33:44.642469Z"
- }
- },
+ "metadata": {},
"outputs": [
{
- "data": {
- "text/plain": [
- "{'data': [{'id': 'tabicl-v2', 'object': 'model', 'default': True}]}"
- ]
- },
- "execution_count": 2,
- "metadata": {},
- "output_type": "execute_result"
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "serving: ['tabicl-v2']\n"
+ ]
}
],
"source": [
- "import json\n",
+ "import atexit\n",
"import os\n",
+ "import socket\n",
"import subprocess\n",
"import sys\n",
"import time\n",
- "import urllib.request\n",
"\n",
- "env = {**os.environ, \"TABCTX_BACKEND\": \"tabicl\"}\n",
+ "from tabctx import TabctxClient\n",
+ "\n",
+ "# A free port, so nothing else on this machine (or an earlier run) answers for us.\n",
+ "with socket.socket() as s:\n",
+ " s.bind((\"127.0.0.1\", 0))\n",
+ " port = s.getsockname()[1]\n",
+ "\n",
+ "log = open(\"tabctx-server.log\", \"w\") # noqa: SIM115 (open while the server runs)\n",
"server = subprocess.Popen(\n",
- " [sys.executable, \"-m\", \"tabctx.serve\"],\n",
- " env=env,\n",
- " stdout=subprocess.DEVNULL,\n",
- " stderr=subprocess.DEVNULL,\n",
+ " [sys.executable, \"-m\", \"tabctx.serve\", \"--port\", str(port)],\n",
+ " # Compiling the model only pays off on large tables; skip it for a fast start.\n",
+ " env={**os.environ, \"TABCTX_BACKEND\": \"tabicl\", \"TABCTX_COMPILE\": \"0\"},\n",
+ " stdout=log,\n",
+ " stderr=subprocess.STDOUT,\n",
+ " start_new_session=True, # interrupting a cell leaves the server running\n",
")\n",
+ "atexit.register(server.terminate)\n",
+ "\n",
"\n",
- "models = None\n",
- "for _ in range(180):\n",
+ "def log_tail(n=3000):\n",
+ " with open(\"tabctx-server.log\") as f:\n",
+ " return f.read()[-n:]\n",
+ "\n",
+ "\n",
+ "client = TabctxClient(f\"http://127.0.0.1:{port}\")\n",
+ "deadline = time.monotonic() + 15 * 60\n",
+ "while True:\n",
+ " if server.poll() is not None:\n",
+ " raise RuntimeError(f\"server exited ({server.returncode}):\\n{log_tail()}\")\n",
" try:\n",
- " with urllib.request.urlopen(\"http://127.0.0.1:8000/v1/models\", timeout=2) as resp:\n",
- " models = json.load(resp)\n",
+ " print(\"serving:\", client.tabular_models())\n",
" break\n",
- " except Exception:\n",
- " time.sleep(5)\n",
- "\n",
- "assert models is not None, \"server did not come up\"\n",
- "models"
+ " except OSError: # not listening yet\n",
+ " if time.monotonic() > deadline:\n",
+ " raise TimeoutError(f\"server not up after 15 min:\\n{log_tail()}\") from None\n",
+ " time.sleep(2)"
]
},
{
@@ -112,14 +120,7 @@
"cell_type": "code",
"execution_count": 3,
"id": "f2c406ce",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-11-11T22:33:44.728917Z",
- "iopub.status.busy": "2026-11-11T22:33:44.728571Z",
- "iopub.status.idle": "2026-11-11T22:34:44.680054Z",
- "shell.execute_reply": "2026-11-11T22:34:44.678987Z"
- }
- },
+ "metadata": {},
"outputs": [
{
"name": "stdout",
@@ -133,12 +134,11 @@
"from sklearn.datasets import fetch_openml\n",
"from sklearn.model_selection import train_test_split\n",
"\n",
- "from tabctx import TabctxClassifier, TabctxClient\n",
+ "from tabctx import TabctxClassifier\n",
"\n",
"X, y = fetch_openml(\"credit-g\", version=1, as_frame=True, return_X_y=True)\n",
"X_train, X_test, y_train, y_test = train_test_split(X, y, random_state=0)\n",
"\n",
- "client = TabctxClient(\"http://127.0.0.1:8000\")\n",
"clf = TabctxClassifier(client=client)\n",
"clf.fit(X_train, y_train)\n",
"print(\"context id:\", clf.dataset_id_)"
@@ -148,14 +148,7 @@
"cell_type": "code",
"execution_count": 4,
"id": "fde60009",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-11-11T22:34:44.699083Z",
- "iopub.status.busy": "2026-11-11T22:34:44.698816Z",
- "iopub.status.idle": "2026-11-11T22:34:52.212283Z",
- "shell.execute_reply": "2026-11-11T22:34:52.210403Z"
- }
- },
+ "metadata": {},
"outputs": [
{
"name": "stdout",
@@ -167,11 +160,11 @@
{
"data": {
"text/plain": [
- "array([[0.7023325 , 0.29766747],\n",
- " [0.05054151, 0.94945848],\n",
- " [0.04760469, 0.95239532],\n",
- " [0.26294938, 0.73705065],\n",
- " [0.39968097, 0.60031903]])"
+ "array([[0.7023347 , 0.2976653 ],\n",
+ " [0.05054444, 0.94945556],\n",
+ " [0.04760655, 0.95239347],\n",
+ " [0.26296899, 0.73703098],\n",
+ " [0.39968073, 0.60031927]])"
]
},
"execution_count": 4,
@@ -198,27 +191,20 @@
"cell_type": "code",
"execution_count": 5,
"id": "06969f36",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-11-11T22:34:52.215051Z",
- "iopub.status.busy": "2026-11-11T22:34:52.214816Z",
- "iopub.status.idle": "2026-11-11T22:35:02.351567Z",
- "shell.execute_reply": "2026-11-11T22:35:02.350755Z"
- }
- },
+ "metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
- "context id: sklearn-aea702693a87d2751cc473edb459f246\n"
+ "context id: sklearn-4dde377673132b8ee2eb271e49ab7f19\n"
]
},
{
"data": {
"text/plain": [
- "array([164.15979004, 143.35258484, 152.58087158, 130.20314026,\n",
- " 195.56369019])"
+ "array([255.16026306, 253.02041626, 154.43307495, 117.87319183,\n",
+ " 171.14213562])"
]
},
"execution_count": 5,
@@ -231,10 +217,8 @@
"\n",
"from tabctx import TabctxRegressor\n",
"\n",
- "data = load_diabetes(as_frame=True)\n",
- "Xr, yr = data.data, data.target\n",
- "Xr_train, Xr_test = Xr.iloc[:-100], Xr.iloc[-100:]\n",
- "yr_train, yr_test = yr.iloc[:-100], yr.iloc[-100:]\n",
+ "Xr, yr = load_diabetes(as_frame=True, return_X_y=True)\n",
+ "Xr_train, Xr_test, yr_train, yr_test = train_test_split(Xr, yr, random_state=0)\n",
"\n",
"reg = TabctxRegressor(client=client)\n",
"reg.fit(Xr_train, yr_train)\n",
@@ -246,15 +230,15 @@
"cell_type": "code",
"execution_count": 6,
"id": "a01752e5",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-11-11T22:35:02.353893Z",
- "iopub.status.busy": "2026-11-11T22:35:02.353630Z",
- "iopub.status.idle": "2026-11-11T22:35:02.958799Z",
- "shell.execute_reply": "2026-11-11T22:35:02.957944Z"
- }
- },
+ "metadata": {},
"outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "held-out rows inside the 90% interval: 92%\n"
+ ]
+ },
{
"data": {
"text/html": [
@@ -283,46 +267,46 @@
" \n",
" \n",
" \n",
- " | 0 | \n",
- " 69.302078 | \n",
- " 160.332001 | \n",
- " 269.507080 | \n",
+ " 362 | \n",
+ " 147.321915 | \n",
+ " 262.817993 | \n",
+ " 334.048401 | \n",
"
\n",
" \n",
- " | 1 | \n",
- " 55.275356 | \n",
- " 138.298859 | \n",
- " 248.152664 | \n",
+ " 249 | \n",
+ " 152.392807 | \n",
+ " 259.652557 | \n",
+ " 327.623749 | \n",
"
\n",
" \n",
- " | 2 | \n",
- " 62.262737 | \n",
- " 149.525345 | \n",
- " 253.321518 | \n",
+ " 271 | \n",
+ " 62.779804 | \n",
+ " 146.852875 | \n",
+ " 264.721466 | \n",
"
\n",
" \n",
- " | 3 | \n",
- " 52.836693 | \n",
- " 122.921402 | \n",
- " 230.515656 | \n",
+ " 435 | \n",
+ " 42.654739 | \n",
+ " 111.133316 | \n",
+ " 213.519043 | \n",
"
\n",
" \n",
- " | 4 | \n",
- " 94.553528 | \n",
- " 195.324875 | \n",
- " 295.893463 | \n",
+ " 400 | \n",
+ " 61.353336 | \n",
+ " 172.986618 | \n",
+ " 275.774841 | \n",
"
\n",
" \n",
"\n",
""
],
"text/plain": [
- " q5 q50 q95\n",
- "0 69.302078 160.332001 269.507080\n",
- "1 55.275356 138.298859 248.152664\n",
- "2 62.262737 149.525345 253.321518\n",
- "3 52.836693 122.921402 230.515656\n",
- "4 94.553528 195.324875 295.893463"
+ " q5 q50 q95\n",
+ "362 147.321915 262.817993 334.048401\n",
+ "249 152.392807 259.652557 327.623749\n",
+ "271 62.779804 146.852875 264.721466\n",
+ "435 42.654739 111.133316 213.519043\n",
+ "400 61.353336 172.986618 275.774841"
]
},
"execution_count": 6,
@@ -334,8 +318,15 @@
"import pandas as pd\n",
"\n",
"quantiles = (0.05, 0.5, 0.95)\n",
- "q = reg.predict_quantiles(Xr_test[:5], quantiles=quantiles)\n",
- "pd.DataFrame(q, columns=[f\"q{int(q_ * 100)}\" for q_ in quantiles])"
+ "q = reg.predict_quantiles(Xr_test, quantiles=quantiles)\n",
+ "intervals = pd.DataFrame(\n",
+ " q, columns=[f\"q{q_ * 100:g}\" for q_ in quantiles], index=Xr_test.index\n",
+ ")\n",
+ "\n",
+ "# Check the intervals on held-out data before relying on them.\n",
+ "inside = yr_test.between(intervals[\"q5\"], intervals[\"q95\"]).mean()\n",
+ "print(f\"held-out rows inside the 90% interval: {inside:.0%}\")\n",
+ "intervals.head()"
]
},
{
@@ -345,27 +336,20 @@
"source": [
"## 5. List and delete contexts\n",
"\n",
- "Contexts live on the server until they are evicted or deleted. `client.datasets()` lists them; `client.delete(...)` removes one."
+ "Contexts live on the server until they are evicted or deleted. `client.datasets()` lists them; `client.delete(...)` removes one. A fitted estimator keeps its training table, so if its context is gone, its next predict quietly fits it again; to remove your data from the server, delete the context and discard the estimator."
]
},
{
"cell_type": "code",
"execution_count": 7,
"id": "594bd733",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-11-11T22:35:02.961580Z",
- "iopub.status.busy": "2026-11-11T22:35:02.961337Z",
- "iopub.status.idle": "2026-11-11T22:35:03.012973Z",
- "shell.execute_reply": "2026-11-11T22:35:03.011921Z"
- }
- },
+ "metadata": {},
"outputs": [
{
"data": {
"text/plain": [
- "['sklearn-93906881b2b76a20dd1a638b8bf37862',\n",
- " 'sklearn-aea702693a87d2751cc473edb459f246']"
+ "['sklearn-4dde377673132b8ee2eb271e49ab7f19',\n",
+ " 'sklearn-93906881b2b76a20dd1a638b8bf37862']"
]
},
"execution_count": 7,
@@ -381,14 +365,7 @@
"cell_type": "code",
"execution_count": 8,
"id": "3d377819",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-11-11T22:35:03.015000Z",
- "iopub.status.busy": "2026-11-11T22:35:03.014784Z",
- "iopub.status.idle": "2026-11-11T22:35:03.112360Z",
- "shell.execute_reply": "2026-11-11T22:35:03.110732Z"
- }
- },
+ "metadata": {},
"outputs": [
{
"data": {
@@ -419,17 +396,12 @@
"cell_type": "code",
"execution_count": 9,
"id": "14664151",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-11-11T22:35:03.114866Z",
- "iopub.status.busy": "2026-11-11T22:35:03.114610Z",
- "iopub.status.idle": "2026-11-11T22:35:03.209491Z",
- "shell.execute_reply": "2026-11-11T22:35:03.200252Z"
- }
- },
+ "metadata": {},
"outputs": [],
"source": [
- "server.terminate()"
+ "server.terminate()\n",
+ "server.wait()\n",
+ "log.close()"
]
}
],
@@ -449,7 +421,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
- "version": "3.12.3"
+ "version": "3.12.8"
}
},
"nbformat": 4,
diff --git a/pyproject.toml b/pyproject.toml
index 36d7a3b..395dfca 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -63,7 +63,7 @@ serve = [
"uvicorn[standard]",
"jinja2",
"pyarrow>=14",
- "python-multipart>=0.0.9",
+ "python-multipart>=0.0.13",
# the agent demo's web app (examples/agent_demo/ui), in the unit tests
"fastapi",
]
@@ -74,7 +74,7 @@ standalone = [
"fastapi",
"uvicorn[standard]",
"pyarrow>=14",
- "python-multipart>=0.0.9",
+ "python-multipart>=0.0.13",
]
# The scikit-learn-style estimators (tabctx.estimators); pyarrow sends
# tables as Parquet (without it, gzip CSV). pandas: the estimators take
@@ -96,7 +96,7 @@ dev = [
"pre-commit",
"ruff",
"pyarrow>=14",
- "python-multipart>=0.0.9",
+ "python-multipart>=0.0.13",
# The standalone host's unit tests exercise the full HTTP service
# in-process (no server, no ray) via httpx's ASGI transport.
"fastapi",
@@ -116,7 +116,7 @@ docs = [
"mkdocstrings[python]>=0.29",
"fastapi",
"uvicorn",
- "python-multipart>=0.0.9",
+ "python-multipart>=0.0.13",
"pyarrow>=14",
]
diff --git a/uv.lock b/uv.lock
index 2222997..3b9eab7 100644
--- a/uv.lock
+++ b/uv.lock
@@ -3995,8 +3995,8 @@ requires-dist = [
{ name = "pyarrow", marker = "extra == 'standalone'", specifier = ">=14" },
{ name = "pytest", marker = "extra == 'dev'", specifier = ">=7.0" },
{ name = "pytest-cov", marker = "extra == 'dev'" },
- { name = "python-multipart", marker = "extra == 'serve'", specifier = ">=0.0.9" },
- { name = "python-multipart", marker = "extra == 'standalone'", specifier = ">=0.0.9" },
+ { name = "python-multipart", marker = "extra == 'serve'", specifier = ">=0.0.13" },
+ { name = "python-multipart", marker = "extra == 'standalone'", specifier = ">=0.0.13" },
{ name = "ray", extras = ["serve"], marker = "extra == 'serve'", specifier = ">=2.58.0" },
{ name = "scikit-learn", marker = "extra == 'client'", specifier = ">=1.6" },
{ name = "tabctx", extras = ["client"], marker = "extra == 'mcp'" },
@@ -4021,7 +4021,7 @@ dev = [
{ name = "pytest", specifier = ">=7.0" },
{ name = "pytest-cov" },
{ name = "pytest-xdist" },
- { name = "python-multipart", specifier = ">=0.0.9" },
+ { name = "python-multipart", specifier = ">=0.0.13" },
{ name = "ruff" },
]
docs = [
@@ -4029,7 +4029,7 @@ docs = [
{ name = "mkdocs-material", specifier = ">=9.6" },
{ name = "mkdocstrings", extras = ["python"], specifier = ">=0.29" },
{ name = "pyarrow", specifier = ">=14" },
- { name = "python-multipart", specifier = ">=0.0.9" },
+ { name = "python-multipart", specifier = ">=0.0.13" },
{ name = "uvicorn" },
]
survivalpfn = [