The Problem

Kronos addresses the challenge of applying foundation models to financial time series. General-purpose time-series models struggle with the high-noise, multi-dimensional nature of candlestick (OHLCV) data. Kronos uses a two-stage approach: a specialized tokenizer quantizes continuous K-line data into hierarchical discrete tokens, and an autoregressive Transformer is pre-trained on those tokens. The upstream project (37k stars, AAAI 2026) provides the model; this fork adds fine-tuning scripts and a web UI.

What This Does

The repository is a portfolio of five self-contained projects, not a single codebase:

  • model/ – Core model implementation: kronos.py (the transformer, tokenizer, encode/decode) and module.py (building blocks like RMSNorm, quantize).
  • finetune/ – Fine-tuning scripts for the base model and tokenizer, including Qlib data preprocessing.
  • finetune_csv/ – Fine-tuning pipeline for CSV data, with a config loader (config_loader.py), a sequential trainer (train_sequential.py), and a sample dataset (HK Alibaba 5-min klines).
  • examples/ – Prediction scripts for various data sources (AkShare, EastMoney, BaoStock) and a GUI (prediction_new_GUI.py).
  • webui/ – A Flask app (app.py) for interactive prediction and visualization.

How It Is Wired

Execution starts at main in webui/run.py:38, which reaches 97 functions. The Flask app (webui/app.py) exposes predict (called from 8 places) as the primary API. The critical path is short: main -> train_model touches the filesystem via os.makedirs, and predict -> save_prediction_results writes results to disk.

The hub module is model/__init__.py – 14 modules depend on it, making it high-blast-radius. model/kronos.py is the core, called from 9 files, and performs model inference. examples/get_akshare_date_2024-2025_x.py is the most externally connected: it makes network calls, reads/writes files, runs external commands, and invokes the model.

The webui/app.py has debug=True hardcoded – a security risk. The call graph shows run_comprehensive_prediction_gui -> update_progress called 27 times, indicating a long-running training loop with progress reporting.

How To Use It

Setup: Install dependencies from requirements.txt (and webui/requirements.txt for the UI). A lockfile is absent, so builds are not reproducible.

Running the web UI:

pip install -r requirements.txt
pip install -r webui/requirements.txt
python webui/run.py

Fine-tuning on CSV data: The finetune_csv/ directory has its own README (README.md, README_CN.md) and a YAML config (configs/config_ali09988_candle-5min.yaml). Run finetune_csv/train_sequential.py with that config.

Examples: Each script in examples/ is self-contained; e.g., python examples/prediction_example.py.

Real-World Use

A quant researcher wants to forecast HK stock prices from 5-minute klines. They use finetune_csv/ to adapt the pre-trained Kronos model to their CSV data, then deploy it via the Flask web UI for analysts to query. The webui/app.py handles data loading, prediction, and result saving, with charts generated via create_prediction_chart.

Code Health & Issues

Static analysis (24 findings: 10 high, 13 medium, 1 low) identifies:

  • High – deep nesting: model/kronos.py, model/module.py have max indentation depth 10; control flow is hard to follow.
  • High – duplicated code: 765 repeated 6-line blocks across 17 files in examples/; extract shared helpers.
  • Medium – hub module: model/__init__.py has 14 dependents; keep it stable.
  • Medium – resource leaks: webui/run.py opens files without context managers.
  • Medium – broad exception handling: examples/prediction_new.py, finetune_csv/train_sequential.py swallow errors.
  • Medium – oversized files: examples/prediction_new.py and prediction_new_GUI.py exceed 970 lines each.

SDLC observations: no CI/CD pipeline, no lockfile, and a 5.6MB CSV committed to the repo. The Flask app runs with debug=True – a production risk.

The Bottom Line

Kronos is a serious research artifact with a solid core model, but this fork is a collection of scripts rather than a maintained codebase. The duplication and lack of CI make it risky to extend. Use it for experimentation and fine-tuning research, not for production deployment without significant hardening.