The Problem
Many organizations need accurate, long‑horizon forecasts for irregular time‑series (e.g., sales, weather, sensor data) but building a custom model from scratch is costly and error‑prone. Existing libraries either lack pretrained large‑scale foundation models or require extensive feature engineering.
What This Does
timesfm delivers a decoder‑only, pretrained foundation model (TimesFM 2.5) that can be invoked directly from Python. The core implementation lives in src/timesfm/ with separate back‑ends:
Torch – src/timesfm/torch/transformer.py, dense.py, util.py expose the model as TimesFM2p5200Mtorch. Flax/JAX – src/timesfm/flax/transformer.py and related utilities provide the same architecture for GPU/TPU acceleration.
Model checkpoints are loaded via the Hugging‑Face hub (frompretrained). The timesfm-forecasting/ folder contains ready‑to‑run examples (anomaly detection, covariate forecasting, global‑temperature animation) that show end‑to‑end usage of the API.
How To Use It
Setup
Clone and enter repo git clone https://github.com/google-research/timesfm.git cd timesfm
Create an isolated env (the repo recommends uv)
uv venv source .venv/bin/activate
Install the package with the desired backend
uv pip install -e .[torch] # PyTorch backend or uv pip install -e .[flax] # JAX/Flax backend optional XReg support for covariates uv pip install -e .[xreg]
The pyproject.toml defines the optional extras (torch, flax, xreg).
Configuration
No runtime config files are required. Forecast parameters are passed via timesfm.ForecastConfig (see src/timesfm/configs.py). Example flags such as maxcontext, maxhorizon, and usecontinuousquantilehead are documented in the README and the class definition.
Running a Forecast
import numpy as np, torch, timesfm
model = timesfm.TimesFM2p5200Mtorch.frompretrained( "google/timesfm-2.5-200m-pytorch" )
model.compile( timesfm.ForecastConfig( maxcontext=1024, maxhorizon=256, normalizeinputs=True, usecontinuousquantilehead=True, forceflipinvariance=True, ) )
point, quant = model.forecast( horizon=12, inputs=[np.linspace(0, 1, 100), np.sin(np.linspace(0, 20, 67))], ) print(point.shape, quant.shape) # (2,12) (2,12,10)
For a full script, see timesfm-forecasting/examples/covariates-forecasting/democovariates.py.
Real‑World Use
A retail analytics pipeline could ingest daily sales data, call the above snippet nightly, and store the 12‑step point forecast together with 10‑quantile confidence bands in a data warehouse. Downstream dashboards would display both the median prediction and the prediction interval, enabling inventory planning with quantified risk.
Code Health & Issues
Low – Missing comprehensive test suite – Only v1/tests/test_timesfm.py exists; the newer src/ code lacks dedicated unit tests. Medium – Optional dependency drift – Extras (torch, flax, xreg) are not pinned in pyproject.toml; updates of PyTorch/JAX could introduce incompatibilities. Low – Documentation gaps – Docstrings in src/timesfm/* are sparse; users must rely on the example scripts for API details. Low – CI only validates basic lint – GitHub Actions (.github/workflows/main.yml) runs a generic CI but does not enforce type checking (e.g., mypy) or coverage thresholds. None – License present – LICENSE at repo root and in v1/ clarifies usage.
Overall, the repository builds cleanly, respects standard Python packaging, and includes CI, but the lack of systematic tests and pinned dependencies are the main risk factors.
The Bottom Line
timesfm provides a ready‑to‑use, pretrained time‑series foundation model with both PyTorch and Flax back‑ends, suitable for teams that need high‑quality forecasts without model development overhead. The codebase is well‑structured and installable, yet production adopters should add their own test coverage and verify backend compatibility before large‑scale deployment.