bun-scikit 0.1.3 → 0.1.5

package/README.md

@@ -3,185 +3,121 @@
 [![CI](https://github.com/Seyamalam/bun-scikit/actions/workflows/ci.yml/badge.svg)](https://github.com/Seyamalam/bun-scikit/actions/workflows/ci.yml)
 [![Benchmark Snapshot](https://github.com/Seyamalam/bun-scikit/actions/workflows/benchmark-snapshot.yml/badge.svg)](https://github.com/Seyamalam/bun-scikit/actions/workflows/benchmark-snapshot.yml)
 
-`bun-scikit` is a scikit-learn-inspired machine learning library for Bun + TypeScript.
-
-## Features
-
-- `StandardScaler`
-- `LinearRegression` (native Zig `normal` solver)
-- `LogisticRegression` (binary classification, native Zig)
-- `KNeighborsClassifier`
-- `DecisionTreeClassifier`
-- `RandomForestClassifier`
-- `trainTestSplit`
-- Regression metrics: `meanSquaredError`, `meanAbsoluteError`, `r2Score`
-- Classification metrics: `accuracyScore`, `precisionScore`, `recallScore`, `f1Score`
-- Dataset-driven benchmark and CI comparison against Python `scikit-learn`
-
-`test_data/heart.csv` is used for integration testing and benchmark comparison.
-
-## Native Zig Backend
-
-`LinearRegression` (`solver: "normal"`) and `LogisticRegression` require native Zig kernels.
-
-```bash
-bun run native:build
-```
-
-Optional Node-API bridge (experimental):
-
-```bash
-bun run native:build:node-addon
-```
-
-```ts
-const linear = new LinearRegression({ solver: "normal" });
-const logistic = new LogisticRegression();
-
-linear.fit(XTrain, yTrain);
-logistic.fit(XTrain, yTrain);
-console.log(linear.fitBackend_, linear.fitBackendLibrary_);
-console.log(logistic.fitBackend_, logistic.fitBackendLibrary_);
-```
-
-If native kernels are missing, `fit()` throws with guidance to run `bun run native:build`.
-
-Bridge selection:
-
-- `BUN_SCIKIT_NATIVE_BRIDGE=node-api|ffi` (`node-api` is attempted first when available)
-- `BUN_SCIKIT_NODE_ADDON=/absolute/path/to/bun_scikit_node_addon.node`
-- `BUN_SCIKIT_ZIG_LIB=/absolute/path/to/bun_scikit_kernels.<ext>`
-
-Native ABI contract: `docs/native-abi.md`
+Scikit-learn-inspired machine learning for Bun + TypeScript, with native Zig acceleration for core training paths.
 
 ## Install
 
 ```bash
-bun install bun-scikit
+bun add bun-scikit
 ```
 
-Postinstall behavior:
-
-- Prebuilt native binaries for `linux-x64` and `windows-x64` are bundled in the npm package.
-- No `bun pm trust` step is required for normal install/use.
-- macOS prebuilt binaries are currently not published.
-
-## Usage
+## Quick Start
 
 ```ts
 import {
   LinearRegression,
+  LogisticRegression,
   StandardScaler,
-  meanSquaredError,
   trainTestSplit,
+  meanSquaredError,
+  accuracyScore,
 } from "bun-scikit";
 
-const X = [
-  [1, 2],
-  [2, 3],
-  [3, 4],
-  [4, 5],
-];
-const y = [5, 7, 9, 11];
+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 XScaled = scaler.fitTransform(X);
-const { XTrain, XTest, yTrain, yTest } = trainTestSplit(XScaled, y, {
-  testSize: 0.25,
+const Xs = scaler.fitTransform(X);
+
+const { XTrain, XTest, yTrain, yTest } = trainTestSplit(Xs, yReg, {
+  testSize: 0.33,
   randomState: 42,
 });
 
-const model = new LinearRegression({ solver: "normal" });
-model.fit(XTrain, yTrain);
-const predictions = model.predict(XTest);
+const reg = new LinearRegression({ solver: "normal" });
+reg.fit(XTrain, yTrain);
+console.log("MSE:", meanSquaredError(yTest, reg.predict(XTest)));
 
-console.log("MSE:", meanSquaredError(yTest, predictions));
+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)));
 ```
 
-## Benchmarks
+## Included APIs
 
-The table below is generated from `bench/results/heart-ci-latest.json`.
-That snapshot is produced by CI in `.github/workflows/benchmark-snapshot.yml`.
+- Models: `LinearRegression`, `LogisticRegression`, `KNeighborsClassifier`, `DecisionTreeClassifier`, `RandomForestClassifier`, plus additional parity models (`LinearSVC`, `GaussianNB`, `SGDClassifier`, `SGDRegressor`, regressors for tree/forest).
+- Baselines: `DummyClassifier`, `DummyRegressor`.
+- Preprocessing: `StandardScaler`, `MinMaxScaler`, `RobustScaler`, `MaxAbsScaler`, `Normalizer`, `Binarizer`, `LabelEncoder`, `PolynomialFeatures`, `SimpleImputer`, `OneHotEncoder`.
+- Composition: `Pipeline`, `ColumnTransformer`, `FeatureUnion`.
+- Feature selection: `VarianceThreshold`.
+- Model selection: `trainTestSplit`, `KFold`, stratified/repeated splitters, `crossValScore`, `GridSearchCV`, `RandomizedSearchCV`.
+- Metrics: regression and classification metrics, including `logLoss`, `rocAucScore`, `confusionMatrix`, `classificationReport`, `balancedAccuracyScore`, `matthewsCorrcoef`, `brierScoreLoss`, `meanAbsolutePercentageError`, and `explainedVarianceScore`.
 
-<!-- BENCHMARK_TABLE_START -->
-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).
+## Scikit Parity Matrix
 
-### Regression
+| Area | Status |
+| --- | --- |
+| Linear models | `LinearRegression`, `LogisticRegression`, `SGDClassifier`, `SGDRegressor`, `LinearSVC` |
+| Tree/ensemble | `DecisionTreeClassifier`, `DecisionTreeRegressor`, `RandomForestClassifier`, `RandomForestRegressor` |
+| Neighbors / Bayes | `KNeighborsClassifier`, `GaussianNB` |
+| Baselines | `DummyClassifier`, `DummyRegressor` |
+| Preprocessing | `StandardScaler`, `MinMaxScaler`, `RobustScaler`, `MaxAbsScaler`, `Normalizer`, `Binarizer`, `LabelEncoder`, `PolynomialFeatures`, `SimpleImputer`, `OneHotEncoder` |
+| Feature selection | `VarianceThreshold` |
+| Model selection | `trainTestSplit`, `KFold`, `StratifiedKFold`, `StratifiedShuffleSplit`, `RepeatedKFold`, `RepeatedStratifiedKFold`, `crossValScore`, `GridSearchCV`, `RandomizedSearchCV` |
+| Metrics (regression) | `meanSquaredError`, `meanAbsoluteError`, `r2Score`, `meanAbsolutePercentageError`, `explainedVarianceScore` |
+| Metrics (classification) | `accuracyScore`, `precisionScore`, `recallScore`, `f1Score`, `balancedAccuracyScore`, `matthewsCorrcoef`, `logLoss`, `brierScoreLoss`, `rocAucScore`, `confusionMatrix`, `classificationReport` |
 
-| Implementation | Model | Fit median (ms) | Predict median (ms) | MSE | R2 |
-|---|---|---:|---:|---:|---:|
-| bun-scikit | StandardScaler + LinearRegression(normal) | 0.2103 | 0.0216 | 0.117545 | 0.529539 |
-| python-scikit-learn | StandardScaler + LinearRegression | 0.3201 | 0.0365 | 0.117545 | 0.529539 |
+Near-term parity gaps vs scikit-learn include clustering, decomposition, calibration, advanced feature selection, and probability calibration/meta-estimators.
 
-Bun fit speedup vs scikit-learn: 1.522x
-Bun predict speedup vs scikit-learn: 1.684x
-MSE delta (bun - sklearn): 6.362e-14
-R2 delta (bun - sklearn): -2.539e-13
+## Native Runtime
 
-### Classification
+- 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.
 
-| Implementation | Model | Fit median (ms) | Predict median (ms) | Accuracy | F1 |
-|---|---|---:|---:|---:|---:|
-| bun-scikit | StandardScaler + LogisticRegression(gd,zig) | 0.4868 | 0.0282 | 0.863415 | 0.876106 |
-| python-scikit-learn | StandardScaler + LogisticRegression(lbfgs) | 1.1246 | 0.0724 | 0.863415 | 0.875000 |
+Optional env vars:
 
-Bun fit speedup vs scikit-learn: 2.310x
-Bun predict speedup vs scikit-learn: 2.574x
-Accuracy delta (bun - sklearn): 0.000e+0
-F1 delta (bun - sklearn): 1.106e-3
+- `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` (opt-in native tree/forest training path; default keeps JS-fast tree splitter)
 
-### Tree Classification
+## Performance Snapshot
 
-| Model | Implementation | Fit median (ms) | Predict median (ms) | Accuracy | F1 |
-|---|---|---:|---:|---:|---:|
-| DecisionTreeClassifier(maxDepth=8) | bun-scikit | 0.8062 | 0.0190 | 0.946341 | 0.948837 |
-| DecisionTreeClassifier | python-scikit-learn | 1.4781 | 0.0999 | 0.931707 | 0.933962 |
-| RandomForestClassifier(nEstimators=80,maxDepth=8) | bun-scikit | 27.6225 | 1.8535 | 0.990244 | 0.990566 |
-| RandomForestClassifier | python-scikit-learn | 172.9585 | 6.4850 | 0.995122 | 0.995261 |
+Latest CI snapshot on `test_data/heart.csv` vs Python scikit-learn:
 
-DecisionTree fit speedup vs scikit-learn: 1.833x
-DecisionTree predict speedup vs scikit-learn: 5.244x
-DecisionTree accuracy delta (bun - sklearn): 1.463e-2
-DecisionTree f1 delta (bun - sklearn): 1.487e-2
+- Regression: fit `1.67x`, predict `1.84x`
+- Classification: fit `1.78x`, predict `2.66x`
+- DecisionTree (`js-fast`): fit `1.54x`, predict `4.06x`
+- RandomForest (`js-fast`): fit `2.59x`, predict `1.29x`
+- Tree backend matrix (`js-fast` vs `zig-tree` vs `sklearn`) is included in `bench/results/heart-ci-latest.md`
 
-RandomForest fit speedup vs scikit-learn: 6.262x
-RandomForest predict speedup vs scikit-learn: 3.499x
-RandomForest accuracy delta (bun - sklearn): -4.878e-3
-RandomForest f1 delta (bun - sklearn): -4.695e-3
+Raw benchmark artifacts:
 
-Snapshot generated at: 2026-02-23T14:55:51.251Z
-<!-- BENCHMARK_TABLE_END -->
+- `bench/results/heart-ci-latest.json`
+- `bench/results/heart-ci-latest.md`
 
 ## Documentation
 
-- Docs index: `docs/README.md`
 - Getting started: `docs/getting-started.md`
 - API reference: `docs/api.md`
-- Benchmarking flow: `docs/benchmarking.md`
+- Benchmarking: `docs/benchmarking.md`
 - Zig acceleration: `docs/zig-acceleration.md`
+- Native ABI: `docs/native-abi.md`
+- Release checklist: `docs/release-checklist.md`
 
-## Maintainer Files
+## Contributing / Project Files
 
 - Changelog: `CHANGELOG.md`
-- Contributing guide: `CONTRIBUTING.md`
+- Contributing: `CONTRIBUTING.md`
+- Security: `SECURITY.md`
 - Code of Conduct: `CODE_OF_CONDUCT.md`
-- Security policy: `SECURITY.md`
-- Support policy: `SUPPORT.md`
-- License: `LICENSE`
-
-## Local Commands
-
-```bash
-bun run test
-bun run typecheck
-bun run docs:api:generate
-bun run docs:coverage:check
-bun run bench
-bun run bench:heart:classification
-bun run bench:heart:tree
-bun run bench:ci
-bun run bench:ci:native
-bun run bench:snapshot
-bun run native:build
-```
+- Support: `SUPPORT.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-scikit",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A scikit-learn-inspired machine learning library for Bun/TypeScript.",
   "license": "MIT",
   "module": "index.ts",
@@ -52,7 +52,7 @@
     "bench:synthetic": "bun run bench/linear-regression.bench.ts",
     "bench:ci": "bun run bench/run-ci-benchmarks.ts --output bench/results/heart-ci-current.json",
     "bench:ci:native": "bun run native:build && bun run bench:ci",
-    "bench:snapshot": "bun run bench/run-ci-benchmarks.ts --output bench/results/heart-ci-latest.json && bun run bench:sync-readme && bun run bench:history:update",
+    "bench:snapshot": "bun run bench/run-ci-benchmarks.ts --output bench/results/heart-ci-latest.json && bun run bench:history:update",
     "bench:sync-readme": "bun run scripts/sync-benchmark-readme.ts",
     "bench:readme:check": "bun run scripts/sync-benchmark-readme.ts --check",
     "bench:health": "bun run scripts/check-benchmark-health.ts",
@@ -69,6 +69,7 @@
   "devDependencies": {
     "@types/bun": "latest",
     "node-addon-api": "^8.3.1",
+    "node-gyp": "^12.2.0",
     "typedoc": "^0.28.14",
     "typescript": "^5.9.2"
   }

package/scripts/build-node-addon.ts

@@ -1,8 +1,24 @@
 import { cp, mkdir } from "node:fs/promises";
+import { createRequire } from "node:module";
 import { resolve } from "node:path";
 
+function resolveNodeGypCommand(): string[] {
+  const npmNodeGyp = process.env.npm_config_node_gyp?.trim();
+  if (npmNodeGyp) {
+    return ["node", npmNodeGyp, "rebuild"];
+  }
+
+  try {
+    const require = createRequire(import.meta.url);
+    const nodeGypScript = require.resolve("node-gyp/bin/node-gyp.js");
+    return ["node", nodeGypScript, "rebuild"];
+  } catch {
+    return ["node-gyp", "rebuild"];
+  }
+}
+
 async function main(): Promise<void> {
-  const child = Bun.spawn(["bunx", "node-gyp", "rebuild"], {
+  const child = Bun.spawn(resolveNodeGypCommand(), {
     stdout: "inherit",
     stderr: "inherit",
   });

package/scripts/check-benchmark-health.ts

@@ -26,6 +26,17 @@ interface TreeModelComparison {
   };
 }
 
+interface TreeBackendModeComparison {
+  comparison: {
+    zigFitSpeedupVsJs: number;
+    zigPredictSpeedupVsJs: number;
+    jsFitSpeedupVsSklearn: number;
+    jsPredictSpeedupVsSklearn: number;
+    zigFitSpeedupVsSklearn: number;
+    zigPredictSpeedupVsSklearn: number;
+  };
+}
+
 interface BenchmarkSnapshot {
   suites: {
     regression: {
@@ -62,9 +73,21 @@ interface BenchmarkSnapshot {
         },
       ];
     };
+    treeBackendModes: {
+      enabled: boolean;
+      models: [TreeBackendModeComparison, TreeBackendModeComparison] | [];
+    };
   };
 }
 
+function parseArgValue(flag: string): string | null {
+  const index = Bun.argv.indexOf(flag);
+  if (index === -1 || index + 1 >= Bun.argv.length) {
+    return null;
+  }
+  return Bun.argv[index + 1];
+}
+
 function speedupThreshold(
   envName: string,
   defaultValue: number,
@@ -80,13 +103,18 @@ function speedupThreshold(
   return parsed;
 }
 
-const pathArgIndex = Bun.argv.indexOf("--input");
-const inputPath =
-  pathArgIndex !== -1 && pathArgIndex + 1 < Bun.argv.length
-    ? resolve(Bun.argv[pathArgIndex + 1])
-    : resolve("bench/results/heart-ci-current.json");
+const inputPath = resolve(parseArgValue("--input") ?? "bench/results/heart-ci-current.json");
+const baselinePath = resolve(
+  parseArgValue("--baseline") ?? process.env.BENCH_BASELINE_INPUT ?? "bench/results/heart-ci-latest.json",
+);
+const baselineInputEnabled = inputPath !== baselinePath;
 
 const snapshot = JSON.parse(await readFile(inputPath, "utf-8")) as BenchmarkSnapshot;
+const baselineSnapshot = baselineInputEnabled
+  ? ((await readFile(baselinePath, "utf-8").then((raw) => JSON.parse(raw) as BenchmarkSnapshot).catch(
+      () => null,
+    )) as BenchmarkSnapshot | null)
+  : null;
 
 const [bunRegression, sklearnRegression] = snapshot.suites.regression.results;
 const [bunClassification, sklearnClassification] = snapshot.suites.classification.results;
@@ -106,7 +134,28 @@ const minDecisionTreePredictSpeedup = speedupThreshold(
 const minRandomForestFitSpeedup = speedupThreshold("BENCH_MIN_RANDOM_FOREST_FIT_SPEEDUP", 2.0);
 const minRandomForestPredictSpeedup = speedupThreshold(
   "BENCH_MIN_RANDOM_FOREST_PREDICT_SPEEDUP",
-  2.0,
+  1.2,
+);
+const maxZigTreeFitSlowdownVsJs = speedupThreshold("BENCH_MAX_ZIG_TREE_FIT_SLOWDOWN_VS_JS", 20);
+const maxZigTreePredictSlowdownVsJs = speedupThreshold(
+  "BENCH_MAX_ZIG_TREE_PREDICT_SLOWDOWN_VS_JS",
+  20,
+);
+const maxZigForestFitSlowdownVsJs = speedupThreshold(
+  "BENCH_MAX_ZIG_FOREST_FIT_SLOWDOWN_VS_JS",
+  20,
+);
+const maxZigForestPredictSlowdownVsJs = speedupThreshold(
+  "BENCH_MAX_ZIG_FOREST_PREDICT_SLOWDOWN_VS_JS",
+  20,
+);
+const minZigTreeFitRetentionVsBaseline = speedupThreshold(
+  "BENCH_MIN_ZIG_TREE_FIT_RETENTION_VS_BASELINE",
+  0.9,
+);
+const minZigForestFitRetentionVsBaseline = speedupThreshold(
+  "BENCH_MIN_ZIG_FOREST_FIT_RETENTION_VS_BASELINE",
+  0.9,
 );
 
 for (const result of [
@@ -237,4 +286,61 @@ if (randomForest.comparison.predictSpeedupVsSklearn < minRandomForestPredictSpee
   );
 }
 
+if (snapshot.suites.treeBackendModes.enabled) {
+  const [decisionTreeModes, randomForestModes] = snapshot.suites.treeBackendModes.models;
+  if (!decisionTreeModes || !randomForestModes) {
+    throw new Error("Tree backend mode suite is enabled but missing model comparisons.");
+  }
+
+  const decisionTreeFitSlowdown = 1 / decisionTreeModes.comparison.zigFitSpeedupVsJs;
+  const decisionTreePredictSlowdown = 1 / decisionTreeModes.comparison.zigPredictSpeedupVsJs;
+  const randomForestFitSlowdown = 1 / randomForestModes.comparison.zigFitSpeedupVsJs;
+  const randomForestPredictSlowdown = 1 / randomForestModes.comparison.zigPredictSpeedupVsJs;
+
+  if (decisionTreeFitSlowdown > maxZigTreeFitSlowdownVsJs) {
+    throw new Error(
+      `DecisionTree zig fit slowdown too large vs js-fast: ${decisionTreeFitSlowdown} > ${maxZigTreeFitSlowdownVsJs}.`,
+    );
+  }
+  if (decisionTreePredictSlowdown > maxZigTreePredictSlowdownVsJs) {
+    throw new Error(
+      `DecisionTree zig predict slowdown too large vs js-fast: ${decisionTreePredictSlowdown} > ${maxZigTreePredictSlowdownVsJs}.`,
+    );
+  }
+  if (randomForestFitSlowdown > maxZigForestFitSlowdownVsJs) {
+    throw new Error(
+      `RandomForest zig fit slowdown too large vs js-fast: ${randomForestFitSlowdown} > ${maxZigForestFitSlowdownVsJs}.`,
+    );
+  }
+  if (randomForestPredictSlowdown > maxZigForestPredictSlowdownVsJs) {
+    throw new Error(
+      `RandomForest zig predict slowdown too large vs js-fast: ${randomForestPredictSlowdown} > ${maxZigForestPredictSlowdownVsJs}.`,
+    );
+  }
+
+  if (baselineSnapshot?.suites?.treeBackendModes?.enabled) {
+    const [baselineDecisionTreeModes, baselineRandomForestModes] =
+      baselineSnapshot.suites.treeBackendModes.models;
+    if (baselineDecisionTreeModes && baselineRandomForestModes) {
+      const decisionTreeFitRetention =
+        decisionTreeModes.comparison.zigFitSpeedupVsJs /
+        baselineDecisionTreeModes.comparison.zigFitSpeedupVsJs;
+      const randomForestFitRetention =
+        randomForestModes.comparison.zigFitSpeedupVsJs /
+        baselineRandomForestModes.comparison.zigFitSpeedupVsJs;
+
+      if (decisionTreeFitRetention < minZigTreeFitRetentionVsBaseline) {
+        throw new Error(
+          `DecisionTree zig/js fit retention too low vs baseline: ${decisionTreeFitRetention} < ${minZigTreeFitRetentionVsBaseline}.`,
+        );
+      }
+      if (randomForestFitRetention < minZigForestFitRetentionVsBaseline) {
+        throw new Error(
+          `RandomForest zig/js fit retention too low vs baseline: ${randomForestFitRetention} < ${minZigForestFitRetentionVsBaseline}.`,
+        );
+      }
+    }
+  }
+}
+
 console.log("Benchmark comparison health checks passed.");

package/scripts/sync-benchmark-readme.ts

@@ -62,6 +62,19 @@ interface BenchmarkSnapshot {
     treeClassification: {
       models: [TreeModelComparison, TreeModelComparison];
     };
+    treeBackendModes?: {
+      enabled: boolean;
+      models: Array<{
+        key: TreeModelKey;
+        jsFast: ClassificationBenchmarkResult;
+        zigTree: ClassificationBenchmarkResult;
+        sklearn: ClassificationBenchmarkResult;
+        comparison: {
+          zigFitSpeedupVsJs: number;
+          zigPredictSpeedupVsJs: number;
+        };
+      }>;
+    };
   };
 }
 
@@ -89,6 +102,11 @@ function renderBenchmarkSection(snapshot: BenchmarkSnapshot): string {
   const [bunReg, sklearnReg] = regression.results;
   const [bunCls, sklearnCls] = classification.results;
   const [decisionTree, randomForest] = treeClassification.models;
+  const treeBackendModes = snapshot.suites.treeBackendModes;
+  const hasTreeBackendModes =
+    treeBackendModes?.enabled === true && Array.isArray(treeBackendModes.models) && treeBackendModes.models.length === 2;
+  const decisionTreeModes = hasTreeBackendModes ? treeBackendModes.models[0] : null;
+  const randomForestModes = hasTreeBackendModes ? treeBackendModes.models[1] : null;
 
   return [
     START_MARKER,
@@ -138,6 +156,44 @@ function renderBenchmarkSection(snapshot: BenchmarkSnapshot): string {
     `RandomForest accuracy delta (bun - sklearn): ${randomForest.comparison.accuracyDeltaVsSklearn.toExponential(3)}`,
     `RandomForest f1 delta (bun - sklearn): ${randomForest.comparison.f1DeltaVsSklearn.toExponential(3)}`,
     "",
+    "### Tree Backend Modes (Bun vs Bun vs sklearn)",
+    "",
+    hasTreeBackendModes
+      ? "| Model | Backend | Fit median (ms) | Predict median (ms) | Accuracy | F1 |"
+      : "Tree backend mode matrix disabled (`BENCH_TREE_BACKEND_MATRIX=0`).",
+    hasTreeBackendModes ? "|---|---|---:|---:|---:|---:|" : "",
+    hasTreeBackendModes
+      ? `| DecisionTreeClassifier(maxDepth=8) | js-fast | ${decisionTreeModes!.jsFast.fitMsMedian.toFixed(4)} | ${decisionTreeModes!.jsFast.predictMsMedian.toFixed(4)} | ${decisionTreeModes!.jsFast.accuracy.toFixed(6)} | ${decisionTreeModes!.jsFast.f1.toFixed(6)} |`
+      : "",
+    hasTreeBackendModes
+      ? `| DecisionTreeClassifier(maxDepth=8) | zig-tree | ${decisionTreeModes!.zigTree.fitMsMedian.toFixed(4)} | ${decisionTreeModes!.zigTree.predictMsMedian.toFixed(4)} | ${decisionTreeModes!.zigTree.accuracy.toFixed(6)} | ${decisionTreeModes!.zigTree.f1.toFixed(6)} |`
+      : "",
+    hasTreeBackendModes
+      ? `| DecisionTreeClassifier | python-scikit-learn | ${decisionTreeModes!.sklearn.fitMsMedian.toFixed(4)} | ${decisionTreeModes!.sklearn.predictMsMedian.toFixed(4)} | ${decisionTreeModes!.sklearn.accuracy.toFixed(6)} | ${decisionTreeModes!.sklearn.f1.toFixed(6)} |`
+      : "",
+    hasTreeBackendModes
+      ? `| RandomForestClassifier(nEstimators=80,maxDepth=8) | js-fast | ${randomForestModes!.jsFast.fitMsMedian.toFixed(4)} | ${randomForestModes!.jsFast.predictMsMedian.toFixed(4)} | ${randomForestModes!.jsFast.accuracy.toFixed(6)} | ${randomForestModes!.jsFast.f1.toFixed(6)} |`
+      : "",
+    hasTreeBackendModes
+      ? `| RandomForestClassifier(nEstimators=80,maxDepth=8) | zig-tree | ${randomForestModes!.zigTree.fitMsMedian.toFixed(4)} | ${randomForestModes!.zigTree.predictMsMedian.toFixed(4)} | ${randomForestModes!.zigTree.accuracy.toFixed(6)} | ${randomForestModes!.zigTree.f1.toFixed(6)} |`
+      : "",
+    hasTreeBackendModes
+      ? `| RandomForestClassifier | python-scikit-learn | ${randomForestModes!.sklearn.fitMsMedian.toFixed(4)} | ${randomForestModes!.sklearn.predictMsMedian.toFixed(4)} | ${randomForestModes!.sklearn.accuracy.toFixed(6)} | ${randomForestModes!.sklearn.f1.toFixed(6)} |`
+      : "",
+    "",
+    hasTreeBackendModes
+      ? `DecisionTree zig/js fit speedup: ${decisionTreeModes!.comparison.zigFitSpeedupVsJs.toFixed(3)}x`
+      : "",
+    hasTreeBackendModes
+      ? `DecisionTree zig/js predict speedup: ${decisionTreeModes!.comparison.zigPredictSpeedupVsJs.toFixed(3)}x`
+      : "",
+    hasTreeBackendModes
+      ? `RandomForest zig/js fit speedup: ${randomForestModes!.comparison.zigFitSpeedupVsJs.toFixed(3)}x`
+      : "",
+    hasTreeBackendModes
+      ? `RandomForest zig/js predict speedup: ${randomForestModes!.comparison.zigPredictSpeedupVsJs.toFixed(3)}x`
+      : "",
+    "",
     `Snapshot generated at: ${snapshot.generatedAt}`,
     END_MARKER,
   ].join("\n");