feat(tabpfn): add TabPFN-3 support with TabPFN-2 default

.github/workflows/ci.yaml

@@ -53,10 +53,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-${{ matrix.python-version }}
+
       - name: Run tests
         run: uv run pytest ${{ matrix.coverage && '--cov=foundationforecast --cov-report=term-missing' || '' }}
         env:
           HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          TABPFN_TOKEN: ${{ secrets.TABPFN_TOKEN }}
 
       - name: Test import FoundationForecast and Chronos
         run: uv run -- python -c "from foundationforecast import FoundationForecast; from foundationforecast.models import Chronos"

README.md

@@ -86,7 +86,7 @@ Licenses verified against Hugging Face model cards. Check the model card for you
 - **Apache-2.0**, **MIT**: generally fine for commercial production (retain notices; T0† is also gated on Hugging Face: accept terms and set `HF_TOKEN`).
 - **CC-BY-NC-4.0** (Moirai), **CC-BY-NC-SA-4.0** (PatchTST-FM): **non-commercial** only; not for revenue-generating production without a separate agreement from the rights holder.
 - **TimesFM 3.0**: weights for `google/timesfm-3.0-pytorch` are [non-commercial](https://huggingface.co/google/timesfm-3.0-pytorch/blob/main/LICENSE); TimesFM 1.0–2.5 checkpoints remain Apache-2.0.
-- **TabPFN NC**‡: TabPFN-2.6+ weights are non-commercial; production requires a [Prior Labs commercial license or API](https://docs.priorlabs.ai/models). First use also requires accepting terms at [ux.priorlabs.ai](https://ux.priorlabs.ai) (`TABPFN_TOKEN`).
+- **TabPFN NC**‡: TabPFN-2.6+ and TabPFN-3 weights are non-commercial; production requires a [Prior Labs commercial license or API](https://docs.priorlabs.ai/models). First LOCAL use requires accepting terms at [ux.priorlabs.ai](https://ux.priorlabs.ai) (`TABPFN_TOKEN`). TabPFN-3 is LOCAL-only today.
 - **Community / Apache-2.0** (TiRex): TiRex 1.0 uses the [NXAI Community License](https://huggingface.co/NX-AI/TiRex/blob/main/LICENSE) (commercial limits for large enterprises); TiRex 2.0 is Apache-2.0.
 - **Nixtla API**§: hosted service via `NIXTLA_API_KEY`; production under [Nixtla terms/pricing](https://www.nixtla.io/docs), not open weights.
 
@@ -104,7 +104,7 @@ Some models require specific Python versions (e.g. FlowState 3.11-3.13, TabPFN &
 - **PatchTST-FM:** `ibm-research/patchtst-fm-r1`
 - **Sundial:** `thuml/sundial-base-128m`
 - **T0:** `theforecastingcompany/t0-alpha`
-- **TabPFN:** `tabpfn-local`, `tabpfn-client`
+- **TabPFN:** default `tabpfn-v2-regressor-2noar4o2.ckpt`; TabPFN-3 via `model_path="tabpfn-v3-regressor-v3_20260506_timeseries.ckpt"` (LOCAL, `TABPFN_TOKEN`); or CLIENT mode with a Prior Labs API token
 - **Tafsut:** `Tafsut-FM/tafsut-univariate-base`
 - **TiRex:** `NX-AI/TiRex`, `NX-AI/TiRex-2`
 - **TimeGPT:** pass `model=` to `TimeGPT()`, e.g. `timegpt-1`, [`timegpt-1-long-horizon`](https://www.nixtla.io/docs/forecasting/model-version/longhorizon_model), `timegpt-2-mini`, `timegpt-2`, `timegpt-2-pro`

docs/changelogs/index.md

@@ -2,6 +2,7 @@
 
 Welcome to the FoundationForecast Changelog. Here you will find a list of changes, updates, and improvements for each release. Explore the details of each version below.
 
+- [v0.1.6](v0.1.6.md)
 - [v0.1.5](v0.1.5.md)
 - [v0.1.4](v0.1.4.md)
 - [v0.1.3](v0.1.3.md)

docs/changelogs/v0.1.6.md

@@ -0,0 +1,36 @@
+### Features
+
+* **TabPFN-3 support**: The `TabPFN` class now supports TabPFN-2 (default) and TabPFN-3 checkpoints via `model_path`. TabPFN-2 remains the default (`tabpfn-v2-regressor-2noar4o2.ckpt`); pass `tabpfn-v3-regressor-v3_20260506_timeseries.ckpt` for TabPFN-3 (LOCAL only, `TABPFN_TOKEN` required). See [#25](https://github.com/TimeCopilot/foundationforecast/pull/25).
+
+    ```python
+    import pandas as pd
+    from tabpfn_time_series import TabPFNMode
+    from foundationforecast.models.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
+    ```
+
+* **TabPFN family notebook**: Added [`tabpfn-family` example notebook](../examples/tabpfn-family.ipynb) comparing TabPFN-2 and TabPFN-3 with prediction intervals.
+
+### Dependencies
+
+* Bumped `tabpfn-time-series` from `>=1.1.0` to `>=1.2.0` (TabPFN-3 checkpoint API via `model_path`).
+
+### CI
+
+* Added `TABPFN_TOKEN` secret and TabPFN checkpoint cache for LOCAL integration tests.
+
+---
+
+**Full Changelog**: https://github.com/TimeCopilot/foundationforecast/compare/v0.1.5...v0.1.6

docs/examples/index.md

@@ -19,5 +19,6 @@ For model API details, see the [Model Hub](../model-hub.md).
 | [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+ |
 | [TiRex Family](tirex-family.ipynb) | Forecast with TiRex 1.0 and 2.0 | Python 3.11+ |
+| [TabPFN Family](tabpfn-family.ipynb) | Forecast with TabPFN-2 and TabPFN-3 (LOCAL) | Python 3.10–3.12; `TABPFN_TOKEN` |
 | [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 |

docs/model-hub.md

@@ -42,7 +42,7 @@ Below is the list of available foundation models. Click a model name for API det
 - [PatchTST-FM](api/models/foundation/models.md#foundationforecast.models.patchtst_fm.PatchTSTFM) ([arXiv:2602.06909](https://arxiv.org/abs/2602.06909)) — Python 3.11–3.13
 - [Sundial](api/models/foundation/models.md#foundationforecast.models.sundial.Sundial) ([arXiv:2502.00816](https://arxiv.org/pdf/2502.00816))
 - [T0](api/models/foundation/models.md#foundationforecast.models.t0.T0) ([model card](https://huggingface.co/theforecastingcompany/t0-alpha)) — Python 3.11–3.13
-- [TabPFN](api/models/foundation/models.md#foundationforecast.models.tabpfn.TabPFN) ([arXiv:2501.02945](https://arxiv.org/abs/2501.02945)) — Python 3.10–3.12
+- [TabPFN](api/models/foundation/models.md#foundationforecast.models.tabpfn.TabPFN) ([arXiv:2501.02945](https://arxiv.org/abs/2501.02945)) — Python 3.10–3.12; TabPFN-2 (default) and TabPFN-3 via `model_path`; TabPFN-3 is LOCAL-only; weights use the [TabPFN NC license](https://ux.priorlabs.ai) (`TABPFN_TOKEN`)
 - [Tafsut](api/models/foundation/models.md#foundationforecast.models.tafsut.Tafsut) ([GitHub](https://github.com/Tafsut-FM/tafsut))
 - [TiRex / TiRex-2](api/models/foundation/models.md#foundationforecast.models.tirex.TiRex) ([arXiv:2505.23719](https://arxiv.org/abs/2505.23719), [arXiv:2607.01204](https://arxiv.org/abs/2607.01204)) — Python 3.11+
 - [TimeGPT](api/models/foundation/models.md#foundationforecast.models.timegpt.TimeGPT) ([arXiv:2310.03589](https://arxiv.org/abs/2310.03589)) — requires `NIXTLA_API_KEY`