Enhance model card with paper details, demo, usage, and model zoo

This PR significantly improves the model card for Kronos by integrating comprehensive information from the research paper and the official GitHub repository. Key additions include:

- A detailed overview of the Kronos model and its purpose, derived from the paper's abstract.
- A direct link to the Hugging Face paper page: [Kronos: A Foundation Model for the Language of Financial Markets](https://huggingface.co/papers/2508.02739).
- A link to the live demo/project page: [Access the Live Demo Here](https://shiyu-coder.github.io/Kronos-demo/).
- A table listing the available model checkpoints with their respective Hugging Face links in the "Model Zoo" section.
- A complete Python code example for quick inference, making the model immediately usable for researchers and practitioners.
- Proper citation information in BibTeX format.
- Addition of `library_name: torch` to the metadata for better categorization.
- Removal of the "File information" section as it's not relevant for a user-facing model card.

This enhancement will make the model more discoverable, understandable, and user-friendly on the Hugging Face Hub.

README.md

@@ -5,8 +5,141 @@ tags:
 - Finance
 - Candlestick
 - K-line
+library_name: torch
 ---
+
 # Model Card for Kronos
 
+**Kronos** is a unified, scalable pre-training framework tailored to financial candlestick (K-line) modeling. It introduces a specialized tokenizer that discretizes continuous market information into token sequences, preserving both price dynamics and trade activity patterns. Pre-trained on a massive, multi-market corpus of over 12 billion K-line records from 45 global exchanges, Kronos learns nuanced temporal and cross-asset representations. Kronos excels in a zero-shot setting across a diverse set of financial tasks, boosting price series forecasting RankIC by 93%, achieving a 9% lower MAE in volatility forecasting, and a 22% improvement in generative fidelity for synthetic K-line sequences.
+
+This model was presented in the paper: [Kronos: A Foundation Model for the Language of Financial Markets](https://huggingface.co/papers/2508.02739).
+
+For full details on how to use this model, please visit our [GitHub page](https://github.com/shiyu-coder/Kronos).
+
+## ✨ Live Demo
+We 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.
+
+**👉 [Access the Live Demo Here](https://shiyu-coder.github.io/Kronos-demo/)**
+
+## 📦 Model Zoo
+We 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.
+
+| Model        | Tokenizer                                                                       | Context length | Param  | Open-source                                                               |
+|--------------|---------------------------------------------------------------------------------| -------------- | ------ |---------------------------------------------------------------------------|
+| Kronos-mini  | [Kronos-Tokenizer-2k](https://huggingface.co/NeoQuasar/Kronos-Tokenizer-2k)     | 2048           | 4.1M   | ✅ [NeoQuasar/Kronos-mini](https://huggingface.co/NeoQuasar/Kronos-mini)  |
+| Kronos-small | [Kronos-Tokenizer-base](https://huggingface.co/NeoQuasar/Kronos-Tokenizer-base) | 512            | 24.7M  | ✅ [NeoQuasar/Kronos-small](https://huggingface.co/NeoQuasar/Kronos-small) |
+| Kronos-base  | [Kronos-Tokenizer-base](https://huggingface.co/NeoQuasar/Kronos-Tokenizer-base) | 512            | 102.3M | ✅ [NeoQuasar/Kronos-base](https://huggingface.co/NeoQuasar/Kronos-base)   |
+| Kronos-large | [Kronos-Tokenizer-base](https://huggingface.co/NeoQuasar/Kronos-Tokenizer-base) | 512            | 499.2M | ❌                                                                         |
+
+## 🚀 Getting Started
+
+### Installation
+
+1.  Install Python 3.10+, and then install the dependencies:
+
+```shell
+pip install -r requirements.txt
+```
+
+### 📈 Making Forecasts
+
+Forecasting 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.
+
+**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.
+
+Here is a step-by-step guide to making your first forecast.
+
+#### 1. Load the Tokenizer and Model
+
+First, load a pre-trained Kronos model and its corresponding tokenizer from the Hugging Face Hub.
+
+```python
+from model import Kronos, KronosTokenizer, KronosPredictor
+
+# Load from Hugging Face Hub
+tokenizer = KronosTokenizer.from_pretrained("NeoQuasar/Kronos-Tokenizer-base")
+model = Kronos.from_pretrained("NeoQuasar/Kronos-small")
+```
+
+#### 2. Instantiate the Predictor
+
+Create an instance of `KronosPredictor`, passing the model, tokenizer, and desired device.
+
+```python
+# Initialize the predictor
+predictor = KronosPredictor(model, tokenizer, device="cuda:0", max_context=512)
+```
+
+#### 3. Prepare Input Data
+
+The `predict` method requires three main inputs:
+-   `df`: A pandas DataFrame containing the historical K-line data. It must include columns `['open', 'high', 'low', 'close']`. `volume` and `amount` are optional.
+-   `x_timestamp`: A pandas Series of timestamps corresponding to the historical data in `df`.
+-   `y_timestamp`: A pandas Series of timestamps for the future periods you want to predict.
+
+```python
+import pandas as pd
+
+# Load your data
+df = pd.read_csv("./data/XSHG_5min_600977.csv")
+df['timestamps'] = pd.to_datetime(df['timestamps'])
+
+# Define context window and prediction length
+lookback = 400
+pred_len = 120
+
+# Prepare inputs for the predictor
+x_df = df.loc[:lookback-1, ['open', 'high', 'low', 'close', 'volume', 'amount']]
+x_timestamp = df.loc[:lookback-1, 'timestamps']
+y_timestamp = df.loc[lookback:lookback+pred_len-1, 'timestamps']
+```
+
+#### 4. Generate Forecasts
+
+Call the `predict` method to generate forecasts. You can control the sampling process with parameters like `T`, `top_p`, and `sample_count` for probabilistic forecasting.
+
+```python
+# Generate predictions
+pred_df = predictor.predict(
+    df=x_df,
+    x_timestamp=x_timestamp,
+    y_timestamp=y_timestamp,
+    pred_len=pred_len,
+    T=1.0,          # Temperature for sampling
+    top_p=0.9,      # Nucleus sampling probability
+    sample_count=1  # Number of forecast paths to generate and average
+)
+
+print("Forecasted Data Head:")
+print(pred_df.head())
+```
+
+The `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.
+
+#### 5. Example and Visualization
+
+For 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).
+
+Running this script will generate a plot comparing the ground truth data against the model's forecast, similar to the one shown below:
+
+<p align="center">
+    <img src="https://huggingface.co/NeoQuasar/Kronos-mini/resolve/main/figures/prediction_example.png" alt="Forecast Example" align="center" width="600px" />
+</p>
+
+Additionally, we also provide a script that makes predictions without Volume and Amount data, which can be found in [`examples/prediction_wo_vol_example.py`](https://github.com/shiyu-coder/Kronos/blob/main/examples/prediction_wo_vol_example.py).
+
+## 📖 Citation
+
+If you use Kronos in your research, we would appreciate a citation to our [paper](https://arxiv.org/abs/2508.02739):
 
-For details on how to use this model, please visit our [GitHub page](https://github.com/shiyu-coder/Kronos).
+```
+@misc{shi2025kronos,
+      title={Kronos: A Foundation Model for the Language of Financial Markets},
+      author={Yu Shi and Zongliang Fu and Shuo Chen and Bohan Zhao and Wei Xu and Changshui Zhang and Jian Li},
+      year={2025},
+      eprint={2508.02739},
+      archivePrefix={arXiv},
+      primaryClass={q-fin.ST},
+      url={https://arxiv.org/abs/2508.02739},
+}
+```