Timestral – Time‑Series Foundation Models

What it is – Timestral is a family of pretrained transformer models for multivariate probabilistic time‑series forecasting. The repo ships only the inference code; model weights live on Hugging Face.

Key capabilities

• Forecast multiple variates jointly, with up to 32 k steps of historical context.
• Handles past‑only, known‑future, and categorical covariates (numeric or one‑hot‑like).
• Returns 21 quantiles per horizon step (non‑crossing), giving a full predictive distribution.
• Four model sizes (5 M, 28 M, 123 M, 209 M) that trade accuracy vs. footprint; the 209 M version topped three public benchmarks (GIFT‑Eval, TIME, fev‑bench) in zero‑shot mode.
• CPU‑friendly inference; works on GPU if available.

Installation

pip install git+https://github.com/mistralai/timestral.git   # Python ≥3.10, torch ≥2.4

Or clone and sync with uv for exact pinned dependencies.

Typical usage

import numpy as np
from timestral import TimestralForecaster

forecaster = TimestralForecaster.from_pretrained(
    "mistralai/Timestral-209M", device="cpu"
)

# context: (batch, variates, time) – NaN marks missing values
context = np.random.randn(2, 1, 2000).cumsum(-1)
forecast = forecaster.forecast(context, prediction_length=96)

print(forecast.quantiles.shape)   # (2, 1, 96, 21)
print(forecast.median.shape)      # (2, 1, 96)

Optional arguments let you pass:

• past_covariates (known only over the historic window)
• known_covariates (extend into the forecast horizon)
• categorical_*_covariates (numeric category codes, internally target‑encoded).

Model zoo – Weights are hosted on Hugging Face under the Mistral AI organization:

Model	Repo	Size
Timestral‑5M	mistralai/Timestral-5M	21 MB
Timestral‑28M	mistralai/Timestral-28M	111 MB
Timestral‑123M	mistralai/Timestral-123M	490 MB
Timestral‑209M	mistralai/Timestral-209M	837 MB

TimestralForecaster.from_pretrained downloads the config.json and model.safetensors automatically.

Architecture snapshot – A causal patch‑based transformer trained with Decoupled Horizon Forecasting. Separate prediction tokens read the encoded context, and a quantile head emits 21 non‑crossing quantiles per step. Covariate rows are read‑only; known‑future covariates see the horizon but never read target tokens.

License – Code is Apache 2.0. Model weights are released under a Modified MIT license (see each Hugging Face repo). Use of the weights must respect that license.

Support – No pull‑requests are accepted; open issues on GitHub for bugs or questions.