🔥 Bankai Random Forest

BankaiRF is a high-performance Random Forest engine powered by a native Rust core. By leveraging LightGBM-style histograms for continuous feature pre-processing, it delivers fast and efficient training while maintaining full compatibility with the familiar scikit-learn estimator API. The Rust core is based on a maintained fork of XRF, the engine behind FRU.

⚠️ BankaiRF is currently in Alpha. APIs and serialized models are subject to change.

Install

Python 3.11 or newer is required. Install the package from PyPI:

python -m pip install bankai-random-forest

Quick start

This example uses the Covertype forest-cover dataset, which has 581,012 rows and 54 named features. It samples 100,000 rows with seed 2077, then treats cover type 2 as the positive class and all other cover types as the negative class. The dataset is provided by scikit-learn and downloaded on first use. Dataset details

import pandas as pd
from sklearn.datasets import fetch_covtype
from sklearn.metrics import f1_score, roc_auc_score
from sklearn.model_selection import train_test_split

from bankai_random_forest import BankaiRandomForestClassifier

covertype = fetch_covtype(as_frame=True)
X = covertype.data
y = (covertype.target == 2).astype("int8")

X, _, y, _ = train_test_split(
    X, y, train_size=100_000, random_state=2077, stratify=y
)

X_train, X_test, y_train, y_test = train_test_split(
    X, y, test_size=0.2, random_state=2077, stratify=y
)

model = BankaiRandomForestClassifier(
    n_estimators=40,
    criterion="gini",
    max_depth=20,
    max_leaf_nodes=511,
    min_samples_leaf=5,
    max_features=None,
    bootstrap=True,
    max_samples=0.8,
    n_jobs=-1,
    random_state=2077,
    importance_type="permutation", # Native permutation importance
    max_bins=63, # Enable histogram binning
)
model.fit(X_train, y_train)

predictions = model.predict(X_test)
positive_class = list(model.classes_).index(1)
probabilities = model.predict_proba(X_test)[:, positive_class]
print(f"F1: {f1_score(y_test, predictions):.3f}")
print(f"ROC-AUC: {roc_auc_score(y_test, probabilities):.3f}")

importances = pd.Series(model.feature_importances_, index=X.columns, name="importance")
print(importances.sort_values(ascending=False).head(10))

The pandas DataFrame keeps the 54 original feature names, so the feature importances are labeled with names such as Elevation, Aspect, and Slope.

Classifier reference

BankaiRandomForestClassifier follows scikit-learn's estimator pattern. The defaults and parameter meanings are listed here; behavior marked as a Bankai limitation is intentionally called out because it differs from scikit-learn.

from bankai_random_forest import BankaiRandomForestClassifier

model = BankaiRandomForestClassifier(
    n_estimators=100,
    criterion="gini",
    max_depth=None,
    min_samples_split=2,
    min_samples_leaf=1,
    min_weight_fraction_leaf=0.0,
    max_features="sqrt",
    max_leaf_nodes=None,
    min_impurity_decrease=0.0,
    bootstrap=True,
    oob_score=False,
    n_jobs=None,
    random_state=None,
    verbose=0,
    warm_start=False,
    class_weight=None,
    ccp_alpha=0.0,
    max_samples=None,
    monotonic_cst=None,
    importance_type="gain",
    max_bins=None,
    binning_strategy="exact_sort",
    bin_sample_size=200_000,
    binning_seed=6,
    extra_trees=False,
    extra_seed=6,
)

extra_trees=True works with exact splits (max_bins=None) and histogram splits. In exact mode, a single continuous threshold is sampled uniformly between the node's observed minimum and maximum for each feature considered. If it cannot satisfy the leaf constraints, that feature does not split the node. In histogram mode, one bin threshold is sampled as before. This option currently applies to classification.

binning_seed only affects sampled binning strategies and does not change tree bootstrap or feature-sampling randomness. It lets repeated experiments vary the rows used to build histogram cut points independently of the forest's random_state.

Call fit(X, y, sample_weight=None) to train. sample_weight accepts one finite, non-negative weight per row. The fitted estimator exposes scikit-learn-style methods including predict, predict_proba, and predict_log_proba, plus classes_, feature_importances_, n_features_in_, and feature_names_in_ when the input has named columns.

predict_proba returns one probability array for a single target and a list of arrays for multioutput targets. monotonic_cst is not supported for multioutput classification. oob_score=True computes accuracy; to use another metric, pass a callable with signature metric(y_true, y_pred).

Regressor

BankaiRandomForestRegressor follows the RandomForestRegressor parameter defaults and supports single and multioutput regression. Regression currently delegates training and prediction to scikit-learn; max_bins, binning_strategy, and bin_sample_size are accepted for API consistency but do not affect regression training. The supported criteria are squared_error, absolute_error, and poisson; Poisson targets must be nonnegative and have a positive sum. With importance_type="permutation", set oob_score=True; importance is the decrease in R² from aggregated OOB predictions.

Development

To build and run the project locally, install Git, Python 3.11 or newer, a stable Rust toolchain, and uv. On Windows, install the Rust MSVC build tools; on macOS, install the Xcode command-line tools.

Clone the repository and create the locked development environment:

git clone https://github.com/breno-jesus-fernandes/bankai-random-forest.git
cd bankai-random-forest
uv python install 3.11
uv sync --locked --no-install-project
uv run maturin develop --release --locked

Run the Python and Rust test suites from the repository root:

uv run pytest -q
uv run cargo test --workspace --locked

Benchmark scripts use an additional dependency group. Install it when needed with uv sync --locked --group benchmark. All commands use the versions recorded in uv.lock and Cargo.lock.

Contributors are expected to follow the Code of Conduct. See the contribution guide for the fork and pull request workflow, local checks, and maintainer review expectations.

License

Bankai is licensed under GPL-3.0-or-later. The maintained XRF fork is also GPL-3.0-or-later; see NOTICE for upstream attribution.