Add README.md

README.md

@@ -0,0 +1,77 @@
+---
+datasets:
+  - autogluon/chronos_datasets
+  - autogluon/fev_datasets
+  - Salesforce/GiftEvalPretrain
+  - Salesforce/GiftEval
+pipeline_tag: time-series-forecasting
+library_name: tirex-2
+license: other
+---
+
+<h1 align="left">
+  <img src="tirex.svg" alt="TiRex mascott" height="48" /> TiRex-2
+</h1>
+
+This repository provides the pretrained TiRex-2 model and inference code for zero-shot
+ multivariate forecasting with past and future-known covariates, as introduced in [TiRex-2:
+ Generalizing TiRex to Multivariate Data and Streaming](ADD ARXIV LINK).
+
+TiRex-2 is a pretrained time series foundation model that forecasts one or many target
+variates directly from their history, optionally conditioned on past and future-known
+covariates. A single checkpoint serves both univariate and multivariate forecasting and
+operates in a streaming fashion as new observations arrive — all zero-shot, with no
+task-specific training or fine-tuning.
+
+## Key facts
+
+- **Zero-shot multivariate forecasting**: 
+  TiRex-2 forecasts multiple target variates out of the box, without training or fine-tuning on you data.
+
+- **Past and future-known covariates**:
+  TiRex-2 natively conditions on past covariates and future-known covariates, such as
+  calendar features, holidays, promotions, or scheduled interventions.
+
+- **Small active footprint**:
+  TiRex-2 activates 38.4M parameters in univariate mode and an additional 44.1M parameters
+  for multivariate forecasting.
+
+# Getting started
+
+The environment is managed by [Pixi](https://pixi.prefix.dev/latest/). Run the following to install it on your machine
+
+```bash
+curl -fsSL https://pixi.sh/install.sh | sh
+git clone https://github.com/NX-AI/tirex-2 && cd tirex-2
+# activate the cpu-only env
+eval "$(pixi shell-hook -e example)"  # to execute on GPUs use `example-cu128` or `example-cu126`
+```
+
+Minimal usage predicting a simple sine wave:
+```python
+import matplotlib.pyplot as plt, torch
+from tirex2 import TimeseriesType, load_model
+
+model = load_model("NX-AI/TiRex-2", device="cpu")  # use `device="cuda"` if cuda is available
+y = torch.sin(torch.arange(160).float() / 8) 
+ts = TimeseriesType(target=y[:128].unsqueeze(0), past_covariates=None, future_covariates=None)
+forecast = model.forecast([ts], prediction_length=32, output_type="numpy")[0][0]
+```
+
+We provide predefined Pixi tasks showcasing examplary forecasts. These run in the CPU-only `example` environment by default:
+- `pixi run minimal` runs above code and creates a plot of the forecast.
+- `pixi run comparison` showcases the additional benefit of future known covariates in forecasting a target.
+
+For a more **interactive demo of TiRex-2**, we also provide a [quick-start](https://github.com/NX-AI/tirex-2/blob/main/examples/getting_started.ipynb) notebook. 
+
+## Cite
+If you use TiRex-2 in your research, please cite our work:
+TBD
+
+## Other versions:
+Alongside this pretrained checkpoint we also provide three other versions:
+- [TiRex-2-g](https://huggingface.co/NX-AI/TiRex-2-gifteval-zs): we took care to exclude any overlap with the GiftEval
+datasets ([pretrain](https://huggingface.co/datasets/Salesforce/GiftEvalPretrain) and [evaluation](https://huggingface.co/datasets/Salesforce/GiftEval)). 
+- [TiRex-2-gp](https://huggingface.co/NX-AI/TiRex-2-gifteval-pretrain): here we included the [GiftEval-Pretrain collection](https://huggingface.co/datasets/Salesforce/GiftEvalPretrain) in our pretraining corpus. 
+- [TiRex-2-f](https://huggingface.co/NX-AI/TiRex-2-fevbench): for the fev-benchmark we took the same measures as for
+GiftEval and removed all [fev-bench eval datasets](https://huggingface.co/datasets/autogluon/fev_datasets) from our pretraining corpus to produce this checkpoint.