🔥 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_trees_backend="exact",
    extra_seed=6,
)

extra_trees=True samples a continuous threshold uniformly between the node's original observed minimum and maximum for each feature considered. With the default extra_trees_backend="exact", max_bins must be None; setting an integer raises ValueError. Opt into the experimental binned backend explicitly to use bins. Features are sampled without replacement; constants are inherited by descendants, and search continues when needed to find a valid partition. Bootstrap uses effective sample weights as sampling probabilities and counts distinct sampled rows for leaf limits. Gain importance is normalized within each tree before aggregation. This option currently applies to classification. See the campaign notes for validation and profiling.

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).

Experimental binned Extra Trees

model = BankaiRandomForestClassifier(
    extra_trees=True,
    extra_trees_backend="binned",
    max_bins=63,
    bootstrap=True,
    n_jobs=6,
    random_state=42,
)
model.fit(X, y)

This backend stores dense bins by column and, for binary classification, accumulates per-feature bin statistics in one pass. It does not build the global histogram caches used by Random Forest. Sparse training input is rejected without densification. Prediction, OOB, gain importance, SHAP and pickle restoration retain the backend. Multiclass inputs use the generic random split scan on column-major bins.

The default is extra_trees_backend="exact", not None. It uses original values and requires max_bins=None. The example above explicitly enables column-major bins and uses the existing exact_sort preparation default on all training rows. To opt into sampled preparation, set binning_strategy="sampled_select" and bin_sample_size=20_000. Both preparation options include layout conversion in fit.

Binning changes the distribution of random thresholds and can reduce ranking quality. Three paired local fraud repetitions with 500,000 rows, 500 features, 100 trees, bootstrap enabled and six jobs produced these medians:

These are screening results for one synthetic scenario, not a quality guarantee. AP here evaluates informative-feature ranking, not classification precision-recall. The standard binning_strategy="exact_sort" and bin_sample_size=200_000 defaults are unchanged. The sample-size limit applies only to sampled strategies.

The layout conversion is included in fit time and temporarily allocates another one-byte-per-cell matrix. Random Forest (extra_trees=False) retains row-major bins; extra_trees_backend="binned" is rejected for that mode.

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.