# jamesinza/timesfm architecture

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

- Interactive diagram: https://gitdiagram.com/jamesinza/timesfm
- Repository: https://github.com/jamesinza/timesfm

## Overview

TimesFM is a pretrained time-series forecasting library. Its primary workflow accepts one or more target series (and, in TimesFM 3.0, optional covariates), loads a pretrained checkpoint, runs a backend model, and returns forecasts and optional quantiles. The graph includes the documented MLX and TimesFM 2.5/XReg branches. Source excerpts are partial, so uncertain connections—especially for unsampled backends and archived versions—are not shown.

Main entry points: [`src/timesfm3/torch/model.py`](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/model.py) (Torch model), [`src/timesfm3/mlx/model.py`](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/mlx/model.py) (MLX model), [`src/timesfm3/torch/timesfm3_forecaster.py`](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/timesfm3_forecaster.py) (TimesFM 3 Torch API), [`v1/src/timesfm/timesfm_base.py`](https://github.com/jamesinza/timesfm/blob/master/v1/src/timesfm/timesfm_base.py) (Legacy forecasting API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Forecasting APIs"]
  node_torch_api["TimesFM 3 Torch API"]
  node_torch_eval["Batch evaluator<br/>[evaluator.py]"]
  node_mlx_api["TimesFM 3 MLX API"]
end

subgraph group_runtime["Model runtimes"]
  node_torch_model["Torch model<br/>[model.py]"]
  node_torch_transformer["Torch transformer<br/>[transformer.py]"]
  node_torch_dense["Torch dense layers<br/>[dense.py]"]
  node_torch_norm["Torch normalization<br/>[normalization.py]"]
  node_mlx_model["MLX model<br/>[model.py]"]
  node_mlx_transformer["MLX transformer<br/>[transformer.py]"]
  node_mlx_dense["MLX dense layers<br/>[dense.py]"]
  node_mlx_norm["MLX normalization<br/>[normalization.py]"]
  node_timesfm25_torch["TimesFM 2.5 Torch"]
  node_timesfm25_flax["TimesFM 2.5 Flax"]
end

subgraph group_extensions["Forecast extensions"]
  node_xreg["Covariate regression<br/>[xreg_lib.py]"]
end

subgraph group_archive["Archived runtime"]
  node_legacy_api["Legacy forecasting API<br/>[timesfm_base.py]"]
  node_legacy_torch["Legacy Torch model<br/>[timesfm_torch.py]"]
  node_legacy_jax["Legacy JAX model<br/>[timesfm_jax.py]"]
end

node_user(("Forecast caller"))
node_checkpoint["Model checkpoint"]

node_user -->|"requests forecast"| node_torch_api
node_torch_api -->|"loads weights"| node_checkpoint
node_torch_api -->|"runs inference"| node_torch_model
node_torch_model -->|"uses stack"| node_torch_transformer
node_torch_model -->|"uses layers"| node_torch_dense
node_torch_model -->|"normalizes"| node_torch_norm
node_user -->|"requests forecast"| node_mlx_api
node_mlx_api -->|"runs inference"| node_mlx_model
node_mlx_model -->|"uses stack"| node_mlx_transformer
node_mlx_model -->|"uses layers"| node_mlx_dense
node_mlx_model -->|"normalizes"| node_mlx_norm
node_user -->|"requests forecast"| node_timesfm25_torch
node_user -->|"requests forecast"| node_timesfm25_flax
node_user -.->|"supplies covariates"| node_xreg
node_user -->|"requests forecast"| node_legacy_api
node_legacy_api -.->|"selects backend"| node_legacy_torch
node_legacy_api -.->|"selects backend"| node_legacy_jax

click node_torch_api "https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/timesfm3_forecaster.py"
click node_torch_model "https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/model.py"
click node_torch_transformer "https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/transformer.py"
click node_torch_dense "https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/dense.py"
click node_torch_norm "https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/normalization.py"
click node_torch_eval "https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/evaluator.py"
click node_mlx_api "https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/mlx/timesfm3_forecaster.py"
click node_mlx_model "https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/mlx/model.py"
click node_mlx_transformer "https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/mlx/transformer.py"
click node_mlx_dense "https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/mlx/dense.py"
click node_mlx_norm "https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/mlx/normalization.py"
click node_timesfm25_torch "https://github.com/jamesinza/timesfm/blob/master/src/timesfm/timesfm_2p5/timesfm_2p5_torch.py"
click node_timesfm25_flax "https://github.com/jamesinza/timesfm/blob/master/src/timesfm/timesfm_2p5/timesfm_2p5_flax.py"
click node_xreg "https://github.com/jamesinza/timesfm/blob/master/src/timesfm/utils/xreg_lib.py"
click node_legacy_api "https://github.com/jamesinza/timesfm/blob/master/v1/src/timesfm/timesfm_base.py"
click node_legacy_torch "https://github.com/jamesinza/timesfm/blob/master/v1/src/timesfm/timesfm_torch.py"
click node_legacy_jax "https://github.com/jamesinza/timesfm/blob/master/v1/src/timesfm/timesfm_jax.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_torch_api,node_torch_eval,node_mlx_api toneBlue
class node_torch_model,node_torch_transformer,node_torch_dense,node_torch_norm,node_mlx_model,node_mlx_transformer,node_mlx_dense,node_mlx_norm,node_timesfm25_torch,node_timesfm25_flax toneAmber
class node_xreg toneMint
class node_legacy_api,node_legacy_torch,node_legacy_jax toneRose
class node_user,node_checkpoint toneIndigo
```

## Components

### Forecasting APIs

- [TimesFM 3 Torch API](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/timesfm3_forecaster.py): `src/timesfm3/torch/timesfm3_forecaster.py`
- [Batch evaluator](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/evaluator.py): `src/timesfm3/torch/evaluator.py`
- [TimesFM 3 MLX API](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/mlx/timesfm3_forecaster.py): `src/timesfm3/mlx/timesfm3_forecaster.py`

### Model runtimes

- [Torch model](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/model.py): `src/timesfm3/torch/model.py`
- [Torch transformer](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/transformer.py): `src/timesfm3/torch/transformer.py`
- [Torch dense layers](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/dense.py): `src/timesfm3/torch/dense.py`
- [Torch normalization](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/torch/normalization.py): `src/timesfm3/torch/normalization.py`
- [MLX model](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/mlx/model.py): `src/timesfm3/mlx/model.py`
- [MLX transformer](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/mlx/transformer.py): `src/timesfm3/mlx/transformer.py`
- [MLX dense layers](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/mlx/dense.py): `src/timesfm3/mlx/dense.py`
- [MLX normalization](https://github.com/jamesinza/timesfm/blob/master/src/timesfm3/mlx/normalization.py): `src/timesfm3/mlx/normalization.py`
- [TimesFM 2.5 Torch](https://github.com/jamesinza/timesfm/blob/master/src/timesfm/timesfm_2p5/timesfm_2p5_torch.py): `src/timesfm/timesfm_2p5/timesfm_2p5_torch.py`
- [TimesFM 2.5 Flax](https://github.com/jamesinza/timesfm/blob/master/src/timesfm/timesfm_2p5/timesfm_2p5_flax.py): `src/timesfm/timesfm_2p5/timesfm_2p5_flax.py`

### Forecast extensions

- [Covariate regression](https://github.com/jamesinza/timesfm/blob/master/src/timesfm/utils/xreg_lib.py): `src/timesfm/utils/xreg_lib.py`

### Archived runtime

- [Legacy forecasting API](https://github.com/jamesinza/timesfm/blob/master/v1/src/timesfm/timesfm_base.py): `v1/src/timesfm/timesfm_base.py`
- [Legacy Torch model](https://github.com/jamesinza/timesfm/blob/master/v1/src/timesfm/timesfm_torch.py): `v1/src/timesfm/timesfm_torch.py`
- [Legacy JAX model](https://github.com/jamesinza/timesfm/blob/master/v1/src/timesfm/timesfm_jax.py): `v1/src/timesfm/timesfm_jax.py`

### Other components

- **Forecast caller**
- **Model checkpoint**

## Connections

- Forecast caller → TimesFM 3 Torch API: requests forecast
- TimesFM 3 Torch API → Model checkpoint: loads weights
- TimesFM 3 Torch API → Torch model: runs inference
- Torch model → Torch transformer: uses stack
- Torch model → Torch dense layers: uses layers
- Torch model → Torch normalization: normalizes
- Forecast caller → TimesFM 3 MLX API: requests forecast
- TimesFM 3 MLX API → MLX model: runs inference
- MLX model → MLX transformer: uses stack
- MLX model → MLX dense layers: uses layers
- MLX model → MLX normalization: normalizes
- Forecast caller → TimesFM 2.5 Torch: requests forecast
- Forecast caller → TimesFM 2.5 Flax: requests forecast
- Forecast caller → Covariate regression: supplies covariates
- Forecast caller → Legacy forecasting API: requests forecast
- Legacy forecasting API → Legacy Torch model: selects backend
- Legacy forecasting API → Legacy JAX model: selects backend