Metadata-Version: 2.4
Name: tafsut
Version: 0.1.0
Summary: Probabilistic univariate time-series forecasting with Tafsut
Author: Tafsut-FM
Project-URL: Homepage, https://huggingface.co/Tafsut-FM/tafsut-univariate-base
Project-URL: Model, https://huggingface.co/Tafsut-FM/tafsut-univariate-base
Keywords: time-series,forecasting,probabilistic-forecasting,pytorch
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.1
Requires-Dist: numpy>=1.24
Requires-Dist: safetensors>=0.4
Requires-Dist: huggingface_hub>=0.24
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.7; extra == "visualization"
Dynamic: license-file

---
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`](https://huggingface.co/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.

```bash
pip install tafsut
```

For forecast visualization:

```bash
pip install "tafsut[visualization]"
```

With `uv`:

```bash
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

```python
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)`.

```python
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:

```text
(batch, horizon, quantile)
```

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

```text
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`:

```python
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:

```bash
pip install "tafsut[visualization]"
```

Then plot history and probabilistic forecasts:

```python
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:

```python
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:

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

Save a forecast visualization:

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

Or specify the model explicitly:

```bash
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:

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

This writes:

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

Reload it with the same API:

```python
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.

