Duplicate from mistralai/Timestral-209M

Co-authored-by: Julien Denize <juliendenize@users.noreply.huggingface.co>

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,10 @@
+Modified MIT License 
+
+Attribution notice: 2026 - Mistral AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of the weights of this model and associated documentation files (the “Model”), to deal in the Model without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Model, and to permit persons to whom the Model is furnished to do so, subject to the following conditions: 
+
+1. The above attribution notice and this permission notice shall be included in all copies or substantial portions of the Model. 
+2. You are not authorized to exercise any rights under this license if the global consolidated monthly revenue of your company (or that of your employer) exceeds $20 million (or its equivalent in another currency) for the preceding month. This restriction in (b) applies to the Model and any derivatives, modifications, or combined works based on it, whether provided by Mistral AI or by a third party. You may contact Mistral AI (sales@mistral.ai) to request a commercial license, which Mistral AI may grant you at its sole discretion, or choose to use the Model on Mistral AI's hosted services available at https://mistral.ai/.
+
+THE MODEL IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL MISTRAL AI BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE MODEL OR THE USE OR OTHER DEALINGS IN THE MODEL.

README.md

@@ -0,0 +1,164 @@
+---
+pipeline_tag: time-series-forecasting
+library_name: timestral
+tags:
+- time-series
+- forecasting
+- foundation-model
+model-index:
+- name: Timestral-209M
+  results:
+  - task:
+      type: time-series-forecasting
+      name: Time Series Forecasting
+    dataset:
+      name: GIFT-Eval
+      type: Salesforce/GiftEval
+    metrics:
+    - name: MASE
+      type: mase
+      value: 0.658
+    - name: CRPS
+      type: crps
+      value: 0.446
+    source:
+      name: GIFT-Eval leaderboard
+      url: https://huggingface.co/spaces/Salesforce/GIFT-Eval
+  - task:
+      type: time-series-forecasting
+      name: Time Series Forecasting
+    dataset:
+      name: TIME
+      type: Real-TSF/TIME
+    metrics:
+    - name: MASE
+      type: mase
+      value: 0.626
+    - name: CRPS
+      type: crps
+      value: 0.522
+    source:
+      name: TIME leaderboard
+      url: https://huggingface.co/spaces/Real-TSF/TIME-leaderboard
+  - task:
+      type: time-series-forecasting
+      name: Time Series Forecasting
+    dataset:
+      name: fev-bench
+      type: autogluon/fev-bench
+    metrics:
+    - name: SQL skill score
+      type: skill-score
+      value: 50.39
+    - name: MASE skill score
+      type: skill-score
+      value: 39.49
+    source:
+      name: fev-bench leaderboard
+      url: https://huggingface.co/spaces/autogluon/fev-bench
+license: other
+---
+
+
+<h1><img src="timestral-hourglass.png" alt="" style="display:inline; height:1em; width:auto; margin:0 0.3em 0 0; vertical-align:-0.1em;"> Timestral-209M</h1>
+
+
+Timestral is a **family of time series foundation models** for zero-shot forecasting, available in [**5M**](https://huggingface.co/mistralai/Timestral-5M), [**28M**](https://huggingface.co/mistralai/Timestral-28M), [**123M**](https://huggingface.co/mistralai/Timestral-123M), and [**209M**](https://huggingface.co/mistralai/Timestral-209M) parameter versions. 
+This repository contains the 209M checkpoint.
+
+Timestral supports univariate and multivariate forecasting, past-only and known-future covariates, and probabilistic predictions across 21 quantiles. It accepts up to 32,768 historical time steps and forecasts up to 1,024 steps in a single forward pass.
+
+We’re releasing the source code in our [GitHub repository](https://github.com/mistralai/timestral/) to make it easy to run Timestral and reproduce our benchmark results.
+
+## Model Details
+
+- **Size:** 209M parameters.
+- **Architecture:** patch-based transformer with time attention and variate attention, 24 layers, embedding dimension 768.
+- **Patching:** 32 time steps per patch. Each patch is embedded from its values together with their missing-value indicators.
+- **Context length:** up to 32,768 time steps (1,024 patches). 
+- **Forecast horizon**: Up to 1,024 time steps (32 patches) in a single forward pass. Longer horizons are forecast block by block, with each block's median forecast appended to the context.
+- **Outputs:** 21 quantiles (0.01, 0.05, 0.1, 0.15, …, 0.85, 0.9, 0.95, 0.99). 
+- **Inputs:** univariate or multivariate target variates, plus past-only and known-future covariates, numeric or categorical (categorical covariates are target-encoded). Missing values are marked as NaN.
+- **Inference:** PyTorch on CPU or GPU.
+
+
+## Benchmarks
+Timestral-209M achieves **state-of-the-art zero-shot accuracy** across three major forecasting benchmarks: [GIFT-Eval](https://huggingface.co/spaces/Salesforce/GIFT-Eval), [TIME](https://huggingface.co/spaces/Real-TSF/TIME-leaderboard), and [fev-bench](https://huggingface.co/spaces/autogluon/fev-bench).
+
+### Timestral-209M compared with other models
+| Benchmark | Metric | [Timestral-209M](https://huggingface.co/mistralai/Timestral-209M) | t0-gamma | TimesFM-3 | Toto-2.0-2.5B | Chronos-2 |
+|---|---|---|---|---|---|---|
+| GIFT-Eval | MASE ↓ | **0.658** | 0.661 | 0.667 | 0.696 | 0.698 |
+| | CRPS ↓ | **0.446** | 0.452 | 0.456 | 0.476 | 0.485 |
+| TIME | MASE ↓ | **0.626** | 0.637 | 0.640 | 0.642 | 0.662 |
+| | CRPS ↓ | **0.522** | 0.534 | 0.536 | 0.539 | 0.556 |
+| fev-bench | SQL skill score ↑ | **50.39** | 49.42 | 48.99 | 44.42 | 47.28 |
+| | MASE skill score ↑ | **39.49** | 37.99 | 37.82 | 32.54 | 35.50 |
+
+### Results across the Timestral family
+| Benchmark | Metric | [Timestral-5M](https://huggingface.co/mistralai/Timestral-5M) | [Timestral-28M](https://huggingface.co/mistralai/Timestral-28M) | [Timestral-123M](https://huggingface.co/mistralai/Timestral-123M) | [Timestral-209M](https://huggingface.co/mistralai/Timestral-209M) |
+|---|---|---|---|---|---|
+| GIFT-Eval | MASE ↓ | 0.705 | 0.678 | 0.659 | **0.658** |
+| | CRPS ↓ | 0.479 | 0.461 | 0.448 | **0.446** |
+| TIME | MASE ↓ | 0.652 | 0.638 | 0.628 | **0.626** |
+| | CRPS ↓ | 0.545 | 0.534 | 0.525 | **0.522** |
+| fev-bench | SQL skill score ↑ | 46.19 | 48.42 | 50.18 | **50.39** |
+| | MASE skill score ↑ | 34.54 | 37.27 | 39.19 | **39.49** |
+
+The Pareto-front plot below illustrates the trade-off between model size and forecasting performance across the Timestral family.
+
+![Pareto front of model size versus forecasting performance for the Timestral models](https://cdn-uploads.huggingface.co/production/uploads/6a883eae29d17c41f6dbdfd4/FoDdgcwd64Zwg4L29FShg.png)
+
+## Usage
+
+### Install
+
+Set up your environment:
+
+```bash
+pip install git+https://github.com/mistralai/timestral.git   # Python >= 3.10, torch >= 2.4
+```
+
+Or from a clone with [uv](https://docs.astral.sh/uv/), using the versions pinned in `uv.lock`:
+
+```bash
+git clone https://github.com/mistralai/timestral.git && cd timestral
+uv sync --frozen
+source .venv/bin/activate
+```
+
+### Run the model
+
+Here is a simple example using synthetic data.
+
+```python
+import numpy as np
+import torch
+from timestral import TimestralForecaster
+
+model = TimestralForecaster.from_pretrained(
+    "mistralai/Timestral-209M",
+    device="cuda" if torch.cuda.is_available() else "cpu"
+)
+
+# Synthetic example: one series with 1,000 historical observations.
+context = np.random.default_rng(42).standard_normal(1000).cumsum()
+forecast = model.forecast(context, prediction_length=96)
+
+median = forecast.median
+lower, upper = forecast.quantile(0.1), forecast.quantile(0.9)
+```
+
+Check out our [GitHub repository](https://github.com/mistralai/timestral/) for more details!
+
+## Additional Resources
+- [Blog post](https://mistral.ai/news/timestral/)
+- [GitHub repository](https://github.com/mistralai/timestral/)
+- Tech report: coming soon!
+
+
+## License
+
+Models have been released under a Modified MIT license: See [here](https://huggingface.co/mistralai/Timestral-209M/blob/main/LICENSE).
+
+*You must not use this model in a manner that infringes, misappropriates, or otherwise violates any third party’s rights, including intellectual property rights*

config.json

@@ -0,0 +1,71 @@
+{
+  "patch_size": 32,
+  "d_model": 768,
+  "num_heads": 12,
+  "mlp_hidden_dim": 2048,
+  "block_schedule": [
+    "time",
+    "time",
+    "time",
+    "time_variate",
+    "time",
+    "time",
+    "time",
+    "time_variate",
+    "time",
+    "time",
+    "time",
+    "time_variate",
+    "time",
+    "time",
+    "time",
+    "time_variate",
+    "time",
+    "time",
+    "time",
+    "time_variate",
+    "time",
+    "time",
+    "time",
+    "time_variate"
+  ],
+  "quantile_knots": [
+    0.01,
+    0.05,
+    0.1,
+    0.15,
+    0.2,
+    0.25,
+    0.3,
+    0.35,
+    0.4,
+    0.45,
+    0.5,
+    0.55,
+    0.6,
+    0.65,
+    0.7,
+    0.75,
+    0.8,
+    0.85,
+    0.9,
+    0.95,
+    0.99
+  ],
+  "block_size": 32,
+  "context_length": 32768,
+  "rope_theta": 10000.0,
+  "rope_partial_factor": 0.5,
+  "norm_eps": 1e-06,
+  "attn_bias": false,
+  "mlp_bias": false,
+  "time_attn_gate": "sdpa_sigmoid",
+  "variate_attn_gate": "sdpa_sigmoid",
+  "minimum_scale": 1e-06,
+  "use_asinh": true,
+  "stabilize_with_global": false,
+  "covariate_enabled": true,
+  "split_context_horizon_attn": true,
+  "attend_missing_patches": true,
+  "quantile_width_factor": 3.0
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1456effb9927e3daa8c7234f10497e3424233869245a9c72b8ecebaf7ad2b7fa
+size 837271648