---

library_name: pytorch pipeline_tag: time-series-forecasting tags:

• time-series
• forecasting
• probabilistic-forecasting
• pytorch

---

Tafsut Univariate Base

Tafsut is a probabilistic model for univariate time-series forecasting. The pretrained base model is hosted at Tafsut-FM/tafsut-univariate-base and can be loaded directly from Python without cloning the model repository.

Installation

Tafsut requires Python 3.10 or newer.

pip install tafsut

For forecast visualization:

pip install "tafsut[visualization]"

With uv:

uv venv --python 3.11 .venv
uv pip install --python .venv/bin/python "tafsut[visualization]"

GPU users: PyTorch must be compatible with the NVIDIA driver on the target machine. If the default PyTorch installation does not match your CUDA environment, install the appropriate PyTorch build for your system before installing Tafsut.

Load the pretrained model

import torch
from tafsut import TafsutModel

device = "cuda" if torch.cuda.is_available() else "cpu"

model = TafsutModel.from_pretrained(
    "Tafsut-FM/tafsut-univariate-base",
    device=device,
)

from_pretrained() downloads config.json and model.safetensors from the Hugging Face Hub and uses the standard Hugging Face cache. A local model directory can also be passed instead of a Hub repository ID.

Forecast

The high-level forecast() helper accepts a single series with shape (T,) or a batch with shape (B, T).

import numpy as np
from tafsut import TafsutModel, forecast

model = TafsutModel.from_pretrained(
    "Tafsut-FM/tafsut-univariate-base",
    device="cpu",
)

context = np.asarray(
    [1.0, 1.2, 1.1, 1.4, 1.5, 1.7],
    dtype=np.float32,
)

pred = forecast(
    model,
    context,
    horizon=128,
)

print(pred.shape)          # (1, 128, 9)
print(model.cfg.quantiles) # (0.1, ..., 0.9)

The returned tensor has shape:

(batch, horizon, quantile)

For tafsut-univariate-base, the released quantiles are:

0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9

If a requested horizon is longer than one native prediction block, forecast() continues autoregressively using the median forecast as feedback.

Missing observations

Missing historical values can be represented with NaN:

context = np.asarray(
    [1.0, 1.2, np.nan, 1.4, 1.5],
    dtype=np.float32,
)

pred = forecast(model, context, horizon=64)

An explicit boolean context_mask can also be supplied to forecast() when needed.

Visualization

Install the optional visualization dependency:

pip install "tafsut[visualization]"

Then plot history and probabilistic forecasts:

from tafsut import plot_forecast

fig, ax = plot_forecast(
    context,
    pred,
    model.cfg.quantiles,
    history_length=256,
)

fig.savefig(
    "forecast.png",
    dpi=160,
    bbox_inches="tight",
)

To overlay observed future values:

fig, ax = plot_forecast(
    context,
    pred,
    model.cfg.quantiles,
    target=observed_future,
)

The plot uses the median forecast as the central prediction and shades available central quantile intervals.

Command-line inference

Installing Tafsut provides the tafsut-forecast command. The model repository defaults to Tafsut-FM/tafsut-univariate-base.

From a NumPy file:

tafsut-forecast \
  --context-file series.npy \
  --horizon 128

Save a forecast visualization:

tafsut-forecast \
  --context-file series.npy \
  --horizon 128 \
  --plot-output forecast.png

Or specify the model explicitly:

tafsut-forecast \
  --model Tafsut-FM/tafsut-univariate-base \
  --context-file series.npy \
  --horizon 128

The context file may be .npy or .json.

Save locally

A loaded model can be saved as a local pretrained directory:

model.save_pretrained("./tafsut-local")

This writes:

tafsut-local/
├── config.json
└── model.safetensors

Reload it with the same API:

model = TafsutModel.from_pretrained("./tafsut-local")

Base model configuration

The published tafsut-univariate-base model uses:

Setting	Value
Context length	32,768
Default prediction length	1,024
Patch size	32
Quantiles	9
Model dimension	768
Encoder layers	14
Attention heads	12

The forecast() helper can request horizons shorter or longer than the configured default prediction length.