How frezazadeh/time-series-foundation-model works
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 ..