tafsut-univariate-base

<div align="center"> <img src="assets/tafsut-icon.png" alt="Tafsut" width="96" height="96">

Tafsut Univariate Base

A ~105M-parameter transformer for zero-shot probabilistic forecasting

Quick start · Model details · Benchmarks · Limitations

GitHub · PyPI · pip install tafsut

</div>

---

<p align="center"> _{Zero-shot probabilistic forecasts across real-world time series.} </p>

---

Give the model a history of scalar observations and a horizon; it returns nine forecast quantiles (q0.1 through q0.9) for every future time step. That gives you a median forecast and an estimate of its uncertainty.

No manual download needed. The tafsut package fetches and caches these weights for you. Don't clone this repository or download model.safetensors by hand.

<div align="center"> </div>

---

Quick start

pip install tafsut

import numpy as np

from tafsut import TafsutModel, forecast


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

context = np.asarray(
    [10.2, 10.8, 11.1, 10.9, 11.5, 12.0],
    dtype=np.float32,
)

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

print(prediction.shape)
# torch.Size([1, 128, 9])

axis 0 → batch
axis 1 → forecast horizon
axis 2 → quantile

---

Model description

Tafsut Univariate Base is a univariate backbone patch-based transformer encoder for probabilistic forecasting.

Univariate. One channel of scalar observations per series; batches of independent series can be forecast together.

Zero-shot. Intended for direct use on new series, with no retraining or per-series fine-tuning.

Temporal patches. Observations are grouped into non-overlapping patches of 32 steps and embedded into the hidden dimension, so a full context becomes 32,768 / 32 = 1,024 patches — far cheaper than attending over every scalar value.

Transformer encoder. 14 blocks, each running RMS-style normalization → multi-head self-attention with rotary positional embeddings → residual, then normalization → feed-forward → residual. Attention uses torch.nn.functional.scaled_dot_product_attention where the installed PyTorch supports it, with an eager fallback.

Normalization. Per-series parameters computed from the visible context, with an arcsinh-based transformation enabled. Forecasts are mapped back to the original data scale before return — so pass raw values rather than standardizing each series yourself.

Probabilistic output. The model projects to nine quantiles rather than one deterministic value.

---

Model details

<details> <summary><b>Full architecture configuration</b></summary> <br>

Input patch stride: 32 Output patch size: 32 Activation: ReLU Dropout: 0.0 Normalization: RMSNorm-style normalization Position encoding: Rotary positional embeddings (RoPE), theta = 10,000 Attention backend: PyTorch SDPA, with eager fallback Arcsinh transform: enabled

`model.safetensors` is roughly 421 MB, consistent with ~105M float32 parameters.

</br> </details>

---

Benchmark performance

Evaluated on GIFT-Eval 23 datasets, 144,000 time series, 177M data points, 7 domains, 10 frequencies, and short- to long-term horizons across Econ/Fin, Energy, Healthcare, Nature, Sales, Transport, and Web/CloudOps.

Among the twelve models compared here, Tafsut places 3rd on CRPS (0.481) and 4th on MASE (0.693) at 105M parameters — ahead of several entries one to two orders of magnitude larger. Lower is better on both metrics.

---

Probabilistic forecasts

print(model.cfg.quantiles)
# (0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9)

For one series and a 128-step horizon, forecast() returns (1, 128, 9) — (batch, horizon, quantile).

q0.1–q0.9 spans a nominal 80% forecast interval. In library code, look the index up from model.cfg.quantiles instead of hard-coding it.

Any horizon. The output patch size is 32, but forecast() accepts arbitrary positive horizons: it forecasts in blocks and extends the context with the median forecast when more horizon is needed. No manual loop required.

---

Missing values

Encode gaps as np.nan and the validity mask is derived from the finite observations:

context = np.array([1.2, 1.4, np.nan, 1.8, 2.0], dtype=np.float32)

Or supply an explicit Boolean mask shaped like the context:

prediction = forecast(
    model,
    context,
    context_mask=mask,
    horizon=128,
)

---

Inputs and devices

forecast() accepts a numpy.ndarray or torch.Tensor of shape (T,) for one series or (B, T) for a batch, converts values to float32, and truncates over-long contexts to the most recent 32,768 observations.

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

Without an explicit device, the loader uses CUDA when PyTorch reports it available, otherwise CPU. It also accepts revision=, token=, cache_dir= and local_files_only=, and caches downloads through the standard Hugging Face cache.

forecast() currently returns its tensor on CPU. Validate with PyTorch:

import torch

finite = torch.isfinite(prediction).all().item()

Avoid calling np.isfinite() directly on the returned tensor — recent NumPy versions may emit array-protocol deprecation warnings.

---

Visualization

pip install "tafsut[visualization]"

from tafsut.visualization import plot_forecast

fig, ax = plot_forecast(
    context,
    prediction,
    model.cfg.quantiles,
    target=future,
    history_length=384,
    title="Tafsut forecast",
)

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

The plot shows observed history, the forecast origin, the median prediction, central quantile bands, and optional observed future values. save_forecast_plot writes a figure directly to a file.

---

Limitations

• Univariate only. This release is a univarite backbone with no covariates, exogenous variables, or cross-series structure.
• Bounded context. Inputs beyond 32,768 steps are truncated to their most recent portion.
• Extended horizons. Past the configured prediction length of 1,024, forecasts are produced by feeding the median back as context, so they are conditioned on the model's own median continuation.
• Inference-focused release. Training scripts, optimizer and scheduler state, and training checkpoint metadata are not included.
• Benchmark scope. The results above cover GIFT-Eval only, against the twelve models compared, at a single point in time.

---

Training data and methodology

The model was trained in two stages:

1. Synthetic pretraining: approximately 40 million in-house generated synthetic time series.
2. Real-world post-training: approximately 30 million real-world time series drawn from the GIFT-Eval pretraining corpus and the Chronos pretraining dataset.

To prevent benchmark contamination, any time series overlapping with the evaluation benchmark were excluded from the training data.

---

License

This project is released under the MIT License. The full license is available in the LICENSE file and is reproduced below for convenience:

MIT License

Copyright (c) 2026 Tafsut-FM

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

<div align="center"> </div>