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): +[![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) + +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 +[![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 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", + "\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
362147.321915262.817993334.048401
249152.392807259.652557327.623749
27162.779804146.852875264.721466
43542.654739111.133316213.519043
40061.353336172.986618275.774841
\n", + "
" + ], + "text/plain": [ + " 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, + "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, 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()" + ] + }, + { + "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. 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": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "['sklearn-4dde377673132b8ee2eb271e49ab7f19',\n", + " 'sklearn-93906881b2b76a20dd1a638b8bf37862']" + ] + }, + "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": {}, + "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": {}, + "outputs": [], + "source": [ + "server.terminate()\n", + "server.wait()\n", + "log.close()" + ] + } + ], + "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.8" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} 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 = [