google-research/timesfm

This system is a Python library for time series forecasting that implements the TimesFM foundation model across versions 1, 2.5, and 3.0. It provides inference and fine-tuning capabilities via PyTorch, Flax, and MLX backends, supporting both univariate and multivariate forecasting with exogenous covariates. The codebase includes utilities for data handling, configuration, and benchmarking, along with examples for zero-shot prediction and parameter-efficient adaptation.

7 changes.

This period focused on expanding the TimesFM framework to support versions 2.5 and 3.0, introducing initial implementations for both PyTorch and Flax backends alongside a new MLX backend for Apple Silicon. The work included migrating the project to a standard pyproject.toml structure, adding in-context regression utilities for exogenous covariates, and resolving critical data loading and leakage issues in the legacy v1 release.

6 changes.

This period focused on introducing the TimesFM 3.0 model with dedicated PyTorch and Apple Silicon (MLX) inference backends, ensuring architectural parity and backward-compatible imports. It also added the TimesFM 2.5 forecasting skill with covariate support and fine-tuning capabilities, alongside comprehensive unit tests and benchmark documentation for both versions.

A new \xreg\_lib.py\ module has been added to \src/timesfm/utils\ to support in-context regression with exogenous covariates. This utility provides helper functions for normalizing time series data and a \BatchedInContextXRegBase\ class that formats dynamic (numerical and categorical) and static covariates for both the training context and the forecast horizon, enabling users to incorporate external variables into their time series forecasts.

src/timesfm/utils · high confidence

This change introduces a new MLX-based inference backend for TimesFM 3.0, enabling native execution on Apple Silicon hardware. The implementation provides a drop-in compatible \TimesFM3Forecaster\ that mirrors the PyTorch interface, supporting univariate and multivariate forecasting with past-only and past-future covariates. It includes full architectural parity with the PyTorch backend—covering stitching, iterative CPM RevIN refinement, linear detrending, and various activation and normalization modes—while adding MLX-specific optimizations like graph compilation for reduced latency. The backend gracefully handles missing MLX installations on non-mac platforms and rejects checkpoints requiring frozen running stats, which are not yet implemented.

src/timesfm3/mlx · high confidence

This change introduces the core Flax (NNX) implementation for the TimesFM model, adding new source files for dense layers (ResidualBlock, RandomFourierFeatures), normalization (RMSNorm, LayerNorm), and transformer components (RotaryPositionalEmbedding, MultiHeadAttention). It also includes utility functions for decoding caches, running statistics, and reversible instance normalization (ReVIN). This represents the initial push of the Flax model architecture into the codebase.

src/timesfm/flax · high confidence

This change introduces the initial PyTorch-based implementation of the TimesFM architecture, adding core modules for dense layers (including residual blocks and random Fourier features), normalization (RMSNorm), and transformer layers (including multi-head attention with rotary positional embeddings and fused attention kernels). It also includes utility functions for decoding caches, running statistics, and reversible instance normalization (ReVIN), enabling users to run TimesFM models using PyTorch.

src/timesfm/torch · high confidence

Adds the TimesFM 2.5 (200M parameter) model implementation, providing framework-specific modules for both Flax and PyTorch alongside a shared base configuration. This change introduces the core architecture—including tokenizers, stacked transformers, and output projections—along with the necessary inference logic for point and quantile forecasting, establishing the foundation for the 2.5 version of the model.

_src/timesfm/timesfm\2p5 · high confidence

This change introduces a new 'timesfm-forecasting' skill that enables zero-shot time series forecasting using Google's TimesFM foundation model. The skill includes a mandatory preflight system checker to verify hardware requirements (RAM, GPU, disk) before loading the model, which defaults to the more efficient TimesFM 2.5 (200M parameters) but supports older versions. It provides examples for basic forecasting, anomaly detection using quantile prediction intervals, and covariate forecasting (XReg) with dynamic and static exogenous variables like price, promotions, and holidays. Additionally, it includes a fine-tuning example using HuggingFace Transformers and PEFT (LoRA) for parameter-efficient adaptation to specific domains like retail sales.

timesfm-forecasting · high confidence

The \src/timesfm\ package now exposes TimesFM 2.5 models for both PyTorch and Flax, alongside TimesFM 3.0 support. Users can import \TimesFM\_2p5\_200M\_torch\ and \TimesFM\_2p5\_200M\_flax\ directly from the package root, with graceful fallbacks if the respective frameworks are not installed. Additionally, \ForecastConfig\ is now available for configuring forecasting parameters, and the legacy JAX/PyTorch version selection logic has been replaced by these explicit framework-specific imports.

src/timesfm · high confidence

The \timesfm3-usage\ directory now includes documentation and evaluation results for TimesFM 3.0. This update adds a README for the benchmarks directory and specific documentation for the AutoGluon FEV-Bench, which evaluates the model on 100 tasks. Additionally, a CSV file containing the results of these evaluations has been added, detailing performance metrics such as MASE, WAPE, and WQL across various datasets including retail, energy, and weather data.

timesfm3-usage · high confidence

The TimesFM3 PyTorch backend is now available as a dedicated \torch/\ subpackage, providing a complete inference implementation of the TimesFM3 model. This includes the core \TimesFM3Torch\ model class, a \TimesFM3Forecaster\ API for high-level forecasting, and a specialized \TimesFM3Evaluator\ for benchmark evaluation with automatic variate chunking. The package also introduces iterative RevIN refinement for CPM-masked patches, framework-agnostic configuration dataclasses, and PyTorch-native layers for dense blocks, normalization, and transformations, all accompanied by comprehensive unit tests.

src/timesfm3/torch · high confidence

The TimesFM3 PyTorch implementation has been moved into a dedicated \\timesfm3.torch\\ subpackage, while the top-level \\timesfm3\\ namespace now lazily re-exports key classes (such as \\TimesFM3Forecaster\\ and \\TimesFM3Torch\\) to ensure existing import paths continue to work without breaking changes. This structural change improves modularity by separating the PyTorch backend from the MLX (Apple Silicon) backend, and includes a comprehensive test suite to verify that legacy import patterns remain fully functional.

src/timesfm3 · high confidence

This update addresses four specific issues in the v1 release of TimesFM. First, the data loader now correctly respects the \batch\_size\ parameter when \permute=False\, ensuring that training batches are sliced by the specified size rather than processing all time series at once. Second, the masked mean and standard deviation calculation in the patched decoder (both JAX and PyTorch backends) has been replaced with a numerically stable centered-variance approach, and the standard deviation floor is now enforced via clamping rather than conditional replacement. Third, the external regressor (\xreg\) logic has been refactored to perform per-input ridge regression normalization and fitting; this prevents data leakage that previously occurred when batch-wide normalization and a single global regression model were applied to multiple independent time series. Finally, the JAX version dependency has been updated to ensure compatibility.

v1 · high confidence

New test files have been added to the tests directory to cover key parts of the TimesFM 2.5 implementation. This includes tests for base utilities like NaN handling and linear interpolation, configuration dataclasses (ForecastConfig, TransformerConfig, etc.) to ensure immutability and correct defaults, PyTorch layer blocks (ResidualBlock, RMSNorm, RandomFourierFeatures), and utility functions for running statistics and RevIN normalization. Additionally, tests verify model loading behavior (including torch\_compile integration) and the force\_flip\_invariance property in autoregressive outputs.

tests · high confidence

The main package manifest has migrated from Poetry to the standard pyproject.toml format (using setuptools), bumping the version to 3.0.2 and simplifying core dependencies to numpy, huggingface\_hub, and safetensors. This change introduces a new optional MLX backend for Apple Silicon devices and reorganizes optional dependencies for Torch, Flax, and xreg. Additionally, a new v1 subdirectory now contains a separate Poetry-based configuration for the legacy 1.3.0 version, and a generated requirements.txt is included for compatibility.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 59.

• Code Health 86
• Architecture 97
• Maturity 71
• Readiness 49
• Security 57

• 300 commits — 256 feature/other, 44 fixes

• (repo) — 87 commits
• (root) — 78 commits
• src/timesfm — 43 commits
• src/timesfm3 — 26 commits
• .github/workflows — 15 commits
• notebooks/finetuning_example.py — 7 commits
• src/adapter — 5 commits
• v1/src — 4 commits
• notebooks/finetuning_torch.ipynb — 3 commits
• peft/finetune.py — 3 commits
• src/finetuning — 3 commits
• src/timesfm_torch — 3 commits
• peft/README.md — 2 commits
• peft/fft.sh — 2 commits
• timesfm-forecasting/examples — 2 commits
• claude-skill/examples — 1 commit
• experiments/extended_benchmarks — 1 commit
• experiments/long_horizon_benchmarks — 1 commit
• notebooks/covariates.ipynb — 1 commit
• notebooks/finetuning_torch.py — 1 commit

• fix: Revert "Merge pull request #130 from google-research/rajat_dev"
• fix: Fix TimesFM3 KV cache indexing for batched decoding
• fix: Fix Wandb errro
• fix: Fix import in notebook
• fix: Fix model loading issues and forecast_naive slicing bug in TimesFM 2.5
• fix: Fix the data function
• fix: Merge pull request #243 from misha-chertushkin/notebook-import-fix
• fix: Merge pull request #247 from misha-chertushkin/fix-finetuning-package
• fix: Merge pull request #310 from ram-from-tvl/fix/remove-lingvo
• fix: Merge pull request #463 from winklemad/fix/flip-invariance-ar-quantiles
• fix: Merge pull request #483 from LngelKyo/fix/pf-covariate-window-alignment
• fix: Merge pull request #492 from devendrasinghjodha/fix-kv-cache-batch-indexing
• fix: Merge pull request #494 from devendrasinghjodha/fix/reject-invalid-swiglu
• fix: Merge pull request #509 from matdou/mlx-torch-parity-fix
• fix: Merge pull request #510 from matdou/fix-weights-cached-stale-ref
• fix: Quantiles PR nit fix
• fix: Small fix with default value
• fix: Style fix
• fix: bug fix
• fix: fix docs string
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

google-research/timesfm was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.