Counterfactual Training

​

What it does

​

Honest limits

• Numeric only. Boolean / categorical features are held as-is on synthetic rows. Perturbation rules for them are undefined — silently perturbing them would corrupt training data.
• Deterministic. mulberry32 RNG seeded by options.seed (default 7) so two runs with the same options produce the same synthetic data.
• Bounded budget. maxSynthetic defaults to 10_000. The function surfaces a summary.syntheticRowsAdded so operators can audit how much data was added per training pass.
• Not a feature-store substitute. This augments the training set at call time. It does not modify any persisted dataset.

​

Opt-in via model config

{
  "config": {
    "counterfactualAugmentation": {
      "enabled": true,           // default false
      "marginalBand": 0.1,       // decision-boundary half-width
      "syntheticPerRow": 4,      // K synthetic neighbors per marginal row
      "maxSynthetic": 10000,     // hard cap
      "perturbStdFraction": 0.5, // gaussian noise as a fraction of feature σ
      "seed": 7                  // deterministic RNG seed
    }
  }
}

​

API surface

import { augmentWithCounterfactuals } from "@/lib/ml/counterfactual-trainer";
import { trainGBMRemote } from "@/lib/ml-worker-client";
import { scoreGradientBoosted } from "@/lib/scoring/gradient-boosted";

// scoreGradientBoosted(modelState, predictors, features) → { score, ... }
const scorer = (features) =>
  scoreGradientBoosted(currentModel.modelState, predictors, features).score;
const { augmented, summary } = augmentWithCounterfactuals({
  request,
  scorer,
  options: { marginalBand: 0.1, syntheticPerRow: 4, seed: 7 },
});
console.log("counterfactual augmentation:", summary);

const result = await trainGBMRemote(augmented);

​

Algorithm — what it does, what it doesn’t

1. Score every row of the labeled training set with the current gradient_boosted model via the supplied scorer.
2. Identify marginal rows — predicted probability in [0.5 - marginalBand .. 0.5 + marginalBand] (default band 0.1).
3. For each marginal row, generate K synthetic neighbors by perturbing each numeric feature with gaussian noise scaled to the observed feature standard deviation (default 0.5σ, K=4).
4. Append the synthetic rows to the training set and return the augmented set with a reproducibility summary.

• It does not perturb boolean or categorical features. Those are held as-is on synthetic rows.
• It does not perform binned-Bayes predictor grouping or online incremental updates. The augmenter only widens the training set; the gradient-boosted trainer itself does the learning.
• It does not vary the learning-rate schedule per row. The augmented set is fed to the remote GBM trainer with the same hyperparameters as any other training pass.
• It does not modify any persisted dataset. Augmentation happens at call time only.