# forestsking/chattime architecture

> Architecture diagram of the GitHub repository forestsking/chattime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/forestsking/chattime
- Repository: https://github.com/forestsking/chattime

## Overview

##### Project Type and Purpose
- ChatTime is an open-source multimodal time-series foundation model library. It provides both pre-training and fine-tuning pipelines for a large language model adapted to numerical (time series) and textual data, plus inference routines (zero-shot forecasting, context-guided forecasting, QA).

##### File Structure Analysis
- Top level:
- dataset/ – CSV files for Traffic, PTF, TSQA tasks
- img/ – architecture illustration
- model/ – core ChatTime class (model/model.py)
- training/ – scripts for continuous pre-training and instruction fine-tuning
- utils/ – helper modules for prompt construction and tool functions
- demo.ipynb – example notebook for all three use cases
- Configuration/Deployment:
- .sh scripts (pretrain.sh, finetune.sh) wrap Python scripts for HPC/Cloud runs
- model weights are published on Hugging Face Hub

##### README Insights
- Describes three key workflows:
a. Continuous Pre-Training (training/pretrain.py → base model)
b. Instruction Fine-Tuning (training/finetune.py → chat model)
c. Inference (model/model.py + utils + demo.ipynb)
- External services: Hugging Face Datasets & Model Hub for storing data and weights.

##### Main Components
A. Data Layer
- Local CSV datasets (dataset/*.csv)
- Hugging Face Datasets (ChengsenWang/ChatTime-1-Pretrain-1M, etc.)
B. Training Pipeline
1. Pre-Training Module (training/pretrain.py)
– Inputs: pre-training data from HF Datasets
– Output: base model artifacts pushed to HF Hub
2. Fine-Tuning Module (training/finetune.py)
– Inputs: base model, finetuning data
– Output: chat model artifacts on HF Hub
C. Model Code
- model/model.py (ChatTime class)
- utils/prompt.py, utils/tools.py (multimodal prompt builder)
D. Inference / Demo
- demo.ipynb – zero-shot forecasting, context-guided forecasting, TSQA
- Model loading from HF Hub
E. External Services
- Hugging Face Hub (Models + Datasets)
- Optional: compute environment (GPU cluster, cloud instances)

##### Relationships & Data Flows
- utils/ and model/ modules are shared libraries imported by both training and inference pipelines

##### Architectural Patterns & Design Principles
- Modular pipeline: clear separation of data ingestion, pre-training, fine-tuning, and inference
- Reusability: single ChatTime class powers all three inference tasks
- Extensibility: utils.prompt and utils.tools abstract prompt engineering for new tasks
- CI/CD-style workflow: shell scripts + Python scripts can be integrated with SLURM or cloud jobs

##### Technologies and Frameworks
- Python 3.x
- PyTorch / Hugging Face Transformers
- Hugging Face Datasets & Model Hub
- Jupyter Notebook for demos
- Shell scripts for automated runs

##### Essential Elements
- Clear component boundaries and names
- Data flow directions and dependencies
- External integrations (Hugging Face Hub)
- Shared libraries (model/, utils/) showing reuse

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Traffic["Traffic.csv"]:::data
        PTF["PTF.csv"]:::data
        TSQA["TSQA.csv"]:::data
        HFDS["Hugging Face Datasets"]:::external
    end

    %% Pre-Training Pipeline
    subgraph "Pre-Training Module"
        direction TB
        PT_SH["pretrain.sh"]:::processing
        PT_PY["pretrain.py"]:::processing
    end

    %% Fine-Tuning Pipeline
    subgraph "Fine-Tuning Module"
        direction TB
        FT_SH["finetune.sh"]:::processing
        FT_PY["finetune.py"]:::processing
    end

    %% Model Artifacts on Hub
    subgraph "Hugging Face Model Hub"
        direction TB
        BaseModel["Base Model Artifacts"]:::artifact
        ChatModel["Chat Model Artifacts"]:::artifact
    end

    %% Core Libraries
    subgraph "Core Libraries"
        direction TB
        ChatTimeClass["ChatTime Class\n(model.py)"]:::library
        ModelInit["__init__.py"]:::library
        Prompt["prompt.py"]:::library
        Tools["tools.py"]:::library
        UtilsInit["__init__.py"]:::library
    end

    %% Inference / Demo
    subgraph "Inference / Demo"
        direction TB
        Demo["demo.ipynb"]:::processing
    end

    %% External Services
    Compute["GPU Cluster / Cloud"]:::external
    IMG["img/"]:::external
    README["README.md"]:::external

    %% Data to Pre-Training
    Traffic -->|"CSV Files"| PT_PY
    PTF -->|"CSV Files"| PT_PY
    TSQA -->|"CSV Files"| PT_PY
    HFDS -->|"HF Dataset API"| PT_PY

    %% Pre-Training to Hub
    PT_PY -->|"Push Base Model"| BaseModel
    PT_SH --> PT_PY

    %% Hub & Data to Fine-Tuning
    BaseModel -->|"Load Base Model"| FT_PY
    PTF -->|"CSV Files"| FT_PY
    TSQA -->|"CSV Files"| FT_PY
    HFDS -->|"HF Dataset API"| FT_PY
    FT_SH --> FT_PY

    %% Fine-Tuning to Hub
    FT_PY -->|"Push Chat Model"| ChatModel

    %% Inference Flow
    ChatModel -->|"Load Chat Model"| Demo
    ChatTimeClass --> Demo
    Prompt --> Demo
    Tools --> Demo
    UtilsInit --> Demo
    ModelInit --> Demo

    %% Libraries used in Training
    ChatTimeClass --> PT_PY
    ModelInit --> PT_PY
    Prompt --> PT_PY
    Tools --> PT_PY
    UtilsInit --> PT_PY

    ChatTimeClass --> FT_PY
    ModelInit --> FT_PY
    Prompt --> FT_PY
    Tools --> FT_PY
    UtilsInit --> FT_PY

    %% Optional External
    Compute --> PT_PY
    Compute --> FT_PY
    Compute --> Demo

    %% Diagram illustration and README
    IMG -.-> Traffic
    IMG -.-> PT_PY
    IMG -.-> FT_PY
    README -.-> Traffic

    %% Click Events
    click Traffic "https://github.com/forestsking/chattime/blob/main/dataset/Traffic.csv"
    click PTF "https://github.com/forestsking/chattime/blob/main/dataset/PTF.csv"
    click TSQA "https://github.com/forestsking/chattime/blob/main/dataset/TSQA.csv"
    click HFDS "https://github.com/forestsking/chattime/blob/main/dataset/Traffic.csv"
    click PT_PY "https://github.com/forestsking/chattime/blob/main/training/pretrain.py"
    click PT_SH "https://github.com/forestsking/chattime/blob/main/training/pretrain.sh"
    click FT_PY "https://github.com/forestsking/chattime/blob/main/training/finetune.py"
    click FT_SH "https://github.com/forestsking/chattime/blob/main/training/finetune.sh"
    click ChatTimeClass "https://github.com/forestsking/chattime/blob/main/model/model.py"
    click ModelInit "https://github.com/forestsking/chattime/blob/main/model/__init__.py"
    click Prompt "https://github.com/forestsking/chattime/blob/main/utils/prompt.py"
    click Tools "https://github.com/forestsking/chattime/blob/main/utils/tools.py"
    click UtilsInit "https://github.com/forestsking/chattime/blob/main/utils/__init__.py"
    click Demo "https://github.com/forestsking/chattime/blob/main/demo.ipynb"
    click IMG "https://github.com/forestsking/chattime/tree/main/img/"
    click README "https://github.com/forestsking/chattime/blob/main/README.md"

    %% Styles
    classDef data fill:#AED6F1,stroke:#3498DB,stroke-width:1px
    classDef processing fill:#FAD7A0,stroke:#E67E22,stroke-width:1px
    classDef artifact fill:#ABEBC6,stroke:#27AE60,stroke-width:1px
    classDef library fill:#F5B7B1,stroke:#C0392B,stroke-width:1px
    classDef external fill:#D7BDE2,stroke:#8E44AD,stroke-width:1px
```
