Kronos turns K-line bars into discrete tokens, then samples a price path from them

A tokenizer absorbs the noise before any learning happens

The pipeline runs in two stages and the first one is not optional. A specialized tokenizer quantizes continuous, multi-dimensional K-line data, meaning the OHLCV values, into hierarchical discrete tokens, and a large autoregressive Transformer is then pre-trained on those token sequences. The architecture is decoder-only, and the stated difference from general-purpose time series foundation models is the data itself: financial bars are treated as unusually high-noise, and the tokenizer stage is what absorbs that noise before training starts. For you this means the model never ingests a raw float the way a regression would. Every price on the forecasting path has already been quantized, and the tokenizer is a separate artifact you load by name rather than a layer inside the model, so the two are versioned independently.

Every checkpoint is welded to one named tokenizer

The Model Zoo table binds each checkpoint to one tokenizer repository and one context length. Kronos-mini pairs a 2k tokenizer with a 2048 context at 4.1M parameters. Kronos-small and Kronos-base both use the base tokenizer with a 512 context, at 24.7M and 102.3M parameters. Kronos-large reaches 499.2M parameters but its open-source cell is empty, so the largest model listed is not published anywhere. Any plan that assumed starting small and scaling up stops at base. The pairing also removes a degree of freedom you might expect to have: the tokenizer name in your loading code is fixed by the checkpoint you picked, and nothing in the repository validates that the two match, so a mismatched pair produces a call that runs and returns numbers.

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")

# Initialize the predictor
predictor = KronosPredictor(model, tokenizer, max_context=512)

Longer lookbacks get cut without anything in the result saying so

The README puts max_context for Kronos-small and Kronos-base at 512, calls it the maximum sequence length the model can process, and recommends that your input data length, meaning the lookback, not exceed that limit. It also states that KronosPredictor will handle truncation automatically for longer contexts. That automatic behavior is the part to plan around. The worked example feeds 400 bars, but a longer history is silently shortened, and predict still hands back a DataFrame with no field telling you which rows were dropped. If your edge depends on long memory, a multi-session pattern or a slow regime shift, the count of surviving bars is the first number to measure rather than assume. The README does not document a warning, an exception, or a result attribute that exposes the cut.

sample_count of one means there is no distribution to read

predict accepts three sampling controls: T for temperature, top_p for nucleus sampling probability, and sample_count for the number of forecast paths to generate and average. The example runs T=1.0, top_p=0.9, and sample_count=1, and a count of one means there is nothing to average, so the frame you get is a single stochastic draw rather than a central tendency. Temperature is left at the value the example chose, so two calls on identical inputs need not agree with each other. To see spread you must raise sample_count yourself and compute the average and the dispersion downstream, because the method returns prices and not a distribution over them. No quantile output and no calibration procedure is described anywhere in the README.

# 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
)

Four columns are mandatory and the failure mode is undocumented

predict takes three inputs: a pandas DataFrame named df, a Series named x_timestamp aligned to that history, and a Series named y_timestamp covering the future periods you want. The DataFrame must include the columns ['open', 'high', 'low', 'close']. volume and amount are optional, and the repository ships examples/prediction_wo_vol_example.py, which shows the token stream running without turnover. The cost of that optionality is comparability, because two runs over the same instrument can differ in what the model was permitted to see, and the predictor consumes whatever columns you hand it without reporting which ones it used. The README does not document the error raised for a missing open or high column, and it states no dtype expectations, so a frame of strings fails at a point you cannot anticipate from the documentation.

The output is a price frame, never a position

Read what the example actually does with the result: it assigns the return of predict to pred_df and prints the head. There is no order placement, no position sizing, no fee or slippage model, and no broker integration on that path. The repository does ship examples/run_backtest_kronos.py, so some form of evaluation harness exists, but the predictor itself stops at a price frame. The horizon is whatever you put into y_timestamp: the bundled walkthrough reads ./data/XSHG_5min_600977.csv, sets lookback to 400 and pred_len to 120, and slices the future timestamps out of that same frame. Every cost between the final bar and a real fill is code you write yourself, and nothing in the repository prices it.

requirements.txt names pandas twice and leaves torch open ended

The dependency file names pandas on one line and then pins pandas==2.2.2 further down, so pip resolves the duplicate to 2.2.2 and the loose line tells you nothing you can act on. numpy carries no version at all, and torch is bounded only from below by 2.0.0, which is the loosest edge in the file since a new torch release can move underneath a hub client pinned to an exact release. The hard pins are einops==0.8.1, huggingface_hub==0.33.1, matplotlib==3.9.3, tqdm==4.67.1, and safetensors==0.6.2. Installation is Python 3.10 or newer followed by a clone, because the repository publishes no GitHub releases, so that is the entire install story. A script written against a newer hub feature will not run in this environment without editing the pin.

pip install -r requirements.txt

Two fine-tuning directories, and a news log that stops early

The news entry dated 2025.08.17 announces that scripts for fine-tuning have been released, and the repository tree carries two sibling directories for that work, finetune/ and finetune_csv/, alongside a webui/ directory and a tests/ directory. Two directories for one task means the names alone do not tell you which to pick, and the news entry says nothing about the data format either one expects. The examples/ directory holds eleven scripts, among them a matched pair for Chinese data, get_akshare_date_2024-2025_x.py and prediction_akshare_2024-2025.py, plus several prediction variants. The last push to master is dated 2026-04-13 while the newest news entry is dated 2025.11.10, so whatever landed in between is not described in the log.

Editorial conclusion

Kronos suits researchers who already hold clean OHLCV frames and want a forecast to study, and the tokenizer plus checkpoint pairing is the first thing to understand. It is the wrong tool for execution: the predictor emits prices rather than orders, the 512 token ceiling truncates silently on the small and base checkpoints, and the 499.2M model is not published. Before trusting one run, count how many bars survived truncation, raise sample_count above one to see spread, and confirm which tokenizer the checkpoint was trained with.

Frequently asked questions

Official sources

1. Official README
2. Project repository