# Kronos

> Pre-trained Transformer models that forecast candlestick (K-line) price data

- Repository: https://github.com/shiyu-coder/Kronos
- Category: Models & local AI
- Stars: 43,234 · Forks: 7,118 · Language: Python · License: MIT
- Experience: Some experience
- Page: https://ir.adyog.com/repos/shiyu-coder/kronos/

Financial candlestick charts are noisy, and general time-series models often handle them poorly. Kronos is built for this one kind of data. It treats sequences of K-lines (open, high, low, close, volume) like a language a model can learn to continue.

It works in two stages. A tokenizer first turns the continuous price numbers into hierarchical discrete tokens. Then an autoregressive Transformer, trained on those tokens, predicts what comes next. The README contrasts it with general-purpose time-series foundation models.

Four model sizes are listed, from 4.1M to 499.2M parameters. Mini, small and base are on Hugging Face. Large is not released. The repo also has a fine-tuning pipeline, shown with Chinese A-share data via Qlib, plus a simple backtest. The authors say it is a demo, not a production trading system.

## What it does

- **Simple forecasting API**: KronosPredictor takes a pandas DataFrame of K-lines plus timestamps. It handles normalization, prediction and inverse normalization, then returns a DataFrame of forecasts.
- **Sampling controls**: Temperature, top-p and sample_count let you generate several forecast paths and average them.
- **Batch prediction**: predict_batch forecasts many series in parallel on a GPU. All series need the same lookback and prediction length.
- **Several model sizes**: Kronos-mini, small and base can be downloaded from Hugging Face. Context length is 2048 for mini and 512 for the others.
- **Fine-tuning pipeline**: Scripts prepare Qlib data, fine-tune the tokenizer and predictor with torchrun on multiple GPUs, and run a top-K backtest.

## What you could build

- Forecast the next hours of a crypto pair from its recent candles.
- Run batch forecasts across many stocks or time periods at once.
- Fine-tune a Kronos model on your own market's daily data.
- Backtest a simple top-K strategy using the model's predicted price changes.
- Compare Kronos forecasts with other time-series models as a research baseline.

## Who it's for

Suits quant-curious developers and ML students who know Python, pandas and basic PyTorch, and who understand that forecasts are not trading advice.

## Get started

Install Python 3.10+ and the requirements. Then load a tokenizer and model from Hugging Face, wrap them in KronosPredictor, and call predict on a DataFrame of candles. The examples/prediction_example.py script runs the whole flow and plots the result.

```
pip install -r requirements.txt
```

Tags: time-series, finance, forecasting, transformer, foundation-model