README.md

---
title: TimeBraid
emoji: 🧵
colorFrom: indigo
colorTo: gray
sdk: gradio
sdk_version: 5.50.0
app_file: app.py
short_description: Understand and forecast time series with language
python_version: "3.12"
startup_duration_timeout: 1h
pinned: false
---

# TimeBraid

Interactive demo for **TimeBraid-2.5B** — *Unifying Time Series and Language for
Understanding and Forecasting*.

- Paper: <https://huggingface.co/papers/2609.29792>
- Model: [`XinyueWangg/TimeBraid-2.5B`](https://huggingface.co/XinyueWangg/TimeBraid-2.5B)
- Code: <https://github.com/CharonWangg/TimeBraid>

TimeBraid braids a Qwen3-1.7B language backbone with a TimesFM 2.5 time-series
expert through an interleaved Mixture-of-Transformers, so numeric series and text
live in the same token stream. The same numbers can therefore be read very
differently depending on the context you give them.

## How to use it

1. **Paste one series per line** — comma-separated numbers. One line = one
   series; two lines = two related series the model can compare or choose
   between.
2. **Write your question or instruction.** Ask for an explanation of the
   observed data, or ask for future values.
3. **Set the forecast horizon.** `0` keeps the run in *understanding* mode and
   the model answers in words. A positive `N` switches to *forecasting* and the
   model returns `N` future values for one target series, plotted against the
   history.
4. Textual context matters for forecasts: describing an upcoming promotion, a
   heatwave, or a school term materially changes the predicted numbers.

Advanced options hold an optional system prompt, a 1-based selector for which
input series to forecast, and the text-generation budget.

## Implementation notes

- Runs on ZeroGPU with the full BF16 checkpoint resident on the GPU.
- The checkpoint vendors its own `timebraid` inference package, loaded through
  `trust_remote_code=True`; no separate TimesFM checkpoint is required.
- MoT mixed attention in TimeBraid is FlashAttention-2 only, and FA3/FA4 have no
  sm_120 kernels, so the Space installs the prebuilt Blackwell FA2 wheel.
- Decoding follows the released recipe: greedy (`do_sample=False`), one
  returned sequence, one request at a time.

## Attribution

The example requests in the UI are the illustrative tasks from the TimeBraid
model card and the authors' `examples/inference_tasks.ipynb` (Apache-2.0).