# frezazadeh/time-series-foundation-model architecture

> Architecture diagram of the GitHub repository frezazadeh/time-series-foundation-model, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/frezazadeh/time-series-foundation-model
- Repository: https://github.com/frezazadeh/time-series-foundation-model

## Overview

##### Project type and purpose
- This is an ML-pipeline library and CLI “toolkit” built in Python and PyTorch, packaged under `src/tsfound`.
- It supports three core workflows:
- Self-supervised pre-training of a masked-patch Transformer on large time-series archives (e.g., CSV, TimeSeries-PILE).
- Supervised fine-tuning on downstream KPI data.
- Inference & evaluation (plus plotting).

##### Top-level components
- CLI & orchestration layer (scripts/):
- `pretrain.py`
- `finetune.py`
- `infer.py`
- `plot_kpi.py`
- Core library (`src/tsfound`):
- `datasets.py` – data ingestion, preprocessing.
- `models.py` – Transformer architecture, masking logic.
- `utils.py` – reproducible seeds, W&B hooks, HF snapshot helper.
- Configuration & packaging:
- `pyproject.toml` – dependencies, entry points.
- External services & data stores:
- Hugging Face (model/data hosting)
- W&B (logging)
- Local filesystem (CSV, NumPy arrays, checkpoints)

##### Key workflows & data flows
A. Pre-training
- Input: raw CSV / HF dataset → `datasets.load_…()` → masked-patch batching → `models.MaskedPatchTransformer` → optimizer → checkpoint (.pt)
- Logging: W&B hooks from `utils.py`
B. Fine-tuning
- Input: `x.npy`, `y.npy` → optional layer unfreeze → supervised training → checkpoint (.pt)
- Logging & metrics via W&B
C. Inference & evaluation
- Load supervised ckpt → pipeline restore (`utils`) → predict → output `y_pred.npy`
D. Plotting
- Reads `y.npy`, `y_pred.npy`, ckpt metadata → generates KPI plots

##### Architectural patterns & principles
- Modular, layered design: CLI scripts depend on a stable core library (`src/tsfound`).
- Separation of concerns: data ingestion vs model definition vs utilities.
- Reproducibility: seed utils, W&B integration.
- Lightweight packaging (`src` layout) for easy `pip install -e .`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI / Orchestration"
        direction TB
        Pretrain["pretrain.py"]:::cli
        Finetune["finetune.py"]:::cli
        Infer["infer.py"]:::cli
        PlotKPI["plot_kpi.py"]:::cli
    end

    subgraph "Core Library (src/tsfound)"
        direction TB
        Datasets["datasets.py"]:::library
        Models["models.py"]:::library
        Utils["utils.py"]:::library
    end

    subgraph "Local Storage"
        direction TB
        CSV["raw CSV"]:::storage
        XNpy["x.npy / y.npy"]:::storage
        Checkpoint[".pt checkpoints"]:::storage
        YPred["y_pred.npy"]:::storage
    end

    subgraph "External Services"
        direction TB
        HF["Hugging Face"]:::external
        WandB["W&B"]:::external
    end

    %% Pre-training workflow
    Pretrain -->|"load CSV"| Datasets
    Datasets -->|"masked batches"| Models
    Models -->|"checkpoint"| Checkpoint
    Pretrain -->|"hooks"| Utils
    Utils --> HF
    Utils --> WandB

    %% Fine-tuning workflow
    Finetune -->|"load x.npy,y.npy"| XNpy
    Finetune -->|"optional unfreeze"| Models
    Models -->|"checkpoint"| Checkpoint
    Finetune -->|"hooks"| Utils
    Utils --> WandB

    %% Inference workflow
    Infer -->|"load checkpoint"| Checkpoint
    Infer -->|"restore pipeline"| Utils
    Utils --> Models
    Models -->|"predict"| YPred

    %% Plotting workflow
    PlotKPI -->|"load y.npy,y_pred.npy,meta"| XNpy
    PlotKPI -->|"generate plots"| PlotKPI

    %% Click Events
    click Pretrain "https://github.com/frezazadeh/time-series-foundation-model/blob/main/scripts/pretrain.py"
    click Finetune "https://github.com/frezazadeh/time-series-foundation-model/blob/main/scripts/finetune.py"
    click Infer "https://github.com/frezazadeh/time-series-foundation-model/blob/main/scripts/infer.py"
    click PlotKPI "https://github.com/frezazadeh/time-series-foundation-model/blob/main/plot_kpi.py"
    click Datasets "https://github.com/frezazadeh/time-series-foundation-model/blob/main/src/tsfound/datasets.py"
    click Models "https://github.com/frezazadeh/time-series-foundation-model/blob/main/src/tsfound/models.py"
    click Utils "https://github.com/frezazadeh/time-series-foundation-model/blob/main/src/tsfound/utils.py"
    click pyproject "https://github.com/frezazadeh/time-series-foundation-model/blob/main/pyproject.toml"

    %% Styles
    classDef cli fill:#bbdefb,stroke:#2196f3,stroke-width:1px;
    classDef library fill:#c8e6c9,stroke:#388e3c,stroke-width:1px;
    classDef storage fill:#ffe0b2,stroke:#f57c00,stroke-width:1px;
    classDef external fill:#fff59d,stroke:#fbc02d,stroke-width:1px;
```
