google-research/timesfm

TimesFM (Time Series Foundation Model) is a pretrained time-series foundation model developed by Google Research for time-series forecasting.

TimesFM – A Foundation Model for Time‑Series Forecasting

What it is – TimesFM (Time Series Foundation Model) is a decoder‑only neural network trained on massive, diverse time‑series data. Google Research releases the model weights and a Python library so you can run zero‑shot forecasts (univariate or multivariate) and fine‑tune the model on your own data.

Why it matters – Like large language models for text, TimesFM is meant to be a general‑purpose forecaster that works out‑of‑the‑box on many domains (finance, energy, retail, etc.) without hand‑crafted feature engineering. The repo ships pretrained checkpoints (up to version 3.0) and code for inference, evaluation, and LoRA‑style fine‑tuning.

Key Highlights (as of the README)

Version 3.0 – native multivariate forecasting, support for past‑only and past‑and‑future dynamic covariates, and the best scores on the three major time‑series foundation‑model benchmarks (fev‑bench, TIME, GIFT‑Eval).
Model sizes – 330 M parameters for the main checkpoint; a lighter 200 M version (2.5) is also available.
Long context – up to 16 k tokens (2.5) and 15 360 tokens for the full model, enabling forecasts that consider long histories.
Quantile forecasts – optional 30 M head provides up to 1 000‑step quantile predictions (9 deciles by default).
Back‑ends – PyTorch (standard) and MLX (Apple‑silicon‑only) with numerically matched results.
Integration points – available in Google Cloud products (BigQuery ML, Vertex Model Garden) and even Google Sheets for end‑users.
Fine‑tuning – example scripts use HuggingFace Transformers + PEFT (LoRA) to adapt the model to a specific series.
Agent support – a markdown file (AGENTS.md) describes how to call TimesFM from autonomous agents.

Typical Use Cases

Domain	How TimesFM helps
Business forecasting (sales, demand, inventory)	Zero‑shot forecasts on new product lines; fine‑tune on historic sales to improve accuracy.
Energy & utilities	Multivariate load and price series with weather covariates can be forecast together.
Finance	Predict multiple asset price series while conditioning on macro‑economic covariates.
IoT / sensor data	Long‑window forecasting for equipment health monitoring.
Rapid prototyping	Plug‑and‑play via BigQuery ML or Sheets without writing code.

Getting Started (Python)

# Install the library (choose backend)
pip install "timesfm[torch]"      # PyTorch (CPU/GPU)
# or
pip install "timesfm[mlx]"        # Apple silicon, no PyTorch

import numpy as np
from timesfm3 import TimesFM3Evaluator, ModelConfig

cfg = ModelConfig(
    checkpoint_path="google/timesfm-3.0-pytorch",
    per_core_batch_size=32,
    device="cuda"               # or "cpu" / "mlx"
)
forecaster = TimesFM3Evaluator(cfg)

# Univariate example
ts = np.sin(np.linspace(0, 2*np.pi, 100)).astype(np.float32)
out = forecaster.predict_batch([ts], horizon=12, return_quantiles=True)[0]
print(out.forecast.shape)   # (12,)
print(out.quantiles.shape)  # (12, 9)

For multivariate series, pass a (num_variates, context_len) array and optional covariate arrays as shown in the README.

Fine‑tuning (LoRA) – quick sketch

# Clone the repo and install editable
git clone https://github.com/google-research/timesfm.git
cd timesfm
uv venv && source .venv/bin/activate
uv pip install -e .[torch]

# Example from timesfm-forecasting/examples/finetuning/
from transformers import AutoModelForCausalLM, Trainer, TrainingArguments
from peft import LoraConfig, get_peft_model

model = AutoModelForCausalLM.from_pretrained("google/timesfm-3.0-pytorch")
peft_cfg = LoraConfig(r=8, lora_alpha=32, target_modules=["c_attn"])
model = get_peft_model(model, peft_cfg)
# …prepare a Dataset of (context, target) pairs and run Trainer…

The repo includes a ready‑to‑run finetuning script and unit tests.

Licensing

Source code – Apache‑2.0 (free to use, modify, and redistribute).
Pre‑trained weights – Versions ≤ 2.5 are Apache‑2.0. Version 3.0 weights are released under a separate non‑commercial license (timesfm-non-commercial-license-v1.0), prohibiting commercial or production deployment without a separate agreement.

Limitations & Caveats

Commercial use restriction – The latest checkpoint (3.0) cannot be used in revenue‑generating products without a license from Google.
Hardware requirements – Full‑size 330 M model runs best on GPUs; the MLX backend is limited to Apple silicon.
Zero‑shot performance – While benchmark‑leading, domain‑specific data may still benefit from fine‑tuning.
Context truncation – Context longer than the model’s global_context (15 360 tokens) is automatically truncated, which may discard very long histories.
No official product support – The repository states it is “not an officially supported Google product,” so bug fixes and updates rely on the open‑source community.

Where to Find More

Paper: A decoder‑only foundation model for time‑series forecasting (ICML 2024) – https://arxiv.org/abs/2310.10688
Model hub: Hugging Face collection – https://huggingface.co/collections/google/timesfm-release-66e4be5fdb56e960c1e482a6
Blog: Google Research blog post (link in README) for high‑level motivation.
Docs & examples – timesfm-forecasting/ directory contains tutorials, agent skill docs, and unit tests.

Bottom line – TimesFM is a genuine, research‑grade foundation model for time‑series forecasting, offering both ready‑to‑use inference (via PyTorch or MLX) and a pathway to adapt the model to your own data. It is well‑documented, benchmark‑validated, and integrates with Google Cloud services, making it a solid option for anyone needing high‑quality forecasts across many domains.