bun-scikit

Scikit-learn-inspired machine learning for Bun + TypeScript, with native Zig acceleration for core training paths.

bun add bun-scikit

Create index.ts:

import { DecisionTreeClassifier, RandomForestClassifier } from "bun-scikit";

const X = [
  [0, 0],
  [0, 1],
  [1, 0],
  [2, 2],
  [2, 3],
  [3, 2],
];
const y = [0, 0, 0, 1, 1, 1];

const tree = new DecisionTreeClassifier({ maxDepth: 3, randomState: 42 });
tree.fit(X, y);
console.log("DecisionTree fit backend:", tree.fitBackend_, tree.fitBackendLibrary_);

const forest = new RandomForestClassifier({ nEstimators: 25, maxDepth: 4, randomState: 42 });
forest.fit(X, y);
console.log("RandomForest fit backend:", forest.fitBackend_, forest.fitBackendLibrary_);

Run:

bun run index.ts

Expected output includes fit backend: zig for both models.

Repo example: examples/zig-backend-smoke.ts

import {
  LinearRegression,
  LogisticRegression,
  StandardScaler,
  trainTestSplit,
  meanSquaredError,
  accuracyScore,
} from "bun-scikit";

const X = [[1], [2], [3], [4], [5], [6]];
const yReg = [3, 5, 7, 9, 11, 13];
const yCls = [0, 0, 0, 1, 1, 1];

const scaler = new StandardScaler();
const Xs = scaler.fitTransform(X);

const { XTrain, XTest, yTrain, yTest } = trainTestSplit(Xs, yReg, {
  testSize: 0.33,
  randomState: 42,
});

const reg = new LinearRegression({ solver: "normal" });
reg.fit(XTrain, yTrain);
console.log("MSE:", meanSquaredError(yTest, reg.predict(XTest)));

const clf = new LogisticRegression({
  solver: "gd",
  learningRate: 0.8,
  maxIter: 100,
  tolerance: 1e-5,
});
clf.fit(Xs, yCls);
console.log("Accuracy:", accuracyScore(yCls, clf.predict(Xs)));

• Models: LinearRegression, LogisticRegression, LogisticRegressionCV, Ridge, RidgeClassifier, RidgeClassifierCV, Lasso, ElasticNet, RidgeCV, LassoCV, ElasticNetCV, BayesianRidge, ARDRegression, Perceptron, PassiveAggressiveClassifier, PassiveAggressiveRegressor, HuberRegressor, PoissonRegressor, GammaRegressor, QuantileRegressor, RANSACRegressor, TweedieRegressor, MultiTaskLasso, MultiTaskElasticNet, MultiTaskLassoCV, MultiTaskElasticNetCV, KNeighborsClassifier, DecisionTreeClassifier, RandomForestClassifier, plus additional parity models (LinearSVC, GaussianNB, SGDClassifier, SGDRegressor, regressors for tree/forest, OneClassSVM).
• Clustering / decomposition / manifold: KMeans, MiniBatchKMeans, DBSCAN, AgglomerativeClustering, SpectralClustering, Birch, OPTICS, MeanShift, AffinityPropagation, PCA, IncrementalPCA, TruncatedSVD, FastICA, NMF, MiniBatchNMF, FactorAnalysis, KernelPCA, PLSSVD, PLSRegression, PLSCanonical, CCA, TSNE, Isomap, LocallyLinearEmbedding, MDS.
• Anomaly detection: IsolationForest, LocalOutlierFactor, OneClassSVM.
• Calibration / meta-estimators: CalibratedClassifierCV, VotingClassifier, VotingRegressor, StackingClassifier, StackingRegressor, BaggingClassifier.
• Gaussian process / isotonic: GaussianProcessRegressor, GaussianProcessClassifier, IsotonicRegression.
• Multioutput: MultiOutputClassifier, MultiOutputRegressor, ClassifierChain, RegressorChain.
• Boosting: AdaBoostClassifier, GradientBoostingClassifier, GradientBoostingRegressor, HistGradientBoostingClassifier, HistGradientBoostingRegressor.
• Baselines: DummyClassifier, DummyRegressor.
• Neighbors / Bayes additions: BallTree, KDTree, KNeighborsTransformer, RadiusNeighborsTransformer, NearestCentroid, NeighborhoodComponentsAnalysis, BernoulliNB, MultinomialNB, ComplementNB, CategoricalNB.
• Covariance additions: EllipticEnvelope, GraphicalLasso, GraphicalLassoCV.
• Preprocessing: StandardScaler, MinMaxScaler, RobustScaler, MaxAbsScaler, Normalizer, Binarizer, LabelEncoder, LabelBinarizer, MultiLabelBinarizer, PolynomialFeatures, SimpleImputer, OneHotEncoder, FunctionTransformer, KernelCenterer, plus functional helpers (addDummyFeature, binarize, scale, minmaxScale, maxabsScale, robustScale).
• Feature extraction: DictVectorizer, FeatureHasher.
• Composition: Pipeline, ColumnTransformer, FeatureUnion.
• Feature selection: VarianceThreshold, SelectKBest, SelectPercentile, SelectFromModel, RFE, RFECV, chi2, f_classif, f_regression, mutualInfoClassif, mutualInfoRegression.
• Model selection: trainTestSplit, KFold, GroupKFold, GroupShuffleSplit, ShuffleSplit, StratifiedKFold, StratifiedGroupKFold, StratifiedShuffleSplit, RepeatedKFold, RepeatedStratifiedKFold, LeaveOneOut, LeavePOut, LeaveOneGroupOut, LeavePGroupsOut, PredefinedSplit, TimeSeriesSplit, crossValScore, crossValidate, crossValPredict, learningCurve, validationCurve, GridSearchCV, RandomizedSearchCV, ParameterGrid, ParameterSampler.
• Metrics: regression/classification metrics plus ranking and curve helpers (auc, averagePrecisionScore, classLikelihoodRatios) and clustering metrics (silhouetteScore, calinskiHarabaszScore, daviesBouldinScore, adjustedRandScore).
• Inspection: permutationImportance, partialDependence, permutationTestScore.

Parity status is aligned across runtime exports, matrix contracts, and docs coverage.

Source of required runtime surface: docs/parity-matrix.json (209 total runtime exports).

Tracked parity status (latest check):

• API surface parity: 209 / 209 required exports (100%).
• API/class/interface contract parity: 0 failures (100% pass).
• API docs coverage: 470 / 470 exported symbols referenced in docs/api.md (100%).
• sklearn snapshot parity gate metrics: 34 / 34 pass (100%).
• Full sklearn public-symbol coverage (non-strict inventory gate): 203 / 454 (44.71%).

Artifacts:

• bench/results/parity/parity-report-latest.md
• bench/results/parity/parity-matrix-report.json
• bench/results/parity/parity-sklearn-report.json
• bench/results/parity/parity-full-report.json
• docs/sklearn-public-api.json

Commands:

• Regenerate sklearn inventory: bun run parity:inventory:generate
• Check runtime export + contract matrix parity: bun run parity:matrix:check
• Check docs symbol coverage: bun run docs:coverage:check
• Check full symbol coverage (report only): bun run parity:full:check
• Enforce strict full-symbol gate: PARITY_FULL_STRICT=1 bun run parity:full:check

Beyond the tracked matrix, remaining gaps to full scikit-learn-wide one-to-one behavior are mainly untracked modules and APIs, including:

• Feature extraction families (for example text/image vectorizers and hashing/vectorization utilities).
• Additional decomposition/manifold variants and solvers not currently exposed.
• Additional covariance and gaussian-process families.
• Additional inspection/display/reporting utilities and plotting-oriented helpers.
• Dataset utilities and other sklearn ecosystem helpers outside this runtime-focused library surface.

Multiclass support is available for GaussianNB, KNeighborsClassifier, LogisticRegression, SGDClassifier, LinearSVC, DecisionTreeClassifier, RandomForestClassifier, VotingClassifier, StackingClassifier, BaggingClassifier, and CalibratedClassifierCV.

DecisionTreeClassifier and RandomForestClassifier now support multiclass native Zig fit/predict paths (up to 256 encoded classes) when BUN_SCIKIT_TREE_BACKEND=zig.

• Prebuilt binaries are bundled in the npm package for:
  • linux-x64
  • windows-x64
• No bun pm trust step is required for standard install/use.
• macOS prebuilt binaries are not published yet.

Optional env vars:

• BUN_SCIKIT_NATIVE_BRIDGE=node-api|ffi
• BUN_SCIKIT_NODE_ADDON=/absolute/path/to/bun_scikit_node_addon.node
• BUN_SCIKIT_ZIG_LIB=/absolute/path/to/bun_scikit_kernels.<ext>
• BUN_SCIKIT_TREE_BACKEND=zig|js (default is zig; set js to force JS tree/forest fallback)

Parity checks are enforced in CI using:

• API parity matrix coverage (bun run parity:matrix:check)
• sklearn snapshot fixtures with multi-seed drift checks (bun run parity:check)
• versioned parity report artifacts (bun run parity:report)

Benchmark snapshot source: bench/results/heart-ci-latest.json (generated in CI workflow Benchmark Snapshot). Dataset: test_data/heart.csv (1025 samples, 13 features, test fraction 0.2).

• Regression: fit 2.888x, predict 6.954x (MSE delta 6.363e-14, R2 delta -2.540e-13)
• Classification: fit 1.866x, predict 4.905x (accuracy delta 0.000e+0, F1 delta 1.106e-3)
• DecisionTree (js-fast): fit 1.561x, predict 7.306x
• RandomForest (js-fast): fit 3.183x, predict 4.077x
• Tree backend matrix: DecisionTree zig/js fit 0.821x, predict 0.504x; RandomForest zig/js fit 1.138x, predict 1.868x
• Snapshot generated at 2026-07-20T11:44:17.006Z

Bun fit speedup vs scikit-learn: 2.888x Bun predict speedup vs scikit-learn: 6.954x MSE delta (bun - sklearn): 6.363e-14 R2 delta (bun - sklearn): -2.540e-13

Bun fit speedup vs scikit-learn: 1.866x Bun predict speedup vs scikit-learn: 4.905x Accuracy delta (bun - sklearn): 0.000e+0 F1 delta (bun - sklearn): 1.106e-3

DecisionTree fit speedup vs scikit-learn: 1.561x DecisionTree predict speedup vs scikit-learn: 7.306x DecisionTree accuracy delta (bun - sklearn): 4.878e-3 DecisionTree f1 delta (bun - sklearn): 3.837e-3

RandomForest fit speedup vs scikit-learn: 3.183x RandomForest predict speedup vs scikit-learn: 4.077x RandomForest accuracy delta (bun - sklearn): 0.000e+0 RandomForest f1 delta (bun - sklearn): 1.110e-16

DecisionTree zig/js fit speedup: 0.821x DecisionTree zig/js predict speedup: 0.504x RandomForest zig/js fit speedup: 1.138x RandomForest zig/js predict speedup: 1.868x

Snapshot generated at: 2026-07-20T11:44:17.006Z

• Getting started: docs/getting-started.md
• API reference: docs/api.md
• Benchmarking: docs/benchmarking.md
• Zig acceleration: docs/zig-acceleration.md
• Native ABI: docs/native-abi.md
• Release checklist: docs/release-checklist.md
• Release notes draft automation: bun run release:notes (updates docs/release-notes/v*.md + parity block in CHANGELOG.md)

• Changelog: CHANGELOG.md
• Contributing: CONTRIBUTING.md
• Security: SECURITY.md
• Code of Conduct: CODE_OF_CONDUCT.md
• Support: SUPPORT.md