# adityalab/samay architecture

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

- Interactive diagram: https://gitdiagram.com/adityalab/samay
- Repository: https://github.com/adityalab/samay

## Overview

Based on our analysis of the file tree and README, Samay is a Python‐based library for time-series foundational models. Its purpose is to offer a unified framework that supports multiple state‐of-the-art time-series forecasting models such as LPTM, TimesFM, Chronos, Moirai, MOMENT, and TinytTimeMixers. The repository is structured into clearly defined submodules and configuration files, with example notebooks and scripts to drive experiments, data downloads, leaderboard creation, and more.

##### Main Components
a. Samay Core Library – Represented mainly in the “src/samay” folder. Include the following subcomponents:
– API Interfaces (e.g., dataset.py, model.py, metric.py): These provide user-facing abstractions for loading data, initializing models, and evaluating performance.
– Utility / Helper Functions and tools (e.g., utils.py, visualization.py, toolkit/ modules).
b. Model Implementations – Under “src/samay/models”, you have multiple distinct model directories (TinyTimeMixer, ChronosForecasting, LPTM, MOMENT, TimesFM, Uni2TS):
– Each model group contains its own internal structure (configuration handling, model definition, training pipelines, and sometimes data-related utilities).
c. Configuration Management – The “config” directory holds JSON files with hyperparameters and experiment settings for various models (e.g., chronos.json, moment_imputation.json). Also note that individual models include resource and data configuration files.
d. Experiment & Leaderboard Infrastructure – Files like “create_leaderboard.py”, “leaderboard/” folder, and experiment scripts such as “TimeGPT_experiments.py” and “plot_timeGPT.py” show that there is a pipeline for performance comparison and visualization.
e. Example Notebooks / Usage Illustrations – The “example/” directory (with Jupyter notebooks and even Colab examples) illustrates how a user would interact with the library.
f. External Dependencies & CI Tools – The GitHub workflows in “.github/workflows” and dependencies like UV (and the instructions for installing Rust) show integration with external tools and the development pipeline.

##### Relationships and Data Flow
– User code (e.g., example notebooks, scripts) calls the Samay Core API.
– The API delegates work to specific model implementations (each in its own subdirectory under “models”) based on the configuration provided.
– These models then use dedicated dataset classes to ingest and preprocess time-series data found under the “data” folder or configured via JSON/YAML settings.
– Utility modules (under toolkit, utils, visualization, etc.) support data handling, model training, evaluation, and post-processing.
– The “leaderboard” scripts and CSV files record experimental results generated by evaluation functions in each model.
– CI/CD pipelines and build scripts (e.g., in “.github/workflows/release.yml”, “pyproject.toml”) support continuous integration, testing, and deployment.

##### Architectural Patterns and Design Principles
– Modularity & Extensibility: Each model (LPTM, TimesFM, etc.) is encapsulated in its own directory with a similar structure (configuration, core model code, utilities). This points to a plugin-like architecture where additional models can be added on top of the same foundation.
– Separated Configuration: With a dedicated “config” directory and per-model resource settings under “src/samay/models/[model]/resources”, configuration is externalized from logic.
– API Abstraction: The core API (e.g., dataset and model interfaces) is designed to abstract the underlying complexity, making it easier for users to replace or extend components.
– Pipeline / Workflow Oriented: The system supports training, finetuning, evaluation, and leaderboard recording, reflecting a clear data-flow (from ingestion to evaluation).

##### Relevant Technologies and Frameworks
– Python (primary language), with use of popular time-series and deep learning frameworks.
– Integration with external tools & packages, such as UV (for dependency management) and Rust for performance-critical components.
– Model-specific technologies (PyTorch for deep learning, YAML/JSON for configurations) are evident.

– Components for Data Ingestion (Dataset API).
– Components for Modeling (Model API and Model Implementations).
– Evaluation and Metrics (Metric API & Plot/Visualization Tools).
- A separate block for Configuration Management (including the “config” directory and embedded resource configurations inside each model’s folder).
- External modules/script blocks:
– Experiment and Leaderboard modules (e.g., create_leaderboard.py, leaderboard CSV files) to indicate how results are aggregated.
– Example Notebooks and user interfaces, showing that these elements drive the library’s usage.
– Indicate CI/CD tools (GitHub workflows) to reflect the integration pipeline.

## Diagram (Mermaid)

```mermaid
graph TD
    USER["User Code"]:::external

    subgraph "Samay Core Library"
        CORE["Samay Core Library"]:::core
        API_D["dataset API"]:::api
        API_M["model API"]:::api
        API_MET["metric API"]:::api
        U1["Utility: utils"]:::util
        U2["Utility: visualization"]:::util
    end

    subgraph "Model Implementations"
        TTM["TinyTimeMixer"]:::model
        TTM_toolkit["Toolkit"]:::util
        CF["ChronosForecasting"]:::model
        LPTM["LPTM"]:::model
        MOM["MOMENT"]:::model
        TFM["TimesFM"]:::model
        U2TS["Uni2TS"]:::model
    end

    subgraph "Configuration Management"
        CONFIG["Configuration Files"]:::config
    end

    subgraph "Experiment & Leaderboard"
        CL["create_leaderboard.py"]:::experiment
        LB["Leaderboard Data"]:::experiment
        TEXP["TimeGPT_experiments.py"]:::experiment
        PLOT["plot_timeGPT.py"]:::experiment
    end

    subgraph "Example Notebooks"
        EXNB["Example Notebooks"]:::example
    end

    subgraph "External Dependencies & CI Tools"
        GH[".github/workflows"]:::external
        PYC["pyproject.toml"]:::external
    end

    USER -->|"triggers"| EXNB
    USER -->|"triggers"| CL

    EXNB -->|"calls"| API_D
    EXNB -->|"calls"| API_M
    EXNB -->|"calls"| API_MET
    CL -->|"evaluates"| API_MET

    API_M -->|"selects"| TTM
    API_M -->|"selects"| CF
    API_M -->|"selects"| LPTM
    API_M -->|"selects"| MOM
    API_M -->|"selects"| TFM
    API_M -->|"selects"| U2TS

    CONFIG -->|"configures"| API_D
    CONFIG -->|"configures"| API_M
    CONFIG -->|"configures"| TTM
    CONFIG -->|"configures"| CF
    CONFIG -->|"configures"| LPTM
    CONFIG -->|"configures"| MOM
    CONFIG -->|"configures"| TFM
    CONFIG -->|"configures"| U2TS

    U2 -->|"supports"| PLOT

    TTM -->|"uses"| TTM_toolkit

    GH -->|"CI_triggers"| CL
    PYC -->|"dependency"| CORE

    classDef core fill:#f9e,stroke:#333,stroke-width:2px
    classDef api fill:#cce,stroke:#333,stroke-width:2px
    classDef util fill:#ccf,stroke:#333,stroke-width:2px
    classDef model fill:#e6ccff,stroke:#333,stroke-width:2px
    classDef config fill:#cff,stroke:#333,stroke-width:2px
    classDef experiment fill:#ffcc99,stroke:#333,stroke-width:2px
    classDef example fill:#ffd,stroke:#333,stroke-width:2px
    classDef external fill:#eee,stroke:#333,stroke-width:2px

    click CORE "https://github.com/adityalab/samay/tree/main/src/samay"
    click API_D "https://github.com/adityalab/samay/blob/main/src/samay/dataset.py"
    click API_M "https://github.com/adityalab/samay/blob/main/src/samay/model.py"
    click API_MET "https://github.com/adityalab/samay/blob/main/src/samay/metric.py"
    click U1 "https://github.com/adityalab/samay/blob/main/src/samay/utils.py"
    click U2 "https://github.com/adityalab/samay/blob/main/src/samay/visualization.py"
    click TTM "https://github.com/adityalab/samay/tree/main/src/samay/models/TinyTimeMixer"
    click TTM_toolkit "https://github.com/adityalab/samay/tree/main/src/samay/models/TinyTimeMixer/toolkit"
    click CF "https://github.com/adityalab/samay/tree/main/src/samay/models/chronosforecasting"
    click LPTM "https://github.com/adityalab/samay/tree/main/src/samay/models/lptm"
    click MOM "https://github.com/adityalab/samay/tree/main/src/samay/models/moment"
    click TFM "https://github.com/adityalab/samay/tree/main/src/samay/models/timesfm"
    click U2TS "https://github.com/adityalab/samay/tree/main/src/samay/models/uni2ts"
    click CONFIG "https://github.com/adityalab/samay/tree/main/config"
    click CL "https://github.com/adityalab/samay/blob/main/create_leaderboard.py"
    click LB "https://github.com/adityalab/samay/tree/main/leaderboard"
    click TEXP "https://github.com/adityalab/samay/blob/main/TimeGPT_experiments.py"
    click PLOT "https://github.com/adityalab/samay/blob/main/plot_timeGPT.py"
    click EXNB "https://github.com/adityalab/samay/tree/main/example"
    click GH "https://github.com/adityalab/samay/tree/main/.github/workflows"
    click PYC "https://github.com/adityalab/samay/blob/main/pyproject.toml"
```
