Metadata-Version: 2.4
Name: timecopilot-tirex2
Version: 0.1.0
Summary: TiRex-2 time series forecasting inference
License: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: torch>=2.8.0
Requires-Dist: torch>=2.10.0; python_version >= "3.14"
Requires-Dist: numpy>=1.26.4
Requires-Dist: einops~=0.8.1
Requires-Dist: flashrnn>=1.0.5
Requires-Dist: xlstm~=2.0.3
Requires-Dist: PyYAML>=6
Requires-Dist: huggingface-hub>=0.35.3
Provides-Extra: examples
Requires-Dist: matplotlib>=3.10.0; extra == "examples"
Requires-Dist: plotly; extra == "examples"
Requires-Dist: jupyterlab; extra == "examples"
Provides-Extra: fev
Requires-Dist: fev; extra == "fev"
Requires-Dist: datasets<5,>=4.4.0; extra == "fev"
Requires-Dist: pyarrow>=22.0.0; extra == "fev"
Provides-Extra: gluonts
Requires-Dist: gluonts>=0.16.2; extra == "gluonts"
Requires-Dist: pandas~=2.3.3; extra == "gluonts"
Dynamic: license-file

# Disclaimer

> This is a personal fork of [tirex-2](https://github.com/NX-AI/tirex-2), maintained to support custom changes for [timecopilot](https://github.com/TimeCopilot/TimeCopilot/) and publish pypi wheels at [`timecopilot-tirex2`](https://pypi.org/project/timecopilot-tirex2/). It may diverge from upstream.

## Credits

This project is a fork of the original TiRex-2 authors.  
All credit for the original code belongs to them. This fork is maintained independently to support TimeCopilot-specific changes.

<h1 align="center">
  <img src="https://raw.githubusercontent.com/NX-AI/tirex-2/refs/heads/main/docs/images/tirex.svg" alt="TiRex emoji" height="48" /> TiRex-2: Generalizing TiRex to Multivariate Data and Streaming
</h1>

<div align="center">

[![Paper](https://img.shields.io/static/v1?label=Paper&message=2607.01204&color=B31B1B&logo=arXiv)](https://arxiv.org/abs/2607.01204)
[![Hugging Face](https://img.shields.io/badge/HuggingFace-TiRex--2-yellow?logo=huggingface)](https://huggingface.co/NX-AI/TiRex-2)
[![PyPI](https://img.shields.io/pypi/v/timecopilot-tirex2?color=blue)](https://pypi.org/project/timecopilot-tirex2/)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/timecopilot-tirex2?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/timecopilot-tirex2)
[![Docker](https://img.shields.io/badge/GHCR-tirex2--cpu%20%2F%20tirex2--gpu-2496ED?logo=docker&logoColor=white)](https://github.com/NX-AI/tirex-2/pkgs/container/tirex2-cpu)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
[![docs](https://img.shields.io/website?url=https%3A%2F%2Fnx-ai.github.io%2Ftirex-2%2F&label=docs&up_message=online&up_color=green&down_message=offline&down_color=red)](https://nx-ai.github.io/tirex-2/)
[![Tests](https://github.com/NX-AI/tirex-2/actions/workflows/test.yaml/badge.svg)](https://github.com/NX-AI/tirex-2/actions/workflows/test.yaml)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)
[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/NX-AI/tirex-2/blob/main/examples/getting_started.ipynb)
[![TiRex-2 Demo](https://img.shields.io/badge/HuggingFace-TiRex--2%20Demo-yellow?logo=huggingface)](https://huggingface.co/spaces/NX-AI/TiRex-2-demo)

</div>

This repository provides the pre-trained multivariate forecasting model TiRex-2 introduced in the paper [TiRex-2: Generalizing TiRex to Multivariate Data and Streaming](https://arxiv.org/pdf/2607.01204).

> **TiRex-2 Pro:** This repository is our open-source release. Our pro version extends TiRex-2 with streaming, hardware-optimized inference (edge, embedded, and industrial PCs, among others), finetuning, and classification & regression support — see [TiRex-2 Pro](#tirex-2-pro) below or contact us at [contact@nx-ai.com](mailto:contact@nx-ai.com).

## TiRex-2

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, built
on a recurrent architecture designed for efficient streaming settings — all zero-shot, with
no task-specific training or fine-tuning.

TiRex-2 generalizes our original univariate model, [TiRex](https://github.com/NX-AI/tirex), to
multivariate forecasting with past and future covariates.

## Key facts

- **Zero-shot multivariate forecasting**:
  TiRex-2 forecasts multiple target variates out of the box, without training or fine-tuning on your 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.

## Installation
### Via Pip
```bash
pip install timecopilot-tirex2
```

Install with additional dependencies:

```bash
pip install "timecopilot-tirex2[examples,fev,gluonts]"
```

The Python package installation is currently only tested on Linux and macOS. Docker usage is documented separately and includes Linux, macOS, and Windows Docker Desktop instructions.

### Via Pixi
We use [Pixi](https://pixi.prefix.dev/latest/) for our development and benchmarking environment to ensure that it is set up correctly. Run the following command to install it on your machine:
```bash
curl -fsSL https://pixi.sh/install.sh | sh
```

## Getting started

The most easy way for you to get started is by checking out our ["Getting Started" notebook](examples/getting_started.ipynb). Moreover, you can jump straight into testing out TiRex using [Google Colab](https://colab.research.google.com/github/NX-AI/tirex-2/blob/main/examples/getting_started.ipynb). If you have cloned this repository, you can also easily start the notebook via Pixi by running:
```bash
pixi run notebook
```
Note that for `pixi`, depending on your CUDA version and use-case, you may need to use another environment, e.g., `-e example-cu128`, that are defined in [pyproject.toml](pyproject.toml) under section `tool.pixi.environments`.

### Minimal usage predicting a simple sine wave
```python
import torch
from tirex2 import TimeseriesType, load_model
from tirex2.plotting import plot_multivariate  # requires matplotlib to be installed

# load model
model = load_model("NX-AI/TiRex-2", device="cpu")  # use `device="cuda"` if cuda is available

# generate data - target expects time series of shape (n_targets, context_length)
context = torch.sin(torch.arange(128).float() / 8)
ts = TimeseriesType(target=context.unsqueeze(0), past_covariates=None, future_covariates=None)

# perform forecast - each forecast is of shape (n_targets, 9 quantiles, prediction_length)
forecast = model.forecast([ts], prediction_length=32, output_type="numpy")[0]

# visualize result
fig = plot_multivariate(ts, forecast, engine="matplotlib")
fig.show()
```
![output of plot_multivariate function visualizing context and forecast](/resources/sine-wave-prediction.png)

### Covariate example
This example originates from the "Getting Started" notebook, showing the value of additional covariates.
```python
from tirex2 import load_model
from tirex2.demo import Demo, plot_demo_forecast

# load model
model = load_model("NX-AI/TiRex-2", device="cpu")  # use `device="cuda"` if cuda is available

# load data
demo = Demo.create_nonstationary_demo()
ts_univariate = demo.to_timeseries_type(include_covariates=False)
ts_multivariate = demo.to_timeseries_type(include_covariates=True)

# perform forecast - each forecast is of shape (n_targets, 9 quantiles, prediction_length)
forecasts = model.forecast(
    timeseries=[ts_univariate, ts_multivariate],
    prediction_length=demo.horizon,
    output_type="numpy",
)

# visualize result
fig = plot_demo_forecast(demo, *forecasts, engine="matplotlib")
fig.show()
```
![output of plot_multivariate function visualizing context and forecast of multivariate input](/resources/multivariate-prediction.png)



### Benchmarking
To reproduce our results for the [GIFT-Eval](https://huggingface.co/spaces/Salesforce/GIFT-Eval) and [fev-bench](https://huggingface.co/spaces/autogluon/fev-bench) leaderboards, follow the instructions in
[/examples/gifteval/](./examples/gifteval/README.md) and [/examples/fevbench/](./examples/fevbench/README.md), respectively.

## TiRex Docker image

For detailed instructions on building and running TiRex-2 in a Docker container, see the [Docker README](./inference/README.md).

## TiRex-2 Pro
TiRex-2 already provides state-of-the-art performance for zero-shot prediction, so you can use this open-source release without training on your own data.

Our pro version extends TiRex-2 with additional capabilities, including:

- **Streaming**: incremental forecast updates as new observations arrive, without recomputing over the full history.
- **Speed**: performance-optimized inference, including optimization for dedicated hardware such as edge, embedded, and industrial PC deployments.
- **Finetuning**: models fine-tuned on your data or with different pretraining.
- **Classification & Regression**: TiRex-2 adapted for classification and regression tasks.

If you are interested in any of these, please contact us at [contact@nx-ai.com](mailto:contact@nx-ai.com).

## Cite

If you use TiRex in your research, please cite our work:

```bibtex
@misc{podest2026tirex2generalizingtirexmultivariate,
      title={TiRex-2: Generalizing TiRex to Multivariate Data and Streaming},
      author={Patrick Podest and Marco Pichler and Elias Bürger and Levente Zólyomi and Bernhard Voggenberger and Wilhelm Berghammer and Daniel Klotz and Sebastian Böck and Günter Klambauer and Sepp Hochreiter},
      year={2026},
      eprint={2607.01204},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2607.01204},
}
```

## License

TiRex-2 is licensed under the [Apache License 2.0](./LICENSE).
