Foundation forecast

polars_ts.adapters.foundation_forecast

Foundation model forecasting adapters (Chronos, TimesFM, Moirai).

Wraps pre-trained time series foundation models for direct zero-shot forecasting, returning a polars DataFrame with point forecasts and prediction intervals.

Extends the existing embedding adapters (issue #151) with a predict pipeline that produces future values rather than fixed-length representations.

References

Chronos-2 (Amazon, 2025). T5-based tokenized time series model. TimesFM (Google, 2024). Pre-trained foundation model for forecasting. Moirai (Salesforce, 2024). Universal time series forecasting model.

ChronosForecaster

Zero-shot forecaster using Amazon Chronos models.

Uses the Chronos pipeline to generate probabilistic forecasts via sample paths. Point forecast is the median; prediction intervals are derived from sample quantiles.

Requires torch and chronos.

Parameters

model_name HuggingFace model identifier (e.g. "amazon/chronos-t5-small"). device Torch device ("cpu", "cuda"). num_samples Number of sample paths for probabilistic forecasts. coverage Prediction interval coverage (e.g. 0.9 for 90%). id_col, time_col, target_col Column names.

predict(df, h)

Generate h-step-ahead forecasts for each series.

Parameters

df Panel DataFrame with historical observations. h Forecast horizon.

Returns

pl.DataFrame Columns: [id_col, time_col, y_hat, y_hat_lower, y_hat_upper].

TimesFMForecaster

Zero-shot forecaster using Google TimesFM.

Requires timesfm.

Parameters

model_name TimesFM model identifier. context_length Number of historical observations to use as context. id_col, time_col, target_col Column names.

predict(df, h)

Generate h-step-ahead forecasts for each series.

Parameters

df Panel DataFrame with historical observations. h Forecast horizon.

Returns

pl.DataFrame Columns: [id_col, time_col, y_hat].

MoiraiForecaster

Zero-shot forecaster using Salesforce Moirai models.

Requires torch and uni2ts.

Parameters

model_name HuggingFace model identifier for Moirai. device Torch device. num_samples Number of sample paths for probabilistic forecasts. coverage Prediction interval coverage. id_col, time_col, target_col Column names.

predict(df, h)

Generate h-step-ahead forecasts for each series.

Parameters

df Panel DataFrame with historical observations. h Forecast horizon.

Returns

pl.DataFrame Columns: [id_col, time_col, y_hat, y_hat_lower, y_hat_upper].

_build_forecast_df(ids, forecasts, df, h, id_col, time_col)

Build output DataFrame with future dates and forecasts.

Parameters

ids Series identifiers. forecasts Mapping with keys "y_hat", "y_hat_lower", "y_hat_upper", each of shape (n_series, h). df Original input DataFrame (for inferring future dates). h Forecast horizon. id_col, time_col Column names.

foundation_forecast(df, model, h, model_name=None, **kwargs)

Unified foundation model forecasting interface.

Parameters

df Panel DataFrame with historical observations. model Model family: "chronos", "timesfm", or "moirai". h Forecast horizon. model_name Override the default HuggingFace model identifier. **kwargs Additional arguments passed to the forecaster constructor.

Returns

pl.DataFrame Forecast DataFrame with [id_col, time_col, y_hat, ...].