@dniskav/neuron 0.2.7 → 0.3.1

package/dist/index.mjs

@@ -2430,12 +2430,12 @@ var Trainer = class {
       precisions.push(colSum > 0 ? tp / colSum : 0);
       recalls.push(rowSum > 0 ? tp / rowSum : 0);
     }
-    const accuracy = totalSamples > 0 ? totalCorrect / totalSamples : 0;
+    const accuracy2 = totalSamples > 0 ? totalCorrect / totalSamples : 0;
     const macroPrecision = precisions.reduce((a, b) => a + b, 0) / nClasses;
     const macroRecall = recalls.reduce((a, b) => a + b, 0) / nClasses;
     const f1 = macroPrecision + macroRecall > 0 ? 2 * macroPrecision * macroRecall / (macroPrecision + macroRecall) : 0;
     return {
-      accuracy,
+      accuracy: accuracy2,
       precision: macroPrecision,
       recall: macroRecall,
       f1
@@ -2598,22 +2598,3728 @@ var ModelSaver = class _ModelSaver {
     _ModelSaver.fromJSON(model, json);
   }
 };
+
+// src/Perceptron.ts
+var Perceptron = class {
+  // ─── Constructor ─────────────────────────────────────────────────────────────
+  // All weights and bias start at 0. The perceptron learning rule does not
+  // require random initialization because the step function already breaks
+  // symmetry when any misclassification occurs.
+  constructor(nInputs) {
+    if (!Number.isInteger(nInputs) || nInputs <= 0) {
+      throw new Error(
+        `Perceptron: nInputs must be a positive integer, got ${nInputs}`
+      );
+    }
+    this.weights = new Array(nInputs).fill(0);
+    this.bias = 0;
+  }
+  // ─── Forward pass ────────────────────────────────────────────────────────────
+  // Computes z = Σ(wᵢ·xᵢ) + bias, then applies the Heaviside step function.
+  // Returns 1 if z > 0, else 0.
+  predict(inputs) {
+    validateArray(inputs, this.weights.length, "Perceptron.predict");
+    let z = this.bias;
+    for (let i = 0; i < this.weights.length; i++) {
+      z += this.weights[i] * inputs[i];
+    }
+    return z > 0 ? 1 : 0;
+  }
+  // ─── Training step ───────────────────────────────────────────────────────────
+  // Applies the perceptron update rule for a single (input, target) pair.
+  //
+  //   error = target − output   (0 on correct prediction → no update)
+  //   wᵢ   ← wᵢ + lr · error · xᵢ
+  //   bias ← bias + lr · error
+  //
+  // Returns the error (useful for tracking convergence).
+  train(inputs, target, lr) {
+    validateArray(inputs, this.weights.length, "Perceptron.train");
+    validateNumber(target, "Perceptron.train");
+    validateNumber(lr, "Perceptron.train");
+    if (target !== 0 && target !== 1) {
+      throw new Error(
+        `Perceptron.train: target must be 0 or 1, got ${target}`
+      );
+    }
+    if (lr <= 0) {
+      throw new Error(
+        `Perceptron.train: learning rate must be positive, got ${lr}`
+      );
+    }
+    const output = this.predict(inputs);
+    const error = target - output;
+    if (error !== 0) {
+      for (let i = 0; i < this.weights.length; i++) {
+        this.weights[i] += lr * error * inputs[i];
+      }
+      this.bias += lr * error;
+    }
+    return error;
+  }
+};
+
+// src/LinearRegression.ts
+function matMul2(A, B) {
+  const m = A.length;
+  const k = A[0].length;
+  const n = B[0].length;
+  const C = Array.from({ length: m }, () => new Array(n).fill(0));
+  for (let i = 0; i < m; i++) {
+    for (let j = 0; j < n; j++) {
+      let sum = 0;
+      for (let p = 0; p < k; p++) sum += A[i][p] * B[p][j];
+      C[i][j] = sum;
+    }
+  }
+  return C;
+}
+function transpose2(A) {
+  const m = A.length;
+  const n = A[0].length;
+  const T = Array.from({ length: n }, () => new Array(m).fill(0));
+  for (let i = 0; i < m; i++) {
+    for (let j = 0; j < n; j++) {
+      T[j][i] = A[i][j];
+    }
+  }
+  return T;
+}
+function invertMatrix(M) {
+  const n = M.length;
+  const aug = M.map((row, i) => {
+    const id = new Array(n).fill(0);
+    id[i] = 1;
+    return [...row, ...id];
+  });
+  for (let col = 0; col < n; col++) {
+    let maxRow = col;
+    let maxVal = Math.abs(aug[col][col]);
+    for (let row = col + 1; row < n; row++) {
+      if (Math.abs(aug[row][col]) > maxVal) {
+        maxVal = Math.abs(aug[row][col]);
+        maxRow = row;
+      }
+    }
+    [aug[col], aug[maxRow]] = [aug[maxRow], aug[col]];
+    const pivot = aug[col][col];
+    if (Math.abs(pivot) < 1e-12) return null;
+    for (let j = 0; j < 2 * n; j++) aug[col][j] /= pivot;
+    for (let row = 0; row < n; row++) {
+      if (row === col) continue;
+      const factor = aug[row][col];
+      for (let j = 0; j < 2 * n; j++) {
+        aug[row][j] -= factor * aug[col][j];
+      }
+    }
+  }
+  return aug.map((row) => row.slice(n));
+}
+function augment(X) {
+  return X.map((row) => [...row, 1]);
+}
+var LinearRegression = class {
+  constructor() {
+    // weights = [w₁, w₂, ..., wₙ, bias]
+    this.weights = [];
+    this._nFeatures = 0;
+  }
+  // ─── Normal Equation ───────────────────────────────────────────────────────
+  // W = (XᵀX)⁻¹Xᵀy   — exact solution in one matrix operation.
+  // Augments X with a bias column so the bias is solved jointly.
+  fitNormal(X, y) {
+    if (X.length === 0) throw new Error("LinearRegression.fitNormal: X is empty");
+    if (X.length !== y.length) {
+      throw new Error(
+        `LinearRegression.fitNormal: X has ${X.length} rows but y has ${y.length} elements`
+      );
+    }
+    this._nFeatures = X[0].length;
+    const Xa = augment(X);
+    const XaT = transpose2(Xa);
+    const XaTXa = matMul2(XaT, Xa);
+    const XaTXaInv = invertMatrix(XaTXa);
+    if (XaTXaInv === null) {
+      throw new Error(
+        "LinearRegression.fitNormal: X\u1D40X is singular \u2014 features may be linearly dependent"
+      );
+    }
+    const yCol = y.map((v) => [v]);
+    const XaTy = matMul2(XaT, yCol);
+    const W = matMul2(XaTXaInv, XaTy);
+    this.weights = W.map((row) => row[0]);
+  }
+  // ─── Gradient Descent ──────────────────────────────────────────────────────
+  // Minimises MSE = (1/m) Σ (ŷᵢ − yᵢ)² iteratively.
+  //
+  //   ŷ  = Xa · W
+  //   dW = (2/m) · Xaᵀ · (ŷ − y)
+  //   W  ← W − lr · dW
+  //
+  // Returns the loss (MSE) at every epoch for convergence diagnostics.
+  fitGD(X, y, lr, epochs) {
+    if (X.length === 0) throw new Error("LinearRegression.fitGD: X is empty");
+    if (X.length !== y.length) {
+      throw new Error(
+        `LinearRegression.fitGD: X has ${X.length} rows but y has ${y.length} elements`
+      );
+    }
+    validateNumber(lr, "LinearRegression.fitGD");
+    if (lr <= 0) throw new Error("LinearRegression.fitGD: lr must be positive");
+    if (!Number.isInteger(epochs) || epochs <= 0) {
+      throw new Error("LinearRegression.fitGD: epochs must be a positive integer");
+    }
+    this._nFeatures = X[0].length;
+    const m = X.length;
+    const Xa = augment(X);
+    this.weights = new Array(this._nFeatures + 1).fill(0);
+    const lossHistory = [];
+    for (let epoch = 0; epoch < epochs; epoch++) {
+      const yHat = Xa.map(
+        (row) => row.reduce((s, x, j) => s + x * this.weights[j], 0)
+      );
+      const residuals = yHat.map((yh, i) => yh - y[i]);
+      const mse2 = residuals.reduce((s, r) => s + r * r, 0) / m;
+      lossHistory.push(mse2);
+      for (let j = 0; j < this.weights.length; j++) {
+        let grad = 0;
+        for (let i = 0; i < m; i++) {
+          grad += Xa[i][j] * residuals[i];
+        }
+        this.weights[j] -= lr * (2 / m) * grad;
+      }
+    }
+    return lossHistory;
+  }
+  // ─── Inference ─────────────────────────────────────────────────────────────
+  // ŷ = Σ wᵢ·xᵢ + bias    (bias = weights[last])
+  predict(x) {
+    if (this.weights.length === 0) {
+      throw new Error("LinearRegression.predict: model has not been fitted yet");
+    }
+    if (x.length !== this._nFeatures) {
+      throw new Error(
+        `LinearRegression.predict: expected ${this._nFeatures} features, got ${x.length}`
+      );
+    }
+    let out = this.weights[this._nFeatures];
+    for (let i = 0; i < this._nFeatures; i++) {
+      out += this.weights[i] * x[i];
+    }
+    return out;
+  }
+  // ─── Introspection ─────────────────────────────────────────────────────────
+  getCoefficients() {
+    if (this.weights.length === 0) {
+      throw new Error(
+        "LinearRegression.getCoefficients: model has not been fitted yet"
+      );
+    }
+    return {
+      weights: this.weights.slice(0, this._nFeatures),
+      bias: this.weights[this._nFeatures]
+    };
+  }
+};
+
+// src/LogisticRegression.ts
+function sigmoid5(z) {
+  return 1 / (1 + Math.exp(-z));
+}
+function bce(target, pred) {
+  const eps = 1e-15;
+  const p = Math.max(eps, Math.min(1 - eps, pred));
+  return -(target * Math.log(p) + (1 - target) * Math.log(1 - p));
+}
+var LogisticRegression = class {
+  constructor() {
+    this.weights = [];
+    this.bias = 0;
+    this._nFeatures = 0;
+  }
+  // ─── Train ────────────────────────────────────────────────────────────────
+  // Online SGD over the full dataset for `epochs` passes.
+  // Updates are applied after each sample (stochastic gradient descent).
+  //
+  // Returns the mean BCE loss per epoch for convergence monitoring.
+  train(X, y, lr, epochs) {
+    if (X.length === 0) throw new Error("LogisticRegression.train: X is empty");
+    if (X.length !== y.length) {
+      throw new Error(
+        `LogisticRegression.train: X has ${X.length} rows but y has ${y.length} labels`
+      );
+    }
+    validateNumber(lr, "LogisticRegression.train");
+    if (lr <= 0) throw new Error("LogisticRegression.train: lr must be positive");
+    if (!Number.isInteger(epochs) || epochs <= 0) {
+      throw new Error("LogisticRegression.train: epochs must be a positive integer");
+    }
+    this._nFeatures = X[0].length;
+    if (this.weights.length !== this._nFeatures) {
+      const limit = Math.sqrt(2 / this._nFeatures);
+      this.weights = Array.from(
+        { length: this._nFeatures },
+        () => (Math.random() * 2 - 1) * limit
+      );
+      this.bias = 0;
+    }
+    const lossHistory = [];
+    for (let epoch = 0; epoch < epochs; epoch++) {
+      let epochLoss = 0;
+      for (let i = 0; i < X.length; i++) {
+        const xi = X[i];
+        const yi = y[i];
+        let z = this.bias;
+        for (let j = 0; j < this._nFeatures; j++) z += this.weights[j] * xi[j];
+        const yHat = sigmoid5(z);
+        epochLoss += bce(yi, yHat);
+        const delta = yi - yHat;
+        for (let j = 0; j < this._nFeatures; j++) {
+          this.weights[j] += lr * delta * xi[j];
+        }
+        this.bias += lr * delta;
+      }
+      lossHistory.push(epochLoss / X.length);
+    }
+    return lossHistory;
+  }
+  // ─── Predict (probability) ────────────────────────────────────────────────
+  // Returns P(y=1|x) ∈ [0, 1].
+  predict(x) {
+    if (this.weights.length === 0) {
+      throw new Error("LogisticRegression.predict: model has not been trained yet");
+    }
+    validateArray(x, this._nFeatures, "LogisticRegression.predict");
+    let z = this.bias;
+    for (let j = 0; j < this._nFeatures; j++) z += this.weights[j] * x[j];
+    return sigmoid5(z);
+  }
+  // ─── Classify (hard label) ────────────────────────────────────────────────
+  // Returns 0 or 1 using 0.5 as the decision threshold.
+  classify(x) {
+    return this.predict(x) >= 0.5 ? 1 : 0;
+  }
+};
+var SoftmaxRegression = class {
+  constructor() {
+    // weights[k][j] = weight for class k, feature j
+    this.weights = [];
+    // biases[k] = bias for class k
+    this.biases = [];
+    this._nFeatures = 0;
+    this._nClasses = 0;
+  }
+  // ─── Softmax helper ──────────────────────────────────────────────────────
+  _softmax(scores) {
+    const maxScore = Math.max(...scores);
+    const exps = scores.map((s) => Math.exp(s - maxScore));
+    const sum = exps.reduce((a, b) => a + b, 0);
+    return exps.map((e) => e / sum);
+  }
+  // ─── Train ────────────────────────────────────────────────────────────────
+  // y must contain integer class labels 0..K-1.
+  // Returns mean cross-entropy loss per epoch.
+  train(X, y, lr, epochs) {
+    if (X.length === 0) throw new Error("SoftmaxRegression.train: X is empty");
+    if (X.length !== y.length) {
+      throw new Error(
+        `SoftmaxRegression.train: X has ${X.length} rows but y has ${y.length} labels`
+      );
+    }
+    validateNumber(lr, "SoftmaxRegression.train");
+    if (lr <= 0) throw new Error("SoftmaxRegression.train: lr must be positive");
+    if (!Number.isInteger(epochs) || epochs <= 0) {
+      throw new Error("SoftmaxRegression.train: epochs must be a positive integer");
+    }
+    this._nFeatures = X[0].length;
+    this._nClasses = Math.max(...y) + 1;
+    if (this._nClasses < 2) {
+      throw new Error("SoftmaxRegression.train: need at least 2 classes in y");
+    }
+    const limit = Math.sqrt(2 / this._nFeatures);
+    this.weights = Array.from(
+      { length: this._nClasses },
+      () => Array.from({ length: this._nFeatures }, () => (Math.random() * 2 - 1) * limit)
+    );
+    this.biases = new Array(this._nClasses).fill(0);
+    const lossHistory = [];
+    for (let epoch = 0; epoch < epochs; epoch++) {
+      let epochLoss = 0;
+      for (let i = 0; i < X.length; i++) {
+        const xi = X[i];
+        const trueClass = y[i];
+        const scores = this.weights.map((wk, k) => {
+          let s = this.biases[k];
+          for (let j = 0; j < this._nFeatures; j++) s += wk[j] * xi[j];
+          return s;
+        });
+        const probs = this._softmax(scores);
+        epochLoss += -Math.log(Math.max(probs[trueClass], 1e-15));
+        for (let k = 0; k < this._nClasses; k++) {
+          const delta = probs[k] - (k === trueClass ? 1 : 0);
+          for (let j = 0; j < this._nFeatures; j++) {
+            this.weights[k][j] -= lr * delta * xi[j];
+          }
+          this.biases[k] -= lr * delta;
+        }
+      }
+      lossHistory.push(epochLoss / X.length);
+    }
+    return lossHistory;
+  }
+  // ─── Predict (class probabilities) ───────────────────────────────────────
+  predictProba(x) {
+    if (this.weights.length === 0) {
+      throw new Error("SoftmaxRegression.predictProba: model has not been trained yet");
+    }
+    validateArray(x, this._nFeatures, "SoftmaxRegression.predictProba");
+    const scores = this.weights.map((wk, k) => {
+      let s = this.biases[k];
+      for (let j = 0; j < this._nFeatures; j++) s += wk[j] * x[j];
+      return s;
+    });
+    return this._softmax(scores);
+  }
+  // ─── Classify (argmax) ────────────────────────────────────────────────────
+  predict(x) {
+    const probs = this.predictProba(x);
+    return probs.indexOf(Math.max(...probs));
+  }
+};
+
+// src/NaiveBayes.ts
+var GaussianNaiveBayes = class {
+  constructor() {
+    // Per-class, per-feature statistics
+    this._means = /* @__PURE__ */ new Map();
+    this._variances = /* @__PURE__ */ new Map();
+    // Log prior: log P(class)
+    this._logPriors = /* @__PURE__ */ new Map();
+    this._classes = [];
+    this._nFeatures = 0;
+  }
+  // ─── Fit ───────────────────────────────────────────────────────────────────
+  // Scans the data once to compute μ, σ², and π per class.
+  // Variance is clamped to a minimum of 1e-9 to prevent division by zero
+  // when a feature is perfectly constant within a class.
+  fit(X, y) {
+    if (X.length === 0) throw new Error("GaussianNaiveBayes.fit: X is empty");
+    if (X.length !== y.length) {
+      throw new Error(
+        `GaussianNaiveBayes.fit: X has ${X.length} rows but y has ${y.length} labels`
+      );
+    }
+    this._nFeatures = X[0].length;
+    const m = X.length;
+    this._classes = [...new Set(y)].sort((a, b) => a - b);
+    for (const c of this._classes) {
+      const rows = X.filter((_, i) => y[i] === c);
+      const count = rows.length;
+      if (count === 0) continue;
+      this._logPriors.set(c, Math.log(count / m));
+      const means = new Array(this._nFeatures).fill(0);
+      for (const row of rows) {
+        for (let j = 0; j < this._nFeatures; j++) means[j] += row[j];
+      }
+      for (let j = 0; j < this._nFeatures; j++) means[j] /= count;
+      this._means.set(c, means);
+      const variances = new Array(this._nFeatures).fill(0);
+      for (const row of rows) {
+        for (let j = 0; j < this._nFeatures; j++) {
+          const diff = row[j] - means[j];
+          variances[j] += diff * diff;
+        }
+      }
+      for (let j = 0; j < this._nFeatures; j++) {
+        variances[j] = Math.max(variances[j] / count, 1e-9);
+      }
+      this._variances.set(c, variances);
+    }
+  }
+  // ─── Log-likelihood of a single feature value under a Gaussian ─────────────
+  // log P(x | μ, σ²) = −0.5·log(2πσ²) − (x−μ)² / (2σ²)
+  _logGaussian(x, mean, variance) {
+    return -0.5 * Math.log(2 * Math.PI * variance) - (x - mean) ** 2 / (2 * variance);
+  }
+  // ─── Log-scores per class ────────────────────────────────────────────────
+  // log P(class|x) ∝ log P(class) + Σⱼ log P(xⱼ|class)
+  _logScores(x) {
+    if (this._classes.length === 0) {
+      throw new Error("GaussianNaiveBayes: model has not been fitted yet");
+    }
+    if (x.length !== this._nFeatures) {
+      throw new Error(
+        `GaussianNaiveBayes: expected ${this._nFeatures} features, got ${x.length}`
+      );
+    }
+    const scores = /* @__PURE__ */ new Map();
+    for (const c of this._classes) {
+      const means = this._means.get(c);
+      const variances = this._variances.get(c);
+      const logPrior = this._logPriors.get(c);
+      let logLikelihood = 0;
+      for (let j = 0; j < this._nFeatures; j++) {
+        logLikelihood += this._logGaussian(x[j], means[j], variances[j]);
+      }
+      scores.set(c, logPrior + logLikelihood);
+    }
+    return scores;
+  }
+  // ─── Predict (argmax class) ──────────────────────────────────────────────
+  // Returns the class with the highest log-posterior.
+  // No exp() needed — argmax is order-preserving.
+  predict(x) {
+    const scores = this._logScores(x);
+    let bestClass = this._classes[0];
+    let bestScore = -Infinity;
+    for (const [c, s] of scores) {
+      if (s > bestScore) {
+        bestScore = s;
+        bestClass = c;
+      }
+    }
+    return bestClass;
+  }
+  // ─── Predict probabilities ────────────────────────────────────────────────
+  // Converts log-scores to actual probabilities using the log-sum-exp trick
+  // to avoid numerical overflow:
+  //
+  //   log Σₖ exp(sₖ) = maxScore + log Σₖ exp(sₖ − maxScore)
+  //
+  // Then P(c|x) = exp(score[c] − log Σ exp).
+  predictProba(x) {
+    const logScores = this._logScores(x);
+    const scores = [...logScores.values()];
+    const maxScore = Math.max(...scores);
+    const logSumExp = maxScore + Math.log(
+      scores.reduce((sum, s) => sum + Math.exp(s - maxScore), 0)
+    );
+    const proba = /* @__PURE__ */ new Map();
+    for (const [c, s] of logScores) {
+      proba.set(c, Math.exp(s - logSumExp));
+    }
+    return proba;
+  }
+};
+
+// src/DecisionTree.ts
+var DecisionTree = class {
+  constructor(options) {
+    this._root = null;
+    this._maxDepth = options?.maxDepth ?? 10;
+    this._minSamplesSplit = options?.minSamplesSplit ?? 2;
+    this._task = options?.task ?? "classification";
+    if (this._maxDepth <= 0) {
+      throw new Error("DecisionTree: maxDepth must be positive");
+    }
+    if (this._minSamplesSplit < 2) {
+      throw new Error("DecisionTree: minSamplesSplit must be at least 2");
+    }
+  }
+  // ─── Gini impurity ─────────────────────────────────────────────────────────
+  // G = 1 − Σₖ pₖ²
+  // G = 0 when all samples share one class (perfectly pure node).
+  // G ≈ 0.5 for a binary node with equal class distribution.
+  _gini(y) {
+    if (y.length === 0) return 0;
+    const counts = /* @__PURE__ */ new Map();
+    for (const label of y) counts.set(label, (counts.get(label) ?? 0) + 1);
+    let g = 1;
+    for (const count of counts.values()) {
+      const p = count / y.length;
+      g -= p * p;
+    }
+    return g;
+  }
+  // ─── Mean Squared Error (regression impurity) ─────────────────────────────
+  // MSE = (1/n) Σ (yᵢ − ȳ)²
+  _mse(y) {
+    if (y.length === 0) return 0;
+    const mean = y.reduce((a, b) => a + b, 0) / y.length;
+    return y.reduce((acc, v) => acc + (v - mean) ** 2, 0) / y.length;
+  }
+  // ─── Impurity selector ─────────────────────────────────────────────────────
+  _impurity(y) {
+    return this._task === "classification" ? this._gini(y) : this._mse(y);
+  }
+  // ─── Leaf value ────────────────────────────────────────────────────────────
+  // Classification: majority class. Regression: mean.
+  _leafValue(y) {
+    if (this._task === "regression") {
+      return y.reduce((a, b) => a + b, 0) / y.length;
+    }
+    const counts = /* @__PURE__ */ new Map();
+    for (const label of y) counts.set(label, (counts.get(label) ?? 0) + 1);
+    let bestClass = y[0];
+    let bestCount = 0;
+    for (const [cls, cnt] of counts) {
+      if (cnt > bestCount) {
+        bestCount = cnt;
+        bestClass = cls;
+      }
+    }
+    return bestClass;
+  }
+  // ─── Best split search ─────────────────────────────────────────────────────
+  // Brute-force: try every feature × every unique threshold.
+  // Returns the split that minimises weighted impurity (or null if none helps).
+  _bestSplit(X, y) {
+    const nFeatures = X[0].length;
+    const n = y.length;
+    let bestImpurity = Infinity;
+    let bestSplit = null;
+    const parentImpurity = this._impurity(y);
+    for (let j = 0; j < nFeatures; j++) {
+      const values = [...new Set(X.map((row) => row[j]))].sort((a, b) => a - b);
+      for (let vi = 0; vi < values.length - 1; vi++) {
+        const threshold = (values[vi] + values[vi + 1]) / 2;
+        const leftY = [];
+        const rightY = [];
+        for (let i = 0; i < n; i++) {
+          if (X[i][j] <= threshold) leftY.push(y[i]);
+          else rightY.push(y[i]);
+        }
+        if (leftY.length === 0 || rightY.length === 0) continue;
+        const weightedImpurity = leftY.length / n * this._impurity(leftY) + rightY.length / n * this._impurity(rightY);
+        if (weightedImpurity < bestImpurity && weightedImpurity < parentImpurity) {
+          bestImpurity = weightedImpurity;
+          bestSplit = { featureIndex: j, threshold };
+        }
+      }
+    }
+    return bestSplit;
+  }
+  // ─── Recursive tree builder ────────────────────────────────────────────────
+  _buildNode(X, y, depth) {
+    const allSame = y.every((v) => v === y[0]);
+    if (depth >= this._maxDepth || y.length < this._minSamplesSplit || allSame) {
+      return { isLeaf: true, value: this._leafValue(y) };
+    }
+    const split = this._bestSplit(X, y);
+    if (split === null) {
+      return { isLeaf: true, value: this._leafValue(y) };
+    }
+    const { featureIndex, threshold } = split;
+    const leftX = [];
+    const leftY = [];
+    const rightX = [];
+    const rightY = [];
+    for (let i = 0; i < y.length; i++) {
+      if (X[i][featureIndex] <= threshold) {
+        leftX.push(X[i]);
+        leftY.push(y[i]);
+      } else {
+        rightX.push(X[i]);
+        rightY.push(y[i]);
+      }
+    }
+    return {
+      isLeaf: false,
+      featureIndex,
+      threshold,
+      left: this._buildNode(leftX, leftY, depth + 1),
+      right: this._buildNode(rightX, rightY, depth + 1)
+    };
+  }
+  // ─── Fit ──────────────────────────────────────────────────────────────────
+  fit(X, y) {
+    if (X.length === 0) throw new Error("DecisionTree.fit: X is empty");
+    if (X.length !== y.length) {
+      throw new Error(
+        `DecisionTree.fit: X has ${X.length} rows but y has ${y.length} labels`
+      );
+    }
+    this._root = this._buildNode(X, y, 0);
+  }
+  // ─── Traverse a single sample ─────────────────────────────────────────────
+  _traverse(node, x) {
+    if (node.isLeaf) return node.value;
+    if (x[node.featureIndex] <= node.threshold) {
+      return this._traverse(node.left, x);
+    }
+    return this._traverse(node.right, x);
+  }
+  // ─── Predict single sample ────────────────────────────────────────────────
+  predict(x) {
+    if (this._root === null) {
+      throw new Error("DecisionTree.predict: model has not been fitted yet");
+    }
+    return this._traverse(this._root, x);
+  }
+  // ─── Predict batch ────────────────────────────────────────────────────────
+  predictBatch(X) {
+    return X.map((x) => this.predict(x));
+  }
+};
+
+// src/KMeans.ts
+var KMeans = class {
+  constructor(k, options = {}) {
+    if (!Number.isInteger(k) || k < 1) {
+      throw new Error(`KMeans: k must be a positive integer, got ${k}`);
+    }
+    this._k = k;
+    this._maxIter = options.maxIter ?? 300;
+    this.centroids = [];
+    if (options.seed !== void 0) {
+      let s = options.seed >>> 0;
+      this._rng = () => {
+        s += 1831565813;
+        let t = Math.imul(s ^ s >>> 15, 1 | s);
+        t ^= t + Math.imul(t ^ t >>> 7, 61 | t);
+        return ((t ^ t >>> 14) >>> 0) / 4294967296;
+      };
+    } else {
+      this._rng = () => Math.random();
+    }
+  }
+  // ── fit ────────────────────────────────────────────────────────────────────
+  // Runs K-Means++ init then Lloyd iterations until centroids stop moving or
+  // maxIter is reached.
+  fit(X) {
+    if (!X || X.length === 0) {
+      throw new Error("KMeans.fit: dataset X must be non-empty");
+    }
+    const n = X.length;
+    const d = X[0].length;
+    if (this._k > n) {
+      throw new Error(`KMeans.fit: k (${this._k}) cannot exceed number of samples (${n})`);
+    }
+    this.centroids = [];
+    const firstIdx = Math.floor(this._rng() * n);
+    this.centroids.push([...X[firstIdx]]);
+    for (let c = 1; c < this._k; c++) {
+      const dists = X.map((x) => this._minDistSq(x));
+      const total = dists.reduce((s, v) => s + v, 0);
+      let threshold = this._rng() * total;
+      let chosen = n - 1;
+      for (let i = 0; i < n; i++) {
+        threshold -= dists[i];
+        if (threshold <= 0) {
+          chosen = i;
+          break;
+        }
+      }
+      this.centroids.push([...X[chosen]]);
+    }
+    const assignments = new Int32Array(n);
+    for (let iter = 0; iter < this._maxIter; iter++) {
+      for (let i = 0; i < n; i++) {
+        assignments[i] = this._nearestCentroid(X[i]);
+      }
+      const sums = Array.from({ length: this._k }, () => new Array(d).fill(0));
+      const counts = new Int32Array(this._k);
+      for (let i = 0; i < n; i++) {
+        const c = assignments[i];
+        counts[c]++;
+        for (let j = 0; j < d; j++) sums[c][j] += X[i][j];
+      }
+      let moved = false;
+      for (let c = 0; c < this._k; c++) {
+        if (counts[c] === 0) continue;
+        for (let j = 0; j < d; j++) {
+          const newVal = sums[c][j] / counts[c];
+          if (Math.abs(newVal - this.centroids[c][j]) > 1e-10) moved = true;
+          this.centroids[c][j] = newVal;
+        }
+      }
+      if (!moved) break;
+    }
+  }
+  // ── predict ────────────────────────────────────────────────────────────────
+  // Returns the index of the nearest centroid for a single point.
+  predict(x) {
+    if (this.centroids.length === 0) {
+      throw new Error("KMeans.predict: call fit() before predict()");
+    }
+    return this._nearestCentroid(x);
+  }
+  // ── predictBatch ──────────────────────────────────────────────────────────
+  // Assigns each point in X to a cluster. Returns array of cluster indices.
+  predictBatch(X) {
+    return X.map((x) => this.predict(x));
+  }
+  // ── inertia ───────────────────────────────────────────────────────────────
+  //   J = Σᵢ d(xᵢ, μ_{cᵢ})²
+  // Lower inertia = tighter clusters. Use the elbow method to pick K:
+  // run fit() for K = 1..10 and plot inertia — the elbow is your optimal K.
+  inertia(X) {
+    if (this.centroids.length === 0) {
+      throw new Error("KMeans.inertia: call fit() before inertia()");
+    }
+    return X.reduce((sum, x) => sum + this._minDistSq(x), 0);
+  }
+  // ── Private helpers ────────────────────────────────────────────────────────
+  _euclideanSq(a, b) {
+    let s = 0;
+    for (let i = 0; i < a.length; i++) s += (a[i] - b[i]) ** 2;
+    return s;
+  }
+  _minDistSq(x) {
+    let min = Infinity;
+    for (const c of this.centroids) {
+      const d = this._euclideanSq(x, c);
+      if (d < min) min = d;
+    }
+    return min;
+  }
+  _nearestCentroid(x) {
+    let best = 0;
+    let bestDist = Infinity;
+    for (let c = 0; c < this.centroids.length; c++) {
+      const d = this._euclideanSq(x, this.centroids[c]);
+      if (d < bestDist) {
+        bestDist = d;
+        best = c;
+      }
+    }
+    return best;
+  }
+};
+
+// src/PCA.ts
+var PCA = class {
+  constructor(nComponents) {
+    if (!Number.isInteger(nComponents) || nComponents < 1) {
+      throw new Error(`PCA: nComponents must be a positive integer, got ${nComponents}`);
+    }
+    this._nComponents = nComponents;
+    this.components = [];
+    this.explainedVariance = [];
+    this.mean = [];
+  }
+  // ── fit ────────────────────────────────────────────────────────────────────
+  // Computes the mean and the top nComponents principal components from X.
+  fit(X) {
+    const n = X.length;
+    if (n < 2) throw new Error("PCA.fit: need at least 2 samples");
+    const p = X[0].length;
+    if (this._nComponents > p) {
+      throw new Error(
+        `PCA: nComponents (${this._nComponents}) cannot exceed number of features (${p})`
+      );
+    }
+    this.mean = new Array(p).fill(0);
+    for (const row of X) for (let j = 0; j < p; j++) this.mean[j] += row[j];
+    for (let j = 0; j < p; j++) this.mean[j] /= n;
+    const Xc = X.map((row) => row.map((v, j) => v - this.mean[j]));
+    let cov = this._covMatrix(Xc, n, p);
+    this.components = [];
+    this.explainedVariance = [];
+    for (let c = 0; c < this._nComponents; c++) {
+      const { eigenvector, eigenvalue } = this._powerIteration(cov, p);
+      this.components.push(eigenvector);
+      this.explainedVariance.push(eigenvalue);
+      for (let i = 0; i < p; i++) {
+        for (let j = 0; j < p; j++) {
+          cov[i][j] -= eigenvalue * eigenvector[i] * eigenvector[j];
+        }
+      }
+    }
+  }
+  // ── transform ──────────────────────────────────────────────────────────────
+  //   Z = (X - μ) · Vᵀ       shape [n × nComponents]
+  transform(X) {
+    if (this.components.length === 0) {
+      throw new Error("PCA.transform: call fit() before transform()");
+    }
+    return X.map((row) => {
+      const centered = row.map((v, j) => v - this.mean[j]);
+      return this.components.map(
+        (pc) => pc.reduce((s, w, j) => s + w * centered[j], 0)
+      );
+    });
+  }
+  // ── fitTransform ───────────────────────────────────────────────────────────
+  // Convenience: fit() then transform() in a single call.
+  fitTransform(X) {
+    this.fit(X);
+    return this.transform(X);
+  }
+  // ── inverseTransform ───────────────────────────────────────────────────────
+  //   X̂ = Z · V + μ          shape [n × nFeatures] (approximate reconstruction)
+  inverseTransform(Z) {
+    if (this.components.length === 0) {
+      throw new Error("PCA.inverseTransform: call fit() before inverseTransform()");
+    }
+    const p = this.mean.length;
+    return Z.map((z) => {
+      const row = new Array(p).fill(0);
+      for (let c = 0; c < this._nComponents; c++) {
+        for (let j = 0; j < p; j++) {
+          row[j] += z[c] * this.components[c][j];
+        }
+      }
+      return row.map((v, j) => v + this.mean[j]);
+    });
+  }
+  // ── explainedVarianceRatio ─────────────────────────────────────────────────
+  //   rₖ = λₖ / Σⱼ λⱼ
+  // Sum of all ratios ≤ 1. If you chose nComponents = p, the sum is exactly 1.
+  explainedVarianceRatio() {
+    const total = this.explainedVariance.reduce((s, v) => s + v, 0);
+    if (total === 0) return this.explainedVariance.map(() => 0);
+    return this.explainedVariance.map((v) => v / total);
+  }
+  // ── Private helpers ────────────────────────────────────────────────────────
+  // Build the [p×p] covariance matrix from a centered matrix Xc.
+  _covMatrix(Xc, n, p) {
+    const cov = Array.from({ length: p }, () => new Array(p).fill(0));
+    for (const row of Xc) {
+      for (let i = 0; i < p; i++) {
+        for (let j = i; j < p; j++) {
+          cov[i][j] += row[i] * row[j];
+        }
+      }
+    }
+    for (let i = 0; i < p; i++) {
+      cov[i][i] /= n;
+      for (let j = i + 1; j < p; j++) {
+        cov[i][j] /= n;
+        cov[j][i] = cov[i][j];
+      }
+    }
+    return cov;
+  }
+  // Power iteration: find the dominant eigenvector of a symmetric matrix.
+  //   v ← M·v / ‖M·v‖   (repeated until ‖v_new - v_old‖ < tol)
+  // Returns both the eigenvector (unit length) and its eigenvalue λ = vᵀ·M·v.
+  _powerIteration(M, p, maxIter = 1e3, tol = 1e-10) {
+    let v = Array.from({ length: p }, () => Math.random() - 0.5);
+    v = this._normalize(v);
+    for (let iter = 0; iter < maxIter; iter++) {
+      const Mv2 = this._matvec(M, v);
+      const vNew = this._normalize(Mv2);
+      const dot = v.reduce((s, vi, i) => s + vi * vNew[i], 0);
+      v = vNew;
+      if (Math.abs(Math.abs(dot) - 1) < tol) break;
+    }
+    const Mv = this._matvec(M, v);
+    const eigenvalue = v.reduce((s, vi, i) => s + vi * Mv[i], 0);
+    return { eigenvector: v, eigenvalue: Math.max(0, eigenvalue) };
+  }
+  _matvec(M, v) {
+    return M.map((row) => row.reduce((s, mij, j) => s + mij * v[j], 0));
+  }
+  _normalize(v) {
+    const norm = Math.sqrt(v.reduce((s, vi) => s + vi * vi, 0));
+    if (norm < 1e-14) return v;
+    return v.map((vi) => vi / norm);
+  }
+};
+
+// src/SOM.ts
+var SOM = class {
+  constructor(rows, cols, inputSize, options = {}) {
+    if (rows < 1 || cols < 1 || inputSize < 1) {
+      throw new Error(
+        `SOM: rows, cols and inputSize must be positive integers, got ${rows}\xD7${cols}\xD7${inputSize}`
+      );
+    }
+    this._rows = rows;
+    this._cols = cols;
+    this._inputSize = inputSize;
+    this._initialLr = options.initialLr ?? 0.5;
+    this._finalLr = options.finalLr ?? 0.01;
+    this._initialSigma = options.initialSigma ?? Math.max(rows, cols) / 2;
+    this._finalSigma = options.finalSigma ?? 1;
+    this.weights = Array.from(
+      { length: rows },
+      () => Array.from(
+        { length: cols },
+        () => Array.from({ length: inputSize }, () => Math.random())
+      )
+    );
+  }
+  // ── train ──────────────────────────────────────────────────────────────────
+  // Iterates over the dataset `epochs` times, presenting each sample and
+  // performing a BMU search + neighborhood weight update.
+  train(X, epochs) {
+    if (!X || X.length === 0) {
+      throw new Error("SOM.train: dataset X must be non-empty");
+    }
+    if (X[0].length !== this._inputSize) {
+      throw new Error(
+        `SOM.train: expected input size ${this._inputSize}, got ${X[0].length}`
+      );
+    }
+    const totalSteps = epochs * X.length;
+    let step = 0;
+    for (let epoch = 0; epoch < epochs; epoch++) {
+      const indices = this._shuffle(X.length);
+      for (const idx of indices) {
+        const x = X[idx];
+        const t = step / totalSteps;
+        const lr = this._initialLr * Math.pow(this._finalLr / this._initialLr, t);
+        const sigma = this._initialSigma * Math.pow(this._finalSigma / this._initialSigma, t);
+        const sigma2 = 2 * sigma * sigma;
+        const [bmuR, bmuC] = this.getBMU(x);
+        for (let r = 0; r < this._rows; r++) {
+          for (let c = 0; c < this._cols; c++) {
+            const dr = r - bmuR;
+            const dc = c - bmuC;
+            const gridDistSq = dr * dr + dc * dc;
+            const h = Math.exp(-gridDistSq / sigma2);
+            if (h < 1e-6) continue;
+            const w = this.weights[r][c];
+            for (let i = 0; i < this._inputSize; i++) {
+              w[i] += lr * h * (x[i] - w[i]);
+            }
+          }
+        }
+        step++;
+      }
+    }
+  }
+  // ── getBMU ─────────────────────────────────────────────────────────────────
+  // Returns [row, col] of the Best Matching Unit for input x.
+  //   BMU = argmin_{r,c} ‖x − w[r][c]‖²
+  getBMU(x) {
+    if (x.length !== this._inputSize) {
+      throw new Error(
+        `SOM.getBMU: expected input of length ${this._inputSize}, got ${x.length}`
+      );
+    }
+    let bestR = 0;
+    let bestC = 0;
+    let bestDist = Infinity;
+    for (let r = 0; r < this._rows; r++) {
+      for (let c = 0; c < this._cols; c++) {
+        const dist = this._distSq(x, this.weights[r][c]);
+        if (dist < bestDist) {
+          bestDist = dist;
+          bestR = r;
+          bestC = c;
+        }
+      }
+    }
+    return [bestR, bestC];
+  }
+  // ── predict ────────────────────────────────────────────────────────────────
+  // Alias for getBMU — returns [row, col] of the winning neuron.
+  predict(x) {
+    return this.getBMU(x);
+  }
+  // ── quantizationError ─────────────────────────────────────────────────────
+  //   QE = (1/n) · Σᵢ ‖xᵢ − w[BMU(xᵢ)]‖
+  // Measures how well the prototypes represent the data. Lower is better.
+  quantizationError(X) {
+    let total = 0;
+    for (const x of X) {
+      const [r, c] = this.getBMU(x);
+      total += Math.sqrt(this._distSq(x, this.weights[r][c]));
+    }
+    return total / X.length;
+  }
+  // ── Private helpers ────────────────────────────────────────────────────────
+  _distSq(a, b) {
+    let s = 0;
+    for (let i = 0; i < a.length; i++) s += (a[i] - b[i]) ** 2;
+    return s;
+  }
+  // Fisher-Yates shuffle — returns an array of shuffled indices.
+  _shuffle(n) {
+    const arr = Array.from({ length: n }, (_, i) => i);
+    for (let i = n - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+    return arr;
+  }
+};
+
+// src/HopfieldNetwork.ts
+var HopfieldNetwork = class {
+  constructor(n) {
+    if (!Number.isInteger(n) || n < 1) {
+      throw new Error(`HopfieldNetwork: n must be a positive integer, got ${n}`);
+    }
+    this.n = n;
+    this.storedPatterns = 0;
+    this.weights = Array.from({ length: n }, () => new Array(n).fill(0));
+  }
+  // ── store ──────────────────────────────────────────────────────────────────
+  // Adds a pattern to the network's memory using the Hebbian learning rule:
+  //   W ← W + (1/N) · p · pᵀ   (diagonal stays 0)
+  //
+  // The pattern must be bipolar: each element must be +1 or −1.
+  store(pattern) {
+    if (pattern.length !== this.n) {
+      throw new Error(
+        `HopfieldNetwork.store: pattern length ${pattern.length} does not match network size ${this.n}`
+      );
+    }
+    for (let i = 0; i < this.n; i++) {
+      if (pattern[i] !== 1 && pattern[i] !== -1) {
+        throw new Error(
+          `HopfieldNetwork.store: pattern values must be +1 or -1, got ${pattern[i]} at index ${i}. Use HopfieldNetwork.binarize() to convert 0/1 arrays.`
+        );
+      }
+    }
+    const scale = 1 / this.n;
+    for (let i = 0; i < this.n; i++) {
+      for (let j = 0; j < this.n; j++) {
+        if (i !== j) {
+          this.weights[i][j] += scale * pattern[i] * pattern[j];
+        }
+      }
+    }
+    this.storedPatterns++;
+    if (this.storedPatterns > Math.floor(0.138 * this.n)) {
+    }
+  }
+  // ── recall ─────────────────────────────────────────────────────────────────
+  // Starting from `input` (a noisy/partial copy of a stored pattern), runs
+  // asynchronous updates until convergence or maxIter is reached.
+  //   hᵢ = Σⱼ Wᵢⱼ · sⱼ
+  //   sᵢ ← sign(hᵢ)           (+1, −1; unchanged when hᵢ = 0)
+  // Returns the converged state vector.
+  recall(input, maxIter = 20 * this.n) {
+    if (input.length !== this.n) {
+      throw new Error(
+        `HopfieldNetwork.recall: input length ${input.length} does not match network size ${this.n}`
+      );
+    }
+    const s = [...input];
+    const order = Array.from({ length: this.n }, (_, i) => i);
+    for (let iter = 0; iter < maxIter; iter++) {
+      this._shuffleInPlace(order);
+      let changed = false;
+      for (const i of order) {
+        let h = 0;
+        const row = this.weights[i];
+        for (let j = 0; j < this.n; j++) h += row[j] * s[j];
+        const newSi = h > 0 ? 1 : h < 0 ? -1 : s[i];
+        if (newSi !== s[i]) {
+          s[i] = newSi;
+          changed = true;
+        }
+      }
+      if (!changed) break;
+    }
+    return s;
+  }
+  // ── energy ─────────────────────────────────────────────────────────────────
+  //   E(s) = −½ · Σᵢⱼ Wᵢⱼ · sᵢ · sⱼ
+  // Stored patterns are local minima. Updates always push E downward (or keep
+  // it constant), so the network is guaranteed to converge.
+  energy(state) {
+    if (state.length !== this.n) {
+      throw new Error(
+        `HopfieldNetwork.energy: state length ${state.length} does not match network size ${this.n}`
+      );
+    }
+    let e = 0;
+    for (let i = 0; i < this.n; i++) {
+      for (let j = 0; j < this.n; j++) {
+        e += this.weights[i][j] * state[i] * state[j];
+      }
+    }
+    return -0.5 * e;
+  }
+  // ── binarize ───────────────────────────────────────────────────────────────
+  // Converts a 0/1 array to bipolar −1/+1.
+  //   0 → −1,   1 → +1
+  static binarize(arr) {
+    return arr.map((v) => v === 0 ? -1 : 1);
+  }
+  // ── unbinarize ─────────────────────────────────────────────────────────────
+  // Converts a bipolar −1/+1 array back to 0/1.
+  //   −1 → 0,   +1 → 1
+  static unbinarize(arr) {
+    return arr.map((v) => v === -1 ? 0 : 1);
+  }
+  // ── Private helpers ────────────────────────────────────────────────────────
+  _shuffleInPlace(arr) {
+    for (let i = arr.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [arr[i], arr[j]] = [arr[j], arr[i]];
+    }
+  }
+};
+
+// src/Autoencoder.ts
+var Autoencoder = class {
+  constructor(inputSize, encoderHidden, latentSize, decoderHidden, options = {}) {
+    if (inputSize < 1) {
+      throw new Error(`Autoencoder: inputSize must be \u2265 1, got ${inputSize}`);
+    }
+    if (latentSize < 1) {
+      throw new Error(`Autoencoder: latentSize must be \u2265 1, got ${latentSize}`);
+    }
+    if (latentSize >= inputSize) {
+    }
+    this._inputSize = inputSize;
+    this._latentSize = latentSize;
+    const encoderStructure = [inputSize, ...encoderHidden, latentSize];
+    const encoderOptions = { ...options };
+    if (options.activations) {
+      const nEncoderLayers = encoderStructure.length - 1;
+      if (options.activations.length >= nEncoderLayers) {
+        encoderOptions.activations = options.activations.slice(0, nEncoderLayers);
+      } else {
+        encoderOptions.activations = void 0;
+      }
+    }
+    this.encoder = new NetworkN(encoderStructure, encoderOptions);
+    const decoderStructure = [latentSize, ...decoderHidden, inputSize];
+    const decoderOptions = { ...options };
+    if (options.activations) {
+      const nEncoderLayers = encoderStructure.length - 1;
+      const nDecoderLayers = decoderStructure.length - 1;
+      const remaining = options.activations.slice(nEncoderLayers);
+      if (remaining.length >= nDecoderLayers) {
+        decoderOptions.activations = remaining.slice(0, nDecoderLayers);
+      } else {
+        decoderOptions.activations = void 0;
+      }
+    }
+    this.decoder = new NetworkN(decoderStructure, decoderOptions);
+  }
+  // ── encode ─────────────────────────────────────────────────────────────────
+  // Maps an input vector to its latent representation.
+  //   z = encoder(x) ∈ ℝ^latentSize
+  encode(x) {
+    if (x.length !== this._inputSize) {
+      throw new Error(
+        `Autoencoder.encode: expected input of length ${this._inputSize}, got ${x.length}`
+      );
+    }
+    return this.encoder.predict(x);
+  }
+  // ── decode ─────────────────────────────────────────────────────────────────
+  // Reconstructs an input from its latent code.
+  //   x̂ = decoder(z) ∈ ℝ^inputSize
+  decode(z) {
+    if (z.length !== this._latentSize) {
+      throw new Error(
+        `Autoencoder.decode: expected latent vector of length ${this._latentSize}, got ${z.length}`
+      );
+    }
+    return this.decoder.predict(z);
+  }
+  // ── reconstruct ───────────────────────────────────────────────────────────
+  // Convenience: encode then decode in a single call.
+  //   x̂ = decode(encode(x))
+  reconstruct(x) {
+    return this.decode(this.encode(x));
+  }
+  // ── train ──────────────────────────────────────────────────────────────────
+  // Trains on a single example using backpropagation through both sub-networks.
+  //
+  // Gradient flow:
+  //   1. Forward:  z = encoder(x),  x̂ = decoder(z)
+  //   2. Compute MSE output deltas at x̂: δᵢ = (xᵢ − x̂ᵢ) · act'(x̂ᵢ)
+  //   3. Walk backward through decoder layers to get ∂L/∂z (BEFORE updating weights)
+  //   4. Update decoder weights via trainWithDeltas(z, outputDeltas, lr)
+  //   5. Update encoder weights via trainWithDeltas(x, dLdz, lr)
+  //
+  // Returns the MSE reconstruction loss: (1/d) · Σᵢ (xᵢ − x̂ᵢ)².
+  train(x, lr) {
+    if (x.length !== this._inputSize) {
+      throw new Error(
+        `Autoencoder.train: expected input of length ${this._inputSize}, got ${x.length}`
+      );
+    }
+    const z = this.encoder.predict(x, true);
+    const xHat = this.decoder.predict(z, true);
+    const loss = mse(xHat, x);
+    const decoderOutAct = this.decoder.layers[this.decoder.layers.length - 1].neurons[0].activation;
+    const outputDeltas = xHat.map((xh, i) => (x[i] - xh) * decoderOutAct.dfn(xh));
+    const decoderLayers = this.decoder.layers;
+    const decoderActVals = [z];
+    let cur = [...z];
+    for (const layer of decoderLayers) {
+      cur = layer.predict(cur);
+      decoderActVals.push(cur);
+    }
+    let deltas = outputDeltas;
+    for (let l = decoderLayers.length - 1; l >= 0; l--) {
+      const layer = decoderLayers[l];
+      const prevAct = decoderActVals[l];
+      const prevLayerActivation = l > 0 ? decoderLayers[l - 1].neurons[0].activation : null;
+      const prevDeltas = prevAct.map((out, j) => {
+        const errProp = layer.neurons.reduce((s, n, k) => s + deltas[k] * n.weights[j], 0);
+        return prevLayerActivation ? errProp * prevLayerActivation.dfn(out) : errProp;
+      });
+      deltas = prevDeltas;
+    }
+    const dLdz = deltas;
+    this.decoder.trainWithDeltas(z, outputDeltas, lr);
+    this.encoder.trainWithDeltas(x, dLdz, lr);
+    return loss;
+  }
+  // ── trainBatch ────────────────────────────────────────────────────────────
+  // Trains on a batch of examples and returns the mean reconstruction MSE.
+  trainBatch(X, lr) {
+    if (X.length === 0) {
+      throw new Error("Autoencoder.trainBatch: batch X must be non-empty");
+    }
+    let totalLoss = 0;
+    for (const x of X) totalLoss += this.train(x, lr);
+    return totalLoss / X.length;
+  }
+};
+
+// src/Conv2D.ts
+var Conv2D = class {
+  constructor(inputHeight, inputWidth, channels, kernelSize, filters, options) {
+    // [filters]
+    this._input = null;
+    this._padded = null;
+    const [kH, kW] = Array.isArray(kernelSize) ? kernelSize : [kernelSize, kernelSize];
+    if (inputHeight <= 0 || inputWidth <= 0 || channels <= 0 || filters <= 0) {
+      throw new Error("Conv2D: dimensions and filters must be positive");
+    }
+    if (kH <= 0 || kW <= 0) {
+      throw new Error("Conv2D: kernelSize must be positive");
+    }
+    this.inputHeight = inputHeight;
+    this.inputWidth = inputWidth;
+    this.channels = channels;
+    this.kH = kH;
+    this.kW = kW;
+    this.filters = filters;
+    this.stride = options?.stride ?? 1;
+    this.padding = options?.padding ?? "valid";
+    const optimizerFactory = options?.optimizerFactory ?? (() => new SGD());
+    const limit = Math.sqrt(2 / (kH * kW * channels));
+    this.kernels = Array.from(
+      { length: filters },
+      () => Array.from(
+        { length: kH },
+        () => Array.from(
+          { length: kW },
+          () => Array.from({ length: channels }, () => (Math.random() * 2 - 1) * limit)
+        )
+      )
+    );
+    this.biases = new Array(filters).fill(0);
+    this._kOpts = Array.from(
+      { length: filters },
+      () => Array.from(
+        { length: kH },
+        () => Array.from(
+          { length: kW },
+          () => Array.from({ length: channels }, () => optimizerFactory())
+        )
+      )
+    );
+    this._bOpts = Array.from({ length: filters }, () => optimizerFactory());
+  }
+  // ── Padding helper ────────────────────────────────────────────────────────
+  _pad(input) {
+    if (this.padding === "valid") return input;
+    const padH = Math.floor(this.kH / 2);
+    const padW = Math.floor(this.kW / 2);
+    const H = input.length;
+    const W = input[0].length;
+    const C = this.channels;
+    const paddedH = H + 2 * padH;
+    const paddedW = W + 2 * padW;
+    const out = Array.from(
+      { length: paddedH },
+      () => Array.from({ length: paddedW }, () => new Array(C).fill(0))
+    );
+    for (let h = 0; h < H; h++) {
+      for (let w = 0; w < W; w++) {
+        for (let c = 0; c < C; c++) {
+          out[h + padH][w + padW][c] = input[h][w][c];
+        }
+      }
+    }
+    return out;
+  }
+  // ── Output shape ──────────────────────────────────────────────────────────
+  outputShape() {
+    const padH = this.padding === "same" ? Math.floor(this.kH / 2) : 0;
+    const padW = this.padding === "same" ? Math.floor(this.kW / 2) : 0;
+    const outH = Math.floor((this.inputHeight - this.kH + 2 * padH) / this.stride) + 1;
+    const outW = Math.floor((this.inputWidth - this.kW + 2 * padW) / this.stride) + 1;
+    return [outH, outW, this.filters];
+  }
+  // ── Forward pass ──────────────────────────────────────────────────────────
+  // output[h][w][f] = bias[f] + Σ_{kh,kw,c} kernel[f][kh][kw][c] · input[h·s+kh][w·s+kw][c]
+  forward(input) {
+    if (input.length !== this.inputHeight) {
+      throw new Error(`Conv2D.forward: expected height ${this.inputHeight}, got ${input.length}`);
+    }
+    if (input[0].length !== this.inputWidth) {
+      throw new Error(`Conv2D.forward: expected width ${this.inputWidth}, got ${input[0].length}`);
+    }
+    this._input = input;
+    this._padded = this._pad(input);
+    const padded = this._padded;
+    const padH = this.padding === "same" ? Math.floor(this.kH / 2) : 0;
+    const padW = this.padding === "same" ? Math.floor(this.kW / 2) : 0;
+    const outH = Math.floor((this.inputHeight - this.kH + 2 * padH) / this.stride) + 1;
+    const outW = Math.floor((this.inputWidth - this.kW + 2 * padW) / this.stride) + 1;
+    const output = Array.from(
+      { length: outH },
+      () => Array.from({ length: outW }, () => new Array(this.filters).fill(0))
+    );
+    for (let f = 0; f < this.filters; f++) {
+      for (let h = 0; h < outH; h++) {
+        for (let w = 0; w < outW; w++) {
+          let sum = this.biases[f];
+          for (let kh = 0; kh < this.kH; kh++) {
+            for (let kw = 0; kw < this.kW; kw++) {
+              for (let c = 0; c < this.channels; c++) {
+                sum += this.kernels[f][kh][kw][c] * padded[h * this.stride + kh][w * this.stride + kw][c];
+              }
+            }
+          }
+          output[h][w][f] = sum;
+        }
+      }
+    }
+    return output;
+  }
+  // ── Backward pass ─────────────────────────────────────────────────────────
+  // dOutput: number[][][] of shape [outH][outW][filters]
+  // Returns dInput: number[][][] of shape [H][W][channels]
+  backward(dOutput, lr) {
+    if (!this._padded || !this._input) {
+      throw new Error("Conv2D.backward: call forward() first");
+    }
+    const padded = this._padded;
+    const outH = dOutput.length;
+    const outW = dOutput[0].length;
+    const dKernels = Array.from(
+      { length: this.filters },
+      () => Array.from(
+        { length: this.kH },
+        () => Array.from({ length: this.kW }, () => new Array(this.channels).fill(0))
+      )
+    );
+    const dBiases = new Array(this.filters).fill(0);
+    const dPadded = Array.from(
+      { length: padded.length },
+      () => Array.from({ length: padded[0].length }, () => new Array(this.channels).fill(0))
+    );
+    for (let f = 0; f < this.filters; f++) {
+      for (let h = 0; h < outH; h++) {
+        for (let w = 0; w < outW; w++) {
+          const dv = dOutput[h][w][f];
+          dBiases[f] += dv;
+          for (let kh = 0; kh < this.kH; kh++) {
+            for (let kw = 0; kw < this.kW; kw++) {
+              for (let c = 0; c < this.channels; c++) {
+                const ph = h * this.stride + kh;
+                const pw = w * this.stride + kw;
+                dKernels[f][kh][kw][c] += dv * padded[ph][pw][c];
+                dPadded[ph][pw][c] += dv * this.kernels[f][kh][kw][c];
+              }
+            }
+          }
+        }
+      }
+    }
+    for (let f = 0; f < this.filters; f++) {
+      for (let kh = 0; kh < this.kH; kh++) {
+        for (let kw = 0; kw < this.kW; kw++) {
+          for (let c = 0; c < this.channels; c++) {
+            this.kernels[f][kh][kw][c] = this._kOpts[f][kh][kw][c].step(
+              this.kernels[f][kh][kw][c],
+              dKernels[f][kh][kw][c],
+              lr
+            );
+          }
+        }
+      }
+      this.biases[f] = this._bOpts[f].step(this.biases[f], dBiases[f], lr);
+    }
+    if (this.padding === "same") {
+      const padH = Math.floor(this.kH / 2);
+      const padW = Math.floor(this.kW / 2);
+      return dPadded.slice(padH, padH + this.inputHeight).map((row) => row.slice(padW, padW + this.inputWidth));
+    }
+    return dPadded.slice(0, this.inputHeight).map((row) => row.slice(0, this.inputWidth));
+  }
+  // ── Weight serialization ──────────────────────────────────────────────────
+  getWeights() {
+    const w = [];
+    for (const kf of this.kernels)
+      for (const kh of kf)
+        for (const kw of kh)
+          for (const v of kw)
+            w.push(v);
+    w.push(...this.biases);
+    return w;
+  }
+  setWeights(weights) {
+    let idx = 0;
+    for (let f = 0; f < this.filters; f++)
+      for (let kh = 0; kh < this.kH; kh++)
+        for (let kw = 0; kw < this.kW; kw++)
+          for (let c = 0; c < this.channels; c++)
+            this.kernels[f][kh][kw][c] = weights[idx++];
+    for (let f = 0; f < this.filters; f++)
+      this.biases[f] = weights[idx++];
+  }
+};
+
+// src/MaxPool2D.ts
+var MaxPool2D = class {
+  constructor(poolSize, stride) {
+    // Mask stored during forward pass for backprop:
+    // _maxMask[h][w][c] = true if input[h][w][c] was the maximum in its window
+    this._maxMask = null;
+    this._inputH = 0;
+    this._inputW = 0;
+    this._inputC = 0;
+    if (poolSize <= 0) {
+      throw new Error("MaxPool2D: poolSize must be positive");
+    }
+    this.poolSize = poolSize;
+    this.stride = stride ?? poolSize;
+  }
+  // ── Output shape ──────────────────────────────────────────────────────────
+  outputShape(inputH, inputW, channels) {
+    const outH = Math.floor((inputH - this.poolSize) / this.stride) + 1;
+    const outW = Math.floor((inputW - this.poolSize) / this.stride) + 1;
+    return [outH, outW, channels];
+  }
+  // ── Forward pass ──────────────────────────────────────────────────────────
+  // output[oh][ow][c] = max over ph in [0..poolSize), pw in [0..poolSize) of
+  //                     input[oh·stride + ph][ow·stride + pw][c]
+  forward(input) {
+    const H = input.length;
+    const W = input[0].length;
+    const C = input[0][0].length;
+    this._inputH = H;
+    this._inputW = W;
+    this._inputC = C;
+    const [outH, outW] = this.outputShape(H, W, C);
+    const output = Array.from(
+      { length: outH },
+      () => Array.from({ length: outW }, () => new Array(C).fill(-Infinity))
+    );
+    this._maxMask = Array.from(
+      { length: H },
+      () => Array.from({ length: W }, () => new Array(C).fill(false))
+    );
+    for (let oh = 0; oh < outH; oh++) {
+      for (let ow = 0; ow < outW; ow++) {
+        for (let c = 0; c < C; c++) {
+          let maxVal = -Infinity;
+          let maxPH = 0;
+          let maxPW = 0;
+          for (let ph = 0; ph < this.poolSize; ph++) {
+            for (let pw = 0; pw < this.poolSize; pw++) {
+              const val = input[oh * this.stride + ph][ow * this.stride + pw][c];
+              if (val > maxVal) {
+                maxVal = val;
+                maxPH = ph;
+                maxPW = pw;
+              }
+            }
+          }
+          output[oh][ow][c] = maxVal;
+          this._maxMask[oh * this.stride + maxPH][ow * this.stride + maxPW][c] = true;
+        }
+      }
+    }
+    return output;
+  }
+  // ── Backward pass ─────────────────────────────────────────────────────────
+  // dOutput: number[][][] of shape [outH][outW][C]
+  // Returns dInput: number[][][] of shape [H][W][C]
+  // Gradient is routed only to the max position; all others get 0.
+  backward(dOutput) {
+    if (!this._maxMask) {
+      throw new Error("MaxPool2D.backward: call forward() first");
+    }
+    const dInput = Array.from(
+      { length: this._inputH },
+      () => Array.from({ length: this._inputW }, () => new Array(this._inputC).fill(0))
+    );
+    const outH = dOutput.length;
+    const outW = dOutput[0].length;
+    const C = this._inputC;
+    for (let oh = 0; oh < outH; oh++) {
+      for (let ow = 0; ow < outW; ow++) {
+        for (let c = 0; c < C; c++) {
+          for (let ph = 0; ph < this.poolSize; ph++) {
+            for (let pw = 0; pw < this.poolSize; pw++) {
+              const ih = oh * this.stride + ph;
+              const iw = ow * this.stride + pw;
+              if (this._maxMask[ih][iw][c]) {
+                dInput[ih][iw][c] += dOutput[oh][ow][c];
+              }
+            }
+          }
+        }
+      }
+    }
+    return dInput;
+  }
+};
+
+// src/Flatten.ts
+var Flatten = class {
+  constructor() {
+    this.inputShape = null;
+  }
+  // [H, W, C]
+  // ── Forward pass ──────────────────────────────────────────────────────────
+  // Flattens input[h][w][c] into a 1D array in row-major, channel-last order.
+  forward(input) {
+    const H = input.length;
+    const W = input[0].length;
+    const C = input[0][0].length;
+    this.inputShape = [H, W, C];
+    const flat = new Array(H * W * C);
+    let idx = 0;
+    for (let h = 0; h < H; h++) {
+      for (let w = 0; w < W; w++) {
+        for (let c = 0; c < C; c++) {
+          flat[idx++] = input[h][w][c];
+        }
+      }
+    }
+    return flat;
+  }
+  // ── Backward pass ─────────────────────────────────────────────────────────
+  // Reshapes a flat gradient vector back into [H][W][C] using the saved shape.
+  backward(dOutput) {
+    if (!this.inputShape) {
+      throw new Error("Flatten.backward: call forward() first");
+    }
+    const [H, W, C] = this.inputShape;
+    if (dOutput.length !== H * W * C) {
+      throw new Error(
+        `Flatten.backward: expected gradient of length ${H * W * C}, got ${dOutput.length}`
+      );
+    }
+    const dInput = Array.from(
+      { length: H },
+      () => Array.from({ length: W }, () => new Array(C).fill(0))
+    );
+    let idx = 0;
+    for (let h = 0; h < H; h++) {
+      for (let w = 0; w < W; w++) {
+        for (let c = 0; c < C; c++) {
+          dInput[h][w][c] = dOutput[idx++];
+        }
+      }
+    }
+    return dInput;
+  }
+};
+
+// src/RNN.ts
+function tanh3(x) {
+  const e = Math.exp(2 * x);
+  return (e - 1) / (e + 1);
+}
+var RNN = class {
+  constructor(inputSize, hiddenSize, outputSize, optimizerFactory = () => new SGD()) {
+    // Trajectory stored during forward for BPTT
+    this._traj = [];
+    this._outputs = [];
+    if (inputSize <= 0 || hiddenSize <= 0 || outputSize <= 0) {
+      throw new Error("RNN: all sizes must be positive");
+    }
+    this.inputSize = inputSize;
+    this.hiddenSize = hiddenSize;
+    this.outputSize = outputSize;
+    const limXH = Math.sqrt(2 / inputSize);
+    const limHH = Math.sqrt(2 / hiddenSize);
+    const limHY = Math.sqrt(2 / hiddenSize);
+    this.Wxh = Array.from(
+      { length: hiddenSize },
+      () => Array.from({ length: inputSize }, () => (Math.random() * 2 - 1) * limXH)
+    );
+    this.Whh = Array.from(
+      { length: hiddenSize },
+      () => Array.from({ length: hiddenSize }, () => (Math.random() * 2 - 1) * limHH)
+    );
+    this.Why = Array.from(
+      { length: outputSize },
+      () => Array.from({ length: hiddenSize }, () => (Math.random() * 2 - 1) * limHY)
+    );
+    this.bh = new Array(hiddenSize).fill(0);
+    this.by = new Array(outputSize).fill(0);
+    this._h = new Array(hiddenSize).fill(0);
+    this._opts = {
+      Wxh: Array.from(
+        { length: hiddenSize },
+        () => Array.from({ length: inputSize }, () => optimizerFactory())
+      ),
+      Whh: Array.from(
+        { length: hiddenSize },
+        () => Array.from({ length: hiddenSize }, () => optimizerFactory())
+      ),
+      Why: Array.from(
+        { length: outputSize },
+        () => Array.from({ length: hiddenSize }, () => optimizerFactory())
+      ),
+      bh: Array.from({ length: hiddenSize }, () => optimizerFactory()),
+      by: Array.from({ length: outputSize }, () => optimizerFactory())
+    };
+  }
+  // ── Reset hidden state ────────────────────────────────────────────────────
+  // Call at the start of each new sequence / episode.
+  reset() {
+    this._h = new Array(this.hiddenSize).fill(0);
+    this._traj = [];
+    this._outputs = [];
+  }
+  // ── Forward pass ──────────────────────────────────────────────────────────
+  // sequence: number[][] of shape [T][inputSize]
+  // Returns outputs and hidden states for all timesteps.
+  forward(sequence) {
+    this._traj = [];
+    this._outputs = [];
+    const outputs = [];
+    const hiddens = [];
+    let hPrev = [...this._h];
+    for (const x of sequence) {
+      const hRaw = this.bh.map(
+        (b, i) => b + this.Wxh[i].reduce((s, w, j) => s + w * x[j], 0) + this.Whh[i].reduce((s, w, j) => s + w * hPrev[j], 0)
+      );
+      const h = hRaw.map(tanh3);
+      const o = this.by.map(
+        (b, i) => b + this.Why[i].reduce((s, w, j) => s + w * h[j], 0)
+      );
+      this._traj.push({ x: [...x], h: [...h], hRaw: [...hRaw], hPrev: [...hPrev] });
+      this._outputs.push(o);
+      outputs.push(o);
+      hiddens.push(h);
+      hPrev = h;
+    }
+    this._h = hPrev;
+    return { outputs, hiddens };
+  }
+  // ── BPTT + weight update ──────────────────────────────────────────────────
+  // targets: number[][] of shape [T][outputSize], paired with the last forward call.
+  // Returns the mean squared error loss.
+  backward(sequence, targets, lr) {
+    this.reset();
+    const { outputs } = this.forward(sequence);
+    const T = this._traj.length;
+    if (T === 0) return 0;
+    let loss = 0;
+    const dOutputs = outputs.map((o, t) => {
+      return o.map((v, k) => {
+        const diff = v - targets[t][k];
+        loss += diff * diff;
+        return 2 * diff / this.outputSize;
+      });
+    });
+    loss /= T * this.outputSize;
+    const dWxh = Array.from({ length: this.hiddenSize }, () => new Array(this.inputSize).fill(0));
+    const dWhh = Array.from({ length: this.hiddenSize }, () => new Array(this.hiddenSize).fill(0));
+    const dWhy = Array.from({ length: this.outputSize }, () => new Array(this.hiddenSize).fill(0));
+    const dbh = new Array(this.hiddenSize).fill(0);
+    const dby = new Array(this.outputSize).fill(0);
+    let dhNext = new Array(this.hiddenSize).fill(0);
+    for (let t = T - 1; t >= 0; t--) {
+      const s = this._traj[t];
+      const do_ = dOutputs[t];
+      for (let i = 0; i < this.outputSize; i++) {
+        for (let j = 0; j < this.hiddenSize; j++) {
+          dWhy[i][j] += do_[i] * s.h[j];
+        }
+        dby[i] += do_[i];
+      }
+      const dh = this.hiddenSize > 0 ? Array.from(
+        { length: this.hiddenSize },
+        (_, j) => this.Why.reduce((sum, row, i) => sum + row[j] * do_[i], 0) + dhNext[j]
+      ) : [];
+      const dhRaw = dh.map((d, k) => d * (1 - s.h[k] ** 2));
+      for (let i = 0; i < this.hiddenSize; i++) {
+        for (let j = 0; j < this.inputSize; j++) {
+          dWxh[i][j] += dhRaw[i] * s.x[j];
+        }
+        dbh[i] += dhRaw[i];
+      }
+      for (let i = 0; i < this.hiddenSize; i++) {
+        for (let j = 0; j < this.hiddenSize; j++) {
+          dWhh[i][j] += dhRaw[i] * s.hPrev[j];
+        }
+      }
+      dhNext = Array.from(
+        { length: this.hiddenSize },
+        (_, j) => this.Whh.reduce((sum, row, i) => sum + row[j] * dhRaw[i], 0)
+      );
+    }
+    const scale = lr / T;
+    for (let i = 0; i < this.hiddenSize; i++) {
+      for (let j = 0; j < this.inputSize; j++) {
+        this.Wxh[i][j] = this._opts.Wxh[i][j].step(this.Wxh[i][j], dWxh[i][j], scale);
+      }
+      for (let j = 0; j < this.hiddenSize; j++) {
+        this.Whh[i][j] = this._opts.Whh[i][j].step(this.Whh[i][j], dWhh[i][j], scale);
+      }
+      this.bh[i] = this._opts.bh[i].step(this.bh[i], dbh[i], scale);
+    }
+    for (let i = 0; i < this.outputSize; i++) {
+      for (let j = 0; j < this.hiddenSize; j++) {
+        this.Why[i][j] = this._opts.Why[i][j].step(this.Why[i][j], dWhy[i][j], scale);
+      }
+      this.by[i] = this._opts.by[i].step(this.by[i], dby[i], scale);
+    }
+    this._traj = [];
+    this._outputs = [];
+    return loss;
+  }
+};
+
+// src/Seq2Seq.ts
+var Seq2Seq = class {
+  // [outputSize]
+  constructor(inputSize, hiddenSize, outputSize, options) {
+    if (inputSize <= 0 || hiddenSize <= 0 || outputSize <= 0) {
+      throw new Error("Seq2Seq: all sizes must be positive");
+    }
+    this.inputSize = inputSize;
+    this.hiddenSize = hiddenSize;
+    this.outputSize = outputSize;
+    const factory = options?.optimizerFactory ?? (() => new SGD());
+    this.encoder = new LSTMLayer(inputSize, hiddenSize, factory);
+    this.decoder = new LSTMLayer(outputSize, hiddenSize, factory);
+    const limit = Math.sqrt(2 / hiddenSize);
+    this.W_out = Array.from(
+      { length: outputSize },
+      () => Array.from({ length: hiddenSize }, () => (Math.random() * 2 - 1) * limit)
+    );
+    this.b_out = new Array(outputSize).fill(0);
+    this._wOutOpts = Array.from(
+      { length: outputSize },
+      () => Array.from({ length: hiddenSize }, () => factory())
+    );
+    this._bOutOpts = Array.from({ length: outputSize }, () => factory());
+  }
+  // ── Linear projection ─────────────────────────────────────────────────────
+  _project(h) {
+    return this.b_out.map(
+      (b, i) => b + this.W_out[i].reduce((s, w, j) => s + w * h[j], 0)
+    );
+  }
+  // ── Encode ────────────────────────────────────────────────────────────────
+  // Runs the encoder over inputSequence and returns the final (h, c) pair.
+  // The context vector summarizes the full input sequence.
+  encode(inputSequence) {
+    this.encoder.reset();
+    for (const x of inputSequence) {
+      this.encoder.predict(x);
+    }
+    return {
+      h: [...this.encoder.h],
+      c: [...this.encoder.c]
+    };
+  }
+  // ── Decode ────────────────────────────────────────────────────────────────
+  // Generates `steps` output tokens autoregressively.
+  // The decoder starts from contextVector and uses its own previous output
+  // as input at each step (greedy / free-running decoding).
+  decode(contextVector, steps) {
+    this.decoder.reset();
+    this.decoder.h = [...contextVector.h];
+    this.decoder.c = [...contextVector.c];
+    const results = [];
+    let prevOutput = new Array(this.outputSize).fill(0);
+    for (let t = 0; t < steps; t++) {
+      const hidden = this.decoder.predict(prevOutput);
+      const output = this._project(hidden);
+      results.push(output);
+      prevOutput = output;
+    }
+    return results;
+  }
+  // ── Training step (teacher forcing) ──────────────────────────────────────
+  // inputSeq:  number[][] of shape [T_in][inputSize]
+  // targetSeq: number[][] of shape [T_out][outputSize]
+  // Returns the MSE loss for this step.
+  trainStep(inputSeq, targetSeq, lr) {
+    const T = targetSeq.length;
+    if (T === 0) return 0;
+    this.encoder.reset();
+    for (const x of inputSeq) {
+      this.encoder.predict(x);
+    }
+    const contextH = [...this.encoder.h];
+    const contextC = [...this.encoder.c];
+    this.decoder.reset();
+    this.decoder.h = [...contextH];
+    this.decoder.c = [...contextC];
+    const hiddens = [];
+    const projOuts = [];
+    let prevTeacher = new Array(this.outputSize).fill(0);
+    for (let t = 0; t < T; t++) {
+      const h = this.decoder.predict(prevTeacher);
+      const out = this._project(h);
+      hiddens.push(h);
+      projOuts.push(out);
+      prevTeacher = targetSeq[t];
+    }
+    let loss = 0;
+    const dProjOut = projOuts.map(
+      (o, t) => o.map((v, k) => {
+        const diff = v - targetSeq[t][k];
+        loss += diff * diff;
+        return 2 * diff / this.outputSize;
+      })
+    );
+    loss /= T * this.outputSize;
+    const dhSeq = Array.from(
+      { length: T },
+      () => new Array(this.hiddenSize).fill(0)
+    );
+    const dWout = Array.from(
+      { length: this.outputSize },
+      () => new Array(this.hiddenSize).fill(0)
+    );
+    const dbOut = new Array(this.outputSize).fill(0);
+    for (let t = 0; t < T; t++) {
+      for (let i = 0; i < this.outputSize; i++) {
+        const dv = dProjOut[t][i];
+        dbOut[i] += dv;
+        for (let j = 0; j < this.hiddenSize; j++) {
+          dWout[i][j] += dv * hiddens[t][j];
+          dhSeq[t][j] += dv * this.W_out[i][j];
+        }
+      }
+    }
+    const scale = lr / T;
+    for (let i = 0; i < this.outputSize; i++) {
+      for (let j = 0; j < this.hiddenSize; j++) {
+        this.W_out[i][j] = this._wOutOpts[i][j].step(this.W_out[i][j], dWout[i][j], scale);
+      }
+      this.b_out[i] = this._bOutOpts[i].step(this.b_out[i], dbOut[i], scale);
+    }
+    this.decoder.backprop(dhSeq, lr);
+    const dContext = dhSeq[0];
+    const encoderDhSeq = inputSeq.map(
+      (_, t) => t === inputSeq.length - 1 ? [...dContext] : new Array(this.hiddenSize).fill(0)
+    );
+    this.encoder.backprop(encoderDhSeq, lr);
+    return loss;
+  }
+};
+
+// src/TCN.ts
+var CausalConv1D = class {
+  constructor(inputChannels, outputChannels, kernelSize, dilation, optimizerFactory = () => new SGD()) {
+    // Cache for backward pass
+    this._paddedInput = null;
+    this._inputLen = 0;
+    if (inputChannels <= 0 || outputChannels <= 0 || kernelSize <= 0 || dilation <= 0) {
+      throw new Error("CausalConv1D: all dimensions must be positive");
+    }
+    this.inputChannels = inputChannels;
+    this.outputChannels = outputChannels;
+    this.kernelSize = kernelSize;
+    this.dilation = dilation;
+    const limit = Math.sqrt(2 / (kernelSize * inputChannels));
+    this.kernels = Array.from(
+      { length: outputChannels },
+      () => Array.from(
+        { length: kernelSize },
+        () => Array.from({ length: inputChannels }, () => (Math.random() * 2 - 1) * limit)
+      )
+    );
+    this.biases = new Array(outputChannels).fill(0);
+    this._kOpts = Array.from(
+      { length: outputChannels },
+      () => Array.from(
+        { length: kernelSize },
+        () => Array.from({ length: inputChannels }, () => optimizerFactory())
+      )
+    );
+    this._bOpts = Array.from({ length: outputChannels }, () => optimizerFactory());
+  }
+  // ── Forward pass ──────────────────────────────────────────────────────────
+  // input: [T][inputChannels]
+  // Returns: [T][outputChannels]  (same length — causal padding preserves T)
+  forward(input) {
+    const T = input.length;
+    const pad = (this.kernelSize - 1) * this.dilation;
+    const zeroCh = new Array(this.inputChannels).fill(0);
+    const padded = [
+      ...Array.from({ length: pad }, () => [...zeroCh]),
+      ...input.map((row) => [...row])
+    ];
+    this._paddedInput = padded;
+    this._inputLen = T;
+    const output = Array.from(
+      { length: T },
+      () => new Array(this.outputChannels).fill(0)
+    );
+    for (let t = 0; t < T; t++) {
+      for (let f = 0; f < this.outputChannels; f++) {
+        let sum = this.biases[f];
+        for (let k = 0; k < this.kernelSize; k++) {
+          const srcPos = t + k * this.dilation;
+          for (let c = 0; c < this.inputChannels; c++) {
+            sum += this.kernels[f][k][c] * padded[srcPos][c];
+          }
+        }
+        output[t][f] = sum;
+      }
+    }
+    return output;
+  }
+  // ── Backward pass ─────────────────────────────────────────────────────────
+  // dOutput: [T][outputChannels]
+  // Returns dInput: [T][inputChannels]
+  backward(dOutput, lr) {
+    if (!this._paddedInput) {
+      throw new Error("CausalConv1D.backward: call forward() first");
+    }
+    const T = this._inputLen;
+    const pad = (this.kernelSize - 1) * this.dilation;
+    const padded = this._paddedInput;
+    const dKernels = Array.from(
+      { length: this.outputChannels },
+      () => Array.from(
+        { length: this.kernelSize },
+        () => new Array(this.inputChannels).fill(0)
+      )
+    );
+    const dBiases = new Array(this.outputChannels).fill(0);
+    const dPadded = Array.from(
+      { length: padded.length },
+      () => new Array(this.inputChannels).fill(0)
+    );
+    for (let t = 0; t < T; t++) {
+      for (let f = 0; f < this.outputChannels; f++) {
+        const dv = dOutput[t][f];
+        dBiases[f] += dv;
+        for (let k = 0; k < this.kernelSize; k++) {
+          const srcPos = t + k * this.dilation;
+          for (let c = 0; c < this.inputChannels; c++) {
+            dKernels[f][k][c] += dv * padded[srcPos][c];
+            dPadded[srcPos][c] += dv * this.kernels[f][k][c];
+          }
+        }
+      }
+    }
+    for (let f = 0; f < this.outputChannels; f++) {
+      for (let k = 0; k < this.kernelSize; k++) {
+        for (let c = 0; c < this.inputChannels; c++) {
+          this.kernels[f][k][c] = this._kOpts[f][k][c].step(
+            this.kernels[f][k][c],
+            dKernels[f][k][c],
+            lr
+          );
+        }
+      }
+      this.biases[f] = this._bOpts[f].step(this.biases[f], dBiases[f], lr);
+    }
+    return dPadded.slice(pad);
+  }
+};
+var TCN = class {
+  // linear projection outputs
+  constructor(inputChannels, channels, kernelSize, levels, outputSize, optimizerFactory = () => new SGD()) {
+    // Cache for backward pass
+    this._layerInputs = [];
+    // inputs to each conv layer
+    this._layerOutputs = [];
+    // outputs from each conv layer (pre-relu)
+    this._lastHidden = [];
+    // post-relu output of last conv layer
+    this._finalOutputs = [];
+    if (levels <= 0) throw new Error("TCN: levels must be positive");
+    if (outputSize <= 0) throw new Error("TCN: outputSize must be positive");
+    this.inputChannels = inputChannels;
+    this.channels = channels;
+    this.kernelSize = kernelSize;
+    this.levels = levels;
+    this.outputSize = outputSize;
+    this.layers = [];
+    for (let l = 0; l < levels; l++) {
+      const dilation = Math.pow(2, l);
+      const inCh = l === 0 ? inputChannels : channels;
+      this.layers.push(new CausalConv1D(inCh, channels, kernelSize, dilation, optimizerFactory));
+    }
+    const outLimit = Math.sqrt(2 / channels);
+    this._outputW = Array.from(
+      { length: outputSize },
+      () => Array.from({ length: channels }, () => (Math.random() * 2 - 1) * outLimit)
+    );
+    this._outputB = new Array(outputSize).fill(0);
+    this._outOpts = Array.from(
+      { length: outputSize },
+      () => Array.from({ length: channels }, () => optimizerFactory())
+    );
+    this._bOutOpts = Array.from({ length: outputSize }, () => optimizerFactory());
+  }
+  // ── Receptive field (informational) ──────────────────────────────────────
+  // RF = (kernelSize - 1) · (2^levels - 1) + 1
+  get receptiveField() {
+    return (this.kernelSize - 1) * (Math.pow(2, this.levels) - 1) + 1;
+  }
+  // ── Forward pass ──────────────────────────────────────────────────────────
+  // sequence: [T][inputChannels]
+  // Returns:  [T][outputSize]
+  forward(sequence) {
+    this._layerInputs = [];
+    this._layerOutputs = [];
+    let current = sequence;
+    for (let l = 0; l < this.levels; l++) {
+      this._layerInputs.push(current.map((row) => [...row]));
+      const convOut = this.layers[l].forward(current);
+      this._layerOutputs.push(convOut);
+      const afterRelu = convOut.map((row) => row.map((v) => relu.fn(v)));
+      if (current[0].length === afterRelu[0].length) {
+        current = afterRelu.map((row, t) => row.map((v, c) => v + current[t][c]));
+      } else {
+        current = afterRelu;
+      }
+    }
+    this._lastHidden = current;
+    const T = current.length;
+    this._finalOutputs = Array.from(
+      { length: T },
+      (_, t) => this._outputB.map(
+        (b, i) => b + this._outputW[i].reduce((s, w, j) => s + w * current[t][j], 0)
+      )
+    );
+    return this._finalOutputs.map((row) => [...row]);
+  }
+  // ── Train one step ────────────────────────────────────────────────────────
+  // sequence: [T][inputChannels]
+  // targets:  [T][outputSize]
+  // Returns MSE loss.
+  train(sequence, targets, lr) {
+    const outputs = this.forward(sequence);
+    const T = outputs.length;
+    let loss = 0;
+    const dOut = outputs.map(
+      (o, t) => o.map((v, k) => {
+        const diff = v - targets[t][k];
+        loss += diff * diff;
+        return 2 * diff / this.outputSize;
+      })
+    );
+    loss /= T * this.outputSize;
+    const dWout = Array.from({ length: this.outputSize }, () => new Array(this.channels).fill(0));
+    const dBout = new Array(this.outputSize).fill(0);
+    const dHidden = Array.from({ length: T }, () => new Array(this.channels).fill(0));
+    for (let t = 0; t < T; t++) {
+      for (let i = 0; i < this.outputSize; i++) {
+        const dv = dOut[t][i];
+        dBout[i] += dv;
+        for (let j = 0; j < this.channels; j++) {
+          dWout[i][j] += dv * this._lastHidden[t][j];
+          dHidden[t][j] += dv * this._outputW[i][j];
+        }
+      }
+    }
+    const scale = lr / T;
+    for (let i = 0; i < this.outputSize; i++) {
+      for (let j = 0; j < this.channels; j++) {
+        this._outputW[i][j] = this._outOpts[i][j].step(this._outputW[i][j], dWout[i][j], scale);
+      }
+      this._outputB[i] = this._bOutOpts[i].step(this._outputB[i], dBout[i], scale);
+    }
+    let dCurrent = dHidden;
+    for (let l = this.levels - 1; l >= 0; l--) {
+      const convOut = this._layerOutputs[l];
+      const layerIn = this._layerInputs[l];
+      const dConvOut = dCurrent.map(
+        (row, t) => row.map((d, c) => d * (convOut[t][c] > 0 ? 1 : 0))
+      );
+      let dPrevLayer = this.layers[l].backward(dConvOut, lr);
+      if (layerIn[0].length === dCurrent[0].length) {
+        dPrevLayer = dPrevLayer.map(
+          (row, t) => row.map((d, c) => d + dCurrent[t][c])
+        );
+      }
+      dCurrent = dPrevLayer;
+    }
+    return loss;
+  }
+};
+
+// src/Word2Vec.ts
+var Word2Vec = class {
+  constructor(embeddingDim = 50, options = {}) {
+    this._trained = false;
+    this.embeddingDim = embeddingDim;
+    this._windowSize = options.windowSize ?? 2;
+    this._model = options.model ?? "skipgram";
+    this._minCount = options.minCount ?? 1;
+    this.embeddings = [];
+    this._W2 = [];
+    this.vocab = /* @__PURE__ */ new Map();
+    this._indexToWord = [];
+    this.vocabSize = 0;
+  }
+  // ── buildVocab ─────────────────────────────────────────────────────────────
+  // Scans the corpus, counts word frequencies, discards rare words (< minCount),
+  // and assigns each remaining word a unique integer index.
+  buildVocab(sentences) {
+    const freq = /* @__PURE__ */ new Map();
+    for (const sentence of sentences) {
+      for (const word of sentence) {
+        freq.set(word, (freq.get(word) ?? 0) + 1);
+      }
+    }
+    this.vocab = /* @__PURE__ */ new Map();
+    this._indexToWord = [];
+    for (const [word, count] of freq) {
+      if (count >= this._minCount) {
+        const idx = this._indexToWord.length;
+        this.vocab.set(word, idx);
+        this._indexToWord.push(word);
+      }
+    }
+    this.vocabSize = this._indexToWord.length;
+    if (this.vocabSize === 0) {
+      throw new Error("Word2Vec.buildVocab: vocabulary is empty after applying minCount filter");
+    }
+    const scale1 = Math.sqrt(1 / this.embeddingDim);
+    const scale2 = Math.sqrt(1 / this.vocabSize);
+    this.embeddings = Array.from(
+      { length: this.vocabSize },
+      () => Array.from({ length: this.embeddingDim }, () => (Math.random() * 2 - 1) * scale1)
+    );
+    this._W2 = Array.from(
+      { length: this.embeddingDim },
+      () => Array.from({ length: this.vocabSize }, () => (Math.random() * 2 - 1) * scale2)
+    );
+    this._trained = false;
+  }
+  // ── tokenize ───────────────────────────────────────────────────────────────
+  // Simple tokenizer: lowercase, strip punctuation, split on whitespace.
+  // Returns an array of tokens suitable for buildVocab / train.
+  static tokenize(text) {
+    return text.toLowerCase().replace(/[^a-z0-9\s'-]/g, " ").split(/\s+/).filter((t) => t.length > 0);
+  }
+  // ── train ──────────────────────────────────────────────────────────────────
+  // Runs SGD over all (center, context) pairs in the corpus for `epochs` passes.
+  // Returns the average cross-entropy loss per epoch.
+  //
+  // Note: uses full-vocabulary softmax (not negative sampling) for educational
+  // clarity. This is O(vocabSize) per step — for large vocabularies you would
+  // normally switch to negative sampling or hierarchical softmax.
+  train(sentences, lr = 0.025, epochs = 5) {
+    if (this.vocabSize === 0) this.buildVocab(sentences);
+    const lossHistory = [];
+    for (let epoch = 0; epoch < epochs; epoch++) {
+      let totalLoss = 0;
+      let nPairs = 0;
+      for (const sentence of sentences) {
+        const indices = sentence.map((w) => this.vocab.get(w)).filter((idx) => idx !== void 0);
+        for (let t = 0; t < indices.length; t++) {
+          const centerIdx = indices[t];
+          const contextIndices = [];
+          for (let offset = -this._windowSize; offset <= this._windowSize; offset++) {
+            if (offset === 0) continue;
+            const pos = t + offset;
+            if (pos >= 0 && pos < indices.length) {
+              contextIndices.push(indices[pos]);
+            }
+          }
+          if (contextIndices.length === 0) continue;
+          if (this._model === "skipgram") {
+            for (const contextIdx of contextIndices) {
+              totalLoss += this._skipgramStep(centerIdx, contextIdx, lr);
+              nPairs++;
+            }
+          } else {
+            totalLoss += this._cbowStep(centerIdx, contextIndices, lr);
+            nPairs++;
+          }
+        }
+      }
+      lossHistory.push(nPairs > 0 ? totalLoss / nPairs : 0);
+    }
+    this._trained = true;
+    return lossHistory;
+  }
+  // ── getEmbedding ───────────────────────────────────────────────────────────
+  // Returns the learned embedding vector for a word. Throws if unknown.
+  getEmbedding(word) {
+    const idx = this.vocab.get(word);
+    if (idx === void 0) throw new Error(`Word2Vec: unknown word "${word}"`);
+    return this.embeddings[idx];
+  }
+  // ── similarity ─────────────────────────────────────────────────────────────
+  // Cosine similarity between two words.
+  //   cos(v1, v2) = (v1 · v2) / (‖v1‖ · ‖v2‖)
+  // Returns a value in [-1, 1]. Higher → more similar context usage.
+  similarity(word1, word2) {
+    const v1 = this.getEmbedding(word1);
+    const v2 = this.getEmbedding(word2);
+    return this._cosine(v1, v2);
+  }
+  // ── mostSimilar ────────────────────────────────────────────────────────────
+  // Returns the topK words (excluding `word` itself) sorted by cosine similarity.
+  mostSimilar(word, topK = 10) {
+    const v = this.getEmbedding(word);
+    return this._nearestByVector(v, topK, /* @__PURE__ */ new Set([word]));
+  }
+  // ── analogy ───────────────────────────────────────────────────────────────
+  // Vector arithmetic analogy: positive1 - negative + positive2 ≈ result
+  //
+  //   getAnalogy('king', 'man', 'woman') finds the word closest to
+  //   vec('king') - vec('man') + vec('woman') ≈ vec('queen')
+  //
+  // The result is excluded from the input words so they don't pollute the top-K.
+  analogy(positive1, negative, positive2, topK = 5) {
+    const vPos1 = this.getEmbedding(positive1);
+    const vNeg = this.getEmbedding(negative);
+    const vPos2 = this.getEmbedding(positive2);
+    const target = vPos1.map((v, i) => v - vNeg[i] + vPos2[i]);
+    const exclude = /* @__PURE__ */ new Set([positive1, negative, positive2]);
+    return this._nearestByVector(target, topK, exclude);
+  }
+  // ── Private: skip-gram step ───────────────────────────────────────────────
+  // Forward + backward for one (center, target) pair.
+  // Returns the cross-entropy loss for this pair.
+  _skipgramStep(centerIdx, targetIdx, lr) {
+    const h = this.embeddings[centerIdx];
+    const scores = this._hiddenToScores(h);
+    const probs = _softmax(scores);
+    const loss = -Math.log(probs[targetIdx] + 1e-12);
+    const err = probs.map((p, j) => j === targetIdx ? p - 1 : p);
+    const dh = new Array(this.embeddingDim).fill(0);
+    for (let d = 0; d < this.embeddingDim; d++) {
+      for (let j = 0; j < this.vocabSize; j++) {
+        this._W2[d][j] -= lr * h[d] * err[j];
+        dh[d] += this._W2[d][j] * err[j];
+      }
+    }
+    for (let d = 0; d < this.embeddingDim; d++) {
+      this.embeddings[centerIdx][d] -= lr * dh[d];
+    }
+    return loss;
+  }
+  // ── Private: CBOW step ────────────────────────────────────────────────────
+  // Forward + backward for one (contextIndices → centerIdx) pair.
+  // h is the mean of all context embeddings. The gradient is distributed
+  // equally back to each context word's embedding row.
+  _cbowStep(centerIdx, contextIndices, lr) {
+    const k = contextIndices.length;
+    const h = new Array(this.embeddingDim).fill(0);
+    for (const ci of contextIndices) {
+      for (let d = 0; d < this.embeddingDim; d++) {
+        h[d] += this.embeddings[ci][d];
+      }
+    }
+    for (let d = 0; d < this.embeddingDim; d++) h[d] /= k;
+    const scores = this._hiddenToScores(h);
+    const probs = _softmax(scores);
+    const loss = -Math.log(probs[centerIdx] + 1e-12);
+    const err = probs.map((p, j) => j === centerIdx ? p - 1 : p);
+    const dh = new Array(this.embeddingDim).fill(0);
+    for (let d = 0; d < this.embeddingDim; d++) {
+      for (let j = 0; j < this.vocabSize; j++) {
+        this._W2[d][j] -= lr * h[d] * err[j];
+        dh[d] += this._W2[d][j] * err[j];
+      }
+    }
+    for (const ci of contextIndices) {
+      for (let d = 0; d < this.embeddingDim; d++) {
+        this.embeddings[ci][d] -= lr * dh[d] / k;
+      }
+    }
+    return loss;
+  }
+  // Computes scores = h · W2  →  [vocabSize]
+  _hiddenToScores(h) {
+    const scores = new Array(this.vocabSize).fill(0);
+    for (let d = 0; d < this.embeddingDim; d++) {
+      for (let j = 0; j < this.vocabSize; j++) {
+        scores[j] += h[d] * this._W2[d][j];
+      }
+    }
+    return scores;
+  }
+  // Returns topK words (from all embeddings) sorted by cosine similarity to v,
+  // skipping any word in the exclude set.
+  _nearestByVector(v, topK, exclude) {
+    const results = [];
+    for (let i = 0; i < this.vocabSize; i++) {
+      const w = this._indexToWord[i];
+      if (exclude.has(w)) continue;
+      results.push({ word: w, score: this._cosine(v, this.embeddings[i]) });
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, topK);
+  }
+  // Cosine similarity: (v1 · v2) / (‖v1‖ · ‖v2‖)
+  _cosine(v1, v2) {
+    let dot = 0, n1 = 0, n2 = 0;
+    for (let i = 0; i < v1.length; i++) {
+      dot += v1[i] * v2[i];
+      n1 += v1[i] * v1[i];
+      n2 += v2[i] * v2[i];
+    }
+    const denom = Math.sqrt(n1) * Math.sqrt(n2);
+    return denom < 1e-12 ? 0 : dot / denom;
+  }
+};
+function _softmax(scores) {
+  const max = Math.max(...scores);
+  const exps = scores.map((s) => Math.exp(s - max));
+  const sum = exps.reduce((a, b) => a + b, 0);
+  return exps.map((e) => e / sum);
+}
+
+// src/TSNE.ts
+var TSNE = class {
+  constructor(options = {}) {
+    // KL divergence tracked during the last fit() call.
+    this._klDivergence = 0;
+    // P matrix stored for kl() reporting.
+    this._P = [];
+    this._nComponents = options.nComponents ?? 2;
+    this._perplexity = options.perplexity ?? 30;
+    this._lr = options.lr ?? 200;
+    this._nIter = options.nIter ?? 1e3;
+    this._seed = options.seed;
+    this.embedding = [];
+  }
+  // ── fit ────────────────────────────────────────────────────────────────────
+  // Runs the full t-SNE algorithm on X (shape [n][d]).
+  // Stores the result in this.embedding ([n][nComponents]).
+  fit(X) {
+    const n = X.length;
+    if (n < 2) throw new Error("TSNE.fit: need at least 2 data points");
+    if (this._perplexity >= n) {
+      throw new Error(
+        `TSNE.fit: perplexity (${this._perplexity}) must be less than n (${n})`
+      );
+    }
+    const rng = this._seed !== void 0 ? _mulberry32(this._seed) : Math.random;
+    const distSq = _pairwiseDistSq(X, n);
+    const Pcond = this._computePcond(distSq, n);
+    const P = _symmetrize(Pcond, n);
+    this._P = P;
+    let Y = Array.from({ length: n }, () => {
+      return Array.from({ length: this._nComponents }, () => {
+        const u1 = Math.max(rng(), 1e-12);
+        const u2 = rng();
+        const z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+        return z * 0.01;
+      });
+    });
+    let Yprev = Y.map((row) => [...row]);
+    const EXAGGERATION_ITERS = 50;
+    const EXAGGERATION_FACTOR = 4;
+    const MOMENTUM_SWITCH = 20;
+    for (let iter = 0; iter < this._nIter; iter++) {
+      const momentum = iter < MOMENTUM_SWITCH ? 0.5 : 0.8;
+      const pScale = iter < EXAGGERATION_ITERS ? EXAGGERATION_FACTOR : 1;
+      const { Q, invDist } = _computeQ(Y, n, this._nComponents);
+      const grad = Array.from(
+        { length: n },
+        () => new Array(this._nComponents).fill(0)
+      );
+      for (let i = 0; i < n; i++) {
+        for (let j = 0; j < n; j++) {
+          if (i === j) continue;
+          const pq = pScale * P[i][j] - Q[i][j];
+          const c = 4 * pq * invDist[i][j];
+          for (let d = 0; d < this._nComponents; d++) {
+            grad[i][d] += c * (Y[i][d] - Y[j][d]);
+          }
+        }
+      }
+      const Ynext = Array.from(
+        { length: n },
+        (_, i) => Array.from(
+          { length: this._nComponents },
+          (_2, d) => Y[i][d] - this._lr * grad[i][d] + momentum * (Y[i][d] - Yprev[i][d])
+        )
+      );
+      Yprev = Y;
+      Y = Ynext;
+    }
+    this.embedding = Y;
+    const { Q: Qfinal } = _computeQ(Y, n, this._nComponents);
+    let kl = 0;
+    for (let i = 0; i < n; i++) {
+      for (let j = 0; j < n; j++) {
+        if (i === j) continue;
+        const p = P[i][j];
+        if (p > 1e-12) {
+          kl += p * Math.log(p / (Qfinal[i][j] + 1e-12));
+        }
+      }
+    }
+    this._klDivergence = kl;
+  }
+  // ── fitTransform ───────────────────────────────────────────────────────────
+  // Convenience: fit() then return this.embedding.
+  fitTransform(X) {
+    this.fit(X);
+    return this.embedding;
+  }
+  // ── kl ─────────────────────────────────────────────────────────────────────
+  // Returns the KL divergence KL(P ‖ Q) from the last fit() call.
+  // Lower is better. Useful for comparing perplexity settings or iteration counts.
+  kl() {
+    return this._klDivergence;
+  }
+  // ── Private: binary search for σi ─────────────────────────────────────────
+  // For each point i, find σi such that the Shannon entropy of P(·|i) equals
+  // log₂(perplexity). We use binary search on σ².
+  _computePcond(distSq, n) {
+    const targetEntropy = Math.log2(this._perplexity);
+    const Pcond = Array.from({ length: n }, () => new Array(n).fill(0));
+    for (let i = 0; i < n; i++) {
+      let sigmaLo = 0;
+      let sigmaHi = 1e10;
+      let sigma2 = 1;
+      for (let attempt = 0; attempt < 50; attempt++) {
+        const dists = distSq[i];
+        let sumExp = 0;
+        const exps = new Array(n).fill(0);
+        for (let j = 0; j < n; j++) {
+          if (j === i) continue;
+          const e = Math.exp(-dists[j] / (2 * sigma2));
+          exps[j] = e;
+          sumExp += e;
+        }
+        if (sumExp < 1e-12) break;
+        let H = 0;
+        for (let j = 0; j < n; j++) {
+          if (j === i) continue;
+          const p = exps[j] / sumExp;
+          Pcond[i][j] = p;
+          if (p > 1e-12) H -= p * Math.log2(p);
+        }
+        const delta = H - targetEntropy;
+        if (Math.abs(delta) < 1e-5) break;
+        if (delta > 0) {
+          sigmaHi = sigma2;
+          sigma2 = (sigmaLo + sigma2) / 2;
+        } else {
+          sigmaLo = sigma2;
+          sigma2 = sigmaHi < 1e9 ? (sigma2 + sigmaHi) / 2 : sigma2 * 2;
+        }
+      }
+    }
+    return Pcond;
+  }
+};
+function _pairwiseDistSq(X, n) {
+  const D = Array.from({ length: n }, () => new Array(n).fill(0));
+  for (let i = 0; i < n; i++) {
+    for (let j = i + 1; j < n; j++) {
+      let d = 0;
+      for (let k = 0; k < X[i].length; k++) {
+        const diff = X[i][k] - X[j][k];
+        d += diff * diff;
+      }
+      D[i][j] = d;
+      D[j][i] = d;
+    }
+  }
+  return D;
+}
+function _symmetrize(Pcond, n) {
+  const P = Array.from({ length: n }, () => new Array(n).fill(0));
+  for (let i = 0; i < n; i++) {
+    for (let j = 0; j < n; j++) {
+      P[i][j] = (Pcond[i][j] + Pcond[j][i]) / (2 * n);
+    }
+  }
+  return P;
+}
+function _computeQ(Y, n, nComponents) {
+  const num = Array.from({ length: n }, () => new Array(n).fill(0));
+  let Z = 0;
+  for (let i = 0; i < n; i++) {
+    for (let j = i + 1; j < n; j++) {
+      let d2 = 0;
+      for (let d = 0; d < nComponents; d++) {
+        const diff = Y[i][d] - Y[j][d];
+        d2 += diff * diff;
+      }
+      const inv = 1 / (1 + d2);
+      num[i][j] = inv;
+      num[j][i] = inv;
+      Z += 2 * inv;
+    }
+  }
+  if (Z < 1e-12) Z = 1e-12;
+  const Q = Array.from(
+    { length: n },
+    (_, i) => num[i].map((v) => v / Z)
+  );
+  return { Q, invDist: num };
+}
+function _mulberry32(seed) {
+  let s = seed >>> 0;
+  return function() {
+    s = s + 1831565813 >>> 0;
+    let z = s;
+    z = Math.imul(z ^ z >>> 15, z | 1);
+    z ^= z + Math.imul(z ^ z >>> 7, z | 61);
+    z = (z ^ z >>> 14) >>> 0;
+    return z / 4294967296;
+  };
+}
+
+// src/PositionalEncoding.ts
+var PositionalEncoding = class _PositionalEncoding {
+  // Compute the full PE vector for one token at position `pos`.
+  // Returns an array of length `dModel`.
+  //
+  // Each pair of dimensions (2i, 2i+1) shares the same frequency 1/10000^(2i/dModel)
+  // but is 90° out of phase (sin vs cos), which ensures no two positions produce
+  // the identical vector.
+  static encode(pos, dModel) {
+    const pe = new Array(dModel);
+    for (let i = 0; i < Math.floor(dModel / 2); i++) {
+      const freq = Math.pow(1e4, 2 * i / dModel);
+      pe[2 * i] = Math.sin(pos / freq);
+      pe[2 * i + 1] = Math.cos(pos / freq);
+    }
+    if (dModel % 2 !== 0) {
+      const i = Math.floor(dModel / 2);
+      const freq = Math.pow(1e4, 2 * i / dModel);
+      pe[dModel - 1] = Math.sin(pos / freq);
+    }
+    return pe;
+  }
+  // Build the full positional encoding matrix for a sequence of `seqLen` tokens.
+  // Returns shape [seqLen][dModel].
+  //
+  // In practice this matrix is computed once and cached — it doesn't change
+  // across examples, batches, or epochs.
+  static encodeSequence(seqLen, dModel) {
+    return Array.from(
+      { length: seqLen },
+      (_, pos) => _PositionalEncoding.encode(pos, dModel)
+    );
+  }
+  // Add positional encoding to an existing embedding matrix (in-place on a copy).
+  //
+  // `embeddings` shape: [seqLen][dModel].
+  // `seqLen` is optional; defaults to embeddings.length.
+  //
+  // The sum e = token_embedding + PE is what actually enters the first
+  // Transformer layer. Summing (rather than concatenating) keeps the model
+  // dimension fixed and lets the network distribute its capacity freely —
+  // it can choose how much of each dimension to allocate to content vs. position.
+  static apply(embeddings, seqLen) {
+    const len = seqLen ?? embeddings.length;
+    const dModel = embeddings[0].length;
+    const pe = _PositionalEncoding.encodeSequence(len, dModel);
+    return embeddings.map(
+      (emb, pos) => emb.map((val, d) => val + pe[pos][d])
+    );
+  }
+};
+var LearnedPositionalEncoding = class {
+  constructor(maxSeqLen, dModel) {
+    this.maxSeqLen = maxSeqLen;
+    this.dModel = dModel;
+    const limit = Math.sqrt(1 / dModel);
+    this.weights = Array.from(
+      { length: maxSeqLen },
+      () => Array.from({ length: dModel }, () => (Math.random() * 2 - 1) * limit)
+    );
+  }
+  // Return the learned encoding for one position.
+  // Returns a copy so callers cannot accidentally mutate the weight table.
+  getEncoding(pos) {
+    if (pos >= this.maxSeqLen) {
+      throw new Error(
+        `Position ${pos} exceeds maxSeqLen=${this.maxSeqLen}. Learned encodings cannot generalize beyond their training length.`
+      );
+    }
+    return [...this.weights[pos]];
+  }
+  // Add learned positional encodings to `embeddings` (returns a new matrix).
+  // Shape: [seqLen][dModel] → [seqLen][dModel].
+  apply(embeddings, seqLen) {
+    const len = seqLen ?? embeddings.length;
+    if (len > this.maxSeqLen) {
+      throw new Error(
+        `Sequence length ${len} exceeds maxSeqLen=${this.maxSeqLen}.`
+      );
+    }
+    return embeddings.map(
+      (emb, pos) => emb.map((val, d) => val + this.weights[pos][d])
+    );
+  }
+  // Apply gradient update to position encoding weights.
+  //
+  // `dWeights` has the same shape as `weights`: [maxSeqLen][dModel].
+  // Each entry is dL/dW_pos[pos][d] — the loss gradient w.r.t. that weight.
+  //
+  // Simple SGD is used here (matching EmbeddingMatrix in MatMul.ts):
+  // position embeddings are updated every step for all positions in the batch,
+  // so the sparse-update problem of token embeddings doesn't apply.
+  update(dWeights, lr) {
+    for (let pos = 0; pos < this.maxSeqLen; pos++) {
+      for (let d = 0; d < this.dModel; d++) {
+        this.weights[pos][d] += lr * dWeights[pos][d];
+      }
+    }
+  }
+};
+
+// src/ContrastiveLearning.ts
+var Augmenter = class _Augmenter {
+  // Add zero-mean Gaussian noise with standard deviation `sigma`.
+  //
+  // Uses the Box-Muller transform to produce normally distributed noise from
+  // two uniform random variables:
+  //   z = √(-2·ln(u₁)) · cos(2π·u₂)   where u₁, u₂ ~ Uniform(0, 1)
+  //
+  // This keeps us dependency-free while yielding proper Gaussian samples.
+  static addNoise(x, sigma = 0.05) {
+    return x.map((v) => {
+      const u1 = Math.max(1e-10, Math.random());
+      const u2 = Math.random();
+      const z = Math.sqrt(-2 * Math.log(u1)) * Math.cos(2 * Math.PI * u2);
+      return v + sigma * z;
+    });
+  }
+  // Randomly zero out features with probability `rate`.
+  //
+  // Analogous to masking in BERT or random crops in vision contrastive learning.
+  // The encoder must learn representations that are robust to missing features —
+  // it cannot simply memorize individual dimensions.
+  static dropoutFeatures(x, rate = 0.1) {
+    return x.map((v) => Math.random() < rate ? 0 : v);
+  }
+  // Apply both noise and feature dropout in sequence.
+  //
+  // Combining augmentations is standard in SimCLR — stronger augmentations
+  // force the encoder to learn more robust, abstract representations.
+  static augment(x, noiseStd = 0.05, dropRate = 0.1) {
+    return _Augmenter.dropoutFeatures(_Augmenter.addNoise(x, noiseStd), dropRate);
+  }
+  // Generate a positive pair: [original, augmented_copy].
+  //
+  // These two views are used as the (i, j) positive pair in NT-Xent.
+  // Everything else in the batch acts as a negative.
+  static makePair(x) {
+    return [x, _Augmenter.augment(x)];
+  }
+};
+var ContrastiveLearning = class _ContrastiveLearning {
+  // encoderHidden: hidden layer sizes for the encoder (not counting input/output).
+  //   e.g. inputSize=64, encoderHidden=[256, 128] → NetworkN([64, 256, 128])
+  //   The encoder output dimension is encoderHidden[last].
+  //
+  // projectionDim: dimension of the projection head output (the z space).
+  //   e.g. 64. Typically smaller than the encoder's output.
+  //
+  // The encoder uses ReLU activations throughout — empirically stronger than
+  // sigmoid for representation learning because it doesn't saturate.
+  constructor(inputSize, encoderHidden, projectionDim, options = {}) {
+    if (encoderHidden.length === 0) {
+      throw new Error("encoderHidden must have at least one element.");
+    }
+    this.temperature = options.temperature ?? 0.5;
+    const encoderStructure = [inputSize, ...encoderHidden];
+    const encoderActivations = encoderHidden.map(() => relu);
+    this.encoder = new NetworkN(encoderStructure, {
+      activations: encoderActivations,
+      ...options.encoderOptions
+    });
+    const encoderOut = encoderHidden[encoderHidden.length - 1];
+    const projHidden = Math.max(projectionDim, Math.floor(encoderOut / 2));
+    this.projectionHead = new NetworkN(
+      [encoderOut, projHidden, projectionDim],
+      { activations: [relu, relu] }
+    );
+  }
+  // ── Inference (downstream tasks use this, not project()) ─────────────────
+  //
+  // Returns h — the encoder representation before the projection head.
+  // This is the vector to use for classification, clustering, retrieval, etc.
+  //
+  // The projection head is only active during training.
+  encode(x) {
+    return this.encoder.predict(x);
+  }
+  // ── Training path: encode then project ───────────────────────────────────
+  //
+  // Returns z — the projected representation used to compute NT-Xent.
+  // Do NOT use this for downstream tasks (see encode() above).
+  project(x) {
+    const h = this.encoder.predict(x);
+    return this.projectionHead.predict(h);
+  }
+  // ── Cosine similarity ─────────────────────────────────────────────────────
+  //
+  // sim(u, v) = uᵀv / (||u|| · ||v||)
+  //
+  // Range: [-1, 1]. We use cosine rather than Euclidean distance because it is
+  // scale-invariant — only the direction of the projection matters, not its
+  // magnitude. This prevents the trivial solution of making ||z|| → ∞.
+  static cosineSimilarity(a, b) {
+    let dot = 0, normA = 0, normB = 0;
+    for (let d = 0; d < a.length; d++) {
+      dot += a[d] * b[d];
+      normA += a[d] * a[d];
+      normB += b[d] * b[d];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    return denom < 1e-10 ? 0 : dot / denom;
+  }
+  // ── NT-Xent loss (no weight update) ──────────────────────────────────────
+  //
+  // Forward-only pass. Used for validation / monitoring during training.
+  computeLoss(pairs) {
+    const { projections, N } = this._forwardProjections(pairs);
+    return this._ntXentLoss(projections, N);
+  }
+  // ── Training step ─────────────────────────────────────────────────────────
+  //
+  // Given a batch of positive pairs, compute NT-Xent loss and update weights
+  // via finite-difference gradient approximation.
+  //
+  // Full analytical backprop through NT-Xent is complex to implement from
+  // scratch without an autograd engine. Finite differences are slower but
+  // correct and keep the implementation readable for educational purposes.
+  // For production use, couple this with the Tape (autograd) module.
+  //
+  // Step-by-step:
+  //   1. Forward all 2N inputs through encoder + projection head → { z_i }.
+  //   2. Build the 2N×2N cosine similarity matrix (scaled by 1/τ).
+  //   3. For each anchor i, identify its positive pair and all 2N-2 negatives.
+  //   4. Apply softmax over the row; loss = -log(softmax at positive index).
+  //   5. Average over all 2N anchors.
+  //   6. Approximate ∂L/∂w per weight with finite differences and apply update.
+  //
+  // Returns: NT-Xent loss before the weight update.
+  trainStep(pairs, lr) {
+    const loss = this.computeLoss(pairs);
+    const eps = 1e-4;
+    for (const layer of this.encoder.layers) {
+      for (const neuron of layer.neurons) {
+        for (let j = 0; j < neuron.weights.length; j++) {
+          neuron.weights[j] += eps;
+          const lossPlus2 = this.computeLoss(pairs);
+          neuron.weights[j] -= 2 * eps;
+          const lossMinus2 = this.computeLoss(pairs);
+          neuron.weights[j] += eps;
+          const grad2 = (lossPlus2 - lossMinus2) / (2 * eps);
+          neuron.weights[j] += lr * -grad2;
+        }
+        neuron.bias += eps;
+        const lossPlus = this.computeLoss(pairs);
+        neuron.bias -= 2 * eps;
+        const lossMinus = this.computeLoss(pairs);
+        neuron.bias += eps;
+        const grad = (lossPlus - lossMinus) / (2 * eps);
+        neuron.bias += lr * -grad;
+      }
+    }
+    for (const layer of this.projectionHead.layers) {
+      for (const neuron of layer.neurons) {
+        for (let j = 0; j < neuron.weights.length; j++) {
+          neuron.weights[j] += eps;
+          const lossPlus2 = this.computeLoss(pairs);
+          neuron.weights[j] -= 2 * eps;
+          const lossMinus2 = this.computeLoss(pairs);
+          neuron.weights[j] += eps;
+          const grad2 = (lossPlus2 - lossMinus2) / (2 * eps);
+          neuron.weights[j] += lr * -grad2;
+        }
+        neuron.bias += eps;
+        const lossPlus = this.computeLoss(pairs);
+        neuron.bias -= 2 * eps;
+        const lossMinus = this.computeLoss(pairs);
+        neuron.bias += eps;
+        const grad = (lossPlus - lossMinus) / (2 * eps);
+        neuron.bias += lr * -grad;
+      }
+    }
+    return loss;
+  }
+  // ── Private: forward all pairs through the projection head ───────────────
+  //
+  // Returns a flat array of 2N projections.
+  // Layout: [ z_0, z_0', z_1, z_1', ..., z_{N-1}, z_{N-1}' ]
+  // Even indices 2i   → original view of pair i
+  // Odd  indices 2i+1 → augmented view of pair i (the positive)
+  _forwardProjections(pairs) {
+    const N = pairs.length;
+    const projections = [];
+    for (const [x, xAug] of pairs) {
+      projections.push(this.project(x));
+      projections.push(this.project(xAug));
+    }
+    return { projections, N };
+  }
+  // ── Private: NT-Xent loss over a set of 2N projections ───────────────────
+  //
+  // pairs[2i]   and pairs[2i+1] are positives.
+  // All other 2N-2 samples are negatives for each anchor.
+  _ntXentLoss(projections, N) {
+    const total = 2 * N;
+    const tau = this.temperature;
+    const sim = Array.from(
+      { length: total },
+      (_, i) => Array.from(
+        { length: total },
+        (_2, j) => _ContrastiveLearning.cosineSimilarity(projections[i], projections[j]) / tau
+      )
+    );
+    let totalLoss = 0;
+    for (let i = 0; i < total; i++) {
+      const posIdx = i % 2 === 0 ? i + 1 : i - 1;
+      const numerator = Math.exp(sim[i][posIdx]);
+      let denominator = 0;
+      for (let k = 0; k < total; k++) {
+        if (k !== i) {
+          denominator += Math.exp(sim[i][k]);
+        }
+      }
+      totalLoss += -Math.log(numerator / (denominator + 1e-10));
+    }
+    return totalLoss / total;
+  }
+};
+
+// src/GAN.ts
+var GAN = class {
+  constructor(latentDim, generatorHidden, outputDim, discriminatorHidden, options) {
+    this.latentDim = latentDim;
+    const gStructure = [latentDim, ...generatorHidden, outputDim];
+    this.generator = new NetworkN(gStructure, options?.generatorOptions ?? {});
+    const dStructure = [outputDim, ...discriminatorHidden, 1];
+    this.discriminator = new NetworkN(dStructure, options?.discriminatorOptions ?? {});
+  }
+  // ── Public API ───────────────────────────────────────────────────────────
+  // Generate a synthetic sample. If z is not provided, samples from N(0, 1).
+  generate(z) {
+    const latent = z ?? this.sampleLatent();
+    return this.generator.predict(latent);
+  }
+  // Returns the discriminator's estimate that x is real, in [0, 1].
+  discriminate(x) {
+    return this.discriminator.predict(x)[0];
+  }
+  // ── Training Step ────────────────────────────────────────────────────────
+  //
+  // Runs one discriminator update and one generator update over the provided
+  // real batch. Returns per-step losses for monitoring.
+  //
+  // Discriminator loss (binary cross-entropy, minimised via SGD):
+  //   L_D = -[ log D(x_real) + log(1 - D(G(z))) ]
+  //
+  // Generator loss:
+  //   L_G = -log D(G(z))   (non-saturating variant — avoids vanishing gradients
+  //                          in early training when D is confident)
+  //
+  trainStep(realBatch, lr) {
+    const eps = 1e-15;
+    let dLossSum = 0;
+    let gLossSum = 0;
+    for (const xReal of realBatch) {
+      const dReal = Math.max(eps, Math.min(1 - eps, this.discriminate(xReal)));
+      const dRealDelta = [1 - dReal];
+      this.discriminator.trainWithDeltas(xReal, dRealDelta, lr);
+      dLossSum += -Math.log(dReal);
+      const z = this.sampleLatent();
+      const xFake = this.generate(z);
+      const dFake = Math.max(eps, Math.min(1 - eps, this.discriminate(xFake)));
+      const dFakeDelta = [0 - dFake];
+      this.discriminator.trainWithDeltas(xFake, dFakeDelta, lr);
+      dLossSum += -Math.log(1 - dFake);
+      const z2 = this.sampleLatent();
+      const xFake2 = this.generate(z2);
+      const dScore = Math.max(eps, Math.min(1 - eps, this.discriminate(xFake2)));
+      const gError = 1 - dScore;
+      const gDelta = xFake2.map(() => gError / xFake2.length);
+      this.generator.trainWithDeltas(z2, gDelta, lr);
+      gLossSum += -Math.log(dScore);
+    }
+    const n = realBatch.length;
+    return {
+      dLoss: dLossSum / n,
+      gLoss: gLossSum / n
+    };
+  }
+  // Samples a latent vector z ~ N(0, 1)^latentDim using Box-Muller transform.
+  sampleLatent() {
+    const z = [];
+    for (let i = 0; i < this.latentDim; i += 2) {
+      const u1 = Math.random();
+      const u2 = Math.random();
+      const r = Math.sqrt(-2 * Math.log(u1 + 1e-15));
+      const theta = 2 * Math.PI * u2;
+      z.push(r * Math.cos(theta));
+      if (i + 1 < this.latentDim) z.push(r * Math.sin(theta));
+    }
+    return z;
+  }
+};
+
+// src/VAE.ts
+var VAE = class {
+  constructor(inputSize, encoderHidden, latentDim, decoderHidden, options) {
+    this.latentDim = latentDim;
+    const encoderStructure = [inputSize, ...encoderHidden, latentDim * 2];
+    this.encoder = new NetworkN(encoderStructure, options ?? {});
+    const decoderStructure = [latentDim, ...decoderHidden, inputSize];
+    this.decoder = new NetworkN(decoderStructure, options ?? {});
+  }
+  // ── Encode ───────────────────────────────────────────────────────────────
+  // Splits the encoder output into μ and logVar vectors.
+  encode(x) {
+    const out = this.encoder.predict(x);
+    const mu = out.slice(0, this.latentDim);
+    const logVar = out.slice(this.latentDim);
+    return { mu, logVar };
+  }
+  // ── Reparametrisation Trick ──────────────────────────────────────────────
+  // z = μ + σ·ε,  ε ~ N(0,1)
+  // σ = exp(0.5 · logVar)  (ensures σ > 0 without constraining the network)
+  reparametrize(mu, logVar) {
+    return mu.map((m, i) => {
+      const sigma = Math.exp(0.5 * logVar[i]);
+      const eps = this._sampleNormal();
+      return m + sigma * eps;
+    });
+  }
+  // ── Decode ───────────────────────────────────────────────────────────────
+  decode(z) {
+    return this.decoder.predict(z);
+  }
+  // ── Forward Pass ─────────────────────────────────────────────────────────
+  // Encodes, samples z, and decodes.
+  forward(x) {
+    const { mu, logVar } = this.encode(x);
+    const z = this.reparametrize(mu, logVar);
+    const reconstruction = this.decode(z);
+    return { reconstruction, mu, logVar, z };
+  }
+  // ── Training Step ────────────────────────────────────────────────────────
+  //
+  // Performs one forward pass, computes the ELBO loss, and updates both
+  // encoder and decoder weights via their built-in SGD.
+  //
+  // Reconstruction loss:   L_recon = MSE(x, x̂)
+  // KL divergence:         L_kl    = -½ Σ(1 + logVarᵢ - μᵢ² - exp(logVarᵢ))
+  // Total:                 L       = L_recon + L_kl
+  //
+  train(x, lr) {
+    const { reconstruction, mu, logVar, z } = this.forward(x);
+    const reconLoss = x.reduce((s, xi, i) => s + (xi - reconstruction[i]) ** 2, 0) / x.length;
+    const klLoss = mu.reduce((s, m, i) => {
+      return s - 0.5 * (1 + logVar[i] - m * m - Math.exp(logVar[i]));
+    }, 0);
+    const totalLoss = reconLoss + klLoss;
+    const decoderDeltas = reconstruction.map((r, i) => (x[i] - r) / x.length);
+    this.decoder.trainWithDeltas(z, decoderDeltas, lr);
+    const encoderDeltas = [
+      ...mu.map((m) => -m),
+      ...logVar.map((lv) => -0.5 * (Math.exp(lv) - 1))
+    ];
+    this.encoder.trainWithDeltas(x, encoderDeltas, lr);
+    return { totalLoss, reconLoss, klLoss };
+  }
+  // ── Generate ─────────────────────────────────────────────────────────────
+  // Samples z ~ N(0, I) and decodes it (pure generation, no input required).
+  generate(z) {
+    const latent = z ?? Array.from({ length: this.latentDim }, () => this._sampleNormal());
+    return this.decode(latent);
+  }
+  // ── Private ──────────────────────────────────────────────────────────────
+  // Box-Muller transform: samples one value from N(0, 1).
+  _sampleNormal() {
+    const u1 = Math.random();
+    const u2 = Math.random();
+    return Math.sqrt(-2 * Math.log(u1 + 1e-15)) * Math.cos(2 * Math.PI * u2);
+  }
+};
+
+// src/Tape.ts
+var Value = class _Value {
+  constructor(data, children = [], op = "") {
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    this._backward = () => {
+    };
+    this.data = data;
+    this.grad = 0;
+    this._prev = new Set(children);
+    this._op = op;
+  }
+  // ── Arithmetic Operations ────────────────────────────────────────────────
+  // z = a + b   →   ∂z/∂a = 1,  ∂z/∂b = 1
+  add(other) {
+    const o = other instanceof _Value ? other : new _Value(other);
+    const out = new _Value(this.data + o.data, [this, o], "+");
+    out._backward = () => {
+      this.grad += out.grad;
+      o.grad += out.grad;
+    };
+    return out;
+  }
+  // z = a * b   →   ∂z/∂a = b,  ∂z/∂b = a
+  mul(other) {
+    const o = other instanceof _Value ? other : new _Value(other);
+    const out = new _Value(this.data * o.data, [this, o], "*");
+    out._backward = () => {
+      this.grad += o.data * out.grad;
+      o.grad += this.data * out.grad;
+    };
+    return out;
+  }
+  // z = aⁿ   →   ∂z/∂a = n·aⁿ⁻¹
+  pow(exp) {
+    const out = new _Value(Math.pow(this.data, exp), [this], `**${exp}`);
+    out._backward = () => {
+      this.grad += exp * Math.pow(this.data, exp - 1) * out.grad;
+    };
+    return out;
+  }
+  // z = max(0, a)   →   ∂z/∂a = a > 0 ? 1 : 0
+  relu() {
+    const out = new _Value(Math.max(0, this.data), [this], "ReLU");
+    out._backward = () => {
+      this.grad += (out.data > 0 ? 1 : 0) * out.grad;
+    };
+    return out;
+  }
+  // z = tanh(a)   →   ∂z/∂a = 1 - tanh(a)² = 1 - z²
+  tanh() {
+    const t = Math.tanh(this.data);
+    const out = new _Value(t, [this], "tanh");
+    out._backward = () => {
+      this.grad += (1 - t * t) * out.grad;
+    };
+    return out;
+  }
+  // z = σ(a) = 1/(1+e⁻ᵃ)   →   ∂z/∂a = z·(1-z)
+  sigmoid() {
+    const s = 1 / (1 + Math.exp(-this.data));
+    const out = new _Value(s, [this], "sigmoid");
+    out._backward = () => {
+      this.grad += s * (1 - s) * out.grad;
+    };
+    return out;
+  }
+  // z = eᵃ   →   ∂z/∂a = eᵃ = z
+  exp() {
+    const e = Math.exp(this.data);
+    const out = new _Value(e, [this], "exp");
+    out._backward = () => {
+      this.grad += e * out.grad;
+    };
+    return out;
+  }
+  // ── Derived Operations (built from primitives) ───────────────────────────
+  // a / b = a * b⁻¹
+  div(other) {
+    const o = other instanceof _Value ? other : new _Value(other);
+    return this.mul(o.pow(-1));
+  }
+  // a - b = a + (b * -1)
+  sub(other) {
+    const o = other instanceof _Value ? other : new _Value(other);
+    return this.add(o.mul(-1));
+  }
+  // -a = a * -1
+  neg() {
+    return this.mul(-1);
+  }
+  // ── Backward Pass ────────────────────────────────────────────────────────
+  //
+  // Propagates gradients from this node (treated as the loss L) back through
+  // the entire computational graph.
+  //
+  // Steps:
+  //   1. Build a topological ordering of all ancestor nodes.
+  //   2. Set this.grad = 1  (∂L/∂L = 1).
+  //   3. Visit nodes in reverse topological order, calling each _backward.
+  //
+  backward() {
+    const topo = [];
+    const visited = /* @__PURE__ */ new Set();
+    const buildTopo = (v) => {
+      if (!visited.has(v)) {
+        visited.add(v);
+        for (const child of v._prev) buildTopo(child);
+        topo.push(v);
+      }
+    };
+    buildTopo(this);
+    this.grad = 1;
+    for (let i = topo.length - 1; i >= 0; i--) {
+      topo[i]._backward();
+    }
+  }
+  toString() {
+    return `Value(data=${this.data.toFixed(4)}, grad=${this.grad.toFixed(4)}, op='${this._op}')`;
+  }
+};
+
+// src/WeightInspector.ts
+var WeightInspector = class _WeightInspector {
+  // ── Per-layer statistics ─────────────────────────────────────────────────
+  // Returns one WeightStats per layer in network.layers order.
+  static inspect(network, deadThreshold = 1e-3) {
+    return network.layers.map((layer) => {
+      const weights = [];
+      for (const neuron of layer.neurons) {
+        weights.push(...neuron.weights, neuron.bias);
+      }
+      return _computeStats(weights, deadThreshold);
+    });
+  }
+  // ── Global statistics ────────────────────────────────────────────────────
+  // Aggregates all weights across the entire network.
+  static inspectAll(network, deadThreshold = 1e-3) {
+    const allWeights = [];
+    for (const layer of network.layers) {
+      for (const neuron of layer.neurons) {
+        allWeights.push(...neuron.weights, neuron.bias);
+      }
+    }
+    return _computeStats(allWeights, deadThreshold);
+  }
+  // ── Formatted table ──────────────────────────────────────────────────────
+  // Prints a compact diagnostic table to the console.
+  static print(network, deadThreshold = 1e-3) {
+    const perLayer = _WeightInspector.inspect(network, deadThreshold);
+    const global = _WeightInspector.inspectAll(network, deadThreshold);
+    const header = [
+      "Layer".padEnd(8),
+      "mean".padStart(9),
+      "std".padStart(9),
+      "min".padStart(9),
+      "max".padStart(9),
+      "dead".padStart(11),
+      "params".padStart(8)
+    ].join("  ");
+    console.log("");
+    console.log("Weight Inspector:");
+    console.log("\u2500".repeat(header.length));
+    console.log(header);
+    console.log("\u2500".repeat(header.length));
+    perLayer.forEach((s, i) => {
+      console.log(_formatRow(`Layer ${i}`, s));
+    });
+    console.log("\u2500".repeat(header.length));
+    console.log(_formatRow("Global", global));
+    console.log("");
+  }
+  // ── Dead ReLU detection ──────────────────────────────────────────────────
+  //
+  // Given a matrix of activations collected over a forward pass (rows = samples,
+  // cols = neurons), counts neurons that output exactly 0 for every sample.
+  //
+  // How to collect activations:
+  //   Run net.predict() for each validation sample and record the output of
+  //   each hidden layer. Pass those as `activations` here.
+  //
+  // threshold: activations below this are counted as "dead" (default: 1e-6).
+  //
+  static countDeadReLUs(activations, threshold = 1e-6) {
+    if (activations.length === 0) return 0;
+    const numNeurons = activations[0].length;
+    let dead = 0;
+    for (let j = 0; j < numNeurons; j++) {
+      const allDead = activations.every((row) => Math.abs(row[j]) < threshold);
+      if (allDead) dead++;
+    }
+    return dead;
+  }
+};
+function _computeStats(weights, deadThreshold) {
+  const n = weights.length;
+  if (n === 0) {
+    return { mean: 0, std: 0, min: 0, max: 0, deadCount: 0, totalParams: 0 };
+  }
+  let sum = 0, sumSq = 0, min = Infinity, max = -Infinity, deadCount = 0;
+  for (const w of weights) {
+    sum += w;
+    sumSq += w * w;
+    if (w < min) min = w;
+    if (w > max) max = w;
+    if (Math.abs(w) < deadThreshold) deadCount++;
+  }
+  const mean = sum / n;
+  const variance = sumSq / n - mean * mean;
+  const std = Math.sqrt(Math.max(0, variance));
+  return { mean, std, min, max, deadCount, totalParams: n };
+}
+function _fmt(n) {
+  return (n >= 0 ? " " : "") + n.toFixed(4);
+}
+function _formatRow(label, s) {
+  const deadStr = `${s.deadCount}/${s.totalParams}`;
+  return [
+    label.padEnd(8),
+    _fmt(s.mean).padStart(9),
+    _fmt(s.std).padStart(9),
+    _fmt(s.min).padStart(9),
+    _fmt(s.max).padStart(9),
+    deadStr.padStart(11),
+    String(s.totalParams).padStart(8)
+  ].join("  ");
+}
+
+// src/Metrics.ts
+function confusionMatrix(yTrue, yPred, numClasses) {
+  const K = numClasses ?? Math.max(...yTrue, ...yPred) + 1;
+  const matrix = Array.from({ length: K }, () => new Array(K).fill(0));
+  for (let i = 0; i < yTrue.length; i++) {
+    matrix[yTrue[i]][yPred[i]]++;
+  }
+  return matrix;
+}
+function precision(yTrue, yPred, positiveClass) {
+  if (positiveClass !== void 0) {
+    return _binaryPrecision(yTrue, yPred, positiveClass);
+  }
+  const K = Math.max(...yTrue, ...yPred) + 1;
+  let sum = 0;
+  for (let c = 0; c < K; c++) sum += _binaryPrecision(yTrue, yPred, c);
+  return sum / K;
+}
+function recall(yTrue, yPred, positiveClass) {
+  if (positiveClass !== void 0) {
+    return _binaryRecall(yTrue, yPred, positiveClass);
+  }
+  const K = Math.max(...yTrue, ...yPred) + 1;
+  let sum = 0;
+  for (let c = 0; c < K; c++) sum += _binaryRecall(yTrue, yPred, c);
+  return sum / K;
+}
+function f1Score(yTrue, yPred, positiveClass) {
+  const p = precision(yTrue, yPred, positiveClass);
+  const r = recall(yTrue, yPred, positiveClass);
+  if (p + r === 0) return 0;
+  return 2 * p * r / (p + r);
+}
+function accuracy(yTrue, yPred) {
+  if (yTrue.length === 0) return 0;
+  const correct = yTrue.filter((y, i) => y === yPred[i]).length;
+  return correct / yTrue.length;
+}
+function rocCurve(yTrue, yScores) {
+  const thresholds = [...new Set(yScores)].sort((a, b) => b - a);
+  thresholds.unshift(thresholds[0] + 1);
+  const P = yTrue.filter((y) => y === 1).length;
+  const N = yTrue.length - P;
+  const points = [];
+  for (const t of thresholds) {
+    let tp = 0, fp = 0;
+    for (let i = 0; i < yTrue.length; i++) {
+      const pred = yScores[i] >= t ? 1 : 0;
+      if (pred === 1 && yTrue[i] === 1) tp++;
+      if (pred === 1 && yTrue[i] === 0) fp++;
+    }
+    points.push({
+      threshold: t,
+      fpr: N > 0 ? fp / N : 0,
+      tpr: P > 0 ? tp / P : 0
+    });
+  }
+  return points.sort((a, b) => a.fpr - b.fpr);
+}
+function auc(yTrue, yScores) {
+  const curve = rocCurve(yTrue, yScores);
+  let area = 0;
+  for (let i = 1; i < curve.length; i++) {
+    const dx = curve[i].fpr - curve[i - 1].fpr;
+    const avgY = (curve[i].tpr + curve[i - 1].tpr) / 2;
+    area += dx * avgY;
+  }
+  return Math.abs(area);
+}
+function mae(yTrue, yPred) {
+  return yTrue.reduce((s, y, i) => s + Math.abs(y - yPred[i]), 0) / yTrue.length;
+}
+function rmse(yTrue, yPred) {
+  const mseVal = yTrue.reduce((s, y, i) => s + (y - yPred[i]) ** 2, 0) / yTrue.length;
+  return Math.sqrt(mseVal);
+}
+function r2Score(yTrue, yPred) {
+  const mean = yTrue.reduce((s, y) => s + y, 0) / yTrue.length;
+  const ssTot = yTrue.reduce((s, y) => s + (y - mean) ** 2, 0);
+  const ssRes = yTrue.reduce((s, y, i) => s + (y - yPred[i]) ** 2, 0);
+  if (ssTot === 0) return 1;
+  return 1 - ssRes / ssTot;
+}
+function perplexity(yTrue, probabilities) {
+  const eps = 1e-15;
+  const T = yTrue.length;
+  let logSum = 0;
+  for (let t = 0; t < T; t++) {
+    const p = Math.max(eps, probabilities[t][yTrue[t]]);
+    logSum += Math.log(p);
+  }
+  return Math.exp(-logSum / T);
+}
+function printConfusionMatrix(matrix, labels) {
+  const K = matrix.length;
+  const lbs = labels ?? Array.from({ length: K }, (_, i) => String(i));
+  const colW = Math.max(6, ...lbs.map((l) => l.length));
+  const pad = (s, w) => s.padStart(w);
+  const header = pad("", colW) + "  " + lbs.map((l) => pad(l, colW)).join("  ");
+  console.log("");
+  console.log("Confusion Matrix (rows = actual, cols = predicted):");
+  console.log(header);
+  console.log("\u2500".repeat(header.length));
+  for (let i = 0; i < K; i++) {
+    const row = pad(lbs[i], colW) + "  " + matrix[i].map((v) => pad(String(v), colW)).join("  ");
+    console.log(row);
+  }
+  console.log("");
+}
+function classificationReport(yTrue, yPred, labels) {
+  const K = Math.max(...yTrue, ...yPred) + 1;
+  const lbs = labels ?? Array.from({ length: K }, (_, i) => `class_${i}`);
+  const rows = [];
+  const colW = Math.max(10, ...lbs.map((l) => l.length));
+  const fmt = (n) => n.toFixed(4).padStart(10);
+  const fmtI = (n) => String(n).padStart(10);
+  rows.push(
+    "label".padEnd(colW) + fmt(0).replace(/\d/g, " ").replace("0.0000", "precision") + fmt(0).replace(/\d/g, " ").replace("0.0000", "   recall") + fmt(0).replace(/\d/g, " ").replace("0.0000", " f1-score") + fmtI(0).replace(/\d/g, " ").replace("0", "   support")
+  );
+  rows.push("\u2500".repeat(colW + 44));
+  let pSum = 0, rSum = 0, f1Sum = 0;
+  for (let c = 0; c < K; c++) {
+    const p = _binaryPrecision(yTrue, yPred, c);
+    const r = _binaryRecall(yTrue, yPred, c);
+    const f1 = p + r > 0 ? 2 * p * r / (p + r) : 0;
+    const support = yTrue.filter((y) => y === c).length;
+    pSum += p;
+    rSum += r;
+    f1Sum += f1;
+    rows.push(lbs[c].padEnd(colW) + fmt(p) + fmt(r) + fmt(f1) + fmtI(support));
+  }
+  rows.push("\u2500".repeat(colW + 44));
+  rows.push("macro avg".padEnd(colW) + fmt(pSum / K) + fmt(rSum / K) + fmt(f1Sum / K) + fmtI(yTrue.length));
+  console.log("");
+  console.log("Classification Report:");
+  rows.forEach((r) => console.log(r));
+  console.log("");
+}
+function _binaryPrecision(yTrue, yPred, pos) {
+  let tp = 0, fp = 0;
+  for (let i = 0; i < yTrue.length; i++) {
+    if (yPred[i] === pos && yTrue[i] === pos) tp++;
+    if (yPred[i] === pos && yTrue[i] !== pos) fp++;
+  }
+  return tp + fp > 0 ? tp / (tp + fp) : 0;
+}
+function _binaryRecall(yTrue, yPred, pos) {
+  let tp = 0, fn = 0;
+  for (let i = 0; i < yTrue.length; i++) {
+    if (yTrue[i] === pos && yPred[i] === pos) tp++;
+    if (yTrue[i] === pos && yPred[i] !== pos) fn++;
+  }
+  return tp + fn > 0 ? tp / (tp + fn) : 0;
+}
+
+// src/EarlyStopping.ts
+var EarlyStopping = class {
+  constructor(options) {
+    this.patience = options?.patience ?? 10;
+    this.minDelta = options?.minDelta ?? 1e-4;
+    this.mode = options?.mode ?? "min";
+    this.restoreBest = options?.restoreBest ?? false;
+    this.counter = 0;
+    this.stopped = false;
+    this.bestEpoch = 0;
+    this.bestWeights = null;
+    this.bestValue = this.mode === "min" ? Infinity : -Infinity;
+  }
+  // ── update ───────────────────────────────────────────────────────────────
+  //
+  // Call once per epoch with the current metric value.
+  // Returns true when training should stop (patience exhausted).
+  //
+  // Optionally pass `weights` (from net.getWeights()) to enable weight
+  // snapshotting when restoreBest = true.
+  //
+  update(value, epoch, weights) {
+    if (this.stopped) return true;
+    const improved = this.mode === "min" ? value < this.bestValue - this.minDelta : value > this.bestValue + this.minDelta;
+    if (improved) {
+      this.bestValue = value;
+      this.bestEpoch = epoch;
+      this.counter = 0;
+      if (this.restoreBest && weights !== void 0) {
+        this.bestWeights = [...weights];
+      }
+    } else {
+      this.counter++;
+      if (this.counter >= this.patience) {
+        this.stopped = true;
+        return true;
+      }
+    }
+    return false;
+  }
+  // Resets all state — use to re-run training with a fresh early-stop monitor.
+  reset() {
+    this.counter = 0;
+    this.stopped = false;
+    this.bestEpoch = 0;
+    this.bestWeights = null;
+    this.bestValue = this.mode === "min" ? Infinity : -Infinity;
+  }
+};
+
+// src/LossPlotter.ts
+var LossPlotter = class {
+  constructor(options) {
+    this.width = options?.width ?? 60;
+    this.height = options?.height ?? 15;
+    this.title = options?.title ?? "Loss Curve";
+    this.losses = [];
+    this.epochs = [];
+  }
+  // Add a single (loss, epoch) pair.
+  add(loss, epoch) {
+    this.losses.push(loss);
+    this.epochs.push(epoch ?? this.losses.length - 1);
+  }
+  // Add multiple loss values (epochs are auto-numbered from 0).
+  addMultiple(losses) {
+    for (const l of losses) this.add(l);
+  }
+  // Returns the ASCII plot as a multi-line string.
+  render() {
+    if (this.losses.length === 0) return `[${this.title}] \u2014 no data yet`;
+    const losses = this.losses;
+    const minL = Math.min(...losses);
+    const maxL = Math.max(...losses);
+    const range = maxL - minL || 1;
+    const yLabelW = 8;
+    const plotW = Math.max(4, this.width - yLabelW - 1);
+    const plotH = Math.max(3, this.height);
+    const grid = Array.from(
+      { length: plotH },
+      () => new Array(plotW).fill(" ")
+    );
+    const n = losses.length;
+    for (let idx = 0; idx < n; idx++) {
+      const col = Math.round(idx / Math.max(1, n - 1) * (plotW - 1));
+      const norm = (losses[idx] - minL) / range;
+      const row = Math.round((1 - norm) * (plotH - 1));
+      grid[row][col] = "*";
+    }
+    const lines = [];
+    const titlePadded = ` ${this.title} `;
+    const dashCount = Math.max(0, plotW + yLabelW - titlePadded.length);
+    lines.push("\u250C" + titlePadded + "\u2500".repeat(dashCount) + "\u2510");
+    for (let row = 0; row < plotH; row++) {
+      let label;
+      if (row === 0) {
+        label = _fmtNum(maxL).padStart(yLabelW - 2) + " \u2524";
+      } else if (row === plotH - 1) {
+        label = _fmtNum(minL).padStart(yLabelW - 2) + " \u2524";
+      } else if (row === Math.floor(plotH / 2)) {
+        const mid = minL + range / 2;
+        label = _fmtNum(mid).padStart(yLabelW - 2) + " \u2524";
+      } else {
+        label = " ".repeat(yLabelW - 1) + "\u2502";
+      }
+      lines.push(label + grid[row].join("") + "\u2502");
+    }
+    const xAxis = " ".repeat(yLabelW - 1) + "\u2514" + "\u2500".repeat(plotW) + "\u2518";
+    lines.push(xAxis);
+    const firstEpoch = String(this.epochs[0]);
+    const lastEpoch = String(this.epochs[this.epochs.length - 1]);
+    const xLabel = " ".repeat(yLabelW) + firstEpoch + " ".repeat(Math.max(1, plotW - firstEpoch.length - lastEpoch.length)) + lastEpoch + "  epoch";
+    lines.push(xLabel);
+    lines.push(
+      ` min=${_fmtNum(minL)}  max=${_fmtNum(maxL)}  last=${_fmtNum(losses[losses.length - 1])}  n=${n}`
+    );
+    return lines.join("\n");
+  }
+  // Prints the chart to stdout.
+  print() {
+    console.log(this.render());
+  }
+  // Clears all accumulated data.
+  reset() {
+    this.losses = [];
+    this.epochs = [];
+  }
+};
+function _fmtNum(n) {
+  if (Math.abs(n) >= 1e4 || Math.abs(n) < 1e-3 && n !== 0) {
+    return n.toExponential(1);
+  }
+  return n.toPrecision(4);
+}
+
+// src/DataAugmentation.ts
+var DataAugmentation = class _DataAugmentation {
+  // ── Noise / Perturbation ─────────────────────────────────────────────────
+  // Adds independent Gaussian noise to each feature: x'ᵢ = xᵢ + N(0, σ²).
+  // sigma: standard deviation of the noise (default: 0.01).
+  static addNoise(x, sigma = 0.01) {
+    return x.map((v) => v + _sampleNormal() * sigma);
+  }
+  // Uniform jitter: x'ᵢ = xᵢ + U(-delta, delta).
+  // delta: half-width of the uniform perturbation (default: 0.01).
+  static jitter(x, delta = 0.01) {
+    return x.map((v) => v + (Math.random() * 2 - 1) * delta);
+  }
+  // Reverses the order of the feature vector.
+  // Useful when features are symmetric or represent a temporal window.
+  static flipHorizontal(x) {
+    return [...x].reverse();
+  }
+  // ── Normalisation ────────────────────────────────────────────────────────
+  // Min-Max normalisation fitted on a dataset X.
+  // Returns the normalised data and the per-feature min/max arrays.
+  // Use normalizePoint() to apply the same transform to new samples.
+  static normalize(X) {
+    if (X.length === 0) return { normalized: [], min: [], max: [] };
+    const d = X[0].length;
+    const min = new Array(d).fill(Infinity);
+    const max = new Array(d).fill(-Infinity);
+    for (const row of X) {
+      for (let j = 0; j < d; j++) {
+        if (row[j] < min[j]) min[j] = row[j];
+        if (row[j] > max[j]) max[j] = row[j];
+      }
+    }
+    const normalized = X.map((row) => _DataAugmentation.normalizePoint(row, min, max));
+    return { normalized, min, max };
+  }
+  // Applies pre-computed min/max normalisation to a single sample.
+  // Handles constant features (min === max) by mapping to 0.
+  static normalizePoint(x, min, max) {
+    return x.map((v, j) => {
+      const range = max[j] - min[j];
+      return range === 0 ? 0 : (v - min[j]) / range;
+    });
+  }
+  // Z-Score standardisation fitted on a dataset X.
+  // Returns the standardised data and per-feature mean/std arrays.
+  // Use standardizePoint() to apply the same transform to new samples.
+  static standardize(X) {
+    if (X.length === 0) return { standardized: [], mean: [], std: [] };
+    const n = X.length;
+    const d = X[0].length;
+    const mean = new Array(d).fill(0);
+    for (const row of X) {
+      for (let j = 0; j < d; j++) mean[j] += row[j];
+    }
+    for (let j = 0; j < d; j++) mean[j] /= n;
+    const variance = new Array(d).fill(0);
+    for (const row of X) {
+      for (let j = 0; j < d; j++) variance[j] += (row[j] - mean[j]) ** 2;
+    }
+    const std = variance.map((v) => Math.sqrt(v / n));
+    const standardized = X.map(
+      (row) => _DataAugmentation.standardizePoint(row, mean, std)
+    );
+    return { standardized, mean, std };
+  }
+  // Applies pre-computed z-score standardisation to a single sample.
+  // Constant features (std === 0) are mapped to 0.
+  static standardizePoint(x, mean, std) {
+    return x.map((v, j) => std[j] === 0 ? 0 : (v - mean[j]) / std[j]);
+  }
+  // ── Batch Augmentation ───────────────────────────────────────────────────
+  // Generates `factor` noisy copies of each sample in X.
+  // The original samples are included in the output (at factor = 1 the output
+  // equals the input; at factor = 3 the dataset triples in size).
+  // sigma: noise std dev (default: 0.01).
+  static augmentBatch(X, y, factor = 2, sigma = 0.01) {
+    const augX = [];
+    const augY = [];
+    for (let i = 0; i < X.length; i++) {
+      augX.push([...X[i]]);
+      augY.push(y[i]);
+      for (let k = 1; k < factor; k++) {
+        augX.push(_DataAugmentation.addNoise(X[i], sigma));
+        augY.push(y[i]);
+      }
+    }
+    return { X: augX, y: augY };
+  }
+  // ── Shuffle ──────────────────────────────────────────────────────────────
+  // Fisher-Yates shuffle — in-place permutation of indices.
+  // Returns new arrays (does not mutate the inputs).
+  static shuffle(X, y) {
+    const indices = Array.from({ length: X.length }, (_, i) => i);
+    for (let i = indices.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [indices[i], indices[j]] = [indices[j], indices[i]];
+    }
+    return {
+      X: indices.map((i) => X[i]),
+      y: indices.map((i) => y[i])
+    };
+  }
+  // ── Train / Val / Test Split ─────────────────────────────────────────────
+  //
+  // Splits the dataset into three non-overlapping partitions.
+  // trainRatio + valRatio must be < 1.0; the remainder goes to test.
+  // Shuffles automatically before splitting.
+  //
+  // Default split: 70% / 15% / 15%.
+  //
+  static split(X, y, trainRatio = 0.7, valRatio = 0.15) {
+    if (trainRatio + valRatio >= 1) {
+      throw new Error(
+        `trainRatio (${trainRatio}) + valRatio (${valRatio}) must be < 1`
+      );
+    }
+    const { X: sX, y: sY } = _DataAugmentation.shuffle(X, y);
+    const n = sX.length;
+    const trainEnd = Math.floor(n * trainRatio);
+    const valEnd = trainEnd + Math.floor(n * valRatio);
+    return {
+      trainX: sX.slice(0, trainEnd),
+      trainY: sY.slice(0, trainEnd),
+      valX: sX.slice(trainEnd, valEnd),
+      valY: sY.slice(trainEnd, valEnd),
+      testX: sX.slice(valEnd),
+      testY: sY.slice(valEnd)
+    };
+  }
+};
+function _sampleNormal() {
+  const u1 = Math.random();
+  const u2 = Math.random();
+  return Math.sqrt(-2 * Math.log(u1 + 1e-15)) * Math.cos(2 * Math.PI * u2);
+}
 export {
   Adam,
   AttentionHead,
+  Augmenter,
+  Autoencoder,
   BatchNorm,
   BiasVector,
+  CausalConv1D,
   ClipOptimizer,
   ClippedOptimizerFactory,
+  ContrastiveLearning,
   Conv1D,
+  Conv2D,
+  DataAugmentation,
   DataLoader,
+  DecisionTree,
   Dropout,
+  EarlyStopping,
   EmbeddingMatrix,
+  Flatten,
+  GAN,
   GRULayer,
+  GaussianNaiveBayes,
+  HopfieldNetwork,
+  KMeans,
   LRScheduler,
   LSTMLayer,
   Layer,
   LayerNorm,
+  LearnedPositionalEncoding,
+  LinearRegression,
+  LogisticRegression,
+  LossPlotter,
+  MaxPool2D,
   ModelSaver,
   Momentum,
   MultiHeadAttention,
@@ -2624,23 +6330,49 @@ export {
   NetworkTransformerRL,
   Neuron,
   NeuronN,
+  PCA,
+  Perceptron,
+  PositionalEncoding,
+  RNN,
   SGD,
+  SOM,
+  Seq2Seq,
+  SoftmaxRegression,
+  TCN,
+  TSNE,
   Trainer,
   TransformerBlock,
+  VAE,
+  Value,
+  WeightInspector,
   WeightMatrix,
+  Word2Vec,
+  accuracy,
+  auc,
+  classificationReport,
+  confusionMatrix,
   crossEntropy,
   crossEntropyDelta,
   crossEntropyDeltaRaw,
   defaultOptimizer,
   elu,
+  f1Score,
   leakyRelu,
   linear,
+  mae,
   makeElu,
   makeLeakyRelu,
   matMul,
   mse,
   mseDelta,
+  perplexity,
+  precision,
+  printConfusionMatrix,
+  r2Score,
+  recall,
   relu,
+  rmse,
+  rocCurve,
   sigmoid2 as sigmoid,
   softmax,
   softmaxBackward,