mistralai / timestral

# Timestral
 Blog post ·
 Hugging Face collection ·
 License 
Timestral is a family of time series foundation models for multivariate probabilistic forecasting, with support for past-only and known-future covariates.
This repository provides standalone inference for Timestral models. It needs only PyTorch, NumPy, `safetensors` and `huggingface_hub`, and runs on CPU or GPU.
> **License:** the code in this repository is licensed under Apache 2.0. The Timestral model weights are released separately on the Hugging Face Hub under a Modified MIT license. See License.
## Highlights
At launch, Timestral-209M ranked first among pretrained and zero-shot models on the three main public forecasting benchmarks:
- 🥇 **GIFT-Eval**: #1 among pretrained and zero-shot models.
- 🥇 **TIME**: #1 across 98 tasks.
- 🥇 **fev-bench**: #1 across 100 tasks.
All four sizes (5M, 28M, 123M, 209M) sit on the Pareto front of accuracy versus model size. Full results are in the blog post and the model cards on Hugging Face.
- **Multivariate**: the variates of a series are forecast jointly.
- **Covariates**: past-only, known-future and categorical.
- **Probabilistic**: 21 quantiles per time step.
- **Long context**: up to 32,768 steps.
- **CPU-friendly**: no GPU needed for inference.
## Install
 [code] 
Or from a clone with uv, using the versions pinned in `uv.lock`:
 [code] 
## Models
The weights are on the Hugging Face Hub, in the Mistral AI organization:
| model | Hub repo | weights (fp32) |
|---|---|---|
| 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 |
`from_pretrained` downloads `config.json` and `model.safetensors` once to the Hub cache.
## Forecast
 [code] 
- `context` can be `(B, V, T)`, `(B, T)` (one variate per series) or `(T,)` (one series),
 as a NumPy array or a torch tensor. The variates of a series are forecast jointly.
- NaN marks a missing value. `observation_mask` (same shape, False = missing) can mark more.
- The context is capped at the trained length (32768 steps); the most recent steps are kept.
- Horizons longer than one decode block (32 patches = 1024 steps) are forecast block by
 block; each block's median is fed back as context.
### Loading options
`from_pretrained` takes a Hub repo id or a local directory with `config.json` and
`model.safetensors`. 
- `revision` pins a branch, tag or commit; `cache_dir` and `token` work as in `huggingface_hub`.
- `local_files_only=True` (or `HF_HUB_OFFLINE=1`) reads from the cache without network access.
### Covariates
 [code] 
Covariates are conditioning rows: they are not forecast, and covariate rows never read the
targets. Known-future covariate rows whose values are all 0 or 1 are treated as indicators.
NaN marks a missing covariate value.
### Categorical covariates
 [code] 
Pass categories as numeric codes (for example `pandas.factorize`), with Na