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): +[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](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 +[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](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", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + " \n", + "
q5q50q95
069.302078160.332001269.507080
155.275356138.298859248.152664
262.262737149.525345253.321518
352.836693122.921402230.515656
494.553528195.324875295.893463
\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. [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](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 = [