TS-Reasoner couples a frozen Time Series Foundation Model (TimesFM) with a Qwen2.5-7B LLM so the language model can reason over raw numerical time series. The TSFM's latent representations are aligned with the LLM's textual input space through a two-stage recipe: alignment pretraining on synthetic time series–caption pairs, followed by instruction finetuning.

📄 Paper: TS-Reasoner: Aligning Time Series Foundation Models with LLM Reasoning | 💻 Code: Yu-Fangxu/TS-Reasoner

Usage

Loading is self-contained — the model code automatically downloads and attaches the frozen TimesFM backbone (google/timesfm-1.0-200m-pytorch) on first use:

python

import numpy as np
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("ParadiseYu/TS-Reasoner-7B", trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    "ParadiseYu/TS-Reasoner-7B", trust_remote_code=True, torch_dtype=torch.float16
).to("cuda").eval()

Prompts contain one <ts><ts/> placeholder per series (preceded by a value-scaling prefix); the raw series are passed to generate via the timeseries= kwarg as a (num_series, length, 2) fp16 tensor of [scaled_value, mask] pairs. See demo.py in the code repository for a complete helper (load_ts_reasoner / ask) that handles the scaling, prompt assembly, and padding:

python

# git clone https://github.com/Yu-Fangxu/TS-Reasoner && cd TS-Reasoner
from demo import load_ts_reasoner, ask

tokenizer, model = load_ts_reasoner()
answer = ask(
    tokenizer, model,
    question="Time series 1: <ts><ts/>\nWhat is the overall trend?",
    timeseries=[[0.1, 0.3, 0.2, 0.5, 0.8, 1.2, 1.1, 1.6]],
)
print(answer)

Citation

bibtex

@article{yu2025tsreasoner,
  title={TS-Reasoner: Aligning Time Series Foundation Models with LLM Reasoning},
  author={Yu, Fangxu and Zhao, Hongyu and Zhou, Tianyi},
  journal={arXiv preprint arXiv:2510.03519},
  year={2025}
}