bun-scikit 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seyamalam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# bun-scikit
+
+[![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`
+
+## Install
+
+```bash
+bun install bun-scikit
+```
+
+Postinstall behavior:
+
+- Downloads prebuilt native binaries from GitHub Releases for `linux-x64` and `windows-x64`.
+- If prebuilt binaries are unavailable, it falls back to local native build.
+- macOS prebuilt binaries are currently not published.
+
+## Usage
+
+```ts
+import {
+  LinearRegression,
+  StandardScaler,
+  meanSquaredError,
+  trainTestSplit,
+} from "bun-scikit";
+
+const X = [
+  [1, 2],
+  [2, 3],
+  [3, 4],
+  [4, 5],
+];
+const y = [5, 7, 9, 11];
+
+const scaler = new StandardScaler();
+const XScaled = scaler.fitTransform(X);
+const { XTrain, XTest, yTrain, yTest } = trainTestSplit(XScaled, y, {
+  testSize: 0.25,
+  randomState: 42,
+});
+
+const model = new LinearRegression({ solver: "normal" });
+model.fit(XTrain, yTrain);
+const predictions = model.predict(XTest);
+
+console.log("MSE:", meanSquaredError(yTest, predictions));
+```
+
+## Benchmarks
+
+The table below is generated from `bench/results/heart-ci-latest.json`.
+That snapshot is produced by CI in `.github/workflows/benchmark-snapshot.yml`.
+
+<!-- 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).
+
+### Regression
+
+| 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 |
+
+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
+
+### Classification
+
+| 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 |
+
+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
+
+### Tree Classification
+
+| 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 |
+
+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
+
+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
+
+Snapshot generated at: 2026-02-23T14:55:51.251Z
+<!-- BENCHMARK_TABLE_END -->
+
+## Documentation
+
+- Docs index: `docs/README.md`
+- Getting started: `docs/getting-started.md`
+- API reference: `docs/api.md`
+- Benchmarking flow: `docs/benchmarking.md`
+- Zig acceleration: `docs/zig-acceleration.md`
+
+## Maintainer Files
+
+- Changelog: `CHANGELOG.md`
+- Contributing guide: `CONTRIBUTING.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
+```

package/binding.gyp

@@ -0,0 +1,21 @@
+{
+  "targets": [
+    {
+      "target_name": "bun_scikit_node_addon",
+      "sources": [ "src/native/node-addon/bun_scikit_addon.cpp" ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")"
+      ],
+      "dependencies": [
+        "<!(node -p \"require('node-addon-api').gyp\")"
+      ],
+      "defines": [ "NAPI_DISABLE_CPP_EXCEPTIONS" ],
+      "cflags_cc!": [ "-fno-exceptions" ],
+      "msvs_settings": {
+        "VCCLCompilerTool": {
+          "ExceptionHandling": 0
+        }
+      }
+    }
+  ]
+}

package/docs/README.md

@@ -0,0 +1,7 @@
+# Documentation
+
+- Getting started: `docs/getting-started.md`
+- API reference: `docs/api.md`
+- Generated API docs (Typedoc output): `docs/api-reference/`
+- Benchmarking and CI snapshot flow: `docs/benchmarking.md`
+- Zig native acceleration: `docs/zig-acceleration.md`

package/docs/native-abi.md

@@ -0,0 +1,53 @@
+# Native ABI Contract
+
+This document defines the stable ABI boundary between JavaScript runtimes (Bun/Node) and the Zig compute core.
+
+## ABI Version
+
+- Exported symbol: `bun_scikit_abi_version() -> u32`
+- Current version: `1`
+- JavaScript bridges must refuse to load mismatched ABI versions.
+
+## Status Codes
+
+Zig exports numeric status constants:
+
+- `bun_scikit_status_ok()`
+- `bun_scikit_status_invalid_handle()`
+- `bun_scikit_status_invalid_shape()`
+- `bun_scikit_status_allocation_failed()`
+- `bun_scikit_status_fit_failed()`
+- `bun_scikit_status_symbol_unavailable()`
+
+## Handle Lifecycle
+
+All model handles are opaque native pointers represented as `usize` in native code and `BigInt` in JS.
+
+Lifecycle:
+
+1. `*_model_create(...) -> handle`
+2. `*_model_fit(...)` / `*_model_predict(...)` / `*_model_copy_coefficients(...)`
+3. `*_model_destroy(handle)` exactly once
+
+## Memory Ownership Rules
+
+- Input tensors (`x`, `y`) are caller-owned contiguous typed arrays.
+- Output tensors (`out`) are caller-owned typed arrays preallocated to required size.
+- Native code does not own caller buffers and must never free them.
+- Native model state is owned by Zig and released only via `*_model_destroy`.
+
+## Tensor Layout
+
+- `x` must be row-major contiguous `Float64Array` with shape `[n_samples, n_features]`.
+- `y` is contiguous `Float64Array` (`LinearRegression`/`LogisticRegression`) or `Uint8Array` for classifier labels where required.
+
+## Runtime Bridges
+
+- Bun FFI bridge: `src/native/zigKernels.ts` (`bun:ffi`).
+- Node-API bridge addon: `src/native/node-addon/bun_scikit_addon.cpp`.
+
+Environment controls:
+
+- `BUN_SCIKIT_NATIVE_BRIDGE=node-api|ffi` (default tries Node-API then FFI)
+- `BUN_SCIKIT_NODE_ADDON=/absolute/path/to/bun_scikit_node_addon.node`
+- `BUN_SCIKIT_ZIG_LIB=/absolute/path/to/bun_scikit_kernels.<ext>`

package/index.ts

@@ -0,0 +1 @@
+export * from "./src/index";

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "bun-scikit",
+  "version": "0.1.1",
+  "description": "A scikit-learn-inspired machine learning library for Bun/TypeScript.",
+  "license": "MIT",
+  "module": "index.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Seyamalam/bun-scikit.git"
+  },
+  "homepage": "https://github.com/Seyamalam/bun-scikit#readme",
+  "bugs": {
+    "url": "https://github.com/Seyamalam/bun-scikit/issues"
+  },
+  "keywords": [
+    "machine-learning",
+    "scikit-learn",
+    "bun",
+    "typescript",
+    "linear-regression",
+    "logistic-regression",
+    "decision-tree",
+    "random-forest",
+    "knn",
+    "classification",
+    "preprocessing"
+  ],
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "zig",
+    "scripts",
+    "binding.gyp",
+    "docs/native-abi.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "engines": {
+    "bun": ">=1.3.9"
+  },
+  "scripts": {
+    "install": "bun run scripts/install-native.ts",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit",
+    "bench": "bun run bench/heart.bench.ts",
+    "bench:heart": "bun run bench/heart.bench.ts",
+    "bench:heart:classification": "bun run bench/heart-classification.bench.ts",
+    "bench:heart:tree": "bun run bench/heart-tree-classification.bench.ts",
+    "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: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",
+    "bench:history:update": "bun run scripts/update-benchmark-history.ts",
+    "native:build": "bun run scripts/build-zig-kernels.ts",
+    "native:build:node-addon": "bun run scripts/build-node-addon.ts",
+    "native:build:all": "bun run native:build && bun run native:build:node-addon",
+    "native:package:assets": "bun run scripts/package-native-artifacts.ts",
+    "docs:api:generate": "typedoc --entryPointStrategy resolve --entryPoints src/index.ts --out docs/api-reference --readme none",
+    "docs:coverage:check": "bun run scripts/check-api-docs-coverage.ts",
+    "build:bench:bytecode": "bun build ./bench/run-ci-benchmarks.ts --target=bun --bytecode --minify --outdir=./dist/bench",
+    "build:bench:compiled": "bun build ./bench/run-ci-benchmarks.ts --target=bun --compile --bytecode --minify --outfile=./dist/bench/bench-ci"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "node-addon-api": "^8.3.1",
+    "typedoc": "^0.28.14",
+    "typescript": "^5.9.2"
+  }
+}

package/scripts/build-node-addon.ts

@@ -0,0 +1,26 @@
+import { cp, mkdir } from "node:fs/promises";
+import { resolve } from "node:path";
+
+async function main(): Promise<void> {
+  const child = Bun.spawn(["bunx", "node-gyp", "rebuild"], {
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+
+  const exitCode = await child.exited;
+  if (exitCode !== 0) {
+    throw new Error(`node-gyp rebuild failed with exit code ${exitCode}.`);
+  }
+
+  const source = resolve("build", "Release", "bun_scikit_node_addon.node");
+  const outputDir = resolve("dist", "native");
+  const destination = resolve(outputDir, "bun_scikit_node_addon.node");
+  await mkdir(outputDir, { recursive: true });
+  await cp(source, destination, { force: true });
+  console.log(`Built Node-API addon: ${destination}`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/scripts/build-zig-kernels.ts

@@ -0,0 +1,50 @@
+import { mkdir } from "node:fs/promises";
+import { resolve } from "node:path";
+
+function sharedLibraryExtension(): string {
+  switch (process.platform) {
+    case "win32":
+      return "dll";
+    case "darwin":
+      return "dylib";
+    default:
+      return "so";
+  }
+}
+
+async function main(): Promise<void> {
+  const extension = sharedLibraryExtension();
+  const outputDir = resolve("dist/native");
+  const outputFile = resolve(outputDir, `bun_scikit_kernels.${extension}`);
+
+  await mkdir(outputDir, { recursive: true });
+
+  const child = Bun.spawn(
+    [
+      "zig",
+      "build-lib",
+      "zig/kernels.zig",
+      "-dynamic",
+      "-O",
+      "ReleaseFast",
+      "-fstrip",
+      `-femit-bin=${outputFile}`,
+    ],
+    {
+      stdout: "inherit",
+      stderr: "inherit",
+    },
+  );
+
+  const exitCode = await child.exited;
+  if (exitCode !== 0) {
+    throw new Error(`zig build-lib failed with exit code ${exitCode}.`);
+  }
+
+  console.log(`Built Zig kernels: ${outputFile}`);
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/scripts/check-api-docs-coverage.ts

@@ -0,0 +1,52 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const INDEX_PATH = resolve("src/index.ts");
+const DOCS_PATH = resolve("docs/api.md");
+
+function normalizeModulePath(pathLiteral: string): string {
+  return pathLiteral.replace(/^\.?\//, "");
+}
+
+function extractExportedSymbolNames(source: string): string[] {
+  const exportMatches = source.matchAll(
+    /export\s+(?:class|function|const|type|interface|enum)\s+([A-Za-z0-9_]+)/g,
+  );
+  return Array.from(exportMatches, (match) => match[1]);
+}
+
+const indexSource = await readFile(INDEX_PATH, "utf-8");
+const docsSource = await readFile(DOCS_PATH, "utf-8");
+
+const modulePaths = Array.from(indexSource.matchAll(/export\s+\*\s+from\s+"\.\/(.+)";/g)).map(
+  (match) => normalizeModulePath(match[1]),
+);
+
+const symbolNames = new Set<string>();
+for (const modulePath of modulePaths) {
+  const moduleSource = await readFile(resolve("src", `${modulePath}.ts`), "utf-8");
+  for (const name of extractExportedSymbolNames(moduleSource)) {
+    symbolNames.add(name);
+  }
+}
+
+function escapeRegExp(literal: string): string {
+  return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+const missing = Array.from(symbolNames)
+  .filter((name) => {
+    const pattern = new RegExp("`[^`]*\\b" + escapeRegExp(name) + "\\b[^`]*`");
+    return !pattern.test(docsSource);
+  })
+  .sort((a, b) => a.localeCompare(b));
+
+if (missing.length > 0) {
+  console.error("docs/api.md is missing exported API symbols:");
+  for (const name of missing) {
+    console.error(`- ${name}`);
+  }
+  process.exit(1);
+}
+
+console.log(`API docs coverage check passed for ${symbolNames.size} exported symbols.`);

package/scripts/check-benchmark-health.ts

@@ -0,0 +1,140 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+interface SharedBenchmarkResult {
+  implementation: string;
+  fitMsMedian: number;
+  predictMsMedian: number;
+}
+
+interface RegressionBenchmarkResult extends SharedBenchmarkResult {
+  mse: number;
+  r2: number;
+}
+
+interface ClassificationBenchmarkResult extends SharedBenchmarkResult {
+  accuracy: number;
+  f1: number;
+}
+
+interface TreeModelComparison {
+  bun: ClassificationBenchmarkResult;
+  sklearn: ClassificationBenchmarkResult;
+  comparison: {
+    accuracyDeltaVsSklearn: number;
+    f1DeltaVsSklearn: number;
+  };
+}
+
+interface BenchmarkSnapshot {
+  suites: {
+    regression: {
+      results: [RegressionBenchmarkResult, RegressionBenchmarkResult];
+      comparison: {
+        mseDeltaVsSklearn: number;
+        r2DeltaVsSklearn: number;
+      };
+    };
+    classification: {
+      results: [ClassificationBenchmarkResult, ClassificationBenchmarkResult];
+      comparison: {
+        accuracyDeltaVsSklearn: number;
+        f1DeltaVsSklearn: number;
+      };
+    };
+    treeClassification: {
+      models: [TreeModelComparison, TreeModelComparison];
+    };
+  };
+}
+
+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 snapshot = JSON.parse(await readFile(inputPath, "utf-8")) as BenchmarkSnapshot;
+
+const [bunRegression, sklearnRegression] = snapshot.suites.regression.results;
+const [bunClassification, sklearnClassification] = snapshot.suites.classification.results;
+const [decisionTree, randomForest] = snapshot.suites.treeClassification.models;
+
+for (const result of [
+  bunRegression,
+  sklearnRegression,
+  bunClassification,
+  sklearnClassification,
+  decisionTree.bun,
+  decisionTree.sklearn,
+  randomForest.bun,
+  randomForest.sklearn,
+]) {
+  if (!(result.fitMsMedian > 0 && result.predictMsMedian > 0)) {
+    throw new Error(`Benchmark timings must be positive for ${result.implementation}.`);
+  }
+}
+
+if (
+  !Number.isFinite(bunRegression.mse) ||
+  !Number.isFinite(sklearnRegression.mse) ||
+  !Number.isFinite(bunRegression.r2) ||
+  !Number.isFinite(sklearnRegression.r2)
+) {
+  throw new Error("Regression metrics must be finite for both implementations.");
+}
+
+if (
+  !Number.isFinite(bunClassification.accuracy) ||
+  !Number.isFinite(sklearnClassification.accuracy) ||
+  !Number.isFinite(bunClassification.f1) ||
+  !Number.isFinite(sklearnClassification.f1)
+) {
+  throw new Error("Classification metrics must be finite for both implementations.");
+}
+
+if (Math.abs(snapshot.suites.regression.comparison.mseDeltaVsSklearn) > 0.01) {
+  throw new Error(
+    `Regression MSE delta too large: ${snapshot.suites.regression.comparison.mseDeltaVsSklearn}.`,
+  );
+}
+
+if (Math.abs(snapshot.suites.regression.comparison.r2DeltaVsSklearn) > 0.01) {
+  throw new Error(
+    `Regression R2 delta too large: ${snapshot.suites.regression.comparison.r2DeltaVsSklearn}.`,
+  );
+}
+
+if (Math.abs(snapshot.suites.classification.comparison.accuracyDeltaVsSklearn) > 0.05) {
+  throw new Error(
+    `Classification accuracy delta too large: ${snapshot.suites.classification.comparison.accuracyDeltaVsSklearn}.`,
+  );
+}
+
+if (Math.abs(snapshot.suites.classification.comparison.f1DeltaVsSklearn) > 0.05) {
+  throw new Error(
+    `Classification F1 delta too large: ${snapshot.suites.classification.comparison.f1DeltaVsSklearn}.`,
+  );
+}
+
+if (Math.abs(decisionTree.comparison.accuracyDeltaVsSklearn) > 0.08) {
+  throw new Error(
+    `DecisionTree accuracy delta too large: ${decisionTree.comparison.accuracyDeltaVsSklearn}.`,
+  );
+}
+
+if (Math.abs(decisionTree.comparison.f1DeltaVsSklearn) > 0.08) {
+  throw new Error(`DecisionTree F1 delta too large: ${decisionTree.comparison.f1DeltaVsSklearn}.`);
+}
+
+if (Math.abs(randomForest.comparison.accuracyDeltaVsSklearn) > 0.08) {
+  throw new Error(
+    `RandomForest accuracy delta too large: ${randomForest.comparison.accuracyDeltaVsSklearn}.`,
+  );
+}
+
+if (Math.abs(randomForest.comparison.f1DeltaVsSklearn) > 0.08) {
+  throw new Error(`RandomForest F1 delta too large: ${randomForest.comparison.f1DeltaVsSklearn}.`);
+}
+
+console.log("Benchmark comparison health checks passed.");