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 (CPU, ~400MB incl. PyTorch)
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

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.

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.