@seanhogg/builderforce-memory-engine 2026.9.34 → 2026.10.1

package/src/ml/train.ts

@@ -0,0 +1,136 @@
+/**
+ * ml/train.ts — the ONE trainer seam for catalog tasks.
+ *
+ * Classical engines fit in closed form or by small iteration (`classical/`);
+ * head engines train a {@link DenseHead} through the shared {@link HeadTrainer}
+ * (GPU AdamW when a device is supplied, CPU AdamW otherwise). A task can name its
+ * own composite fit (`TrainSpec.fit`), or say that something else trains it
+ * (`TrainSpec.trainedBy`, e.g. `LimbicTrainer` for `limbic.affect`).
+ *
+ * Held-out loss is measured the same way everywhere ({@link mlEvalLoss}) — it is
+ * also what gates a federated merge.
+ */
+import { fitClassical, type ClassicalOptions } from "./classical/index.js";
+import { DenseHead } from "./dense_head.js";
+import { extractFeatureMatrix, type TextEmbedder } from "./features.js";
+import { HeadTrainer, type HeadTrainOptions } from "./head_trainer.js";
+import type { MlModelStore } from "./run.js";
+import { engineKey, type MlEngineRef, type MlPredictor, type MlSample, type MlTask, type MlTaskKind } from "./types.js";
+
+/** One labelled example in input space. */
+export interface MlTrainExample<I> {
+  input: I;
+  /** classify: class index; regress: target value; cluster/anomaly: ignored (use 0). */
+  label: number;
+  weight?: number;
+}
+
+export interface MlTrainOptions {
+  /** Engine to fit (default: the task's first trainable local engine). */
+  engine?: MlEngineRef;
+  embedder?: TextEmbedder;
+  device?: GPUDevice | null;
+  classical?: ClassicalOptions;
+  head?: { hiddenDim?: number; seed?: number; train?: HeadTrainOptions };
+  /** Overrides the task's `holdoutFraction`. 0 disables the held-out measurement. */
+  holdoutFraction?: number;
+  /** After measuring on the held-out tail, refit on everything. Default true. */
+  refitOnAll?: boolean;
+  /** Store the fitted predictor here under (task id, engine key). */
+  models?: MlModelStore;
+}
+
+export interface MlTrainResult {
+  predictor: MlPredictor;
+  engine: MlEngineRef;
+  /** Examples the final fit saw. */
+  samples: number;
+  /** Size of the held-out tail, and the model's loss on it (null when none was held out). */
+  holdout: number;
+  holdoutLoss: number | null;
+}
+
+/**
+ * Mean loss of `predictor` on `samples` for a task of `kind` — classify: weighted
+ * cross-entropy of the true class; regress: weighted ½·squared error. Null for
+ * kinds without a supervised loss, or an empty set.
+ */
+export function mlEvalLoss(kind: MlTaskKind, predictor: MlPredictor, samples: readonly MlSample[]): number | null {
+  if (samples.length === 0 || (kind !== "classify" && kind !== "regress")) return null;
+  let sum = 0;
+  let wSum = 0;
+  for (const s of samples) {
+    const w = s.weight ?? 1;
+    const p = predictor.predict(s.x);
+    const loss = kind === "classify" ? -Math.log(Math.max(p.scores[s.y] ?? 0, 1e-12)) : 0.5 * (p.scores[0]! - s.y) ** 2;
+    sum += w * loss;
+    wSum += w;
+  }
+  return wSum > 0 ? sum / wSum : null;
+}
+
+/** The task's first local engine the seam can train. */
+function defaultEngine(task: MlTask<any, any>): MlEngineRef {
+  const e = task.engines.find((r) => r.tier === "local" && (r.engine === "classical" || r.engine === "head"));
+  if (!e) throw new Error(`trainMlTask(${task.id}): no trainable local engine`);
+  return e;
+}
+
+async function fitEngine(task: MlTask<any, any>, ref: MlEngineRef, samples: MlSample[], opts: MlTrainOptions): Promise<MlPredictor> {
+  if (task.train?.fit) return task.train.fit(samples, ref);
+  if (ref.engine === "classical") return fitClassical(ref.algorithm, samples, opts.classical);
+  if (ref.engine === "head") {
+    const objective = task.kind === "classify" ? "softmax" : task.kind === "regress" ? "mse" : null;
+    if (!objective) throw new Error(`trainMlTask(${task.id}): a head engine trains classify or regress tasks only`);
+    const head = new DenseHead({
+      inputDim: samples[0]!.x.length,
+      hiddenDim: ref.head === "linear" ? 0 : (opts.head?.hiddenDim ?? 16),
+      outputDim: objective === "softmax" ? task.output.labels!.length : 1,
+      objective,
+      ...(opts.head?.seed != null ? { seed: opts.head.seed } : {}),
+    });
+    await new HeadTrainer(head, opts.device ?? null, `trainMlTask(${task.id})`).train(samples, opts.head?.train);
+    return head;
+  }
+  throw new Error(`trainMlTask(${task.id}): engine '${engineKey(ref)}' is not trained here`);
+}
+
+/**
+ * Fit task `task` on labelled examples. Returns null when there are fewer than
+ * the task's `minSamples` (it stays untrained). Throws for a task with no train
+ * spec, or one another trainer owns.
+ */
+export async function trainMlTask<I>(
+  task: MlTask<I, any>,
+  examples: readonly MlTrainExample<I>[],
+  opts: MlTrainOptions = {},
+): Promise<MlTrainResult | null> {
+  const spec = task.train;
+  if (!spec) throw new Error(`trainMlTask(${task.id}): task is rule-based or pre-trained only`);
+  if (spec.trainedBy) throw new Error(`trainMlTask(${task.id}): trained by ${spec.trainedBy}`);
+  if (examples.length < spec.minSamples) return null;
+
+  const ref = opts.engine ?? defaultEngine(task);
+  const X = await extractFeatureMatrix(task.features, examples.map((e) => e.input), opts.embedder);
+  const samples: MlSample[] = examples.map((e, i) => ({ x: X[i]!, y: e.label, ...(e.weight != null ? { weight: e.weight } : {}) }));
+
+  // Hold out the chronological TAIL: examples arrive oldest first, and the question
+  // is always "does this generalise to what comes next".
+  const supervised = task.kind === "classify" || task.kind === "regress";
+  const frac = supervised ? (opts.holdoutFraction ?? spec.holdoutFraction ?? 0.2) : 0;
+  const nHold = Math.floor(samples.length * frac);
+  let holdoutLoss: number | null = null;
+  if (nHold >= 1 && samples.length - nHold >= 1) {
+    const train = samples.slice(0, samples.length - nHold);
+    const hold = samples.slice(samples.length - nHold);
+    const predictor = await fitEngine(task, ref, train, opts);
+    holdoutLoss = mlEvalLoss(task.kind, predictor, hold);
+    if (opts.refitOnAll === false) {
+      opts.models?.set(task.id, engineKey(ref), predictor);
+      return { predictor, engine: ref, samples: train.length, holdout: nHold, holdoutLoss };
+    }
+  }
+  const predictor = await fitEngine(task, ref, samples, opts);
+  opts.models?.set(task.id, engineKey(ref), predictor);
+  return { predictor, engine: ref, samples: samples.length, holdout: nHold >= 1 ? nHold : 0, holdoutLoss };
+}

package/src/ml/types.ts

@@ -0,0 +1,132 @@
+/**
+ * ml/types.ts — the ML task catalog contract (docs/ml-task-catalog.md §3).
+ *
+ * One bounded question Evermind answers without an LLM is ONE data row: how its
+ * input becomes a vector, which engines may answer it (in preference order), how
+ * it trains, and what its output means. Pure types — no vscode, no DOM, no network.
+ */
+
+/** The shape of the question. */
+export type MlTaskKind = "classify" | "regress" | "cluster" | "anomaly" | "rank";
+
+/** Pure-TypeScript algorithms that run everywhere (`ml/classical/`). */
+export type ClassicalAlgorithm =
+  | "knn"
+  | "naive-bayes"
+  | "logistic"
+  | "linear"
+  | "kmeans"
+  | "robust-z"
+  | "ewma"
+  | "isolation-forest"
+  | "gbm-small";
+
+/** An engine that can answer a task. Cloud engines are a port the HOST supplies. */
+export type MlEngineRef =
+  | { tier: "local"; engine: "classical"; algorithm: ClassicalAlgorithm }
+  | { tier: "local"; engine: "head"; head: "mlp" | "linear" }
+  | { tier: "local"; engine: "onnx"; model: string }
+  | { tier: "cloud"; engine: "workers-ai"; model: string };
+
+/**
+ * Which engines a run may use — the person's inference setting.
+ *  - `local-only`: local tiers only, never the network.
+ *  - `hybrid`: local first, the cloud port when no local engine can answer (or the
+ *    local answer is below the caller's confidence floor).
+ *  - `specific`: exactly the engine the caller names.
+ */
+export type InferenceMode = "local-only" | "hybrid" | "specific";
+
+/** What an engine returns before the task decodes it. */
+export interface MlPrediction {
+  /**
+   * classify: one probability per label; regress: the predicted value(s);
+   * cluster: `[clusterId]`; anomaly: `[score]` where ≥ 1 is anomalous;
+   * rank: one score per candidate.
+   */
+  scores: number[];
+  /** Calibrated confidence in [0, 1]. */
+  confidence: number;
+}
+
+/** A fitted model that answers on a feature vector. */
+export interface MlPredictor {
+  predict(x: Float32Array): MlPrediction;
+  /** Trainable state as one flat vector — present on models that federate. */
+  exportParams?(): Float32Array;
+  /** Load a flat vector produced by {@link exportParams} (e.g. after a merge). */
+  importParams?(params: ArrayLike<number>): void;
+}
+
+/** How an input becomes a vector: an embedded text part, numeric fields, or both. */
+export interface FeatureSpec<I> {
+  /** Text to embed (needs an embedder in the run context). */
+  text?: (input: I) => string;
+  /** Numeric fields, already on a stable scale (so federated weights mean the same thing everywhere). */
+  numeric?: (input: I) => number[];
+  /** Names of the numeric fields, index-aligned — documentation and Insights labels. */
+  numericNames?: readonly string[];
+}
+
+/** One labelled training example in feature space. */
+export interface MlSample {
+  x: Float32Array;
+  /** classify: class index; regress: target value; cluster/anomaly: ignored. */
+  y: number;
+  /** Sample weight (default 1). */
+  weight?: number;
+}
+
+/** How a task trains. Absent on the task = rule-based or pre-trained only. */
+export interface TrainSpec {
+  /** Fewer labelled examples than this and the task stays untrained. */
+  minSamples: number;
+  /** Fraction held out for the eval gate (default 0.2). */
+  holdoutFraction?: number;
+  /**
+   * A task-specific fit (e.g. a composite of two classical detectors). When absent
+   * the trainer fits the engine named by the run (`ml/train.ts`).
+   */
+  fit?: (samples: readonly MlSample[], engine: MlEngineRef) => MlPredictor;
+  /** Who trains it when not `ml/train.ts` (e.g. `LimbicTrainer` for `limbic.affect`). */
+  trainedBy?: string;
+}
+
+/** What a task's answer means. */
+export interface OutputSpec<O> {
+  /** Label set for classify tasks (index-aligned with `MlPrediction.scores`). */
+  labels?: readonly string[];
+  /** Decode an engine prediction into the task's output. */
+  decode(p: MlPrediction): O;
+}
+
+/** One bounded question Evermind can answer without an LLM. DATA, not a class tree. */
+export interface MlTask<I = unknown, O = unknown> {
+  kind: MlTaskKind;
+  /** Stable id, e.g. `experience.quality`. */
+  id: string;
+  /** One line on what it answers. */
+  description: string;
+  features: FeatureSpec<I>;
+  /** In preference order; filtered by the inference mode. */
+  engines: readonly MlEngineRef[];
+  train?: TrainSpec;
+  output: OutputSpec<O>;
+}
+
+/** Task ids: lowercase dotted segments, e.g. `run.local-success`. */
+export const ML_TASK_ID_RE = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+
+/** A stable string key for an engine ref, e.g. `local:classical:logistic`. */
+export function engineKey(ref: MlEngineRef): string {
+  switch (ref.engine) {
+    case "classical":
+      return `local:classical:${ref.algorithm}`;
+    case "head":
+      return `local:head:${ref.head}`;
+    case "onnx":
+      return `local:onnx:${ref.model}`;
+    case "workers-ai":
+      return `cloud:workers-ai:${ref.model}`;
+  }
+}

package/src/moe/moe_model.ts

@@ -25,6 +25,7 @@
 
 import { SeededRng } from "../utils/rng.js";
 import { quantizeFp16, dequantizeFp16 } from "../utils/quantization.js";
+import { softmax } from "../training/cpu_ops.js";
 
 export interface MoEConfig {
   /** Model (token) dimension — FFN input/output width. Default 64. */
@@ -462,16 +463,3 @@ export class SharedExpertMoE {
   }
 }
 
-/** Numerically-stable softmax over a flat array. */
-function softmax(logits: Float32Array): Float32Array {
-  let max = -Infinity;
-  for (let i = 0; i < logits.length; i++) if (logits[i]! > max) max = logits[i]!;
-  const out = new Float32Array(logits.length);
-  let sum = 0;
-  for (let i = 0; i < logits.length; i++) {
-    out[i] = Math.exp(logits[i]! - max);
-    sum += out[i]!;
-  }
-  for (let i = 0; i < logits.length; i++) out[i] = out[i]! / sum;
-  return out;
-}

package/src/training/cpu_ops.ts

@@ -1,127 +1,141 @@
-/**
- * cpu_ops.ts — the small set of exact CPU primitives the reference forward and
- * backward passes share (linear, RMSNorm, SiLU, softplus).
- *
- * Each one mirrors a WGSL kernel exactly, so a gradient computed here is the
- * gradient of the function the GPU actually evaluates. They are deliberately
- * plain loops over `Float32Array`: correctness first, and small enough that the
- * finite-difference check in `tests/backprop.test.ts` is meaningful.
- */
-
-/** Epsilon used by `rmsnorm_forward` in `ACTIVATIONS_WGSL`. */
-export const RMSNORM_EPS = 1e-6;
-
-export function sigmoid(x: number): number {
-    return 1 / (1 + Math.exp(-x));
-}
-
-/** SiLU(x) = x * sigmoid(x) — mirrors `silu_forward`. */
-export function silu(x: number): number {
-    return x / (1 + Math.exp(-x));
-}
-
-/** d/dx SiLU(x) = sigmoid(x) * (1 + x * (1 - sigmoid(x))). */
-export function siluGrad(x: number): number {
-    const s = sigmoid(x);
-    return s * (1 + x * (1 - s));
-}
-
-/** Numerically stable softplus — mirrors the kernel's `max(x,0) + log1p(exp(-|x|))`. */
-export function softplus(x: number): number {
-    return Math.max(x, 0) + Math.log1p(Math.exp(-Math.abs(x)));
-}
-
-/**
- * Y = X @ W^T + b, mirroring `linear_forward`.
- *
- * @param X   (M, K)
- * @param W   (N, K) row-major
- * @param b   (N,)
- * @param out (M, N) — written, not accumulated
- */
-export function linearForward(
-    X: Float32Array, W: Float32Array, b: Float32Array,
-    M: number, K: number, N: number, out: Float32Array,
-): void {
-    for (let r = 0; r < M; r++) {
-        const xo = r * K;
-        const yo = r * N;
-        for (let n = 0; n < N; n++) {
-            let acc = b[n]!;
-            const wo = n * K;
-            for (let k = 0; k < K; k++) acc += X[xo + k]! * W[wo + k]!;
-            out[yo + n] = acc;
-        }
-    }
-}
-
-/**
- * Backward of {@link linearForward}. `dX` is written; `dW` and `db` are
- * ACCUMULATED into (so one parameter can collect gradient from several call
- * sites without a temporary).
- */
-export function linearBackward(
-    dY: Float32Array, X: Float32Array, W: Float32Array,
-    M: number, K: number, N: number,
-    dX: Float32Array, dW: Float32Array, db: Float32Array,
-): void {
-    dX.fill(0);
-    for (let r = 0; r < M; r++) {
-        const xo = r * K;
-        const yo = r * N;
-        for (let n = 0; n < N; n++) {
-            const g = dY[yo + n]!;
-            if (g === 0) continue;
-            db[n] = db[n]! + g;
-            const wo = n * K;
-            for (let k = 0; k < K; k++) {
-                dX[xo + k] = dX[xo + k]! + g * W[wo + k]!;
-                dW[wo + k] = dW[wo + k]! + g * X[xo + k]!;
-            }
-        }
-    }
-}
-
-/**
- * RMSNorm forward — mirrors `rmsnorm_forward`:
- *   inv[r] = 1 / sqrt(mean(x[r]²) + eps);  y[r,i] = x[r,i] * inv[r] * w[i]
- */
-export function rmsNormForward(
-    x: Float32Array, w: Float32Array, M: number, D: number,
-    out: Float32Array, inv: Float32Array, eps: number = RMSNORM_EPS,
-): void {
-    for (let r = 0; r < M; r++) {
-        const base = r * D;
-        let sq = 0;
-        for (let i = 0; i < D; i++) { const v = x[base + i]!; sq += v * v; }
-        const iv = 1 / Math.sqrt(sq / D + eps);
-        inv[r] = iv;
-        for (let i = 0; i < D; i++) out[base + i] = x[base + i]! * iv * w[i]!;
-    }
-}
-
-/**
- * RMSNorm backward. `dx` and `dw` are ACCUMULATED into — `dx` in particular is
- * usually the residual path, which already carries a gradient.
- */
-export function rmsNormBackward(
-    dY: Float32Array, x: Float32Array, w: Float32Array, inv: Float32Array,
-    M: number, D: number,
-    dx: Float32Array, dw: Float32Array, _eps: number = RMSNORM_EPS,
-): void {
-    for (let r = 0; r < M; r++) {
-        const base = r * D;
-        const iv = inv[r]!;
-        let dot = 0;   // Σ_i (dY[r,i] * w[i]) * x[r,i]
-        for (let i = 0; i < D; i++) {
-            const g = dY[base + i]! * w[i]!;
-            dot += g * x[base + i]!;
-            dw[i] = dw[i]! + dY[base + i]! * x[base + i]! * iv;
-        }
-        const scale = (iv * iv * iv) / D;
-        for (let i = 0; i < D; i++) {
-            const g = dY[base + i]! * w[i]!;
-            dx[base + i] = dx[base + i]! + g * iv - scale * dot * x[base + i]!;
-        }
-    }
-}
+/**
+ * cpu_ops.ts — the small set of exact CPU primitives the reference forward and
+ * backward passes share (linear, RMSNorm, SiLU, softplus).
+ *
+ * Each one mirrors a WGSL kernel exactly, so a gradient computed here is the
+ * gradient of the function the GPU actually evaluates. They are deliberately
+ * plain loops over `Float32Array`: correctness first, and small enough that the
+ * finite-difference check in `tests/backprop.test.ts` is meaningful.
+ */
+
+/** Epsilon used by `rmsnorm_forward` in `ACTIVATIONS_WGSL`. */
+export const RMSNORM_EPS = 1e-6;
+
+export function sigmoid(x: number): number {
+    return 1 / (1 + Math.exp(-x));
+}
+
+/** Numerically-stable softmax over a flat array. */
+export function softmax(logits: ArrayLike<number>): Float32Array {
+    let max = -Infinity;
+    for (let i = 0; i < logits.length; i++) if (logits[i]! > max) max = logits[i]!;
+    const out = new Float32Array(logits.length);
+    let sum = 0;
+    for (let i = 0; i < logits.length; i++) {
+        out[i] = Math.exp(logits[i]! - max);
+        sum += out[i]!;
+    }
+    for (let i = 0; i < logits.length; i++) out[i] = out[i]! / sum;
+    return out;
+}
+
+/** SiLU(x) = x * sigmoid(x) — mirrors `silu_forward`. */
+export function silu(x: number): number {
+    return x / (1 + Math.exp(-x));
+}
+
+/** d/dx SiLU(x) = sigmoid(x) * (1 + x * (1 - sigmoid(x))). */
+export function siluGrad(x: number): number {
+    const s = sigmoid(x);
+    return s * (1 + x * (1 - s));
+}
+
+/** Numerically stable softplus — mirrors the kernel's `max(x,0) + log1p(exp(-|x|))`. */
+export function softplus(x: number): number {
+    return Math.max(x, 0) + Math.log1p(Math.exp(-Math.abs(x)));
+}
+
+/**
+ * Y = X @ W^T + b, mirroring `linear_forward`.
+ *
+ * @param X   (M, K)
+ * @param W   (N, K) row-major
+ * @param b   (N,)
+ * @param out (M, N) — written, not accumulated
+ */
+export function linearForward(
+    X: Float32Array, W: Float32Array, b: Float32Array,
+    M: number, K: number, N: number, out: Float32Array,
+): void {
+    for (let r = 0; r < M; r++) {
+        const xo = r * K;
+        const yo = r * N;
+        for (let n = 0; n < N; n++) {
+            let acc = b[n]!;
+            const wo = n * K;
+            for (let k = 0; k < K; k++) acc += X[xo + k]! * W[wo + k]!;
+            out[yo + n] = acc;
+        }
+    }
+}
+
+/**
+ * Backward of {@link linearForward}. `dX` is written; `dW` and `db` are
+ * ACCUMULATED into (so one parameter can collect gradient from several call
+ * sites without a temporary).
+ */
+export function linearBackward(
+    dY: Float32Array, X: Float32Array, W: Float32Array,
+    M: number, K: number, N: number,
+    dX: Float32Array, dW: Float32Array, db: Float32Array,
+): void {
+    dX.fill(0);
+    for (let r = 0; r < M; r++) {
+        const xo = r * K;
+        const yo = r * N;
+        for (let n = 0; n < N; n++) {
+            const g = dY[yo + n]!;
+            if (g === 0) continue;
+            db[n] = db[n]! + g;
+            const wo = n * K;
+            for (let k = 0; k < K; k++) {
+                dX[xo + k] = dX[xo + k]! + g * W[wo + k]!;
+                dW[wo + k] = dW[wo + k]! + g * X[xo + k]!;
+            }
+        }
+    }
+}
+
+/**
+ * RMSNorm forward — mirrors `rmsnorm_forward`:
+ *   inv[r] = 1 / sqrt(mean(x[r]²) + eps);  y[r,i] = x[r,i] * inv[r] * w[i]
+ */
+export function rmsNormForward(
+    x: Float32Array, w: Float32Array, M: number, D: number,
+    out: Float32Array, inv: Float32Array, eps: number = RMSNORM_EPS,
+): void {
+    for (let r = 0; r < M; r++) {
+        const base = r * D;
+        let sq = 0;
+        for (let i = 0; i < D; i++) { const v = x[base + i]!; sq += v * v; }
+        const iv = 1 / Math.sqrt(sq / D + eps);
+        inv[r] = iv;
+        for (let i = 0; i < D; i++) out[base + i] = x[base + i]! * iv * w[i]!;
+    }
+}
+
+/**
+ * RMSNorm backward. `dx` and `dw` are ACCUMULATED into — `dx` in particular is
+ * usually the residual path, which already carries a gradient.
+ */
+export function rmsNormBackward(
+    dY: Float32Array, x: Float32Array, w: Float32Array, inv: Float32Array,
+    M: number, D: number,
+    dx: Float32Array, dw: Float32Array, _eps: number = RMSNORM_EPS,
+): void {
+    for (let r = 0; r < M; r++) {
+        const base = r * D;
+        const iv = inv[r]!;
+        let dot = 0;   // Σ_i (dY[r,i] * w[i]) * x[r,i]
+        for (let i = 0; i < D; i++) {
+            const g = dY[base + i]! * w[i]!;
+            dot += g * x[base + i]!;
+            dw[i] = dw[i]! + dY[base + i]! * x[base + i]! * iv;
+        }
+        const scale = (iv * iv * iv) / D;
+        for (let i = 0; i < D; i++) {
+            const g = dY[base + i]! * w[i]!;
+            dx[base + i] = dx[base + i]! + g * iv - scale * dot * x[base + i]!;
+        }
+    }
+}