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 28ab281..68dc9a4 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,12 @@ 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) + +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 ea8b872..e66666b 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -1,8 +1,13 @@ # 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 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 new file mode 100644 index 0000000..5f367ed --- /dev/null +++ b/examples/quickstart.ipynb @@ -0,0 +1,429 @@ +{ + "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 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." + ] + }, + { + "cell_type": "markdown", + "id": "4eb6943b", + "metadata": {}, + "source": [ + "## 1. Install" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "ac7b3069", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Note: you may need to restart the kernel to use updated packages.\n" + ] + } + ], + "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 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": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "serving: ['tabicl-v2']\n" + ] + } + ], + "source": [ + "import atexit\n", + "import os\n", + "import socket\n", + "import subprocess\n", + "import sys\n", + "import time\n", + "\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\", \"--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", + "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", + " print(\"serving:\", client.tabular_models())\n", + " break\n", + " 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)" + ] + }, + { + "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": {}, + "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\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", + "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": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "accuracy: 0.772\n" + ] + }, + { + "data": { + "text/plain": [ + "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, + "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": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "context id: sklearn-4dde377673132b8ee2eb271e49ab7f19\n" + ] + }, + { + "data": { + "text/plain": [ + "array([255.16026306, 253.02041626, 154.43307495, 117.87319183,\n", + " 171.14213562])" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "from sklearn.datasets import load_diabetes\n", + "\n", + "from tabctx import TabctxRegressor\n", + "\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", + "print(\"context id:\", reg.dataset_id_)\n", + "reg.predict(Xr_test[:5])" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "a01752e5", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "held-out rows inside the 90% interval: 92%\n" + ] + }, + { + "data": { + "text/html": [ + "
| \n", + " | q5 | \n", + "q50 | \n", + "q95 | \n", + "
|---|---|---|---|
| 362 | \n", + "147.321915 | \n", + "262.817993 | \n", + "334.048401 | \n", + "
| 249 | \n", + "152.392807 | \n", + "259.652557 | \n", + "327.623749 | \n", + "
| 271 | \n", + "62.779804 | \n", + "146.852875 | \n", + "264.721466 | \n", + "
| 435 | \n", + "42.654739 | \n", + "111.133316 | \n", + "213.519043 | \n", + "
| 400 | \n", + "61.353336 | \n", + "172.986618 | \n", + "275.774841 | \n", + "