Update README.md

README.md

@@ -6,13 +6,16 @@ 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
+  - name: t0-alpha
     results:
       - task:
           type: time-series-forecasting
@@ -36,42 +39,74 @@ model-index:
   <img src="https://www.theforecastingcompany.com/logo/logo_horizontal_pride_universal.png" alt="The Forecasting Company" width="280" />
 </p>
 
-# `t0`
+# `t0-alpha`
 
-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 our first iteration of the model.
+`t0-alpha` is an open-weights time-series forecasting foundation model from [The Forecasting Company](https://theforecastingcompany.com/).
 
-You can use `t0` on [Retrocast](https://app.retrocast.com/), our platform for forecasting on your own data. You can also compare forecast across different open-weight models.
+`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/)._
+_`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
 
-## 📈 Forecasting with covariates
+`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.
 
-`t0` leverages covariate information, in the past and future when
-available, to improve its forecast.
+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._
+_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.
+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.
 
-## 🚀 Quickstart
+## 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
@@ -86,18 +121,11 @@ out.quantiles  # (4, 64, 3)
 out.median     # (4, 64)
 ```
 
-`predict` accepts `numpy` arrays. 1-D contexts are auto-promoted to a
-single-row batch. NaN values in the context are treated as missing
-observations.
+`predict` accepts PyTorch tensors and NumPy arrays.
 
-### Forecasting with covariates
+### Forecasting With Covariates
 
-Anything you know over the **past** goes in `context` — alongside the
-target, extra variates attend to it and are forecast together. Anything
-you know over the **future** (calendar features, planned promotions,
-weather forecasts) goes in `future_covariates`, shaped
-`[B, F, context + horizon]`; the model conditions on it but does not
-forecast it.
+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
@@ -118,46 +146,72 @@ 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 that alternates time and
-covariate attention layers. It predicts 5 quantiles (0.1, 0.25, 0.5,
-0.75, 0.9), decoding multiple horizons in parallel — up to 1024
-timesteps in one forward pass — and falling back on autoregressive
-rollout for longer horizons.
-
-|                 |                           |
-| --------------- | ------------------------- |
-| Parameters      | ~102M                     |
-| Layers          | 24                        |
-| Embedding dim   | 512                       |
-| Feedforward dim | 2048                      |
-| Attention heads | 8                         |
-| Patch size      | 32                        |
-| Quantile levels | 0.1, 0.25, 0.5, 0.75, 0.9 |
-
-### 🧬 Lineage
-
-`t0` builds on ideas — and in places, code — from open-source forecasting
-models. We gratefully acknowledge:
-
-- **Toto** by Datadog ([repo](https://github.com/DataDog/toto)) &
-  **Chronos-2** by Amazon
-  ([repo](https://github.com/amazon-science/chronos-forecasting)) —
-  factorizing attention in the time and variates dimension.
-- **TiRex** by NXAI
-  ([repo](https://github.com/NX-AI/tirex)) — contiguous patch masking.
-
-Code-level attributions are listed in [`NOTICE`](NOTICE), all under
-Apache-2.0.
+`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).
+
+| Benchmark | CRPS | MASE |
+| --- | ---: | ---: |
+| GIFT-Eval | 0.4941 | 0.7240 |
+
+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` — `nn.Module` with `from_pretrained` /
-  `save_pretrained` (via `huggingface_hub.PyTorchModelHubMixin`) and the
-  user-facing `predict(context, horizon, quantiles, future_covariates)`.
-- `T0Config` — frozen dataclass; `T0Config.medium()` is the published
-  configuration.
+- `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
 
@@ -172,6 +226,10 @@ Apache-2.0.
 
 ## ⚖️ License
 
-Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).
-</content>
-</invoke>
+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