TimesFM 3.0: A Practical First Look at Foundation Models for Forecasting

Time-series forecasting traditionally starts with model selection: ARIMA or exponential smoothing? Gradient boosting or an LSTM? One model per product, region, or sensor? That works, but it can create a long tail of training jobs and models to maintain.

TimesFM, which appeared in GitHub Trending today, proposes a different starting point: use a pretrained model for a zero-shot forecast, then decide whether the problem needs task-specific work. TimesFM 3.0 adds native multivariate forecasting and covariates for realistic datasets.

The mental model

A foundation model for time series learns reusable temporal patterns from many datasets. At inference time, we provide a context window and ask for the next horizon values. We may also request quantiles to describe uncertainty.

The change:

Traditional workflow	Foundation-model workflow
select a model family first	establish a zero-shot baseline first
train for each dataset	reuse a pretrained checkpoint
hand-design many temporal features	provide context and optional covariates
return a point estimate	return points and forecast quantiles

This changes the order of operations. A reusable baseline arrives earlier, so engineering time can focus on evaluation, data quality, and cases where customization adds value.

Installing the project

The repository documents a PyTorch installation:

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install "timesfm[torch]"

For application work, lock the resolved dependencies. Model code, CUDA libraries, and array libraries evolve at different speeds.

One crucial detail: the repository says the TimesFM 3.0 pretrained weights currently use a non-commercial license and cannot be used commercially or in production. The source is Apache-2.0, but code and weights have separate permissions. Check the current license before planning a product.

A minimal univariate forecast

The current API accepts a batch of NumPy arrays, including series with different context lengths:

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

config = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=32,
    device="cuda",
)

model = TimesFM3Evaluator(config)

sales = np.array(
    [102, 98, 105, 111, 109, 118, 121, 117, 125, 132],
    dtype=np.float32,
)

result = list(
    model.predict_batch(
        [sales],
        horizon=7,
        return_quantiles=True,
        use_symmetric_averaging=False,
    )
)[0]

print(result.forecast)
print(result.quantiles.shape)  # (7, 9)

Quantiles are often more actionable than the point forecast. Inventory teams may plan against an upper quantile to reduce stockouts, while capacity teams can compare several risk levels.

Do not skip a naive baseline

A sophisticated checkpoint should still compete against simple rules. For seasonal daily data, a useful baseline is “same weekday last week”:

def seasonal_naive(values: np.ndarray, horizon: int, season: int = 7):
    if len(values) < season:
        raise ValueError("not enough history for seasonal baseline")
    tail = values[-season:]
    repeats = int(np.ceil(horizon / season))
    return np.tile(tail, repeats)[:horizon]

If a foundation model cannot beat this rule on the business metric, its sophistication is not creating value. Baselines also expose leakage, timestamp misalignment, scaling mistakes, and incorrect horizon slicing.

Evaluate as if the future were unknown

Random train/test splits are usually wrong for forecasting because they allow information from the future to influence the past. Prefer rolling-origin evaluation:

def rolling_windows(series, context, horizon, step):
    end = context
    while end + horizon <= len(series):
        history = series[end - context:end]
        actual = series[end:end + horizon]
        yield history, actual
        end += step

Each window simulates a forecast made at that historical moment. Report results across calm periods, holidays, promotions, outages, and regime changes; one average can hide expensive failures.

Useful metrics answer different questions:

Metric	Strength	Watch out for
MAE	easy to interpret in original units	treats every absolute error equally
RMSE	emphasizes large misses	sensitive to outliers
WAPE	useful across groups with different scale	unstable when total actual volume is near zero
Pinball loss	evaluates quantile forecasts	must be reported per quantile or carefully aggregated

Choose metrics that mirror the downstream decision.

Multivariate data and covariates

Real systems rarely have only one signal. Demand may depend on price, promotions, weather, and calendar events. TimesFM 3.0 distinguishes past-only covariates from values known into the forecast horizon.

context_len = 128
horizon = 24

target = np.random.randn(3, context_len).astype(np.float32)
past_only = np.random.randn(1, context_len).astype(np.float32)
known_future = np.random.randn(
    2, context_len + horizon
).astype(np.float32)

outputs = list(model.predict_batch(
    contexts=[target],
    horizon=horizon,
    past_only_covariates=[past_only],
    past_future_covariates=[known_future],
    return_quantiles=True,
    use_symmetric_averaging=False,
))

print(outputs[0].forecast.shape)   # (3, 24)
print(outputs[0].quantiles.shape)  # (3, 24, 9)

Only include future covariates genuinely known at inference time. A finalized promotion calendar can qualify; realized future weather cannot. Violating this boundary creates impressive offline results that collapse in production.

Production is more than predict_batch

Before serving any forecasting model, define contracts for:

1. timestamp frequency and timezone;
2. missing observations and duplicate timestamps;
3. minimum and maximum context length;
4. scaling and inverse transformations;
5. model version, checkpoint hash, and license;
6. latency, batch size, and fallback behavior;
7. drift, coverage, and post-deployment error monitoring.

A service should reject malformed data rather than silently interpolate everything. It also needs a cheap fallback such as seasonal naive or last value. GPU availability should not decide whether the business receives any forecast.

Where TimesFM fits

TimesFM is compelling as a baseline across many related series or where maintaining thousands of small models is costly. It is less convincing for tiny stable datasets, strict latency budgets, fully interpretable domains, or uses that conflict with the checkpoint license.

Foundation models do not replace forecasting work; they compress prior modeling into a reusable starting point. Defining the target, preventing leakage, measuring uncertainty, and connecting predictions to decisions still determines whether a forecast is useful.