Timestral: from model release to local forecasts

Shared support: univariate or multivariate targets, past-only and known-future covariates, and 21 output quantiles. Context is capped at 32,768 historical time steps, not text tokens. One prediction block covers up to 1,024 future steps; longer horizons feed predicted medians back into subsequent blocks.

File size is a download/storage figure. Runtime RAM or VRAM also depends on tensor buffers, context length, batch size and the number of variables; no minimum-memory guarantee is implied.

1. 01

   Historical observations

   Supply regularly spaced targets and optional covariates. Mark missing observations with NaN.

2. 02

   Patches of 32 steps

   Values and missing-value indicators are embedded together, preserving the order of time.

3. 03

   Time and variate attention

   Attention relates history over time and across variables. Covariates can inform targets without reading target rows.

4. 04

   Prediction tokens and quantiles

   Decoupled Horizon Forecasting uses separate prediction tokens to read the encoded context and produce ordered quantiles.

The model card still lists the technical report as coming soon at the verification date. Architecture details here come from the README and model card; undisclosed training details are not inferred.

Source-label difference: the release article labels a GIFT-Eval probability chart WQL, while the model-card table labels its row CRPS. We retain CRPS for the values shown here and do not assume the two labels describe an identical calculation. Arrows indicate whether lower or higher is better.

1. 01

   MASE ↓

   Mean Absolute Scaled Error compares absolute forecast error with a naive reference scale. Lower is better. These GIFT-Eval and TIME figures are aggregate results, not percentages of correct predictions.

2. 02

   CRPS ↓

   Continuous Ranked Probability Score evaluates a predicted distribution against observations. Lower is better; inspect the benchmark definition and aggregation before comparing across datasets.

3. 03

   SQL skill score ↑

   Scaled Quantile Loss skill score reports improvement relative to a reference forecast. Higher is better. A score of 50.39 is not 50.39% prediction accuracy. The MASE skill-score row also uses higher-is-better scoring.

4. 04

   Inputs and evaluation scope

   The README specifies forecaster defaults and history up to 32,768 steps: GIFT-Eval uses 97 configurations with past numeric covariates; TIME uses 98 tasks without covariates; fev-bench uses 100 tasks with past and known covariates, including encoded categories.

These aggregate results do not establish a winner for every sensor, demand series or business horizon. Evaluate the same forecast origin, horizon, covariates and error metric on your own holdout period; exclude future information from history.

The article does not identify an exact CPU SKU or a complete timing protocol. Cold downloads, model loading, I/O and your variable count can change end-to-end time. Do not turn these numbers into a general speedup claim.

Local inference consumes your CPU/GPU time, RAM, electricity and operations effort. Downloadable weights are subject to their license. This guide has not verified a public Timestral-specific hosted API price or endpoint; no per-token or per-forecast selling price is inferred from the benchmark.

Reference instructions only: this site has not installed Timestral, downloaded weights or run these forecasts. First use needs network access to fetch dependencies and the selected checkpoint.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install git+https://github.com/mistralai/timestral.git

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install git+https://github.com/mistralai/timestral.git

Choose one environment setup, not both. The python3 command must resolve to Python ≥ 3.10. Installation from Git follows the official README and resolves current dependencies; it is not a frozen environment. For reproducibility, the repository also provides uv.lock and uv sync --frozen. CPU-only PyTorch builds can be selected through the official PyTorch installer.

import numpy as np
from timestral import TimestralForecaster

model = TimestralForecaster.from_pretrained(
    "mistralai/Timestral-5M", device="cpu"
)
rng = np.random.default_rng(42)
context = rng.standard_normal(1000).cumsum()
forecast = model.forecast(context, prediction_length=96)
median = forecast.median
lower = forecast.quantile(0.1)
upper = forecast.quantile(0.9)
print("shape:", tuple(median.shape))  # (1, 1, 96)
print("first median:", median[0, 0, 0].item())
print("first interval:", lower[0, 0, 0].item(), upper[0, 0, 0].item())

python forecast.py

Expected interface shape, not a captured test result: median has shape (1, 1, 96), representing one series, one variable and 96 future steps. The random walk is synthetic demonstration data; its predictions do not establish model quality.

To evaluate the flagship, replace the model ID with mistralai/Timestral-209M. A supported CUDA environment can use device="cuda". Check memory and compare on held-out data before increasing context, variables or batch size.

value
100
103
""
108
110

import csv
import numpy as np
from timestral import TimestralForecaster

# series.csv: one header named "value"; oldest observation first.
# Each row represents one equally spaced time step; blank = missing.
with open("series.csv", newline="", encoding="utf-8-sig") as stream:
    rows = list(csv.DictReader(stream))
context = np.array([
    float(row["value"]) if row["value"].strip() else np.nan
    for row in rows
], dtype=np.float32)
if context.size == 0 or not np.isfinite(context).any():
    raise ValueError("Provide at least one finite observation")
if np.isinf(context).any():
    raise ValueError("Use blank cells for missing values, not infinity")

model = TimestralForecaster.from_pretrained(
    "mistralai/Timestral-5M", device="cpu"
)
result = model.forecast(context, prediction_length=96)
values = result.median[0, 0].cpu().numpy()
np.savetxt("forecast.csv", values, delimiter=",", header="median", comments="")

Blank cells become NaN; retain rows for missing time slots. The script does not parse timestamps, sort, deduplicate or resample data. Do those steps before exporting the single column, and define its sampling interval. The output has 96 median values; assign future timestamps using that interval.

For multivariate input use (B, V, T): batch, variables, history. Past numeric covariates use (B, C, T); known-future covariates use (B, C, T + H), where H is prediction_length. A single target series is not an instruction to treat unrelated sensors as independent batch rows.

from timestral import TimestralForecaster

# First load online to populate the Hugging Face cache:
model = TimestralForecaster.from_pretrained(
    "mistralai/Timestral-5M", device="cpu"
)
# Later, load the same cached checkpoint without a network lookup:
cached = TimestralForecaster.from_pretrained(
    "mistralai/Timestral-5M", device="cpu", local_files_only=True
)
# Alternative: directory containing config.json and model.safetensors.
local = TimestralForecaster.from_pretrained(
    "/path/to/Timestral-5M", device="cpu", local_files_only=True
)

Use the cached or local branch after preparing its files; the three loads above are alternatives for illustrating the lifecycle, not a required sequence in every script. Replace the placeholder path, or use a Windows path such as r"D:\models\Timestral-5M". local_files_only=True cannot recover missing files. Packages must also be installed before going offline.

1. 01

   Installation or import fails

   Check python --version and python -m pip show torch inside the activated environment. Confirm Python ≥ 3.10, torch ≥ 2.4 and Git availability. A CUDA device also needs a compatible PyTorch build and driver; begin with CPU to separate these issues.

2. 02

   Checkpoint download or offline load fails

   Check network access, available disk space and the exact case-sensitive model ID. An offline cache must contain the selected revision. A local folder must contain both config.json and model.safetensors; a filename alone is not a checkpoint directory.

3. 03

   Shape or covariate errors

   Targets accept (T,), (B, T) or (B, V, T). Align all series on a common sampling interval, use NaN for missing values and provide T + H steps for known-future covariates. Do not put observations from the test horizon into the input history.

4. 04

   Memory use or latency is too high

   Start with 5M, a smaller batch and fewer variables; shorten history only if that fits the task. Measure downloads and loading separately from inference. Weight-file size does not include runtime activations or library overhead.

Sources checked: 2026-10-25