amaye15/tirex-gguf

TiRex (NXAI sLSTM) — GGUF

GGUF conversion of NX-AI's TiRex — a 35M parameter sLSTM-based zero-shot time-series forecasting model. Converted and run with **zsfm**, a Rust workspace that ports zero-shot forecasting and tabular foundation models to GGUF + candle. No PyTorch, no Python runtime required to run inference.

F16 is generally the best size/accuracy trade-off; Q8_0 is smallest. This repo's default recommendation matches the upstream conversion default: F32.

Context must be at least 32 timesteps (TiRex has no hard minimum (it left-pads short contexts internally), but 32 gives a meaningful example) — a shorter context fails with context too short. The examples below use a 32-value context.

Use it

Python (pip install zsfm)

pip install zsfm huggingface_hub

import zsfm
from huggingface_hub import hf_hub_download

gguf_path = hf_hub_download("amaye15/tirex-gguf", "tirex-f32.gguf")

model = zsfm.TirexModel(gguf_path)

context = [0.85, 0.93, 1.01, 1.09, 1.17, 1.25, 1.33, 1.06, 1.14, 1.22, 1.3, 1.38, 1.46, 1.54, 1.27, 1.35, 1.43, 1.51, 1.59, 1.67, 1.75, 1.48, 1.56, 1.64, 1.72, 1.8, 1.88, 1.96, 1.69, 1.77, 1.85, 1.93]
point = model.forecast(context, horizon=64)
# -> List[float], the median (q0.5) forecast

# full 9-quantile distribution (added in zsfm 0.2.7)
quantile_matrix = model.forecast_quantiles(context, horizon=64)  # 9 rows, one per level below
levels = model.quantiles()  # [0.1, 0.2, ..., 0.9] — quantile_matrix[i] is the level[i] forecast

Earlier versions of this card said forecast() returned TiRex's mean rather than its median — that was a misreading on our part of a confusingly-named internal Rust variable (literally called mean but always computed as the 0.5 quantile row). Verified in zsfm 0.2.7: forecast() output is byte-identical to forecast_quantiles()[4]. The variable has since been renamed for clarity; no numeric output changed.

Rust / CLI (cargo install zsfm)

cargo install zsfm --locked

# downloads the original weights and converts to GGUF locally
# (produces the same bytes as tirex-f32.gguf in this repo):
zsfm tirex convert --dtype f32 -o gguf/tirex-f32.gguf
echo '{"context": [0.85, 0.93, 1.01, 1.09, 1.17, 1.25, 1.33, 1.06, 1.14, 1.22, 1.3, 1.38, 1.46, 1.54, 1.27, 1.35, 1.43, 1.51, 1.59, 1.67, 1.75, 1.48, 1.56, 1.64, 1.72, 1.8, 1.88, 1.96, 1.69, 1.77, 1.85, 1.93], "horizon": 64}' \
  | zsfm tirex infer --gguf gguf/tirex-f32.gguf

-m/--model takes the full HuggingFace repo id (default NX-AI/TiRex) — there's only one published checkpoint for this architecture, so you normally don't need to change it. -o/--output defaults to gguf/tirex-f32.gguf regardless of --dtype, so always pass -o explicitly (as above) — otherwise repeated runs overwrite the same file under a name that may not even match the dtype you chose:

zsfm tirex convert --dtype f32 -o gguf/tirex-f32.gguf
zsfm tirex convert --dtype q8  -o gguf/tirex-q8.gguf

To skip conversion and run a file already published here:

huggingface-cli download amaye15/tirex-gguf tirex-f32.gguf --local-dir .
echo '{"context": [0.85, 0.93, 1.01, 1.09, 1.17, 1.25, 1.33, 1.06, 1.14, 1.22, 1.3, 1.38, 1.46, 1.54, 1.27, 1.35, 1.43, 1.51, 1.59, 1.67, 1.75, 1.48, 1.56, 1.64, 1.72, 1.8, 1.88, 1.96, 1.69, 1.77, 1.85, 1.93], "horizon": 64}' \
  | zsfm tirex infer --gguf tirex-f32.gguf

Source, the other 9 time-series forecasters + 5 tabular models, and full docs: [amaye15/zsfm-rs](https://github.com/amaye15/zsfm-rs).

Response format

{
  "id": "forecast-000001932b7a1234",
  "object": "forecast",
  "created": 1736290000,
  "model": "tirex",
  "choices": [{
    "index": 0,
    "forecast": {
      "point": [2.1, 2.3, 2.5],
      "quantiles": {
        "0.10": [1.8, 2.0, 2.2],
        "0.50": [2.1, 2.3, 2.5],
        "0.90": [2.4, 2.6, 2.8]
      }
    },
    "finish_reason": "stop"
  }],
  "usage": {"context_length": 32, "forecast_length": 64}
}

point is the median (q0.5); all 9 quantile levels (q0.10–q0.90) are included.

Pass a batch of series ("context": [[...], [...]]) for one choice per series.

Architecture

TiRex is a 35M parameter sLSTM-based time-series foundation model:

• —Input: Patch context of fixed length 2048 (left-padded with NaN if shorter), patch size 32 → 64 patches
• —Normalization: Per-series StandardScaler (non-causal mean/std over full context)
• —Patch embedding: ResidualBlock(64→2048→512) over concatenated [values | mask]
• —Backbone: 12 × sLSTM blocks (sequential recurrence over 64 tokens)
• —Pre-RMSNorm → 4 headwise-linear gate projections (NH=4, DH=128) → sLSTM cell → MultiHeadLayerNorm → residual
• —Pre-RMSNorm → SiLU gated FFN (512→1408→512) → residual
• —Output: ResidualBlock(512→2048→288) → 9 quantiles × 32 patch offsets per token
• —Decoding: AR loop: take last token's prediction, extend context with NaN, repeat

License

Conversion code: MIT (amaye15/zsfm-rs). Weights: NXAI Community License (not MIT, not a standard permissive license), per NX-AI/TiRex's LICENSE. Summary (not a substitute for reading the license itself):

• —Free to use, reproduce, and create derivative works of, including commercially, for most organizations.
• —If you redistribute the weights or a product built on them, you must include a copy of the license and display "Built with technology from NXAI".
• —If your organization's consolidated annual revenue exceeds €100,000,000 and you incorporate this model into a commercial product/service, you need a separate commercial license from NXAI.
• —Conversion code in amaye15/zsfm-rs is MIT; only the weights carry the NXAI license.