---
license: apache-2.0
pipeline_tag: time-series-forecasting
library_name: tfc-t0
thumbnail: https://www.theforecastingcompany.com/images/og.png
tags:
  - time-series
  - forecasting
  - probabilistic-forecasting
  - foundation-models
  - pretrained-models
  - covariates
  - pytorch
  - safetensors
  - model_hub_mixin
  - pytorch_model_hub_mixin
model-index:
  - name: t0-alpha
    results:
      - task:
          type: time-series-forecasting
          name: Time Series Forecasting
        dataset:
          name: fev-bench
          type: autogluon/fev-bench
        metrics:
          - name: Skill score
            type: skill-score
            value: 42.2
        source:
          name: fev-bench leaderboard
          url: https://huggingface.co/spaces/autogluon/fev-bench
      - task:
          type: time-series-forecasting
          name: Time Series Forecasting
        dataset:
          name: GIFT-Eval
          type: Salesforce/GiftEval
        metrics:
          - name: CRPS
            type: crps
            value: 0.4941
          - name: MASE
            type: mase
            value: 0.7240
        source:
          name: GIFT-Eval leaderboard
          url: https://huggingface.co/spaces/Salesforce/GIFT-Eval
---

<p align="center">
  <img src="https://www.theforecastingcompany.com/logo/logo_horizontal_pride_universal.png" alt="The Forecasting Company" width="280" />
</p>

# `t0-alpha`

`t0-alpha` is an open-weights time-series forecasting foundation model from [The Forecasting Company](https://theforecastingcompany.com/).

`t0` is a transformer-based model that produces probabilistic multi-horizon forecasts and natively operates on multiple covariates. `t0-alpha` is the first public iteration of the model.

You can use `t0` on [Retrocast](https://app.retrocast.com/), The Forecasting Company's platform for forecasting on your own data and comparing forecasts across open-weight models.

![t0 forecasting French national electricity demand in Retrocast](assets/enedis_with_holidays.png)

_`t0` forecasting French national electricity demand in Retrocast. Data: [Enedis open data](https://data.enedis.fr/)._

## Model Details

- Model name: `t0-alpha`
- Model family: `t0`
- Developer: [The Forecasting Company](https://theforecastingcompany.com/)
- Task: probabilistic time-series forecasting
- Architecture: decoder-style patch transformer
- Parameters: approximately 102M
- License: Apache-2.0
- Weights: https://huggingface.co/theforecastingcompany/t0-alpha
- Source code: https://github.com/theforecastingcompany/tfc-t0
- Issues: https://github.com/theforecastingcompany/tfc-t0/issues
- Package: `tfc-t0`

`t0-alpha` is an alpha release intended for research, experimentation, and applied forecasting evaluation.

## Intended Use

`t0-alpha` is intended for probabilistic time-series forecasting. It can be used for univariate and multivariate forecasting, forecasting with historical or known-future covariates and multi-horizon forecasting.

Known-future covariates can include calendar features, planned events, holidays, promotions, weather forecasts, or other external signals available over the forecast horizon.

Forecasts should be treated as probabilistic estimates, not guarantees.

## 📈 Forecasting With Covariates

`t0` leverages covariate information, in the past and future when available, to improve its forecast.

| Without covariates                                                | With covariates                                             |
| ----------------------------------------------------------------- | ----------------------------------------------------------- |
| ![t0 forecast without covariates](assets/medicam_without_cov.png) | ![t0 forecast with covariates](assets/medicam_with_cov.png) |

_Data: [Medic'AM](https://www.assurance-maladie.ameli.fr/etudes-et-donnees/medicaments-classe-atc-medicam), monthly drug reimbursements from the French national health insurance._

The [Quickstart](#quickstart) below shows the API for both a plain univariate forecast and a multivariate forecast that conditions on historical and known-future covariates.

## Installation

```bash
pip install tfc-t0
```

Requirements:

- Python `>=3.11,<3.14`
- PyTorch `>=2.4,<3`

Optional extras:

```bash
pip install "tfc-t0[evaluation]"
pip install "tfc-t0[plot]"
```

## 🚀 Quickstart

The simplest path is a univariate forecast through `predict`:

```python
import torch
from t0 import T0Forecaster

model = T0Forecaster.from_pretrained("theforecastingcompany/t0-alpha").eval()

context = torch.randn(4, 512)  # 4 series, 512 past timesteps
out = model.predict(context, horizon=64, quantiles=[0.1, 0.5, 0.9])
out.quantiles  # (4, 64, 3)
out.median     # (4, 64)
```

`predict` accepts PyTorch tensors and NumPy arrays.

### Forecasting With Covariates

Anything known over the past goes in `context`. Alongside the target, extra variates attend to it and are forecast together. Anything known over the future, such as calendar features, planned promotions, or weather forecasts, goes in `future_covariates`, shaped `[B, F, context + horizon]`; the model conditions on it but does not forecast it.

```python
import torch
from t0 import T0Forecaster

model = T0Forecaster.from_pretrained("theforecastingcompany/t0-alpha").eval()

context = torch.randn(2, 512)                    # 2 series, 512 past timesteps
future_covariates = torch.randn(2, 3, 512 + 64)  # 3 covariates known over context + horizon

out = model.predict(
    context,
    horizon=64,
    quantiles=[0.1, 0.5, 0.9],
    future_covariates=future_covariates,
)
out.quantiles  # (2, 64, 3)
out.median     # (2, 64)
```

## Input Contract

- `context` may be shaped `(B, T)` for batched univariate forecasting.
- `context` may also be shaped `(T,)`; it is promoted to a single-row batch.
- `context` may be shaped `(B, V, T)` for multiple target variates.
- `future_covariates`, when provided, should be shaped `(B, F, context + horizon)`.
- NaN values are treated as missing observations.
- `horizon` must be at least 1.
- Requested quantiles must be non-empty, sorted ascending, unique, and in `(0, 1)`.
- The model was trained to emit quantiles `0.1`, `0.25`, `0.5`, `0.75`, and `0.9`.
- Requested quantiles are produced by inference-time interpolation when needed.
- Horizons up to 1024 timesteps are decoded in one forward pass.
- Longer horizons use autoregressive rollout.
- Returned forecasts are finite `float32` tensors on the model's device.

## 🏗️ Architecture

`t0` is a decoder-style patch transformer.

It encodes each patch from values, within-patch time index, and validity mask. The transformer alternates causal time-axis self-attention with variate-axis group self-attention. Time attention uses time-aware rotary embeddings. Variate attention lets variates in the same sample attend to one another. The stack uses pre-norm RMSNorm blocks, SwiGLU feed-forward layers, and a quantile head.

At inference, target and historical variates are normalized with causal running statistics. Future covariates use per-row global statistics.

| Field | Value |
| --- | --- |
| Parameters | approximately 102M |
| Layers | 24 |
| Layer pattern | 2 time-attention layers, then 1 group-attention layer |
| Time attention layers | 16 |
| Group attention layers | 8 |
| Embedding dim | 512 |
| Feedforward dim | 2048 |
| Attention heads | 8 |
| Patch size | 32 |
| Dropout | 0.1 |
| Scaler | causal mean/std with `arcsinh` transform |
| Native quantile levels | 0.1, 0.25, 0.5, 0.75, 0.9 |

## Evaluation

`t0-alpha` is reported on the [GIFT-Eval leaderboard](https://huggingface.co/spaces/Salesforce/GIFT-Eval) and the [fev-bench leaderboard](https://huggingface.co/spaces/autogluon/fev-bench).

| Benchmark | Metric | Value |
| --- | --- | ---: |
| GIFT-Eval | CRPS | 0.4941 |
| GIFT-Eval | MASE | 0.7240 |
| fev-bench | Skill score | 42.2 |

Users should also evaluate `t0-alpha` on their own historical backtests. Useful checks include quantile loss, CRPS, MASE, empirical quantile coverage, calibration, and breakdowns by frequency, horizon, domain, history length, and covariate availability.

## 🧰 Public API

- `T0Forecaster`: The actual PyTorch module class.
- `Forecast`: return object encapsulating forecasted quantiles.
- `T0Config`: dataclass to configure the model.

## 🧬 Lineage and Attributions

`t0` builds on ideas from open-source forecasting models. We gratefully acknowledge:

- **Toto** by Datadog ([repo](https://github.com/DataDog/toto)) and **Chronos-2** by Amazon ([repo](https://github.com/amazon-science/chronos-forecasting)) for factorizing attention in the time and variates dimension.
- **TiRex** by NXAI ([repo](https://github.com/NX-AI/tirex)) for contiguous patch masking.

Code-level attributions are listed in [`NOTICE`](NOTICE), all under Apache-2.0.

## Environmental Impact

Training compute and carbon emissions are not currently reported.

## 📚 Citation

```bibtex
@misc{tfc-t0,
  title  = {t0: A time-series forecasting foundation model},
  author = {The Forecasting Company},
  year   = {2026},
  url    = {https://huggingface.co/theforecastingcompany/t0-alpha},
}
```

## ⚖️ License

Apache-2.0. See [`LICENSE`](LICENSE) and [`NOTICE`](NOTICE).

## Contact

For issues, bug reports, or API questions, please use the GitHub issue tracker:

https://github.com/theforecastingcompany/tfc-t0/issues