diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 5b5cd69..07f0a16 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -48,10 +48,17 @@ jobs:
path: ~/.cache/huggingface/hub/
key: ${{ Runner.os }}-huggingface-${{ hashFiles('**/tests/') }}
+ - name: Cache TabPFN checkpoints
+ uses: actions/cache@v4
+ with:
+ path: ~/.cache/tabpfn
+ key: ${{ runner.os }}-tabpfn-v1
+
- name: Run tests
run: uv run pytest
env:
HF_TOKEN: ${{ secrets.HF_TOKEN }}
+ TABPFN_TOKEN: ${{ secrets.TABPFN_TOKEN }}
- name: Test import class
run: uv run -- python -c "from timecopilot import TimeCopilot, TimeCopilotForecaster"
diff --git a/docs/changelogs/index.md b/docs/changelogs/index.md
index 364df27..41737a4 100644
--- a/docs/changelogs/index.md
+++ b/docs/changelogs/index.md
@@ -2,6 +2,7 @@
Welcome to the TimeCopilot Changelog. Here, you will find a comprehensive list of all the changes, updates, and improvements made to the TimeCopilot project. This section is designed to keep you informed about the latest features, bug fixes, and enhancements as we continue to develop and refine the TimeCopilot experience. Stay tuned for regular updates and feel free to explore the details of each release below.
+- [v0.0.33](v0.0.33.md)
- [v0.0.32](v0.0.32.md)
- [v0.0.31](v0.0.31.md)
- [v0.0.30](v0.0.30.md)
diff --git a/docs/changelogs/v0.0.33.md b/docs/changelogs/v0.0.33.md
new file mode 100644
index 0000000..8c49573
--- /dev/null
+++ b/docs/changelogs/v0.0.33.md
@@ -0,0 +1,38 @@
+### Features
+
+* **TabPFN-3 foundation model**: Added support for TabPFN-3 via `foundationforecast>=0.1.6`. Use the existing `TabPFN` class with `model_path`; TabPFN-2 remains the default.
+
+ ```python
+ import pandas as pd
+ from tabpfn_time_series import TabPFNMode
+ from timecopilot.models.foundation.tabpfn import TABPFN_V2_MODEL, TABPFN_V3_MODEL, TabPFN
+
+ df = pd.read_csv(
+ "https://timecopilot.s3.amazonaws.com/public/data/air_passengers.csv",
+ parse_dates=["ds"],
+ )
+
+ model = TabPFN(
+ model_path=TABPFN_V3_MODEL,
+ mode=TabPFNMode.LOCAL,
+ context_length=32768,
+ alias="TabPFN-3",
+ )
+ assert model.model_path == TABPFN_V3_MODEL
+ ```
+
+ **License note:** TabPFN-2.6+ and TabPFN-3 weights use the TabPFN Non-Commercial license. First LOCAL use requires accepting terms at [ux.priorlabs.ai](https://ux.priorlabs.ai) (`TABPFN_TOKEN`). TabPFN-3 is LOCAL-only today.
+
+* **TabPFN family notebook**: Added [`tabpfn-family` example notebook](../examples/tabpfn-family.ipynb) comparing TabPFN-2 and TabPFN-3 with prediction intervals.
+
+### Dependencies
+
+* Bumped `foundationforecast` from `>=0.1.3` to `>=0.1.6` (TabPFN-3 via `model_path`, `tabpfn-time-series>=1.2.0`).
+
+### CI
+
+* Added `TABPFN_TOKEN` secret and TabPFN checkpoint cache for LOCAL integration tests.
+
+---
+
+**Full Changelog**: https://github.com/TimeCopilot/timecopilot/compare/v0.0.32...v0.0.33
diff --git a/docs/examples/index.md b/docs/examples/index.md
index b29b340..75ff7bb 100644
--- a/docs/examples/index.md
+++ b/docs/examples/index.md
@@ -29,6 +29,7 @@ For model API details, see the [Model Hub](../model-hub.md).
| [Compare Foundation Models](ts-foundation-models-comparison-quickstart.ipynb) | Benchmark multiple foundation models side by side | Python 3.10+; GPU optional |
| [Chronos Family](chronos-family.ipynb) | Forecast with Chronos 1.x and 2.x checkpoints | Python 3.10+ |
| [TimesFM Family](timesfm-family.ipynb) | Forecast with TimesFM 1.0, 2.0, 2.5, and 3.0 with prediction intervals | Python 3.10+ |
+| [TabPFN Family](tabpfn-family.ipynb) | Forecast with TabPFN-2 and TabPFN-3 with prediction intervals | Python 3.10–3.12; `TABPFN_TOKEN` for LOCAL |
| [TiRex Family](tirex-family.ipynb) | Forecast with TiRex 1.0 and 2.0 | Python 3.11+ |
| [Toto Family](toto-family.ipynb) | Forecast with Toto 1.0 and 2.0 | Python 3.10+ |
| [Finetuning](finetuning.ipynb) | Adapt Chronos 2 and TimeGPT to your data | Python 3.10+; GPU recommended |
diff --git a/docs/examples/tabpfn-family.ipynb b/docs/examples/tabpfn-family.ipynb
new file mode 100644
index 0000000..bda32bd
--- /dev/null
+++ b/docs/examples/tabpfn-family.ipynb
@@ -0,0 +1,858 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "29edac33",
+ "metadata": {},
+ "source": [
+ "# Forecast Using the TabPFN Family\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "b2fa5716",
+ "metadata": {},
+ "source": [
+ "TimeCopilot ships a single `TabPFN` class that supports TabPFN-2 (default) and TabPFN-3 checkpoints. Pass `model_path` to select the checkpoint:\n",
+ "\n",
+ "| Version | `model_path` | Notes |\n",
+ "|---------|-------------|-------|\n",
+ "| **TabPFN-2** (default) | `tabpfn-v2-regressor-2noar4o2.ckpt` | TabPFN NC license |\n",
+ "| **TabPFN-3** | `tabpfn-v3-regressor-v3_20260506_timeseries.ckpt` | Finetuned TS checkpoint; TabPFN NC license; LOCAL only |\n",
+ "\n",
+ "*Requirements*:\n",
+ "\n",
+ " - Python 3.10 \u2013 3.12\n",
+ " - LOCAL mode (default when CUDA is available): accept terms at [ux.priorlabs.ai](https://ux.priorlabs.ai) and set `TABPFN_TOKEN`\n",
+ " - TabPFN-3 recommends `context_length=32768`; TabPFN-2 defaults to 4096\n",
+ "\n",
+ "**License:** TabPFN-2.6+ and TabPFN-3 weights use the TabPFN Non-Commercial license. Commercial production requires a [Prior Labs license or API](https://docs.priorlabs.ai/models).\n",
+ "\n",
+ "In this example we compare TabPFN-2 and TabPFN-3 on event pageview data.\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "8b280b18",
+ "metadata": {},
+ "source": [
+ "## Import libraries\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "c371b7eb",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-09-14T18:44:11.802516Z",
+ "iopub.status.busy": "2026-09-14T18:44:11.802413Z",
+ "iopub.status.idle": "2026-09-14T18:44:17.912816Z",
+ "shell.execute_reply": "2026-09-14T18:44:17.912497Z"
+ }
+ },
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "/Users/azul/projects/foundationforecast/.venv/lib/python3.11/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n",
+ " from .autonotebook import tqdm as notebook_tqdm\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "INFO:datasets:JAX version 0.7.1 available.\n"
+ ]
+ }
+ ],
+ "source": [
+ "import sys\n",
+ "from pathlib import Path\n",
+ "\n",
+ "import pandas as pd\n",
+ "from dotenv import load_dotenv\n",
+ "\n",
+ "from timecopilot import TimeCopilotForecaster\n",
+ "\n",
+ "load_dotenv(Path(\".env\"))\n",
+ "\n",
+ "if sys.version_info >= (3, 13):\n",
+ " raise RuntimeError(\"TabPFN requires Python < 3.13\")\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "4724fbc4",
+ "metadata": {},
+ "source": [
+ "## Load the dataset\n",
+ "\n",
+ "The DataFrame must include at least the following columns:\n",
+ "- unique_id: Unique identifier for each time series (string)\n",
+ "- ds: Date column (datetime format)\n",
+ "- y: Target variable for forecasting (float format)\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "801b50be",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-09-14T18:44:17.915071Z",
+ "iopub.status.busy": "2026-09-14T18:44:17.914890Z",
+ "iopub.status.idle": "2026-09-14T18:44:18.490177Z",
+ "shell.execute_reply": "2026-09-14T18:44:18.489535Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " unique_id | \n",
+ " ds | \n",
+ " y | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " Oktoberfest | \n",
+ " 2020-01-31 | \n",
+ " 25376 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " Oktoberfest | \n",
+ " 2020-02-29 | \n",
+ " 28470 | \n",
+ "
\n",
+ " \n",
+ " | 2 | \n",
+ " Oktoberfest | \n",
+ " 2020-03-31 | \n",
+ " 23816 | \n",
+ "
\n",
+ " \n",
+ " | 3 | \n",
+ " Oktoberfest | \n",
+ " 2020-04-30 | \n",
+ " 46186 | \n",
+ "
\n",
+ " \n",
+ " | 4 | \n",
+ " Oktoberfest | \n",
+ " 2020-05-31 | \n",
+ " 31213 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
"
+ ]
+ },
+ "execution_count": 3,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "TimeCopilotForecaster.plot(df)\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "7a50356d",
+ "metadata": {},
+ "source": [
+ "## Import the models\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "8237cd39",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-09-14T18:44:18.903953Z",
+ "iopub.status.busy": "2026-09-14T18:44:18.903882Z",
+ "iopub.status.idle": "2026-09-14T18:44:18.905435Z",
+ "shell.execute_reply": "2026-09-14T18:44:18.905119Z"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "from tabpfn_time_series import TabPFNMode\n",
+ "\n",
+ "from timecopilot.models.foundation.tabpfn import TABPFN_V2_MODEL, TABPFN_V3_MODEL, TabPFN\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "b53fbb9f",
+ "metadata": {},
+ "source": [
+ "## Create a TimeCopilotForecaster\n",
+ "\n",
+ "We compare TabPFN-2 with TabPFN-3 in LOCAL mode. Each model gets a distinct `alias`.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "a6ecf9c0",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-09-14T18:44:18.906341Z",
+ "iopub.status.busy": "2026-09-14T18:44:18.906286Z",
+ "iopub.status.idle": "2026-09-14T18:44:18.908015Z",
+ "shell.execute_reply": "2026-09-14T18:44:18.907751Z"
+ }
+ },
+ "outputs": [],
+ "source": [
+ "models = [\n",
+ " TabPFN(\n",
+ " model_path=TABPFN_V2_MODEL,\n",
+ " mode=TabPFNMode.LOCAL,\n",
+ " alias=\"TabPFN-2\",\n",
+ " ),\n",
+ " TabPFN(\n",
+ " model_path=TABPFN_V3_MODEL,\n",
+ " mode=TabPFNMode.LOCAL,\n",
+ " context_length=32768,\n",
+ " alias=\"TabPFN-3\",\n",
+ " ),\n",
+ "]\n",
+ "\n",
+ "tcf = TimeCopilotForecaster(models=models)\n"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "8a98344a",
+ "metadata": {},
+ "source": [
+ "## Generate forecast\n",
+ "\n",
+ "TabPFN outputs nine fixed quantiles (0.1 through 0.9). Pass `level=[0, 20, 40, 60, 80]` to request all supported prediction intervals.\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 6,
+ "id": "49a609e6",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-09-14T18:44:18.908916Z",
+ "iopub.status.busy": "2026-09-14T18:44:18.908866Z",
+ "iopub.status.idle": "2026-09-14T18:44:53.068317Z",
+ "shell.execute_reply": "2026-09-14T18:44:53.049636Z"
+ }
+ },
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "\r",
+ "0it [00:00, ?it/s]"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "\n"
+ ]
+ },
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "\r",
+ "Predicting time series: 0%| | 0/6 [00:00"
+ ]
+ },
+ "execution_count": 7,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "tcf.plot(df, cv_df.drop(columns=[\"cutoff\", \"y\"]), level=[80])\n"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 8,
+ "id": "03db9715",
+ "metadata": {
+ "execution": {
+ "iopub.execute_input": "2026-09-14T18:44:54.872569Z",
+ "iopub.status.busy": "2026-09-14T18:44:54.872487Z",
+ "iopub.status.idle": "2026-09-14T18:44:54.985277Z",
+ "shell.execute_reply": "2026-09-14T18:44:54.984860Z"
+ }
+ },
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ "\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | \n",
+ " unique_id | \n",
+ " ds | \n",
+ " cutoff | \n",
+ " y | \n",
+ " TabPFN-2 | \n",
+ " TabPFN-2-lo-0 | \n",
+ " TabPFN-2-hi-0 | \n",
+ " TabPFN-2-lo-20 | \n",
+ " TabPFN-2-hi-20 | \n",
+ " TabPFN-2-lo-40 | \n",
+ " ... | \n",
+ " TabPFN-3-lo-0 | \n",
+ " TabPFN-3-hi-0 | \n",
+ " TabPFN-3-lo-20 | \n",
+ " TabPFN-3-hi-20 | \n",
+ " TabPFN-3-lo-40 | \n",
+ " TabPFN-3-hi-40 | \n",
+ " TabPFN-3-lo-60 | \n",
+ " TabPFN-3-hi-60 | \n",
+ " TabPFN-3-lo-80 | \n",
+ " TabPFN-3-hi-80 | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | 0 | \n",
+ " Black Friday | \n",
+ " 2024-09-30 | \n",
+ " 2024-09-01 | \n",
+ " 2607 | \n",
+ " 2283.965088 | \n",
+ " 2283.965088 | \n",
+ " 2283.965088 | \n",
+ " 2177.424561 | \n",
+ " 2420.626465 | \n",
+ " 2081.235596 | \n",
+ " ... | \n",
+ " 2306.467773 | \n",
+ " 2306.467773 | \n",
+ " 2169.607178 | \n",
+ " 2497.994629 | \n",
+ " 2056.207275 | \n",
+ " 2797.267334 | \n",
+ " 1941.594482 | \n",
+ " 3244.148438 | \n",
+ " 1798.154785 | \n",
+ " 4146.946777 | \n",
+ "
\n",
+ " \n",
+ " | 1 | \n",
+ " Black Friday | \n",
+ " 2024-10-31 | \n",
+ " 2024-09-01 | \n",
+ " 2470 | \n",
+ " 3523.283203 | \n",
+ " 3523.283203 | \n",
+ " 3523.283203 | \n",
+ " 3156.973877 | \n",
+ " 3964.171875 | \n",
+ " 2814.589111 | \n",
+ " ... | \n",
+ " 3155.802979 | \n",
+ " 3155.802979 | \n",
+ " 2800.380371 | \n",
+ " 3559.806152 | \n",
+ " 2491.012451 | \n",
+ " 4029.166504 | \n",
+ " 2239.562500 | \n",
+ " 4868.718750 | \n",
+ " 1980.670654 | \n",
+ " 6789.798340 | \n",
+ "
\n",
+ " \n",
+ " | 2 | \n",
+ " Black Friday | \n",
+ " 2024-11-30 | \n",
+ " 2024-09-01 | \n",
+ " 11058 | \n",
+ " 12908.764648 | \n",
+ " 12908.764648 | \n",
+ " 12908.764648 | \n",
+ " 9775.419922 | \n",
+ " 16364.140625 | \n",
+ " 7223.555664 | \n",
+ " ... | \n",
+ " 6755.500000 | \n",
+ " 6755.500000 | \n",
+ " 5224.051270 | \n",
+ " 9573.415039 | \n",
+ " 4197.266113 | \n",
+ " 15283.360352 | \n",
+ " 3451.474609 | \n",
+ " 19639.794922 | \n",
+ " 2746.735352 | \n",
+ " 24622.894531 | \n",
+ "
\n",
+ " \n",
+ " | 3 | \n",
+ " Black Friday | \n",
+ " 2024-12-31 | \n",
+ " 2024-09-01 | \n",
+ " 3548 | \n",
+ " 3868.746582 | \n",
+ " 3868.746582 | \n",
+ " 3868.746582 | \n",
+ " 3513.119385 | \n",
+ " 4233.543945 | \n",
+ " 3093.505371 | \n",
+ " ... | \n",
+ " 3064.281494 | \n",
+ " 3064.281494 | \n",
+ " 2702.104736 | \n",
+ " 3447.574219 | \n",
+ " 2388.743896 | \n",
+ " 3879.081543 | \n",
+ " 2119.647461 | \n",
+ " 4505.389160 | \n",
+ " 1864.812134 | \n",
+ " 5696.427734 | \n",
+ "
\n",
+ " \n",
+ " | 4 | \n",
+ " Black Friday | \n",
+ " 2025-01-31 | \n",
+ " 2024-09-01 | \n",
+ " 1724 | \n",
+ " 2284.322510 | \n",
+ " 2284.322510 | \n",
+ " 2284.322510 | \n",
+ " 2164.592773 | \n",
+ " 2436.935303 | \n",
+ " 2059.958984 | \n",
+ " ... | \n",
+ " 2201.597168 | \n",
+ " 2201.597168 | \n",
+ " 2054.866211 | \n",
+ " 2375.402832 | \n",
+ " 1918.067749 | \n",
+ " 2579.746582 | \n",
+ " 1779.724976 | \n",
+ " 2839.138428 | \n",
+ " 1587.375732 | \n",
+ " 3371.126953 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "
5 rows \u00d7 26 columns
\n",
+ "
\n",
+ "\n",
+ "
\n",
+ " \n",
+ " \n",
+ " | metric | \n",
+ " mase | \n",
+ " scaled_crps | \n",
+ "
\n",
+ " \n",
+ " \n",
+ " \n",
+ " | TabPFN-3 | \n",
+ " 0.789 | \n",
+ " 0.254 | \n",
+ "
\n",
+ " \n",
+ " | TabPFN-2 | \n",
+ " 1.020 | \n",
+ " 0.279 | \n",
+ "
\n",
+ " \n",
+ "
\n",
+ "