@seanhogg/builderforce-memory-engine 2026.7.11 → 2026.7.14

package/dist/training/mixed_precision.d.ts

@@ -0,0 +1,67 @@
+/**
+ * mixed_precision.ts — mixed-precision training discipline (AMP) for the CPU
+ * reference, faithful to the cookbook's recipe:
+ *
+ *   • fp16 compute, fp32 MASTER weights. The model's Float32Array params ARE the
+ *     master copy; the forward runs on an fp16-rounded view, so tiny weight
+ *     updates still accumulate in fp32 instead of vanishing.
+ *   • Dynamic LOSS SCALING. fp16 gradients underflow to zero below ~6e-5; scaling
+ *     the loss by a large factor S lifts them into fp16 range, then we unscale by
+ *     S before the optimiser step. On overflow (inf/nan) we skip the step and back
+ *     the scale off; after a clean streak we grow it. This is the mechanism that
+ *     makes fp16 training numerically stable.
+ *
+ * The payoff is memory/throughput: activations and gradients at half precision.
+ * On CPU we can't reclaim the bytes, so this module models the NUMERICS exactly
+ * (fp16 rounding + loss scaling) — the property the WGSL path will inherit — and
+ * its tests prove a small gradient survives WITH scaling and underflows WITHOUT.
+ */
+/** Round a value to what fp16 storage would preserve (half-precision simulation). */
+export declare function roundFp16(x: number): number;
+/** Round every element of a copy to fp16 precision (leaves the input untouched). */
+export declare function fp16View(a: Float32Array): Float32Array;
+export interface LossScalerOptions {
+    /** Initial scale. Default 2^14 = 16384. */
+    initScale?: number;
+    /** Multiply the scale by this after `growthInterval` clean steps. Default 2. */
+    growthFactor?: number;
+    /** Multiply the scale by this on overflow. Default 0.5. */
+    backoffFactor?: number;
+    /** Clean steps between growth attempts. Default 200. */
+    growthInterval?: number;
+    /** Floor for the scale so it can't collapse to zero. Default 1. */
+    minScale?: number;
+}
+/**
+ * Dynamic loss scaler — the standard AMP controller. Scale the loss/grads up
+ * before backward, {@link check} them for overflow, {@link unscale} the good ones,
+ * and {@link update} the scale based on whether this step overflowed.
+ */
+export declare class DynamicLossScaler {
+    private _scale;
+    private readonly growthFactor;
+    private readonly backoffFactor;
+    private readonly growthInterval;
+    private readonly minScale;
+    private cleanStreak;
+    private _overflows;
+    private _skipped;
+    constructor(opts?: LossScalerOptions);
+    get scale(): number;
+    get overflows(): number;
+    get skipped(): number;
+    /** True if any gradient is inf/nan (an fp16 overflow) — such a step must be skipped. */
+    check(grads: {
+        data: Float32Array;
+    }[]): boolean;
+    /** Divide gradients back down by the current scale, in place. */
+    unscale(grads: {
+        data: Float32Array;
+    }[]): void;
+    /**
+     * Advance the scale controller. Pass whether this step overflowed. Returns
+     * `true` if the optimiser step should PROCEED, `false` if it must be skipped.
+     */
+    update(overflow: boolean): boolean;
+}
+//# sourceMappingURL=mixed_precision.d.ts.map

package/dist/training/mixed_precision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mixed_precision.d.ts","sourceRoot":"","sources":["../../src/training/mixed_precision.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,qFAAqF;AACrF,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAED,oFAAoF;AACpF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,YAAY,GAAG,YAAY,CAItD;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAK;gBAET,IAAI,GAAE,iBAAsB;IAQxC,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,SAAS,IAAI,MAAM,CAEtB;IACD,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,wFAAwF;IACxF,KAAK,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE,GAAG,OAAO;IAW/C,iEAAiE;IACjE,OAAO,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,YAAY,CAAA;KAAE,EAAE,GAAG,IAAI;IAQ9C;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO;CAcnC"}

package/dist/training/mixed_precision.js

@@ -0,0 +1,101 @@
+/**
+ * mixed_precision.ts — mixed-precision training discipline (AMP) for the CPU
+ * reference, faithful to the cookbook's recipe:
+ *
+ *   • fp16 compute, fp32 MASTER weights. The model's Float32Array params ARE the
+ *     master copy; the forward runs on an fp16-rounded view, so tiny weight
+ *     updates still accumulate in fp32 instead of vanishing.
+ *   • Dynamic LOSS SCALING. fp16 gradients underflow to zero below ~6e-5; scaling
+ *     the loss by a large factor S lifts them into fp16 range, then we unscale by
+ *     S before the optimiser step. On overflow (inf/nan) we skip the step and back
+ *     the scale off; after a clean streak we grow it. This is the mechanism that
+ *     makes fp16 training numerically stable.
+ *
+ * The payoff is memory/throughput: activations and gradients at half precision.
+ * On CPU we can't reclaim the bytes, so this module models the NUMERICS exactly
+ * (fp16 rounding + loss scaling) — the property the WGSL path will inherit — and
+ * its tests prove a small gradient survives WITH scaling and underflows WITHOUT.
+ */
+import { floatToFp16, fp16ToFloat } from "../utils/quantization.js";
+/** Round a value to what fp16 storage would preserve (half-precision simulation). */
+export function roundFp16(x) {
+    return fp16ToFloat(floatToFp16(x));
+}
+/** Round every element of a copy to fp16 precision (leaves the input untouched). */
+export function fp16View(a) {
+    const out = new Float32Array(a.length);
+    for (let i = 0; i < a.length; i++)
+        out[i] = roundFp16(a[i]);
+    return out;
+}
+/**
+ * Dynamic loss scaler — the standard AMP controller. Scale the loss/grads up
+ * before backward, {@link check} them for overflow, {@link unscale} the good ones,
+ * and {@link update} the scale based on whether this step overflowed.
+ */
+export class DynamicLossScaler {
+    _scale;
+    growthFactor;
+    backoffFactor;
+    growthInterval;
+    minScale;
+    cleanStreak = 0;
+    _overflows = 0;
+    _skipped = 0;
+    constructor(opts = {}) {
+        this._scale = opts.initScale ?? 16384;
+        this.growthFactor = opts.growthFactor ?? 2;
+        this.backoffFactor = opts.backoffFactor ?? 0.5;
+        this.growthInterval = opts.growthInterval ?? 200;
+        this.minScale = opts.minScale ?? 1;
+    }
+    get scale() {
+        return this._scale;
+    }
+    get overflows() {
+        return this._overflows;
+    }
+    get skipped() {
+        return this._skipped;
+    }
+    /** True if any gradient is inf/nan (an fp16 overflow) — such a step must be skipped. */
+    check(grads) {
+        for (const g of grads) {
+            const a = g.data;
+            for (let i = 0; i < a.length; i++) {
+                const x = a[i];
+                if (!Number.isFinite(x))
+                    return true;
+            }
+        }
+        return false;
+    }
+    /** Divide gradients back down by the current scale, in place. */
+    unscale(grads) {
+        const inv = 1 / this._scale;
+        for (const g of grads) {
+            const a = g.data;
+            for (let i = 0; i < a.length; i++)
+                a[i] = a[i] * inv;
+        }
+    }
+    /**
+     * Advance the scale controller. Pass whether this step overflowed. Returns
+     * `true` if the optimiser step should PROCEED, `false` if it must be skipped.
+     */
+    update(overflow) {
+        if (overflow) {
+            this._overflows++;
+            this._skipped++;
+            this._scale = Math.max(this.minScale, this._scale * this.backoffFactor);
+            this.cleanStreak = 0;
+            return false;
+        }
+        if (++this.cleanStreak >= this.growthInterval) {
+            this._scale *= this.growthFactor;
+            this.cleanStreak = 0;
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=mixed_precision.js.map

package/dist/training/mixed_precision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mixed_precision.js","sourceRoot":"","sources":["../../src/training/mixed_precision.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory-engine",
-  "version": "2026.7.11",
+  "version": "2026.7.14",
   "description": "BuilderForce Agent Memory — engine layer. TypeScript/WGSL Mamba SSM kernels, model blocks, autograd, training, and BPE tokenizer (zero runtime deps, WebGPU-native).",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/index.ts

@@ -41,9 +41,15 @@ export type {
 
 // ── EvermindLM (the generative model) + AdamW ──────────────────────────────────
 export { EvermindLM, EvermindLMTrainer, DEFAULT_LM_CONFIG, DEFAULT_LM_SEED } from './lm/index.js';
-export type { EvermindLMConfig, LMGenerateOptions, TextCodec } from './lm/index.js';
+export type { EvermindLMConfig, LMGenerateOptions, TextCodec, EvermindLMTrainOptions } from './lm/index.js';
 export { AdamW } from './optim/adamw.js';
-export type { AdamWOptions, OptimTarget, OptimParam } from './optim/adamw.js';
+export type { AdamWOptions, OptimTarget, OptimParam, ShardSpec } from './optim/adamw.js';
+
+// PEFT / efficient-training toolkit (LoRA, QLoRA, mixed precision, checkpointing).
+export { LoRAAdapter, EvermindLMLoRA, quantizeBase } from './training/lora.js';
+export type { LoRAConfig, LoRAFitOptions, BaseQuant } from './training/lora.js';
+export { DynamicLossScaler, roundFp16, fp16View } from './training/mixed_precision.js';
+export type { LossScalerOptions } from './training/mixed_precision.js';
 
 // ── Training ──────────────────────────────────────────────────────────────────
 

package/src/limbic/limbic_trainer.ts

@@ -46,7 +46,10 @@ export interface LimbicTrainOptions {
   eps?: number;
   /** Max global gradient L2 norm before the optimiser step. Default 1.0. */
   maxGradNorm?: number;
-  onEpochEnd?: ((epoch: number, loss: number) => void) | null;
+  /** Per-epoch hook. `gradNorm` is the pre-clip gradient L2 norm this epoch (the
+   *  instability early-warning) — computed CPU-side so it's always available, unlike
+   *  the GPU trainer where it's opt-in. */
+  onEpochEnd?: ((epoch: number, loss: number, gradNorm?: number) => void) | null;
 }
 
 interface AdamMoment {
@@ -146,7 +149,7 @@ export class LimbicTrainer {
         for (let i = 0; i < g.data.length; i++) g.data[i]! *= invN;
       }
 
-      this._clipGradients(grads, maxGradNorm);
+      const gradNorm = this._clipGradients(grads, maxGradNorm);
 
       this._step++;
       const beta1_t = Math.pow(beta1, this._step);
@@ -160,7 +163,7 @@ export class LimbicTrainer {
 
       const avg = epochLoss / samples.length;
       losses.push(avg);
-      if (onEpochEnd) onEpochEnd(epoch + 1, avg);
+      if (onEpochEnd) onEpochEnd(epoch + 1, avg, gradNorm);
     }
     return losses;
   }
@@ -184,7 +187,8 @@ export class LimbicTrainer {
     return total / samples.length;
   }
 
-  private _clipGradients(grads: LimbicParam[], maxNorm: number): void {
+  /** Clip grads to `maxNorm` in place; returns the PRE-clip L2 norm (the signal). */
+  private _clipGradients(grads: LimbicParam[], maxNorm: number): number {
     let normSq = 0;
     for (const g of grads) for (let i = 0; i < g.data.length; i++) normSq += g.data[i]! * g.data[i]!;
     const norm = Math.sqrt(normSq);
@@ -192,6 +196,7 @@ export class LimbicTrainer {
       const scale = maxNorm / norm;
       for (const g of grads) for (let i = 0; i < g.data.length; i++) g.data[i]! *= scale;
     }
+    return norm;
   }
 
   private _adamwStepCpu(