PriorLabs/tabpfn-time-series

📦 What is TabPFN‑TS?

TabPFN‑TS is a Python library that lets you do zero‑shot time‑series forecasting by re‑using the TabPFN foundation model – a large neural net trained on synthetic tabular data. The library turns a univariate series into a table, adds a few engineered calendar‑style features, and then runs TabPFN as a regression model. Because the model is already pretrained, you get point and probabilistic forecasts without any training.

---

🛠️ Core components

Component	Role
TabPFNTSPipeline	High‑level class that handles the whole workflow – data conversion, feature creation, calling TabPFN (locally or via the cloud client), and returning forecasts.
Feature engineering	A default set (TABPFN_TS_DEFAULT_FEATURES) that automatically creates calendar, sine/cosine, and other temporal features.
TabPFN model	The underlying tabular foundation model. By default the package pulls TabPFN‑3.5 (or the finetuned TabPFN‑TS‑3 checkpoint) from Hugging Face.
tabpfn-client	Optional cloud inference backend; lets you run predictions without a GPU.

---

🚀 How to use it (quick example)

from tabpfn_time_series import TabPFNTSPipeline

# `context_df` contains the historic target column (and any known‑future covariates)
pipeline = TabPFNTSPipeline()          # defaults to cloud client, no GPU needed
forecast = pipeline.predict_df(context_df, prediction_length=24)

• predict_df expects a pandas DataFrame with a time index and a target column. If you have known‑future covariates (e.g., holidays), pass them in the future_df argument.
• The returned object contains point forecasts and, if requested, probabilistic quantiles.

For a step‑by‑step walk‑through, see the notebooks linked in the README:

• quickstart.ipynb – get a forecast on a toy dataset.
• how-it-works.ipynb – dives into the table conversion and feature pipeline.

---

🎯 When does it shine?

Strength	Why it matters
Zero‑shot – no training data or fine‑tuning required	Ideal for rapid prototyping or when you have only a short historical window.
Fast inference – either local (CPU) or cloud client	Works even on modest hardware; the cloud client removes the need for a GPU.
Probabilistic output	Gives prediction intervals, useful for risk‑aware decisions.
Known‑future covariates	You can feed in calendar effects, holiday flags, or external forecasts that are available at prediction time.

---

⚠️ Limitations

Limitation	Detail
Univariate focus	Multivariate targets are split into independent forecasts; cross‑series interactions are ignored.
No past dynamic covariates	Features that require past observations (e.g., past weather) are dropped.
Static covariates ignored	Item‑level attributes like store_id are not used.
Depends on TabPFN checkpoint	Forecast quality is bounded by how well the tabular model generalises to the transformed series.

If your problem relies heavily on past dynamic or static information, a dedicated multivariate time‑series model may perform better.

---

📦 Installation & requirements

pip install tabpfn-time-series

• Requires tabpfn>=9.0.0 and tabpfn-client>=0.5.3 for the default cloud mode.
• In local mode the first run will download the TabPFN‑3.5 checkpoint after you accept the license at ux.priorlabs.ai.

---

📚 Further reading & citation

• Paper – Zero‑Shot Time Series Forecasting with TabPFN (arXiv:2501.02945).
• TabPFN‑3 report – details the finetuned checkpoint used for SOTA results on the GIFT‑EVAL benchmark.
• Cite both when using the library in academic work.

---

🔍 Telemetry & privacy

The library sends only anonymous usage stats (package version, Python version, call counts, input dimensions). No data, code, or model outputs are transmitted. Set TABPFN_DISABLE_TELEMETRY=1 to opt‑out.

---

TL;DR – TabPFN‑TS is a lightweight, zero‑training library that repurposes the TabPFN tabular foundation model for fast, point‑and‑probabilistic univariate time‑series forecasts, with optional cloud inference for GPU‑free use.