How adityalab/samay works
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.