# google-research/timesfm architecture

> Architecture diagram of the GitHub repository google-research/timesfm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-research/timesfm
- Repository: https://github.com/google-research/timesfm
- Video tour (about a minute): https://gitdiagram.com/google-research/timesfm/video

## Overview

TimesFM is a pretrained time-series forecasting library with current 3.0 PyTorch and MLX inference, a 2.5 implementation, and archived 1.x/2.x code. The principal workflow configures or loads a forecaster, accepts time-series context (and, for 3.0, covariates), then returns forecasts and optional quantiles. The graph preserves documented model capabilities and major implementation branches; unsampled internals are represented only where the README or source index supports the component or relationship.

Main entry points: [`src/timesfm3/torch/model.py`](https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/model.py) (Torch model), [`v1/peft/finetune.py`](https://github.com/google-research/timesfm/blob/master/v1/peft/finetune.py) (Fine-tuning), [`src/timesfm3/mlx/model.py`](https://github.com/google-research/timesfm/blob/master/src/timesfm3/mlx/model.py) (MLX model), [`src/timesfm/timesfm_2p5/timesfm_2p5_base.py`](https://github.com/google-research/timesfm/blob/master/src/timesfm/timesfm_2p5/timesfm_2p5_base.py) (2.5 model definition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_v3["TimesFM 3.0"]
  node_v3api["Forecast API"]
  node_v3model["Torch model<br/>[model.py]"]
  node_v3transform["Transformer stack<br/>[transformer.py]"]
  node_v3refine["CPM RevIN"]
  node_v3config["Torch configuration<br/>[configs.py]"]
  node_mlxapi["MLX forecast API"]
  node_mlxmodel["MLX model<br/>[model.py]"]
  node_mlxtransform["MLX transformer<br/>[transformer.py]"]
  node_mlxconfig["MLX configuration<br/>[configs.py]"]
end

subgraph group_v25["TimesFM 2.5"]
  node_v25base["2.5 model definition"]
  node_v25torch["2.5 Torch backend"]
  node_v25flax["2.5 Flax backend"]
  node_v25config["2.5 configuration<br/>[configs.py]"]
  node_xreg25["2.5 XReg support<br/>[xreg_lib.py]"]
end

subgraph group_legacy["Archived Models"]
  node_legacyapi["Legacy model API<br/>[timesfm_base.py]"]
  node_legacydata["Legacy data loader<br/>[data_loader.py]"]
  node_legacyjax["Legacy JAX decoder<br/>[patched_decoder.py]"]
  node_legacytorch["Legacy Torch decoder"]
  node_legacyxreg["Legacy XReg<br/>[xreg_lib.py]"]
end

subgraph group_adapt["Adaptation"]
  node_finetune["Fine-tuning<br/>[finetune.py]"]
  node_lora["LoRA layers<br/>[lora_layers.py]"]
  node_dora["DoRA layers<br/>[dora_layers.py]"]
end

node_user(("Forecast caller"))

node_user -->|"requests forecast"| node_v3api
node_v3api -->|"invokes model"| node_v3model
node_v3model -->|"uses stack"| node_v3transform
node_v3model -->|"uses refinement"| node_v3refine
node_v3model -->|"reads config"| node_v3config
node_user -->|"requests forecast"| node_mlxapi
node_mlxapi -->|"uses model"| node_mlxmodel
node_mlxmodel -->|"uses stack"| node_mlxtransform
node_mlxmodel -->|"reads config"| node_mlxconfig
node_v25torch -->|"uses definition"| node_v25base
node_v25flax -->|"uses definition"| node_v25base
node_v25torch -->|"reads config"| node_v25config
node_v25flax -->|"reads config"| node_v25config
node_v25base -->|"uses covariates"| node_xreg25
node_legacyapi -->|"uses XReg"| node_legacyxreg
node_legacydata -->|"supplies training data"| node_finetune
node_finetune -->|"uses decoder"| node_legacyjax
node_finetune -->|"uses adapters"| node_lora
node_finetune -.->|"optional adapter"| node_dora

click node_v3api "https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/timesfm3_forecaster.py"
click node_v3model "https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/model.py"
click node_v3transform "https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/transformer.py"
click node_v3refine "https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/cpm_revin_refine.py"
click node_v3config "https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/configs.py"
click node_mlxapi "https://github.com/google-research/timesfm/blob/master/src/timesfm3/mlx/timesfm3_forecaster.py"
click node_mlxmodel "https://github.com/google-research/timesfm/blob/master/src/timesfm3/mlx/model.py"
click node_mlxtransform "https://github.com/google-research/timesfm/blob/master/src/timesfm3/mlx/transformer.py"
click node_mlxconfig "https://github.com/google-research/timesfm/blob/master/src/timesfm3/mlx/configs.py"
click node_v25base "https://github.com/google-research/timesfm/blob/master/src/timesfm/timesfm_2p5/timesfm_2p5_base.py"
click node_v25torch "https://github.com/google-research/timesfm/blob/master/src/timesfm/timesfm_2p5/timesfm_2p5_torch.py"
click node_v25flax "https://github.com/google-research/timesfm/blob/master/src/timesfm/timesfm_2p5/timesfm_2p5_flax.py"
click node_v25config "https://github.com/google-research/timesfm/blob/master/src/timesfm/configs.py"
click node_xreg25 "https://github.com/google-research/timesfm/blob/master/src/timesfm/utils/xreg_lib.py"
click node_legacyapi "https://github.com/google-research/timesfm/blob/master/v1/src/timesfm/timesfm_base.py"
click node_legacydata "https://github.com/google-research/timesfm/blob/master/v1/src/timesfm/data_loader.py"
click node_legacyjax "https://github.com/google-research/timesfm/blob/master/v1/src/timesfm/patched_decoder.py"
click node_legacytorch "https://github.com/google-research/timesfm/blob/master/v1/src/timesfm/pytorch_patched_decoder.py"
click node_legacyxreg "https://github.com/google-research/timesfm/blob/master/v1/src/timesfm/xreg_lib.py"
click node_finetune "https://github.com/google-research/timesfm/blob/master/v1/peft/finetune.py"
click node_lora "https://github.com/google-research/timesfm/blob/master/v1/src/adapter/lora_layers.py"
click node_dora "https://github.com/google-research/timesfm/blob/master/v1/src/adapter/dora_layers.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_v3api,node_v3model,node_v3transform,node_v3refine,node_v3config,node_mlxapi,node_mlxmodel,node_mlxtransform,node_mlxconfig toneBlue
class node_v25base,node_v25torch,node_v25flax,node_v25config,node_xreg25 toneAmber
class node_legacyapi,node_legacydata,node_legacyjax,node_legacytorch,node_legacyxreg toneMint
class node_finetune,node_lora,node_dora toneRose
class node_user toneIndigo
```

## Components

### TimesFM 3.0

- [Forecast API](https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/timesfm3_forecaster.py): `src/timesfm3/torch/timesfm3_forecaster.py`
- [Torch model](https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/model.py): `src/timesfm3/torch/model.py`
- [Transformer stack](https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/transformer.py): `src/timesfm3/torch/transformer.py`
- [CPM RevIN](https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/cpm_revin_refine.py): `src/timesfm3/torch/cpm_revin_refine.py`
- [Torch configuration](https://github.com/google-research/timesfm/blob/master/src/timesfm3/torch/configs.py): `src/timesfm3/torch/configs.py`
- [MLX forecast API](https://github.com/google-research/timesfm/blob/master/src/timesfm3/mlx/timesfm3_forecaster.py): `src/timesfm3/mlx/timesfm3_forecaster.py`
- [MLX model](https://github.com/google-research/timesfm/blob/master/src/timesfm3/mlx/model.py): `src/timesfm3/mlx/model.py`
- [MLX transformer](https://github.com/google-research/timesfm/blob/master/src/timesfm3/mlx/transformer.py): `src/timesfm3/mlx/transformer.py`
- [MLX configuration](https://github.com/google-research/timesfm/blob/master/src/timesfm3/mlx/configs.py): `src/timesfm3/mlx/configs.py`

### TimesFM 2.5

- [2.5 model definition](https://github.com/google-research/timesfm/blob/master/src/timesfm/timesfm_2p5/timesfm_2p5_base.py): `src/timesfm/timesfm_2p5/timesfm_2p5_base.py`
- [2.5 Torch backend](https://github.com/google-research/timesfm/blob/master/src/timesfm/timesfm_2p5/timesfm_2p5_torch.py): `src/timesfm/timesfm_2p5/timesfm_2p5_torch.py`
- [2.5 Flax backend](https://github.com/google-research/timesfm/blob/master/src/timesfm/timesfm_2p5/timesfm_2p5_flax.py): `src/timesfm/timesfm_2p5/timesfm_2p5_flax.py`
- [2.5 configuration](https://github.com/google-research/timesfm/blob/master/src/timesfm/configs.py): `src/timesfm/configs.py`
- [2.5 XReg support](https://github.com/google-research/timesfm/blob/master/src/timesfm/utils/xreg_lib.py): `src/timesfm/utils/xreg_lib.py`

### Archived Models

- [Legacy model API](https://github.com/google-research/timesfm/blob/master/v1/src/timesfm/timesfm_base.py): `v1/src/timesfm/timesfm_base.py`
- [Legacy data loader](https://github.com/google-research/timesfm/blob/master/v1/src/timesfm/data_loader.py): `v1/src/timesfm/data_loader.py`
- [Legacy JAX decoder](https://github.com/google-research/timesfm/blob/master/v1/src/timesfm/patched_decoder.py): `v1/src/timesfm/patched_decoder.py`
- [Legacy Torch decoder](https://github.com/google-research/timesfm/blob/master/v1/src/timesfm/pytorch_patched_decoder.py): `v1/src/timesfm/pytorch_patched_decoder.py`
- [Legacy XReg](https://github.com/google-research/timesfm/blob/master/v1/src/timesfm/xreg_lib.py): `v1/src/timesfm/xreg_lib.py`

### Adaptation

- [Fine-tuning](https://github.com/google-research/timesfm/blob/master/v1/peft/finetune.py): `v1/peft/finetune.py`
- [LoRA layers](https://github.com/google-research/timesfm/blob/master/v1/src/adapter/lora_layers.py): `v1/src/adapter/lora_layers.py`
- [DoRA layers](https://github.com/google-research/timesfm/blob/master/v1/src/adapter/dora_layers.py): `v1/src/adapter/dora_layers.py`

### Other components

- **Forecast caller**

## Connections

- Forecast caller → Forecast API: requests forecast
- Forecast API → Torch model: invokes model (evidence: `src/timesfm3/torch/timesfm3_forecaster.py`)
- Torch model → Transformer stack: uses stack (evidence: `src/timesfm3/torch/model.py`)
- Torch model → CPM RevIN: uses refinement (evidence: `src/timesfm3/torch/model.py`)
- Torch model → Torch configuration: reads config (evidence: `src/timesfm3/torch/model.py`)
- Forecast caller → MLX forecast API: requests forecast
- MLX forecast API → MLX model: uses model (evidence: `src/timesfm3/mlx/timesfm3_forecaster.py`)
- MLX model → MLX transformer: uses stack (evidence: `src/timesfm3/mlx/model.py`)
- MLX model → MLX configuration: reads config (evidence: `src/timesfm3/mlx/model.py`)
- 2.5 Torch backend → 2.5 model definition: uses definition (evidence: `src/timesfm/timesfm_2p5/timesfm_2p5_torch.py`)
- 2.5 Flax backend → 2.5 model definition: uses definition (evidence: `src/timesfm/timesfm_2p5/timesfm_2p5_flax.py`)
- 2.5 Torch backend → 2.5 configuration: reads config (evidence: `src/timesfm/timesfm_2p5/timesfm_2p5_torch.py`)
- 2.5 Flax backend → 2.5 configuration: reads config (evidence: `src/timesfm/timesfm_2p5/timesfm_2p5_flax.py`)
- 2.5 model definition → 2.5 XReg support: uses covariates (evidence: `src/timesfm/timesfm_2p5/timesfm_2p5_base.py`)
- Legacy model API → Legacy XReg: uses XReg (evidence: `v1/src/timesfm/timesfm_base.py`)
- Legacy data loader → Fine-tuning: supplies training data (evidence: `v1/peft/finetune.py`)
- Fine-tuning → Legacy JAX decoder: uses decoder (evidence: `v1/peft/finetune.py`)
- Fine-tuning → LoRA layers: uses adapters (evidence: `v1/peft/finetune.py`)
- Fine-tuning → DoRA layers: optional adapter
