The Problem

Time‑series teams need a high‑capacity pretrained model that can be fine‑tuned or used out‑of‑the‑box for short‑ and long‑horizon forecasts, but building such a model from scratch is expensive and error‑prone.

What This Does

The repository ships the TimesFM 2.5 decoder‑only foundation model with both PyTorch and Flax/JAX back‑ends. Core model code lives in src/timesfm/torch/ and src/timesfm/flax/; the higher‑level API is exposed through src/timesfm/__init__.py (e.g. TimesFM_2p5_200M_torch). Example notebooks (v1/notebooks/finetuning_torch.ipynb) and the timesfm-forecasting/examples/ scripts demonstrate end‑to‑end forecasting, including covariate handling via src/timesfm/utils/xreg_lib.py.

How It Is Wired

  • Entry point – a typical run starts at a script such as timesfm-forecasting/examples/anomaly-detection/detect_anomalies.py (line 391 defines main). The function calls the public forecast method (via TimesFM_2p5_200M_torch.forecast).
  • Core call chain – forecast → forecast_with_covariates → fit → _to_padded_jax_array (4 calls) and forecast → decode → revin (8 calls). The most‑fan‑in functions are forecast (called from 8 places) and revin (5 places).
  • Data flow – forecast consumes NumPy arrays, builds a covariate matrix (create_covariate_matrix → _unnest, _repeat), and ultimately invokes the transformer decoder (src/timesfm/torch/transformer.py).
  • File system touches – the only external I/O observed from the entry point is plot_results which creates OUTPUT_DIR via mkdir. Scripts under timesfm-forecasting/scripts/ also read/write CSVs (forecast_csv.py).
  • High‑impact modules – v1/src/timesfm/pytorch_patched_decoder.py (33 functions, 9 classes) and v1/src/timesfm/timesfm_base.py (17 functions, 3 classes) are called from many other files; changes here have the widest blast radius.
  • No circular imports – the static import graph contains 49 internal modules with 20 edges and zero cycles, simplifying refactoring.

How To Use It

# Clone the repo (exact URL required)
git clone https://github.com/moses-y/timesfm.git
cd timesfm

# Create a venv and install the desired backend (requires poetry or uv)
uv venv
source .venv/bin/activate
uv pip install -e .[torch]   # or .[flax] / .[xreg] as needed

No additional environment variables are required; the model is fetched from Hugging Face on first call.

Run an example:

python timesfm-forecasting/examples/anomaly-detection/detect_anomalies.py

Or forecast a CSV:

python timesfm-forecasting/scripts/forecast_csv.py \
    --model google/timesfm-2.5-200m-pytorch \
    --input data.csv \
    --output forecast.csv

Real‑World Use

A monitoring service can stream recent sensor readings into a NumPy array, call TimesFM_2p5_200M_torch.from_pretrained(...) and invoke model.forecast(horizon=24, inputs=[sensor_series]). The returned point and quantile forecasts can be stored in a time‑series database for downstream alerting.

Code Health & Issues

  • HIGH – Pinned vulnerable dependencies (e.g. idna@3.10, click@8.3.0, filelock@3.19.1). Upgrade to fixed versions.
  • HIGH – Absolute path in v1/notebooks/finetuning.ipynb. Replace with repo‑relative paths.
  • HIGH – No lockfile accompanies pyproject.toml. Generate and commit a poetry.lock.
  • MEDIUM – GitHub Actions lack least‑privilege GITHUB_TOKEN permissions. Add permissions: contents: read.
  • MEDIUM – No automated dependency update bot. Add dependabot.yml.
  • MEDIUM – No CI step runs a dependency‑vulnerability scan. Insert dependency-review-action or osv-scanner.
  • MEDIUM – Checkout step keeps credentials; set persist-credentials: false.
  • MEDIUM – Test coverage is low (1 test file vs. 42 source files). Add unit tests for high‑fan‑in modules (forecast, revin).
  • LOW – Workflow jobs lack timeout-minutes. Define reasonable limits.

Additional observations: the repository includes a license, CI config, and documentation files, but no Dockerfile for containerized deployment.

The Bottom Line

TimesFM provides a ready‑to‑use pretrained transformer for time‑series forecasting with clear PyTorch/Flax APIs and useful example scripts. The codebase is modestly sized, well‑structured, and free of circular imports, but it ships vulnerable dependency pins, missing lockfiles, and limited test coverage. Teams comfortable adding their own CI hardening and expanding tests can adopt it quickly for production forecasting workloads.