# ibm-granite/granite-tsfm architecture

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

- Interactive diagram: https://gitdiagram.com/ibm-granite/granite-tsfm
- Repository: https://github.com/ibm-granite/granite-tsfm

## Overview

TSFM is a public time-series foundation-model library with companion inference and fine-tuning services, examples, and demos. A typical forecasting flow takes tabular time-series input through preprocessing and dataset construction into a forecasting pipeline and model, producing forecasts. The toolkit also supports anomaly detection, classification, imputation, conformal methods, and model utilities; separate service paths load models for inference or tuning. Edges are limited to relationships visible in the supplied excerpts, SOURCE INDEX references, or README; many notebook and model-family details were not sampled.

Main entry points: [`tsfm_public/toolkit/time_series_forecasting_pipeline.py`](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/time_series_forecasting_pipeline.py) (Forecasting Pipeline), [`tsfm_public/toolkit/dataset.py`](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/dataset.py) (Dataset Builders), [`services/inference/tsfminference/service_handler.py`](https://github.com/ibm-granite/granite-tsfm/blob/main/services/inference/tsfminference/service_handler.py) (Inference Service API), [`services/finetuning/tsfmfinetuning/service_handler.py`](https://github.com/ibm-granite/granite-tsfm/blob/main/services/finetuning/tsfmfinetuning/service_handler.py) (Fine-Tuning Service API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_models["Foundation Models"]
  node_ttm["TinyTimeMixer"]
  node_ttm_config["TTM Configuration"]
  node_tspulse["TSPulse"]
  node_tspulse_config["TSPulse Configuration"]
  node_patchtst["PatchTST-FM Components<br/>[basic.py]"]
  node_flowstate["FlowState"]
end

subgraph group_toolkit["Time-Series Toolkit"]
  node_preprocessor["Time-Series Preprocessor"]
  node_dataset["Dataset Builders<br/>[dataset.py]"]
  node_forecast["Forecasting Pipeline"]
  node_anomaly["Anomaly Pipeline"]
  node_classification["Classification Pipeline"]
  node_imputation["Imputation Pipeline"]
  node_conformal["Conformal Processing<br/>[conformal.py]"]
  node_model_loading["Model Loading<br/>[get_model.py]"]
  node_service_config["Service Model Config<br/>[tsfm_config.py]"]
end

subgraph group_inference["Inference Service"]
  node_infer_api["Inference Service API<br/>[service_handler.py]"]
  node_infer_payload["Inference Payloads"]
  node_infer_handler["Forecasting Inference Handler"]
end

subgraph group_finetuning["Fine-Tuning Service"]
  node_tune_api["Fine-Tuning Service API<br/>[service_handler.py]"]
  node_tune_payload["Tuning Payloads"]
  node_tune_handler["Forecasting Tuning Handler"]
end

subgraph group_examples["Examples and Demos"]
  node_acas_demo["Adaptive Conformal TSAD<br/>[main_acas_w1.py]"]
  node_ttm_benchmark["TTM Benchmarking"]
  node_neurips_demo["NeurIPS Demo<br/>[app.py]"]
end

node_user(("Data User"))
node_model_hub(("Hugging Face Models"))

node_user -->|"submits series"| node_forecast
node_forecast -->|"uses preprocessing"| node_preprocessor
node_forecast -->|"builds batches"| node_dataset
node_forecast -->|"supports calibration"| node_conformal
node_anomaly -->|"uses forecasting"| node_forecast
node_anomaly -->|"uses datasets"| node_dataset
node_classification -->|"uses datasets"| node_dataset
node_classification -->|"reuses pipeline"| node_forecast
node_imputation -->|"uses datasets"| node_dataset
node_imputation -->|"reuses pipeline"| node_forecast
node_ttm -->|"uses config"| node_ttm_config
node_tspulse -->|"uses config"| node_tspulse_config
node_model_hub -->|"provides pretrained models"| node_ttm
node_model_hub -->|"provides pretrained models"| node_tspulse
node_model_hub -->|"provides pretrained models"| node_patchtst
node_model_hub -->|"provides pretrained models"| node_flowstate
node_user -->|"requests inference"| node_infer_api
node_infer_api -->|"validates payload"| node_infer_payload
node_infer_api -->|"dispatches inference"| node_infer_handler
node_infer_api -->|"loads configuration"| node_service_config
node_infer_handler -->|"constructs preprocessor"| node_preprocessor
node_infer_handler -->|"uses calibration"| node_conformal
node_user -->|"requests tuning"| node_tune_api
node_tune_api -->|"uses payload types"| node_tune_payload
node_tune_api -->|"dispatches tuning"| node_tune_handler
node_tune_api -->|"loads configuration"| node_service_config
node_tune_handler -->|"uses preprocessing"| node_preprocessor
node_tune_handler -->|"builds training data"| node_dataset
node_tune_handler -->|"uses learning-rate finder"| node_model_loading
node_user -->|"runs example"| node_acas_demo
node_user -->|"runs benchmark"| node_ttm_benchmark
node_user -->|"uses demo"| node_neurips_demo
node_neurips_demo -->|"uses forecasting pipeline"| node_forecast

click node_ttm "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/tinytimemixer/modeling_tinytimemixer.py"
click node_ttm_config "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/tinytimemixer/configuration_tinytimemixer.py"
click node_tspulse "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/tspulse/modeling_tspulse.py"
click node_tspulse_config "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/tspulse/configuration_tspulse.py"
click node_patchtst "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/patchtst_fm/basic.py"
click node_flowstate "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/flowstate/modeling_flowstate.py"
click node_preprocessor "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/time_series_preprocessor.py"
click node_dataset "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/dataset.py"
click node_forecast "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/time_series_forecasting_pipeline.py"
click node_anomaly "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/time_series_anomaly_detection_pipeline.py"
click node_classification "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/time_series_classification_pipeline.py"
click node_imputation "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/time_series_imputation_pipeline.py"
click node_conformal "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/conformal.py"
click node_model_loading "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/get_model.py"
click node_service_config "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/tsfm_config.py"
click node_infer_api "https://github.com/ibm-granite/granite-tsfm/blob/main/services/inference/tsfminference/service_handler.py"
click node_infer_payload "https://github.com/ibm-granite/granite-tsfm/blob/main/services/inference/tsfminference/inference_payloads.py"
click node_infer_handler "https://github.com/ibm-granite/granite-tsfm/blob/main/services/inference/tsfminference/tsfm_inference_handler.py"
click node_tune_api "https://github.com/ibm-granite/granite-tsfm/blob/main/services/finetuning/tsfmfinetuning/service_handler.py"
click node_tune_payload "https://github.com/ibm-granite/granite-tsfm/blob/main/services/finetuning/tsfmfinetuning/inference_payloads.py"
click node_tune_handler "https://github.com/ibm-granite/granite-tsfm/blob/main/services/finetuning/tsfmfinetuning/tsfm_tuning_handler.py"
click node_acas_demo "https://github.com/ibm-granite/granite-tsfm/blob/main/notebooks/hfdemo/adaptive_conformal_tsad/main_acas_w1.py"
click node_ttm_benchmark "https://github.com/ibm-granite/granite-tsfm/blob/main/notebooks/hfdemo/tinytimemixer/full_benchmarking/ttm_full_benchmarking.py"
click node_neurips_demo "https://github.com/ibm-granite/granite-tsfm/blob/main/tsfmhfdemos/neurips/app.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_ttm,node_ttm_config,node_tspulse,node_tspulse_config,node_patchtst,node_flowstate,node_user toneBlue
class node_preprocessor,node_dataset,node_forecast,node_anomaly,node_classification,node_imputation,node_conformal,node_model_loading,node_service_config toneAmber
class node_infer_api,node_infer_payload,node_infer_handler toneMint
class node_tune_api,node_tune_payload,node_tune_handler toneRose
class node_acas_demo,node_ttm_benchmark,node_neurips_demo,node_model_hub toneIndigo
```

## Components

### Foundation Models

- [TinyTimeMixer](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/tinytimemixer/modeling_tinytimemixer.py): `tsfm_public/models/tinytimemixer/modeling_tinytimemixer.py`
- [TTM Configuration](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/tinytimemixer/configuration_tinytimemixer.py): `tsfm_public/models/tinytimemixer/configuration_tinytimemixer.py`
- [TSPulse](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/tspulse/modeling_tspulse.py): `tsfm_public/models/tspulse/modeling_tspulse.py`
- [TSPulse Configuration](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/tspulse/configuration_tspulse.py): `tsfm_public/models/tspulse/configuration_tspulse.py`
- [PatchTST-FM Components](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/patchtst_fm/basic.py): `tsfm_public/models/patchtst_fm/basic.py`
- [FlowState](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/models/flowstate/modeling_flowstate.py): `tsfm_public/models/flowstate/modeling_flowstate.py`

### Time-Series Toolkit

- [Time-Series Preprocessor](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/time_series_preprocessor.py): `tsfm_public/toolkit/time_series_preprocessor.py`
- [Dataset Builders](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/dataset.py): `tsfm_public/toolkit/dataset.py`
- [Forecasting Pipeline](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/time_series_forecasting_pipeline.py): `tsfm_public/toolkit/time_series_forecasting_pipeline.py`
- [Anomaly Pipeline](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/time_series_anomaly_detection_pipeline.py): `tsfm_public/toolkit/time_series_anomaly_detection_pipeline.py`
- [Classification Pipeline](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/time_series_classification_pipeline.py): `tsfm_public/toolkit/time_series_classification_pipeline.py`
- [Imputation Pipeline](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/time_series_imputation_pipeline.py): `tsfm_public/toolkit/time_series_imputation_pipeline.py`
- [Conformal Processing](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/conformal.py): `tsfm_public/toolkit/conformal.py`
- [Model Loading](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/get_model.py): `tsfm_public/toolkit/get_model.py`
- [Service Model Config](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfm_public/toolkit/tsfm_config.py): `tsfm_public/toolkit/tsfm_config.py`

### Inference Service

- [Inference Service API](https://github.com/ibm-granite/granite-tsfm/blob/main/services/inference/tsfminference/service_handler.py): `services/inference/tsfminference/service_handler.py`
- [Inference Payloads](https://github.com/ibm-granite/granite-tsfm/blob/main/services/inference/tsfminference/inference_payloads.py): `services/inference/tsfminference/inference_payloads.py`
- [Forecasting Inference Handler](https://github.com/ibm-granite/granite-tsfm/blob/main/services/inference/tsfminference/tsfm_inference_handler.py): `services/inference/tsfminference/tsfm_inference_handler.py`

### Fine-Tuning Service

- [Fine-Tuning Service API](https://github.com/ibm-granite/granite-tsfm/blob/main/services/finetuning/tsfmfinetuning/service_handler.py): `services/finetuning/tsfmfinetuning/service_handler.py`
- [Tuning Payloads](https://github.com/ibm-granite/granite-tsfm/blob/main/services/finetuning/tsfmfinetuning/inference_payloads.py): `services/finetuning/tsfmfinetuning/inference_payloads.py`
- [Forecasting Tuning Handler](https://github.com/ibm-granite/granite-tsfm/blob/main/services/finetuning/tsfmfinetuning/tsfm_tuning_handler.py): `services/finetuning/tsfmfinetuning/tsfm_tuning_handler.py`

### Examples and Demos

- [Adaptive Conformal TSAD](https://github.com/ibm-granite/granite-tsfm/blob/main/notebooks/hfdemo/adaptive_conformal_tsad/main_acas_w1.py): `notebooks/hfdemo/adaptive_conformal_tsad/main_acas_w1.py`
- [TTM Benchmarking](https://github.com/ibm-granite/granite-tsfm/blob/main/notebooks/hfdemo/tinytimemixer/full_benchmarking/ttm_full_benchmarking.py): `notebooks/hfdemo/tinytimemixer/full_benchmarking/ttm_full_benchmarking.py`
- [NeurIPS Demo](https://github.com/ibm-granite/granite-tsfm/blob/main/tsfmhfdemos/neurips/app.py): `tsfmhfdemos/neurips/app.py`

### Other components

- **Data User**
- **Hugging Face Models**

## Connections

- Data User → Forecasting Pipeline: submits series
- Forecasting Pipeline → Time-Series Preprocessor: uses preprocessing (evidence: `tsfm_public/toolkit/time_series_forecasting_pipeline.py`)
- Forecasting Pipeline → Dataset Builders: builds batches (evidence: `tsfm_public/toolkit/time_series_forecasting_pipeline.py`)
- Forecasting Pipeline → Conformal Processing: supports calibration (evidence: `tsfm_public/toolkit/time_series_forecasting_pipeline.py`)
- Anomaly Pipeline → Forecasting Pipeline: uses forecasting (evidence: `tsfm_public/toolkit/time_series_anomaly_detection_pipeline.py`)
- Anomaly Pipeline → Dataset Builders: uses datasets (evidence: `tsfm_public/toolkit/time_series_anomaly_detection_pipeline.py`)
- Classification Pipeline → Dataset Builders: uses datasets (evidence: `tsfm_public/toolkit/time_series_classification_pipeline.py`)
- Classification Pipeline → Forecasting Pipeline: reuses pipeline (evidence: `tsfm_public/toolkit/time_series_classification_pipeline.py`)
- Imputation Pipeline → Dataset Builders: uses datasets (evidence: `tsfm_public/toolkit/time_series_imputation_pipeline.py`)
- Imputation Pipeline → Forecasting Pipeline: reuses pipeline (evidence: `tsfm_public/toolkit/time_series_imputation_pipeline.py`)
- TinyTimeMixer → TTM Configuration: uses config (evidence: `tsfm_public/models/tinytimemixer/modeling_tinytimemixer.py`)
- TSPulse → TSPulse Configuration: uses config (evidence: `tsfm_public/models/tspulse/modeling_tspulse.py`)
- Hugging Face Models → TinyTimeMixer: provides pretrained models (evidence: `README.md`)
- Hugging Face Models → TSPulse: provides pretrained models (evidence: `README.md`)
- Hugging Face Models → PatchTST-FM Components: provides pretrained models (evidence: `README.md`)
- Hugging Face Models → FlowState: provides pretrained models (evidence: `README.md`)
- Data User → Inference Service API: requests inference
- Inference Service API → Inference Payloads: validates payload (evidence: `services/inference/tsfminference/service_handler.py`)
- Inference Service API → Forecasting Inference Handler: dispatches inference (evidence: `services/inference/tsfminference/service_handler.py`)
- Inference Service API → Service Model Config: loads configuration (evidence: `services/inference/tsfminference/service_handler.py`)
- Forecasting Inference Handler → Time-Series Preprocessor: constructs preprocessor (evidence: `services/inference/tsfminference/tsfm_inference_handler.py`)
- Forecasting Inference Handler → Conformal Processing: uses calibration (evidence: `services/inference/tsfminference/tsfm_inference_handler.py`)
- Data User → Fine-Tuning Service API: requests tuning
- Fine-Tuning Service API → Tuning Payloads: uses payload types (evidence: `services/finetuning/tsfmfinetuning/service_handler.py`)
- Fine-Tuning Service API → Forecasting Tuning Handler: dispatches tuning (evidence: `services/finetuning/tsfmfinetuning/service_handler.py`)
- Fine-Tuning Service API → Service Model Config: loads configuration (evidence: `services/finetuning/tsfmfinetuning/service_handler.py`)
- Forecasting Tuning Handler → Time-Series Preprocessor: uses preprocessing (evidence: `services/finetuning/tsfmfinetuning/tsfm_tuning_handler.py`)
- Forecasting Tuning Handler → Dataset Builders: builds training data (evidence: `services/finetuning/tsfmfinetuning/tsfm_tuning_handler.py`)
- Forecasting Tuning Handler → Model Loading: uses learning-rate finder (evidence: `services/finetuning/tsfmfinetuning/tsfm_tuning_handler.py`)
- Data User → Adaptive Conformal TSAD: runs example (evidence: `README.md`)
- Data User → TTM Benchmarking: runs benchmark (evidence: `README.md`)
- Data User → NeurIPS Demo: uses demo (evidence: `README.md`)
- NeurIPS Demo → Forecasting Pipeline: uses forecasting pipeline
