bonsai-gbt

bonsai

A histogram gradient-boosted tree library and CLI in modern C++23.

C++23 CMake

Documentation · Install · Guide · Decisions · Releases

What is bonsai?

bonsai is a from-scratch, histogram-based gradient boosted trees (GBT) library and command-line tool written in C++23. It pairs a small, concept-checked component API (objectives, growers, split finders, samplers) with compile-time dispatch in the training hot path, and ships the benchmark harness that pits it against XGBoost, LightGBM, and CatBoost on real data. The aim is a readable, thoroughly documented GBT: a reference-grade implementation that competes with the production libraries instead of merely tolerating comparison with them.

Compile-time dispatch, concept-checked components. The runtime TOML config resolves once to a monomorphized Booster<Objective, Grower, Splitter, Sampler>; no virtual calls in the hot path, and contract violations fail at compile time. Adding a component is a short recipe.
Six growers, one engine. depthwise (XGBoost-style), leafwise (LightGBM-style), levelwise (CatBoost-style), and their CUDA twins cuda_depthwise / cuda_leafwise / cuda_levelwise; with 7 objectives and 3 samplers the dispatch space is 126 statically-typed combinations, selectable per run from config.
Deterministic parallelism. Models are bit-identical across runs, thread counts, and even CPU architectures (arm64 == x86-64), a property no reference library offers, enforced per-commit in CI (the contract).
A guide, not just docs. The guide explains gradient boosting chapter by chapter: concept, math, then the ~50 real lines that implement it here, then an experiment against the reference libraries.

Install

pip install bonsai-gbt

Wheels cover Linux x86_64/aarch64 and macOS arm64, Python 3.9 to 3.13, no toolchain needed. The linux x86_64 wheel is CUDA-enabled at 2.3MB total: GPU training works out of the box on any NVIDIA driver R525+, it behaves exactly like a CPU wheel on machines without a GPU, and every release's CUDA wheel passes a live GPU validation before it ships (decision 70). The full story, docker image included, is Install; everything past a wheel (the CLI binary, development setups, CUDA source builds) is Building from source.

Quick start

import bonsai

model = bonsai.BonsaiRegressor(
    n_iters=200, learning_rate=0.05, grower="leafwise",
    early_stopping_rounds=20,
    params={"tree.lambda_l1": 0.5},   # any dotted config key the CLI accepts
)
model.fit(X_train, y_train, eval_set=(X_valid, y_valid))
pred = model.predict(X_test)
model.save("model.msgpack")           # loadable by `bonsai predict` and vice versa

The CLI (a source-build artifact) drives the same engine with the same keys and the same models:

bonsai fit      -c CONFIG --model OUT.msgpack
bonsai predict  -c CONFIG --model IN.msgpack [--data CSV] --out PREDS.csv
bonsai eval     -c CONFIG --model IN.msgpack [--data CSV]
bonsai info                        # list (objective, grower, sampler) combos
bonsai params                      # dump the default config as TOML

Any key overrides inline (bonsai fit -c config.toml --set tree.max_depth=8 --set dispatch.grower_name=levelwise ...), and make fit-benchmark trains and times bonsai against xgboost/lightgbm/catboost on California Housing in one command. The rest of the API is one read: the API tour.

Results

Two divisions, per the benchmark charter: perf (latency and memory, accuracy as a sanity guard) and quality (accuracy, timing never citable). The evidence is the results ledger, one generated page per study.

Perf

On GPU at the tall scenario, fit totals run depthwise 2.8s vs XGBoost 16.9s; leafwise 2.9s vs LightGBM 22.4s; levelwise 2.7s vs CatBoost 15.2s. On CPU at the tall scenario: depthwise 10.1s vs XGBoost 8.2s; leafwise 11.3s vs LightGBM 11.2s (tie); levelwise 10.6s vs CatBoost 9.1s. The wide and extreme scenarios, the host and device memory columns, and the early-stopping axis are on the panels page.

The panels, and the closed campaigns behind them, are in the ledger.

Quality

On the Grinsztajn et al. tabular benchmark (55 OpenML tasks selected by third parties, three seeds, matched knobs, best variant per library), every library on the CPU:

library	mean rank	outright wins
bonsai	1.49	35
lightgbm	2.40	6
xgboost	2.93	5
catboost	3.18	9

The same suite with every library on its GPU build:

library	mean rank	outright wins
bonsai	1.24	42
xgboost	2.29	7
catboost	2.47	6

lgbm_cuda is measured but not ranked: LightGBM's CUDA tree learner does not apply max_depth (LightGBM 4.7.0: the only depth check is the serial learner's BeforeFindBestSplit, which the CUDA Train loop never calls), so at the campaign knobs it grows 63 leaves at any depth where every other arm is capped at depth 6. Ranked among all arms it would read 1.71 with 38 outright wins. Its rows are read in the ledger.

bonsai leafwise against LightGBM head to head on the GPU, both at 63 leaves with no binding depth cap (the regime LightGBM's CUDA learner grows in, the ledger has the task-by-task table):

library	mean rank	outright wins
bonsai	1.42	32
lightgbm	1.58	23

bonsai keeps the lead under either reading of the one knob that translates ambiguously between libraries, which the standings page records; reproduce with pip install bonsai-gbt[bench], then python -m bonsai.bench.grinsztajn out.jsonl to run the suite and python -m bonsai.bench.grinsztajn out.jsonl --report to render the standings.

Every headline claim links a reproducible run and the decision that records it: claims and proofs.

Documentation

The home is daniel-m-campos.github.io/bonsai, four doors:

Learn: gradient boosting from intuition to the shipping code, one concept per chapter, each with an experiment against the reference libraries.
Use: install, the API in one read, parameters, building from source.
Results: the measurement discipline; its rules in the benchmark charter, its evidence in the results ledger.
Invariants: the contracts the engine holds, generated from the tests that prove them, beside the archive (decisions log).

The early planning records (proposal, context briefing, MVP retrospective) have been retired; git history holds them.

Project layout

include/bonsai/   public headers (Booster, Tree, Grower, Sampler, …)
src/              implementation + CLI (src/cli/)
python/           the bonsai package (bindings, encoding, bonsai.bench)
tests/unit/       Catch2 unit + parity tests (ctest)
benchmarks/       evidence docs + committed results data
scripts/          uv-managed Python: compare.py, probes, render_results.py
configs/          example TOML configs
docs/             the documentation site source + design records

License

Development Status
- 4 - Beta
Intended Audience
- Science/Research
License
- OSI Approved :: MIT License
Operating System
- MacOS
- POSIX :: Linux
Programming Language
- C++
- Python :: 3
Topic
- Scientific/Engineering :: Artificial Intelligence

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bonsai_gbt-2.3.0.tar.gz (2.4 MB view details)

Uploaded Sep 11, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

bonsai_gbt-2.3.0-cp313-cp313-manylinux_2_34_x86_64.manylinux_2_35_x86_64.whl (4.7 MB view details)

Uploaded Sep 11, 2026 CPython 3.13manylinux: glibc 2.34+ x86-64manylinux: glibc 2.35+ x86-64

bonsai_gbt-2.3.0-cp313-cp313-manylinux_2_34_aarch64.manylinux_2_35_aarch64.whl (2.2 MB view details)

Uploaded Sep 11, 2026 CPython 3.13manylinux: glibc 2.34+ ARM64manylinux: glibc 2.35+ ARM64

bonsai_gbt-2.3.0-cp313-cp313-macosx_14_0_arm64.whl (1.6 MB view details)

Uploaded Sep 11, 2026 CPython 3.13macOS 14.0+ ARM64

bonsai_gbt-2.3.0-cp312-cp312-manylinux_2_34_x86_64.manylinux_2_35_x86_64.whl (4.7 MB view details)

Uploaded Sep 11, 2026 CPython 3.12manylinux: glibc 2.34+ x86-64manylinux: glibc 2.35+ x86-64

bonsai_gbt-2.3.0-cp312-cp312-manylinux_2_34_aarch64.manylinux_2_35_aarch64.whl (2.2 MB view details)

Uploaded Sep 11, 2026 CPython 3.12manylinux: glibc 2.34+ ARM64manylinux: glibc 2.35+ ARM64

bonsai_gbt-2.3.0-cp312-cp312-macosx_14_0_arm64.whl (1.6 MB view details)

Uploaded Sep 11, 2026 CPython 3.12macOS 14.0+ ARM64

bonsai_gbt-2.3.0-cp311-cp311-manylinux_2_34_x86_64.manylinux_2_35_x86_64.whl (4.7 MB view details)

Uploaded Sep 11, 2026 CPython 3.11manylinux: glibc 2.34+ x86-64manylinux: glibc 2.35+ x86-64

bonsai_gbt-2.3.0-cp311-cp311-manylinux_2_34_aarch64.manylinux_2_35_aarch64.whl (2.2 MB view details)

Uploaded Sep 11, 2026 CPython 3.11manylinux: glibc 2.34+ ARM64manylinux: glibc 2.35+ ARM64

bonsai_gbt-2.3.0-cp311-cp311-macosx_14_0_arm64.whl (1.6 MB view details)

Uploaded Sep 11, 2026 CPython 3.11macOS 14.0+ ARM64

bonsai_gbt-2.3.0-cp310-cp310-manylinux_2_34_x86_64.manylinux_2_35_x86_64.whl (4.7 MB view details)

Uploaded Sep 11, 2026 CPython 3.10manylinux: glibc 2.34+ x86-64manylinux: glibc 2.35+ x86-64

bonsai_gbt-2.3.0-cp310-cp310-manylinux_2_34_aarch64.manylinux_2_35_aarch64.whl (2.2 MB view details)

Uploaded Sep 11, 2026 CPython 3.10manylinux: glibc 2.34+ ARM64manylinux: glibc 2.35+ ARM64

bonsai_gbt-2.3.0-cp310-cp310-macosx_14_0_arm64.whl (1.6 MB view details)

Uploaded Sep 11, 2026 CPython 3.10macOS 14.0+ ARM64

bonsai_gbt-2.3.0-cp39-cp39-manylinux_2_34_x86_64.manylinux_2_35_x86_64.whl (4.7 MB view details)

Uploaded Sep 11, 2026 CPython 3.9manylinux: glibc 2.34+ x86-64manylinux: glibc 2.35+ x86-64

bonsai_gbt-2.3.0-cp39-cp39-manylinux_2_34_aarch64.manylinux_2_35_aarch64.whl (2.2 MB view details)

Uploaded Sep 11, 2026 CPython 3.9manylinux: glibc 2.34+ ARM64manylinux: glibc 2.35+ ARM64

bonsai_gbt-2.3.0-cp39-cp39-macosx_14_0_arm64.whl (1.6 MB view details)

Uploaded Sep 11, 2026 CPython 3.9macOS 14.0+ ARM64

File details

Details for the file bonsai_gbt-2.3.0.tar.gz.

File metadata

Download URL: bonsai_gbt-2.3.0.tar.gz
Upload date: Sep 11, 2026
Size: 2.4 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bonsai_gbt-2.3.0.tar.gz
Algorithm	Hash digest
SHA256	`bb562bcc2ecab6c7febb0c213974ac0dbdc557415f8919424b616938c696ec63`
MD5	`6a8164ca7719ed0ae3b0278a21ef3e60`
BLAKE2b-256	`be210e0c9f49b009478ff189b1cc9a477f564380cc09293302b1ae64b9f644cc`

Algorithm	Hash digest
SHA256	`c9258781ec0a0e21522eac1e4b24850128da230ac5ac24eee18abbd676c0a3e9`
MD5	`dcf3fc68dc1f09c76efd42db902252e3`
BLAKE2b-256	`aba0c68c2978970ce50e743e45c7c1cba3fa12a0ef432173c4ca8ee61c0b3ded`

Algorithm	Hash digest
SHA256	`8fa7ebd034ed768451599b6b4257b002eb8a775314ab260bad6a129bf7af5628`
MD5	`656d560f6b7561ea44d9aedb9b04d399`
BLAKE2b-256	`8106bfe934aa26c312cff23beb6320bb9b1618f03cbe2293e8aed1819432c6d7`

Algorithm	Hash digest
SHA256	`8cbdd72f21d2cb742da227ff42947b6b6666104aeb336312f52cdd908175309d`
MD5	`ae6cd5cc472f92a97fd4e87fe6120481`
BLAKE2b-256	`7791581a63a9e0f6ccbc47bfb7191aa8815eda98b4a626bcf241a669b909149f`

Algorithm	Hash digest
SHA256	`ee928ad3866e7a0e5126835e722933d436d076b1b42a382579474af46d8a396c`
MD5	`f8533df474f4ed238ab31f6c0bc73667`
BLAKE2b-256	`1f5495fc9a30ff17c127d282996788a1b0dfad7ed98c8ed8d98d4cc13a6f6c5e`

Algorithm	Hash digest
SHA256	`46a9749efd83f3d980e00177b91e57fa9abfb53649f9b14f4980399e15c7c498`
MD5	`0f174f916bb2b021bc754c5c709f2666`
BLAKE2b-256	`06abfb8f5f1bc9f47d67e5e621e9e20f3cc51dfeaedcbf92140af414d4aed9e9`

Algorithm	Hash digest
SHA256	`95d8799524dd639d9366145056ea5ee1aedb58258fbf42565fb0f1bc0b1ed462`
MD5	`71f393048389efc008e0b186f6303504`
BLAKE2b-256	`7e1e4adb67e4ab6190db6649d18e8102e0c7a05b830fc31243837e609eb77821`

Algorithm	Hash digest
SHA256	`c11ad09de57f4d5f8559d0a4bc683250ac584f0c577827fc67842896e0a86a3c`
MD5	`ca675a9c842c9182862ecd64d67722f5`
BLAKE2b-256	`fb3959efd0e1f9f6fb252962618ffc4fa0000a8f590834ec0ce14ca0eb4931b8`

Algorithm	Hash digest
SHA256	`275039a989cb8c7b1abb75a4d8cb75446c66d4372b799d04af419811aa4b246b`
MD5	`0a35ce421643a7270cef401b1171fcc4`
BLAKE2b-256	`ad77bd24052bd844e42df1aeb3ee2d30b2696fd526df929e785be9f9f2a16dfb`

Algorithm	Hash digest
SHA256	`97fda569ec544de9d1a76a73fd9623097f23d2bfec4a9a77af52d5711282cd01`
MD5	`ef3677ba5e591aff9f3b78c522941906`
BLAKE2b-256	`d1b4e3b981629af900c39e4baacaa11b6074f4e730a299d2907a77fe66915dc8`

Algorithm	Hash digest
SHA256	`afc9674c974d743d92b64454ab4416812d819c8ba5e388cd2a30b1f2c29c11c6`
MD5	`5458f4b903d53a35f45db8b41cf5001b`
BLAKE2b-256	`d2e6a4300e4c9e4f9e5a180a65518d0d24679c66d97ee2499c15520022265fc4`

Algorithm	Hash digest
SHA256	`971db36ea91d29944dae4ba17d526951796f35e3aa3fc13f51bdafc9ff855401`
MD5	`ba8c2815dff60ca820265158189f1809`
BLAKE2b-256	`41de63ba907720921e39113f3bbf82e5c4a45abeccc6cd24217eefd6d490a7c9`

Algorithm	Hash digest
SHA256	`4646e55cee898de924dae7c23c7f0562dab7e411d04b4432b8bbc4e320261c40`
MD5	`cb225b98b6990f91dd5a8584dab4ebe6`
BLAKE2b-256	`2c7a9f3edd9891f81ae2eb65046a30b2df04e7976b04b69512c8578baa2cb53f`

Algorithm	Hash digest
SHA256	`38e21a8e9b4ec0000241489c18e6d9dc6210f7084421787a04da8306e59735d9`
MD5	`966eff1e62b2a36f3710c60e85579d52`
BLAKE2b-256	`0a954c2867e8a241df30704ba91aea3563d25ae34bafb59884464b712b068d07`

Algorithm	Hash digest
SHA256	`84de2088281aa2421980dd504b135a4543ad4024cc8a9d237e48bdb4d7d6551a`
MD5	`c143f38e06b8c6878346f8a7a8ffb506`
BLAKE2b-256	`61b1f4ef9a7ad67ee1d75d2c20559e4eb07e249c6362e93a88fd9098bec2fc06`

Algorithm	Hash digest
SHA256	`b7b4a5ee80e575598b1bcf1e6accc5c8ecb4600f88db0b63d15593339ff0a167`
MD5	`43d7eb4be2cd23cd531b926702a34bae`
BLAKE2b-256	`bfd6a03510c02e5a281af169bd618c6380ef53b66435d0989001453827b9da80`

bonsai-gbt 2.3.0

What is bonsai?

Install

Quick start

Results

Perf

Quality

Documentation

Project layout

License

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details