TuiML Documentation

TimesFM — Google's pretrained decoder-only forecaster, used zero-shot.

Wraps the upstream timesfm package. TuiML ships no weights; timesfm fetches its own checkpoint from the Hugging Face Hub on first use. The package and the google/timesfm-2.5-200m-pytorch checkpoint are both Apache-2.0, which is compatible with TuiML's BSD-3-Clause license, so there is no usage restriction to accept.

Classes

TimesFMForecaster

class foundation.timesfm.TimesFMForecaster(_ZeroShotForecaster)

Zero-shot forecasting with Google's pretrained TimesFM checkpoint.

TimesFM is a time series foundation model: a decoder-only transformer pretrained on a corpus of roughly 100 billion real-world time points, so that it forecasts any univariate series it is shown without being trained on it. Your series is the context; the model emits a point forecast and a full set of decile quantiles for every future step in one forward pass. Nothing is estimated on your data -- fit only stores the context and loads the checkpoint, and all the cost lands in predict.

This wrapper targets TimesFM 2.5 (200M parameters), the PyTorch release with the continuous quantile head and a context window of up to 16k points.

Constructor

__init__(
    self,
    checkpoint: str = 'google/timesfm-2.5-200m-pytorch',
    context_length: int = 1024,
    max_horizon: int = 128,
    infer_is_positive: bool = True,
    batch_size: int = 32) -> None,
)

Overview

The last context_length points are per-series normalised, so the

model never sees the raw units.

The context is cut into non-overlapping input patches of 32 points;

each is embedded by a residual MLP.

A stack of causal self-attention layers runs over the patch sequence --

a decoder-only design, so every patch attends only to those before it.

The final patch's representation is decoded by a second residual MLP

into an output patch of 128 points, longer than the input patch, so most horizons need a single step.

A continuous quantile head produces the deciles; predict

returns the median and predict_quantiles the whole set.

Theory

TimesFM treats forecasting as next-patch prediction, the time series analogue of next-token prediction in a language model. With input patches $\tilde{y}_1, \dots, \tilde{y}_N$ of length $p$ and output patches of length $h > p$ , the pretraining objective is the mean squared error of each output patch given all preceding input patches:

\mathcal{L} = \frac{1}{N} \sum_{j=1}^{N} \big\| \hat{y}_{pj+1:pj+h} - y_{pj+1:pj+h} \big\|^2

Making the output patch longer than the input patch is the design choice that matters: it cuts the number of autoregressive steps a long horizon needs, which both speeds up inference and limits error accumulation. Version 2.5 adds a quantile head trained with the pinball loss, giving calibrated deciles rather than a point alone.

Parameters

checkpoint

str = "google/timesfm-2.5-200m-pytorch"

Hugging Face model id, or a local directory holding one.

context_length

int = 1024

Trailing points of the series handed to the model. Rounded up to a multiple of 32 when the model is compiled; the model supports up to 16384.

max_horizon

int = 128

Longest horizon the compiled model serves without recompiling. Rounded up to a multiple of 128. A predict beyond it recompiles the model for the larger horizon, which costs a second or two once.

infer_is_positive

bool = True

Clip forecasts at zero for series whose context is entirely non-negative, as counts and prices are.

batch_size

int = 32

Series per forward pass inside the model. Only matters for memory.

Attributes

model_

object

The underlying timesfm.TimesFM_2p5_200M_torch.

series_

np.ndarray of shape (n_context,)

The context window stored at fit.

n_obs_

int

Length of the series seen during fit.

quantile_levels_

np.ndarray of shape (9,)

The deciles 0.1 … 0.9, in the column order of predict_quantiles.

compiled_horizon_

int

Horizon the model is currently compiled for.

Notes

Requires pip install 'tuiml[foundation]', which pulls in timesfm and PyTorch. Importing TuiML and constructing this class work without either; only fit needs them.

Weights are not shipped by TuiML. On first use timesfm downloads the checkpoint (about 800 MB) from the Hugging Face Hub into ~/.cache/huggingface. Code and weights are Apache-2.0, compatible with TuiML's BSD-3-Clause, so there is no commercial-use restriction to accept.

Device: the upstream model picks CUDA when it is available and the CPU otherwise; there is no device knob to expose.

Saved models stay small. Pickling a fitted wrapper stores the context and the hyperparameters, never the checkpoint or its compiled state; the model is reloaded and recompiled from the Hugging Face cache on the first forecast after loading.

Complexity: fitting costs one checkpoint load plus a compile. Prediction is one decoder forward pass over $n_{\text{context}} / 32$ patches per 128-step chunk of horizon. A GPU is worth roughly an order of magnitude.

When to use TimesFMForecaster:

A strong forecast with zero tuning, on a series you have not modelled

before -- the natural first baseline alongside ChronosForecaster.

Long contexts: the 16k-point window is far longer than Chronos-Bolt's.
When you need calibrated deciles, not just a point.

Prefer ThetaForecaster or SARIMAXForecaster when you need a model you can inspect, exogenous regressors, or a CPU-only deployment without PyTorch.

References

Das2024

Das, A., Kong, W., Sen, R. and Zhou, Y. (2024). A decoder-only foundation model for time-series forecasting. Proceedings of the 41st International Conference on Machine Learning (ICML). arXiv: 2310.10688

Methods

get_parameter_schema (cls) -> Dict[str, Dict[str, Any]]

Return JSON Schema for constructor parameters.

get_capabilities (cls) -> List[str]

Return the data and task properties this model supports.

timesfm.py