kronos-finance

Pythonic wrapper around the Kronos foundation model for OHLCV forecasting across any market.

Built on Kronos

Kronos is the first open-source foundation model for financial candlesticks (K-lines), by the NeoQuasar team, accepted at AAAI 2026, MIT-licensed.

This package (kronos-finance) is a wrapper that turns the upstream research codebase into a pip-installable library with a CLI, a dashboard, multi-source data loaders, and comprehensive tests. All model code comes from the original project — see the Citation section.

• Original repo: https://github.com/shiyu-coder/Kronos
• Paper: https://arxiv.org/abs/2508.02739
• Model zoo on HuggingFace: https://huggingface.co/NeoQuasar

Use a virtual environment (recommended)

A virtual environment keeps your system Python clean and avoids the error: externally-managed-environment (PEP 668) error on Ubuntu 23.04+, macOS Homebrew Python, and Fedora 39+.

python -m venv .venv
source .venv/bin/activate          # macOS / Linux
# .venv\Scripts\activate           # Windows PowerShell

Every install command below assumes you've activated a venv first.

Installation

pip install kronos-finance                       # core (CUDA-enabled PyTorch, ~800MB)
pip install kronos-finance[cn]                   # + AKShare for Chinese A-shares
pip install kronos-finance[global]               # + yfinance for global equities
pip install kronos-finance[crypto]               # + CCXT for crypto exchanges
pip install kronos-finance[qlib]                 # + Qlib for CN finetune data
pip install kronos-finance[ui]                   # + Flask + Plotly for the dashboard
pip install kronos-finance[analysis]             # + pandas-ta + quantstats
pip install kronos-finance[all]                  # everything above

The default install includes CUDA-enabled PyTorch and works on CPU or GPU. For CPU-only or a specific CUDA version, see Hardware below before installing.

Verify the install:

kronos --version

Quickstart (60 seconds)

from kronos_finance import load_kronos
from kronos_finance.data import load_ohlcv
import pandas as pd

df = load_ohlcv("AAPL", period="2y", interval="1d")
wrapper = load_kronos(model_id="small")
y_ts = pd.date_range(df["timestamps"].iloc[-1], periods=31, freq="1D")[1:]
pred = wrapper.predict(
    df=df[["open", "high", "low", "close", "volume", "amount"]].tail(400),
    x_timestamp=df["timestamps"].tail(400), y_timestamp=y_ts, pred_len=30,
)
print(pred.head())

Features

• One-line predict on any market — US equities, CN A-shares, crypto, HK, JP, EU.
• Multi-source loaders — AKShare, yfinance, CCXT, Qlib, local CSV.
• Ticker auto-detection — type "600519" and AKShare is picked; type "BTC/USDT" and CCXT is picked.
• Bundled ticker catalog + user-extendable ~/.kronos/tickers.json.
• CLI: kronos predict, kronos backtest, kronos ui, kronos tickers.
• Flask dashboard with candlestick chart, autocomplete, model selector, indicator overlay.
• Optional indicators (RSI, MACD, BBands) and HTML tearsheets (quantstats).
• 12 runnable examples + comprehensive docs + a 35-term glossary.

How to predict any ticker in the world

Market	Ticker format	Source	Install extra
US equity	AAPL, MSFT, NVDA	yfinance	[global]
US ETF	SPY, QQQ, IWM	yfinance	[global]
US index	^GSPC, ^DJI, ^IXIC	yfinance	[global]
CN A-share	600519, 000001, 002594	AKShare	[cn]
CN index	000300, 000905	AKShare	[cn]
Crypto pair	BTC/USDT, ETH/USDT	CCXT (Binance default)	[crypto]
HK stock	0700.HK, 9988.HK	yfinance	[global]
JP stock	7203.T, 6758.T	yfinance	[global]
EU stock	ASML.AS, SAP.DE	yfinance	[global]
Local CSV	path to .csv	csv_path=	(core)

The source="auto" default routes the ticker to the right loader based on its shape.

CLI reference

kronos predict TICKER [--source auto] [--model small] [--interval 1d]
                     [--pred-len 30] [--lookback 400] [--export forecast.csv]
                     [--device cpu]
kronos batch TICKERS_FILE [--output ./out] [--model small] [--pred-len 30]
kronos backtest TICKER [--period 1y] [--interval 1d] [--source auto]
                      [--export tearsheet.html]
kronos ui [--host 127.0.0.1] [--port 5000] [--debug]
kronos tickers list
kronos tickers search QUERY [--market cn|us|crypto|...]
kronos tickers add SYMBOL NAME SOURCE [--exchange binance]
kronos --version
kronos --help

Examples:

kronos predict 600519 --source akshare
kronos predict BTC/USDT --source ccxt --exchange binance

Exit codes: 0 ok, 1 generic error, 2 usage error, 130 SIGINT (clean Ctrl+C).

Python API

from kronos_finance import load_kronos          # model
from kronos_finance.data import load_ohlcv       # data fetchers
from kronos_finance.tickers import catalog, search, add_user_ticker
from kronos_finance.analysis import (
    enrich_with_indicators, forecast_to_returns, make_tearsheet,
)
from kronos_finance import (                      # errors
    KronosFinanceError, TickerNotFoundError,
    DataSourceError, ModelLoadError, PredictionError, CatalogError,
)

Full reference: docs/API.md.

Dashboard

Launch with kronos ui (default http://127.0.0.1:5000):

• Ticker input with autocomplete from the bundled + user catalog.
• Candlestick chart with historical in green/red and forecast in blue/purple.
• Model selector (mini / small / base with parameter counts).
• Source + interval pickers.
• Indicator overlay (RSI / MACD / BBands).
• Recent predictions history with CSV export.
• Dark / light theme toggle.

Full tour: docs/DASHBOARD.md.

Examples

Twelve runnable examples in examples/. Each starts with the venv setup reminder. See examples/README.md.

Troubleshooting

The most common pitfalls — full list in docs/TROUBLESHOOTING.md:

• error: externally-managed-environment — you're trying to pip install into system Python. Use a venv (see the section at the top of this README).
• Model download stalls / 401 from HuggingFace — set HF_TOKEN or run huggingface-cli login.
• CUDA version mismatch — install PyTorch from the matching CUDA index URL.
• yfinance rate limit — switch to auto source or add period= to limit.
• AKShare returns empty — the ticker may have delisted. Try yfinance with 600519.SS.
• Playwright browser missing — playwright install --with-deps chromium.
• max_context exceeded — reduce lookback or use Kronos-mini (2048 context).
• Tz-aware timestamp warning — convert to UTC and drop the tz before passing in.
• PermissionError on Windows — run your terminal as Administrator or use a venv.

Hardware (CPU vs CUDA)

Kronos runs on both CPU and CUDA GPUs. The default pip install kronos-finance installs the standard PyPI torch wheel, which is CUDA-enabled by default and works on either. There's no separate "GPU version" of kronos-finance.

You pick the device at runtime via --device (CLI) or device= (Python):

kronos predict AAPL --device cpu       # default; works everywhere
kronos predict AAPL --device cuda     # first GPU
kronos predict AAPL --device cuda:0   # specific GPU

wrapper = load_kronos(model_id="small", device="cuda")

Which device should I use?

Model	Params	CPU latency (30-step forecast)	CUDA latency	Recommendation
Kronos-mini	4.1M	~2s	~0.2s	Either works
Kronos-small	24.7M	~5s	~0.3s	Either works
Kronos-base	102.3M	~15s	~1s	CUDA recommended

Memory

• CPU: ~1 GB RAM for small, +500 MB for base.
• CUDA: ~1 GB VRAM for small, ~2 GB VRAM for base. An RTX 3060 (12 GB) is plenty.

Pinning your CUDA version

If you have an NVIDIA GPU, install PyTorch from the matching CUDA index URL before installing kronos-finance to control which CUDA toolkit version is bundled:

# CUDA 12.1 — match your NVIDIA driver
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install kronos-finance[global]

# CUDA 11.8
pip install torch --index-url https://download.pytorch.org/whl/cu118
pip install kronos-finance[global]

# CPU-only (smaller download, ~200 MB instead of ~800 MB)
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install kronos-finance[global]

Apple Silicon (M1/M2/M3)

pip install kronos-finance on Apple Silicon uses PyTorch's MPS backend automatically. Pass --device mps in the CLI or device="mps" in the API.

Common CUDA errors

• CUDA error: no kernel image is available — your PyTorch CUDA version doesn't match your NVIDIA driver. Reinstall PyTorch from the matching index URL above.
• CUDA out of memory — your GPU is too small. Use Kronos-mini or reduce lookback. On CPU there's no such limit (just slower).
• CUDA unavailable but requested — your install doesn't have CUDA support, or no GPU is visible. nvidia-smi to check.

How it works

Ticker (e.g. "AAPL")
    │
    ▼  load_ohlcv() auto-detects source -> yfinance
pd.DataFrame [timestamps, open, high, low, close, volume, amount]
    │
    ▼  load_kronos() downloads Kronos-small from HuggingFace
KronosWrapper (model + tokenizer + predictor)
    │
    ▼  wrapper.predict() runs autoregressive Transformer
pd.DataFrame [predicted OHLCV]
    │
    ▼  analysis: indicators + backtest -> HTML tearsheet

Performance & limits

Setting	Default	Cap	Note
pred_len	30	1000 (CLI), no cap in API	Larger = slower inference
lookback	400	512 (small/base/large), 2048 (mini)	Auto-truncated
sample_count	1	20	Quantile bands need >1
Memory (CPU, small)	~1GB	—	+500MB for base
Memory (CUDA, base)	~2GB VRAM	—	RTX 3060+ recommended
Latency (CPU, 30-step, 1 ticker)	~5s	—	~1s on CUDA

Development

git clone https://github.com/lordxmen2k/kronos-finance.git
cd kronos-finance
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,test,ui]"
pytest                         # unit + CLI tests
ruff check src/                # lint

See docs/CONTRIBUTING.md.

Citation

If you use this in research, please cite the original Kronos paper:

@inproceedings{kronos2026,
  title  = {Kronos: A Foundation Model for the Language of Financial Markets},
  author = {Shi, Yu and others},
  booktitle = {AAAI},
  year   = {2026},
}

And this wrapper:

@software{kronos_finance,
  author = {lordxmen2k},
  title  = {kronos-finance: A Python wrapper for Kronos},
  year   = {2026},
  url    = {https://github.com/lordxmen2k/kronos-finance}
}

License

MIT — see LICENSE for the full text. The original Kronos project is also MIT; see src/kronos_finance/_vendor/LICENSE_KRONOS for the vendored upstream license.

Acknowledgements

• The NeoQuasar team for the Kronos foundation model.
• HuggingFace for model hosting.
• AKShare, yfinance, CCXT, Qlib — the data layer.
• pandas-ta, quantstats — analysis.
• Plotly, Flask — the dashboard.

Glossary

See docs/INSTALL.md#glossary for the full 35-term glossary. A quick index of the most important ones:

• OHLCV — Open, High, Low, Close, Volume. The five columns Kronos expects.
• K-line — Chinese term for candlestick; same thing.
• Context length / max_context — maximum past bars the model can see (512 for small/base/large; 2048 for mini).
• AR / autoregressive — generates outputs one step at a time.
• Tokenizer — converts continuous OHLCV to discrete tokens before the Transformer.
• Sample count — number of forecast paths to draw; more = smoother quantile band.
• Tearsheet — one-page performance report; quantstats generates HTML.
• Nucleus sampling (top-p) — sampling from smallest token set whose cumulative prob ≥ p.
• Temperature (T) — sampling temperature; T<1 conservative, T>1 exploratory.
• Quantile band — uncertainty interval drawn when sample_count > 1.
• PEP 668 — Python spec marking system Python as externally managed; use venv.
• Twine — twine upload dist/* publishes to PyPI.
• Wheel (.whl) — built distribution format.