NeoQuasar/Kronos-small
331.1m
1---2license: mit3pipeline_tag: time-series-forecasting4tags:5- Finance6- Candlestick7- K-line8- time-series9---10 11# Kronos: A Foundation Model for the Language of Financial Markets12 13[](https://arxiv.org/abs/2508.02739)14[](https://shiyu-coder.github.io/Kronos-demo/)15[](https://github.com/shiyu-coder/Kronos)16 17<p align="center">18 <img src="https://github.com/shiyu-coder/Kronos/blob/master/figures/logo.png?raw=true" alt="Kronos Logo" width="100">19</p>20 21**Kronos** is the **first open-source foundation model** for financial candlesticks (K-lines), trained on data from over **45 global exchanges**. It is designed to handle the unique, high-noise characteristics of financial data.22 23## Introduction24 25Kronos is a family of decoder-only foundation models, pre-trained specifically for the "language" of financial markets—K-line sequences. It leverages a novel two-stage framework:261. A specialized tokenizer first quantizes continuous, multi-dimensional K-line data (OHLCV) into **hierarchical discrete tokens**.272. A large, autoregressive Transformer is then pre-trained on these tokens, enabling it to serve as a unified model for diverse quantitative tasks.28 29<p align="center">30 <img src="https://github.com/shiyu-coder/Kronos/blob/master/figures/overview.png?raw=true" alt="Kronos Overview" align="center" width="700px" />31</p>32 33The success of large-scale pre-training paradigm, exemplified by Large Language Models (LLMs), has inspired the development of Time Series Foundation Models (TSFMs). Kronos addresses existing limitations by introducing a specialized tokenizer that discretizes continuous market information into token sequences, preserving both price dynamics and trade activity patterns. We pre-train Kronos using an autoregressive objective on a massive, multi-market corpus of over 12 billion K-line records from 45 global exchanges, enabling it to learn nuanced temporal and cross-asset representations. Kronos excels in a zero-shot setting across a diverse set of financial tasks, including price series forecasting, volatility forecasting, and synthetic data generation.34 35## Live Demo36 37We have set up a live demo to visualize Kronos's forecasting results. The webpage showcases a forecast for the **BTC/USDT** trading pair over the next 24 hours.38 39👉 [Access the Live Demo Here](https://shiyu-coder.github.io/Kronos-demo/)40 41## Model Zoo42 43We release a family of pre-trained models with varying capacities to suit different computational and application needs. All models are readily accessible from the Hugging Face Hub.44 45| Model | Tokenizer | Context length | Param | Hugging Face Model Card |46|--------------|---------------------------------------------------------------------------------| -------------- | ------ |--------------------------------------------------------------------------|47| Kronos-mini | [Kronos-Tokenizer-2k](https://huggingface.co/NeoQuasar/Kronos-Tokenizer-2k) | 2048 | 4.1M | ✅ [NeoQuasar/Kronos-mini](https://huggingface.co/NeoQuasar/Kronos-mini) |48| Kronos-small | [Kronos-Tokenizer-base](https://huggingface.co/NeoQuasar/Kronos-Tokenizer-base) | 512 | 24.7M | ✅ [NeoQuasar/Kronos-small](https://huggingface.co/NeoQuasar/Kronos-small) |49| Kronos-base | [Kronos-Tokenizer-base](https://huggingface.co/NeoQuasar/Kronos-Tokenizer-base) | 512 | 102.3M | ✅ [NeoQuasar/Kronos-base](https://huggingface.co/NeoQuasar/Kronos-base) |50| Kronos-large | [Kronos-Tokenizer-base](https://huggingface.co/NeoQuasar/Kronos-Tokenizer-base) | 512 | 499.2M | ❌ Not yet publicly available |51 52## Getting Started: Making Forecasts53 54Forecasting with Kronos is straightforward using the `KronosPredictor` class. It handles data preprocessing, normalization, prediction, and inverse normalization, allowing you to get from raw data to forecasts in just a few lines of code.55 56**Important Note**: The `max_context` for `Kronos-small` and `Kronos-base` is **512**. This is the maximum sequence length the model can process. For optimal performance, it is recommended that your input data length (i.e., `lookback`) does not exceed this limit. The `KronosPredictor` will automatically handle truncation for longer contexts.57 58Here is a step-by-step guide to making your first forecast.59 60### Installation61 621. Install Python 3.10+, and then install the dependencies from the [GitHub repository's `requirements.txt`](https://github.com/shiyu-coder/Kronos/blob/main/requirements.txt):63 64 ```shell65 pip install -r requirements.txt66 ```67 68### 1. Load the Tokenizer and Model69 70First, load a pre-trained Kronos model and its corresponding tokenizer from the Hugging Face Hub.71 72```python73from model import Kronos, KronosTokenizer, KronosPredictor74 75# Load from Hugging Face Hub76tokenizer = KronosTokenizer.from_pretrained("NeoQuasar/Kronos-Tokenizer-base")77model = Kronos.from_pretrained("NeoQuasar/Kronos-small")78```79 80### 2. Instantiate the Predictor81 82Create an instance of `KronosPredictor`, passing the model, tokenizer, and desired device.83 84```python85# Initialize the predictor86predictor = KronosPredictor(model, tokenizer, device="cuda:0", max_context=512)87```88 89### 3. Prepare Input Data90 91The `predict` method requires three main inputs:92- `df`: A pandas DataFrame containing the historical K-line data. It must include columns `['open', 'high', 'low', 'close']`. `volume` and `amount` are optional.93- `x_timestamp`: A pandas Series of timestamps corresponding to the historical data in `df`.94- `y_timestamp`: A pandas Series of timestamps for the future periods you want to predict.95 96```python97import pandas as pd98 99# Load your data (example data can be found in the GitHub repo)100df = pd.read_csv("./data/XSHG_5min_600977.csv")101df['timestamps'] = pd.to_datetime(df['timestamps'])102 103# Define context window and prediction length104lookback = 400105pred_len = 120106 107# Prepare inputs for the predictor108x_df = df.loc[:lookback-1, ['open', 'high', 'low', 'close', 'volume', 'amount']]109x_timestamp = df.loc[:lookback-1, 'timestamps']110y_timestamp = df.loc[lookback:lookback+pred_len-1, 'timestamps']111```112 113### 4. Generate Forecasts114 115Call the `predict` method to generate forecasts. You can control the sampling process with parameters like `T`, `top_p`, and `sample_count` for probabilistic forecasting.116 117```python118# Generate predictions119pred_df = predictor.predict(120 df=x_df,121 x_timestamp=x_timestamp,122 y_timestamp=y_timestamp,123 pred_len=pred_len,124 T=1.0, # Temperature for sampling125 top_p=0.9, # Nucleus sampling probability126 sample_count=1 # Number of forecast paths to generate and average127)128 129print("Forecasted Data Head:")130print(pred_df.head())131```132 133The `predict` method returns a pandas DataFrame containing the forecasted values for `open`, `high`, `low`, `close`, `volume`, and `amount`, indexed by the `y_timestamp` you provided.134 135### 5. Example and Visualization136 137For a complete, runnable script that includes data loading, prediction, and plotting, please see [`examples/prediction_example.py`](https://github.com/shiyu-coder/Kronos/blob/main/examples/prediction_example.py) in the GitHub repository.138 139Running this script will generate a plot comparing the ground truth data against the model's forecast, similar to the one shown below:140 141<p align="center">142 <img src="https://github.com/shiyu-coder/Kronos/blob/master/figures/prediction_example.png?raw=true" alt="Forecast Example" align="center" width="600px" />143</p>144 145Additionally, a script that makes predictions without Volume and Amount data can be found in [`examples/prediction_wo_vol_example.py`](https://github.com/shiyu-coder/Kronos/blob/main/examples/prediction_wo_vol_example.py).146 147## 🔧 Finetuning on Your Own Data (A-Share Market Example)148 149Refer to the [README](https://github.com/shiyu-coder/Kronos) of GitHub repository.150 151## Citation152 153If you use Kronos in your research, we would appreciate a citation to our [paper](https://huggingface.co/papers/2508.02739):154 155```bibtex156@misc{shi2025kronos,157 title={Kronos: A Foundation Model for the Language of Financial Markets}, 158 author={Yu Shi and Zongliang Fu and Shuo Chen and Bohan Zhao and Wei Xu and Changshui Zhang and Jian Li},159 year={2025},160 eprint={2508.02739},161 archivePrefix={arXiv},162 primaryClass={q-fin.ST},163 url={https://arxiv.org/abs/2508.02739}, 164}165```166 167## License168 169This project is licensed under the [MIT License](https://github.com/shiyu-coder/Kronos/blob/main/LICENSE).