skforecast/skforecast-ai/foundation-forecasting

Foundation Model Forecasting (Zero-Shot)

When to Use

Use ForecasterFoundation when:

• You want accurate forecasts without training a model. The best pre-trained models are among the top performers in public benchmarks (GIFT-Eval, fev-bench).
• You have very short histories where ML models struggle.
• You need to forecast cold-start series (new product, new sensor).
• You have many heterogeneous series (different lengths, exogenous variables or missing values).

Trade-offs: prediction needs more computing resources (usually a GPU), and a forecaster trained on the user's data with well-designed features and exogenous variables can still be more accurate for a specific problem. Compare them with backtesting on the same folds.

Foundation models are pre-trained on massive corpora — fit() does not train them; it only stores the recent context and metadata.

Related skills

• Prerequisite: choosing-a-forecaster (decide whether a zero-shot model fits the problem at all)
• Alongside: baseline-forecasting (compare the zero-shot model against a naive rule with MASE)
• Next: hyperparameter-optimization (tune context_length with bayesian_search_foundation)
• Next: metric-selection (probabilistic metrics for the native quantile output)

Stop Conditions

Scan before writing code. Each row lists a rule, the symptom when it is broken, and the recovery. Full pitfall catalog: the troubleshooting-common-errors skill.

Installation

Foundation model backends are not bundled with skforecast. Install only the backend(s) you need:

pip install chronos-forecasting    # For Chronos-2
pip install "timesfm[torch]"       # For TimesFM 2.5 and 3.0
pip install uni2ts                 # For Moirai-2
pip install tabicl[forecast]       # For TabICL
pip install "tabpfn-time-series>=1.3"  # For TabPFN-TS
pip install tfc-t0                 # For T0
pip install tsicl                  # For TS-ICL
pip install synthefy-nori          # For Nori

Models are downloaded from HuggingFace on first use.

Quick Start (single series)

import pandas as pd
from skforecast.foundation import FoundationModel, ForecasterFoundation
# Data must have a DatetimeIndex with a frequency
data = pd.read_csv('data.csv', index_col='date', parse_dates=True).asfreq('h')
# 1. Configure a foundation model (adapter is resolved from model_id)
model = FoundationModel(
    model_id='autogluon/chronos-2-small',
    context_length=2048,      # Adapter-specific default: see reference
    device_map='auto',        # 'auto' picks CUDA > MPS > CPU
)
# 2. Wrap it in ForecasterFoundation for the skforecast API
forecaster = ForecasterFoundation(estimator=model)
# 3. "Fit" only stores the last context_length observations (no training)
forecaster.fit(series=data['target'])
# 4. Point forecast — returns long-format DataFrame: columns ['level', 'pred']
predictions = forecaster.predict(steps=24)

Multi-Series (Global Zero-Shot Model)

Pass a wide DataFrame, a long-format DataFrame (MultiIndex), or a dict[str, pd.Series] to fit.

The series do not need to be aligned: they can have different lengths and time spans, a different subset of exog columns each, and NaN values. Each series is forecast from its own context and horizon, so no padding or imputation is required before fit. See the user guide Foundation models with heterogeneous series for the per-backend rules.

# series: wide DataFrame — each column is one series
forecaster.fit(series=series)
# Forecast all series
predictions = forecaster.predict(steps=24)
# Forecast a subset
predictions = forecaster.predict(steps=24, levels=['series_1', 'series_2'])

Chronos-2 supports cross_learning=True to share information across series in the batch (ignored in single-series mode):

model = FoundationModel(
    model_id='autogluon/chronos-2-small',
    cross_learning=True,
)

With Exogenous Variables (Chronos-2, TimesFM 3.0, TabICL, TabPFN-TS, TFC-T0, Nori, and TS-ICL)

Chronos-2, TimesFM 3.0, TabICL, TabPFN-TS, TFC-T0, Nori, and TS-ICL (allow_exog=True) accept exogenous variables. TimesFM 2.5 and Moirai-2 ignore them. At predict time the future exog columns are validated per series against the historical exog: a future column with no history raises ValueError; a historical column with no future values is a past-only covariate, used by Chronos-2, TS-ICL and TimesFM 3.0 (supports_past_only_covariates=True) and ignored with an IgnoredArgumentWarning by TabICL, TabPFN-TS, TFC-T0 and Nori. Series in a multi-series input may differ in length and in their exog columns: each series is forecast with its own columns, and adapters whose backend needs identical columns per batch (supports_heterogeneous_covariates=False: Chronos-2, TS-ICL, TabICL, TimesFM 3.0) are called once per group of series sharing the same columns, so the forecast of a series never depends on the exog of the others.

# Historical + future exog (must cover the forecast horizon)
forecaster.fit(series=data['target'], exog=exog_train)
predictions = forecaster.predict(steps=24, exog=exog_test)

Prediction Intervals and Quantiles

Foundation models output native quantile forecasts — no bootstrapping or conformal calibration is required.

# Interval (lower/upper bounds from the model's quantiles)
predictions = forecaster.predict_interval(
    steps=24,
    interval=[0.1, 0.9],   # 80% prediction interval (quantiles, 0-1 scale)
)
# Columns: ['level', 'pred', 'lower_bound', 'upper_bound']
# Explicit quantiles
predictions = forecaster.predict_quantiles(
    steps=24,
    quantiles=[0.1, 0.5, 0.9],
)
# Columns: ['level', 'q_0.1', 'q_0.5', 'q_0.9']

For TimesFM (2.5 and 3.0) and Moirai-2, requested quantiles must be a subset of [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]. TS-ICL accepts any level on a finer 0.01 grid in [0.01, 0.99] (e.g. 0.05, 0.37); off-grid levels raise a ValueError. Chronos-2, TabICL, TabPFN-TS, TFC-T0 and Nori support any quantile in (0, 1).

Choosing a Model

The adapter is resolved automatically from the model_id prefix — no need to import adapter classes directly.

To check what a model supports before installing its backend or loading its weights, use get_model_info (one model_id) or list_adapters (one entry per adapter, or a DataFrame with as_frame=True). Both return a frozen FoundationModelInfo read from the adapter classes, so it always matches the installed skforecast version; prefer it over hard-coding the table above.

from skforecast.foundation import get_model_info, list_adapters
info = get_model_info('google/timesfm-3.0-pytorch')
info.allow_exog, info.supported_quantiles  # supported_quantiles None = any level in (0, 1)
info.backend_package                       # 'timesfm[torch]', as passed to pip install
info.license, info.license_url             # SPDX id (or model card license name) and link, always informed
info.commercial_use_restricted             # True if the license restricts commercial use
info.requires_hf_auth                      # gated on the Hugging Face Hub
info.requires_provider_auth                # provider account/license acceptance (TabPFN, Prior Labs)
info.weights_repo_id                       # HF repo the weights come from, e.g. 'jingang/TabICL' for TabICL
info.weights_in_hf_cache                   # False when the weights are not in the HF Hub cache (TabPFN)
list_adapters(as_frame=True)  # DataFrame, one row per adapter; default: list of FoundationModelInfo

TimesFM 3.0, Moirai-2, TabPFN-TS, and TS-ICL weights are released under known non-commercial licenses; loading them raises a LicenseWarning naming the license and a link to the model card. Terms vary by provider (e.g. TabPFN-TS permits commercial use under an enterprise license), so review the linked license rather than the warning text alone. A model id not covered by this warning is not confirmed to be unrestricted.

Backtesting

Use the dedicated backtesting_foundation function — it is the only backtester that accepts a ForecasterFoundation. Internally cv is deep-copied and forced to refit=True, fixed_train_size=False, so the context window expands with each fold up to context_length; no weights are ever trained. Probabilistic output is requested via quantiles, not interval.

from skforecast.model_selection import backtesting_foundation, TimeSeriesFold
cv = TimeSeriesFold(
    steps=24,
    initial_train_size=len(series) - 200,
    refit=False,      # Overridden internally; passing True emits IgnoredArgumentWarning
)