amazon-science/chronos-forecasting

Purpose and public entry points

Chronos is a Python package for zero-shot probabilistic time-series forecasting using pretrained Hugging Face models. Its principal user-facing entry point is Chronos2Pipeline.from_pretrained(...).predict_df(...) for pandas/DataFrame forecasting with univariate, multivariate, and covariate inputs. Package exports and shared abstractions begin at src/chronos/__init__.py and src/chronos/base.py.

Model-family boundary

Three inference families coexist behind separate implementations:

• Original Chronos tokenizes scaled/quantized series and samples future token trajectories through a language model: src/chronos/chronos.py.

• Chronos-Bolt performs patch-based direct multi-step quantile forecasting: src/chronos/chronos_bolt.py.

• Chronos-2 is the current universal forecasting stack, supporting covariates and multivariate targets: src/chronos/chronos2/pipeline.py, src/chronos/chronos2/model.py.

This separation preserves model-specific preprocessing and output semantics while presenting a common package surface.

Chronos-2 prediction pipeline

Chronos2Pipeline is the primary orchestration boundary. It loads pretrained weights/configuration, accepts tabular or series-oriented inputs, validates/normalizes input representation, invokes the model, and formats forecast DataFrames. Core flow is:

predict_df input → DataFrame utilities/preprocessing → dataset/batch construction → model inference → prediction DataFrame.

Relevant paths: src/chronos/chronos2/pipeline.py, src/chronos/chronos2/preprocess.py, src/chronos/df_utils.py.

Chronos-2 model and data layer

Chronos-2’s configurable neural architecture is defined independently from pipeline I/O. Model configuration and network assembly reside in src/chronos/chronos2/config.py and src/chronos/chronos2/model.py; reusable architectural layers are in src/chronos/chronos2/layers.py. The dataset layer converts prepared time-series/covariate examples into model-ready batches and establishes the data contract between preprocessing and training/inference: src/chronos/chronos2/dataset.py.

Training path

Training is a distinct offline path rather than part of package inference. The Chronos-2 trainer coordinates model optimization over dataset batches: src/chronos/chronos2/trainer.py. Legacy Chronos training is launched through scripts/training/train.py, parameterized by model-specific YAML configurations such as scripts/training/configs/chronos-t5-base.yaml and scripts/training/configs/chronos-gpt2.yaml. These paths produce or fine-tune artifacts consumable through pretrained-model loading.

Evaluation and benchmark flow

Evaluation scripts run configured model backtests and aggregate relative scores, separating benchmark execution from library APIs: scripts/evaluation/evaluate.py, scripts/evaluation/agg-relative-score.py, and scripts/evaluation/configs/zero-shot.yaml. The repository includes committed result tables under scripts/evaluation/results/, while the README identifies the external fev benchmark ecosystem and Hugging Face datasets as important evaluation dependencies.

Runtime, artifacts, and deployment

The package is distributed through PyPI (pyproject.toml; publishing workflow .github/workflows/publish-to-pypi.yml) and runs as Python, with pandas/pyarrow used for DataFrame-oriented Chronos-2 inputs. Pretrained model weights and datasets are externally hosted on Hugging Face; from_pretrained is the principal artifact-loading boundary. AWS is a deployment integration target: SageMaker JumpStart and AutoGluon-Cloud are documented externally, with a SageMaker deployment example in notebooks/deploy-chronos-to-amazon-sagemaker.ipynb. AWS/Boto support is isolated in src/chronos/boto_utils.py.