bireactive 0.2.4 → 0.3.0

package/dist/learn/data.d.ts

@@ -0,0 +1,49 @@
+import { type Sample } from "./mlp.js";
+/** A 2D point dataset: each sample's `x` is `[px, py]`, `y` is `0|1`. */
+export type Points = Sample[];
+/** Two interleaving half-moons (the reliable "is it learning" classic). */
+export declare function moons(n: number, opts?: {
+    seed?: number;
+    noise?: number;
+}): Points;
+/** Concentric rings: inner blob (class 0) inside an outer ring (class 1). */
+export declare function circles(n: number, opts?: {
+    seed?: number;
+    noise?: number;
+}): Points;
+/** Four quadrant clusters; class 1 where the coordinate signs differ. */
+export declare function xor(n: number, opts?: {
+    seed?: number;
+    noise?: number;
+}): Points;
+/** Two intertwined spirals — the hard one (may need more steps/capacity). */
+export declare function spirals(n: number, opts?: {
+    seed?: number;
+    noise?: number;
+}): Points;
+/** A 2D dataset family selectable in the demo. */
+export type PointsKind = "moons" | "circles" | "xor" | "spirals";
+/** Build a 2D dataset by name. */
+export declare function points(kind: PointsKind, n: number, opts?: {
+    seed?: number;
+    noise?: number;
+}): Points;
+/** A rasterisable shape. The binary task is `circle` (class 1) vs the rest. */
+export type ShapeKind = "circle" | "square" | "triangle";
+/** Placement of a shape in normalised `[0,1]²` grid space. */
+export interface ShapePose {
+    cx: number;
+    cy: number;
+    r: number;
+    rot: number;
+}
+/** Rasterise a posed shape onto a `grid×grid` coverage buffer (0..1) via
+ *  3×3 supersampling. */
+export declare function rasterShape(kind: ShapeKind, grid: number, pose: ShapePose): Float64Array;
+/** Random pose for a roughly-centred shape (small jitter, moderate size,
+ *  free rotation) — learnable from raw pixels and legible when drawn. */
+export declare function randomPose(r: () => number): ShapePose;
+/** One labelled pixel sample: `circle` → class 1, `square`/`triangle` → 0. */
+export declare function shapeSample(grid: number, r: () => number, noise?: number): Sample;
+/** A batch of `n` fresh pixel samples. */
+export declare function shapeBatch(grid: number, n: number, r: () => number): Sample[];

package/dist/learn/data.js

@@ -0,0 +1,181 @@
+// data.ts — synthetic, reproducible datasets for the learning demos.
+//
+// Two families: 2D point clouds (moons / circles / xor / spirals) where the
+// learned decision boundary is the visual; and rasterised shapes on a small
+// pixel grid (circle vs square/triangle) generated on the fly, so training
+// data is endless and the label is whatever the generator drew.
+import { gaussian, rng } from "./mlp.js";
+/** Two interleaving half-moons (the reliable "is it learning" classic). */
+export function moons(n, opts = {}) {
+    const r = rng(opts.seed ?? 7);
+    const noise = opts.noise ?? 0.12;
+    const out = [];
+    for (let i = 0; i < n; i++) {
+        const top = i % 2 === 0;
+        const a = r() * Math.PI;
+        let px;
+        let py;
+        if (top) {
+            px = Math.cos(a);
+            py = Math.sin(a) - 0.25;
+        }
+        else {
+            px = 1 - Math.cos(a);
+            py = 0.25 - Math.sin(a);
+        }
+        out.push({
+            x: [px - 0.5 + gaussian(r) * noise, py + gaussian(r) * noise],
+            y: top ? 0 : 1,
+        });
+    }
+    return out;
+}
+/** Concentric rings: inner blob (class 0) inside an outer ring (class 1). */
+export function circles(n, opts = {}) {
+    const r = rng(opts.seed ?? 7);
+    const noise = opts.noise ?? 0.1;
+    const out = [];
+    for (let i = 0; i < n; i++) {
+        const inner = i % 2 === 0;
+        const rad = inner ? 0.35 : 0.9;
+        const a = r() * 2 * Math.PI;
+        out.push({
+            x: [Math.cos(a) * rad + gaussian(r) * noise, Math.sin(a) * rad + gaussian(r) * noise],
+            y: inner ? 0 : 1,
+        });
+    }
+    return out;
+}
+/** Four quadrant clusters; class 1 where the coordinate signs differ. */
+export function xor(n, opts = {}) {
+    const r = rng(opts.seed ?? 7);
+    const noise = opts.noise ?? 0.18;
+    const out = [];
+    for (let i = 0; i < n; i++) {
+        const sx = i & 1 ? 1 : -1;
+        const sy = i & 2 ? 1 : -1;
+        out.push({
+            x: [sx * 0.6 + gaussian(r) * noise, sy * 0.6 + gaussian(r) * noise],
+            y: sx === sy ? 0 : 1,
+        });
+    }
+    return out;
+}
+/** Two intertwined spirals — the hard one (may need more steps/capacity). */
+export function spirals(n, opts = {}) {
+    const r = rng(opts.seed ?? 7);
+    const noise = opts.noise ?? 0.06;
+    const out = [];
+    const per = Math.ceil(n / 2);
+    for (let c = 0; c < 2; c++) {
+        for (let i = 0; i < per; i++) {
+            const t = (i / per) * 3.2;
+            const a = t * Math.PI + c * Math.PI;
+            const rad = 0.15 + t * 0.26;
+            out.push({
+                x: [Math.cos(a) * rad + gaussian(r) * noise, Math.sin(a) * rad + gaussian(r) * noise],
+                y: c,
+            });
+        }
+    }
+    return out;
+}
+/** Build a 2D dataset by name. */
+export function points(kind, n, opts = {}) {
+    switch (kind) {
+        case "moons":
+            return moons(n, opts);
+        case "circles":
+            return circles(n, opts);
+        case "xor":
+            return xor(n, opts);
+        default:
+            return spirals(n, opts);
+    }
+}
+// Point-in-shape test in normalised coords.
+function inside(kind, p, x, y) {
+    const dx = x - p.cx;
+    const dy = y - p.cy;
+    if (kind === "circle")
+        return dx * dx + dy * dy <= p.r * p.r;
+    const cs = Math.cos(-p.rot);
+    const sn = Math.sin(-p.rot);
+    const rx = dx * cs - dy * sn;
+    const ry = dx * sn + dy * cs;
+    if (kind === "square") {
+        const s = p.r * 0.86;
+        return Math.abs(rx) <= s && Math.abs(ry) <= s;
+    }
+    // Equilateral triangle, circumradius r, vertices at 90°/210°/330°.
+    for (let k = 0; k < 3; k++) {
+        const a = (Math.PI / 2) * -1 + (k * 2 * Math.PI) / 3;
+        // Inward normal of the edge opposite vertex k points toward center;
+        // test the half-plane through the two other vertices.
+        const a1 = -Math.PI / 2 + (((k + 1) % 3) * 2 * Math.PI) / 3;
+        const a2 = -Math.PI / 2 + (((k + 2) % 3) * 2 * Math.PI) / 3;
+        const x1 = Math.cos(a1) * p.r;
+        const y1 = Math.sin(a1) * p.r;
+        const x2 = Math.cos(a2) * p.r;
+        const y2 = Math.sin(a2) * p.r;
+        const ex = x2 - x1;
+        const ey = y2 - y1;
+        // Cross product sign: center (0,0) must be on the same side as (rx,ry).
+        const side = ex * (ry - y1) - ey * (rx - x1);
+        const cside = ex * (0 - y1) - ey * (0 - x1);
+        if (Math.sign(side) !== Math.sign(cside) && side !== 0)
+            return false;
+        void a;
+    }
+    return true;
+}
+/** Rasterise a posed shape onto a `grid×grid` coverage buffer (0..1) via
+ *  3×3 supersampling. */
+export function rasterShape(kind, grid, pose) {
+    const out = new Float64Array(grid * grid);
+    const S = 3;
+    for (let gy = 0; gy < grid; gy++) {
+        for (let gx = 0; gx < grid; gx++) {
+            let hit = 0;
+            for (let sy = 0; sy < S; sy++) {
+                for (let sx = 0; sx < S; sx++) {
+                    const x = (gx + (sx + 0.5) / S) / grid;
+                    const y = (gy + (sy + 0.5) / S) / grid;
+                    if (inside(kind, pose, x, y))
+                        hit++;
+                }
+            }
+            out[gy * grid + gx] = hit / (S * S);
+        }
+    }
+    return out;
+}
+/** Random pose for a roughly-centred shape (small jitter, moderate size,
+ *  free rotation) — learnable from raw pixels and legible when drawn. */
+export function randomPose(r) {
+    return {
+        cx: 0.5 + (r() - 0.5) * 0.16,
+        cy: 0.5 + (r() - 0.5) * 0.16,
+        r: 0.26 + r() * 0.12,
+        rot: r() * Math.PI * 2,
+    };
+}
+/** One labelled pixel sample: `circle` → class 1, `square`/`triangle` → 0. */
+export function shapeSample(grid, r, noise = 0.04) {
+    const kind = r() < 0.5 ? "circle" : r() < 0.5 ? "square" : "triangle";
+    const buf = rasterShape(kind, grid, randomPose(r));
+    if (noise > 0)
+        for (let i = 0; i < buf.length; i++)
+            buf[i] = clamp01(buf[i] + gaussian(r) * noise);
+    return { x: buf, y: kind === "circle" ? 1 : 0 };
+}
+/** A batch of `n` fresh pixel samples. */
+export function shapeBatch(grid, n, r) {
+    const out = [];
+    for (let i = 0; i < n; i++)
+        out.push(shapeSample(grid, r));
+    return out;
+}
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}

package/dist/learn/index.d.ts

@@ -0,0 +1,3 @@
+export { circles, moons, type Points, type PointsKind, points, randomPose, rasterShape, type ShapeKind, type ShapePose, shapeBatch, shapeSample, spirals, xor, } from "./data.js";
+export { accuracyOf, classifyOf, inputGradient, type LayerParams, type LensLayer, type LensNet, type LensNetCfg, lensNet, logitsOf, meanLossOf, probsOf, trainEpoch, trainExample, } from "./lens-net.js";
+export { type Activation, gaussian, rng, type Sample } from "./mlp.js";

package/dist/learn/index.js

@@ -0,0 +1,6 @@
+// learn — a tiny, dependency-free MLP framed as a stack of parametric lenses,
+// plus reproducible datasets for the classification demos. Imported by the
+// site via "@bireactive/learn"; not part of the main barrel.
+export { circles, moons, points, randomPose, rasterShape, shapeBatch, shapeSample, spirals, xor, } from "./data.js";
+export { accuracyOf, classifyOf, inputGradient, lensNet, logitsOf, meanLossOf, probsOf, trainEpoch, trainExample, } from "./lens-net.js";
+export { gaussian, rng } from "./mlp.js";

package/dist/learn/lens-net.d.ts

@@ -0,0 +1,63 @@
+import { type Cell, type Writable } from "../core/index.js";
+import { type Activation, type Sample } from "./mlp.js";
+/** Dense-layer parameters: row-major `out×in` weights + `out` biases. */
+export interface LayerParams {
+    W: Float64Array;
+    b: Float64Array;
+}
+/** Training knobs read live by every layer's backward map. */
+export interface LensNetCfg {
+    /** SGD learning rate for the weight step. */
+    lr: number;
+    /** Freeze the weights: their backward update is `SKIP`ped and only the input
+     *  cotangent flows — the inversion ("dream") leg. */
+    frozen: boolean;
+}
+/** One dense layer as a lens: `out = act(W·in + b)`, `params` its weight source. */
+export interface LensLayer {
+    inDim: number;
+    outDim: number;
+    act: Activation;
+    params: Writable<Cell<LayerParams>>;
+    out: Writable<Cell<Float64Array>>;
+}
+/** A net wired as a lens DAG `input → layer → … → logits`. Train by writing the
+ *  output cotangent to `logits`; the engine backpropagates to the sources. */
+export interface LensNet {
+    input: Writable<Cell<Float64Array>>;
+    layers: LensLayer[];
+    logits: Writable<Cell<Float64Array>>;
+    cfg: LensNetCfg;
+    dims: readonly number[];
+}
+/** Build a net as a lens DAG. `dims` is `[in, h1, …, out]`; hidden layers use
+ *  `hidden` activation, the output is `linear` (the squash folds into the loss). */
+export declare function lensNet(dims: readonly number[], opts?: {
+    seed?: number;
+    hidden?: Activation;
+    lr?: number;
+}): LensNet;
+/** Logits for `x`, reading the current weight cells (no training, untracked).
+ *  Applies any pending backward write first, so it always sees fresh weights. */
+export declare function logitsOf(net: LensNet, x: ArrayLike<number>): Float64Array;
+/** Class probabilities: sigmoid for a 1-logit (binary) net, else softmax. */
+export declare function probsOf(net: LensNet, x: ArrayLike<number>): Float64Array;
+/** Argmax class for a multi-logit net, or `P ≥ 0.5` for a binary net. */
+export declare function classifyOf(net: LensNet, x: ArrayLike<number>): number;
+/** Fraction of `data` classified correctly. */
+export declare function accuracyOf(net: LensNet, data: readonly Sample[]): number;
+/** Mean cross-entropy over a dataset (no update) — for monitoring/tests. */
+export declare function meanLossOf(net: LensNet, data: readonly Sample[]): number;
+/** Train one example with a single backward write: pin the input, read the
+ *  prediction (the forward pull), then write the output cotangent to `logits`.
+ *  The engine backpropagates and lands an SGD step on every weight cell. The
+ *  step is forced before returning (while the input still holds this example),
+ *  so callers may move on immediately. Returns the loss before the step. */
+export declare function trainExample(net: LensNet, x: ArrayLike<number>, y: number): number;
+/** Train one shuffled pass — one backward write per example (online SGD).
+ *  Returns the mean loss over the epoch. */
+export declare function trainEpoch(net: LensNet, data: readonly Sample[], r: () => number): number;
+/** Input-space gradient toward raising logit `cls`, by one frozen-weight
+ *  backward write: with the weights held fixed the cotangent flows past them to
+ *  the input cell, which then holds dL/dInput. Drives the "dream" / saliency. */
+export declare function inputGradient(net: LensNet, x: ArrayLike<number>, cls?: number): Float64Array;

package/dist/learn/lens-net.js

@@ -0,0 +1,219 @@
+// lens-net.ts — the MLP of `mlp.ts`, but wired as an actual lens DAG so that
+// *training is a backward write*.
+//
+// Each dense layer is a multi-parent stateful lens over `[paramsCell, inputCell]`:
+//   fwd  computes the activation `act(W·x + b)`,
+//   bwd  receives the cotangent dL/da, deposits an SGD step on the weight cell,
+//        and passes dL/dx up to the previous layer.
+// Composing the layers composes their backward passes in reverse, so writing
+// the output cotangent to the `logits` cell makes the engine run reverse-mode
+// backprop down the whole chain and land an update on every weight source.
+// There is no optimizer object and no training loop inside the net: the
+// statement `logits.value = cotangent` *is* one gradient step.
+//
+// The very same lens, run with the weights frozen (`cfg.frozen`), inverts
+// instead of fits — the cotangent still flows to the input, so the input cell
+// receives dL/dx. That is the gradient the "dream" ascends to paint a class
+// prototype: inference-time inversion is just the backward leg with the
+// parameters held fixed.
+//
+// `mlp.ts` stays the flat, fast reference (and the offline ground truth); this
+// is the reactive realization the demos drive.
+import { cell, lens, SKIP } from "../core/index.js";
+import { actGrad, applyAct, gaussian, rng, softmax } from "./mlp.js";
+const toF64 = (x) => x instanceof Float64Array ? x : Float64Array.from(x);
+// Forward of one dense layer (the lens `fwd`).
+function denseForward(p, inDim, outDim, act, x) {
+    const y = new Float64Array(outDim);
+    for (let o = 0; o < outDim; o++) {
+        let z = p.b[o];
+        const base = o * inDim;
+        for (let i = 0; i < inDim; i++)
+            z += p.W[base + i] * x[i];
+        y[o] = applyAct(act, z);
+    }
+    return y;
+}
+// Backward of one dense layer (the lens `bwd` math): given dL/da, return the
+// input cotangent dL/dx and the parameter gradients gW/gb. Shared by the
+// engine-routed training step and the frozen inversion pass so they can't drift.
+function denseBackward(p, inDim, outDim, act, x, dOut) {
+    const dIn = new Float64Array(inDim);
+    const gW = new Float64Array(outDim * inDim);
+    const gb = new Float64Array(outDim);
+    for (let o = 0; o < outDim; o++) {
+        let z = p.b[o];
+        const base = o * inDim;
+        for (let i = 0; i < inDim; i++)
+            z += p.W[base + i] * x[i];
+        const dz = dOut[o] * actGrad(act, applyAct(act, z));
+        gb[o] = dz;
+        for (let i = 0; i < inDim; i++) {
+            gW[base + i] = dz * x[i];
+            dIn[i] = dIn[i] + p.W[base + i] * dz;
+        }
+    }
+    return { dIn, gW, gb };
+}
+// Build one dense layer-lens over its weight source and input cell. Forward is
+// the activation; backward steps the weights (unless frozen) and always returns
+// dL/dx for the input parent — for a hidden layer that propagates the gradient
+// up the chain; for the first layer it lands on the input cell (where the
+// inversion pass reads it).
+function denseLens(params, input, inDim, outDim, act, cfg) {
+    const parents = [params, input];
+    return lens(parents, {
+        init: () => null,
+        step: (_s, c) => c,
+        fwd: (s) => denseForward(s[0], inDim, outDim, act, s[1]),
+        bwd: (cot, s, c) => {
+            const { dIn, gW, gb } = denseBackward(s[0], inDim, outDim, act, s[1], cot);
+            let pUpd;
+            if (cfg.frozen) {
+                pUpd = SKIP;
+            }
+            else {
+                const W = new Float64Array(s[0].W);
+                const b = new Float64Array(s[0].b);
+                const lr = cfg.lr;
+                for (let k = 0; k < W.length; k++)
+                    W[k] = W[k] - lr * gW[k];
+                for (let o = 0; o < b.length; o++)
+                    b[o] = b[o] - lr * gb[o];
+                pUpd = { W, b };
+            }
+            return { updates: [pUpd, dIn], complement: c };
+        },
+    });
+}
+/** Build a net as a lens DAG. `dims` is `[in, h1, …, out]`; hidden layers use
+ *  `hidden` activation, the output is `linear` (the squash folds into the loss). */
+export function lensNet(dims, opts = {}) {
+    const hidden = opts.hidden ?? "tanh";
+    const r = rng(opts.seed ?? 1);
+    const cfg = { lr: opts.lr ?? 0.05, frozen: false };
+    const input = cell(new Float64Array(dims[0]));
+    const layers = [];
+    let x = input;
+    for (let i = 0; i + 1 < dims.length; i++) {
+        const inDim = dims[i];
+        const outDim = dims[i + 1];
+        const act = i + 2 < dims.length ? hidden : "linear";
+        const scale = act === "relu" ? Math.sqrt(2 / inDim) : Math.sqrt(1 / inDim);
+        const W = new Float64Array(outDim * inDim);
+        for (let k = 0; k < W.length; k++)
+            W[k] = gaussian(r) * scale;
+        const params = cell({ W, b: new Float64Array(outDim) });
+        const out = denseLens(params, x, inDim, outDim, act, cfg);
+        layers.push({ inDim, outDim, act, params, out });
+        x = out;
+    }
+    return { input, layers, logits: x, cfg, dims };
+}
+/** Logits for `x`, reading the current weight cells (no training, untracked).
+ *  Applies any pending backward write first, so it always sees fresh weights. */
+export function logitsOf(net, x) {
+    let a = toF64(x);
+    for (const L of net.layers)
+        a = denseForward(L.params.peek(), L.inDim, L.outDim, L.act, a);
+    return a;
+}
+/** Class probabilities: sigmoid for a 1-logit (binary) net, else softmax. */
+export function probsOf(net, x) {
+    const z = logitsOf(net, x);
+    return z.length === 1 ? Float64Array.of(1 / (1 + Math.exp(-z[0]))) : softmax(z);
+}
+/** Argmax class for a multi-logit net, or `P ≥ 0.5` for a binary net. */
+export function classifyOf(net, x) {
+    const p = probsOf(net, x);
+    if (p.length === 1)
+        return p[0] >= 0.5 ? 1 : 0;
+    let best = 0;
+    for (let i = 1; i < p.length; i++)
+        if (p[i] > p[best])
+            best = i;
+    return best;
+}
+/** Fraction of `data` classified correctly. */
+export function accuracyOf(net, data) {
+    let ok = 0;
+    for (const s of data)
+        if (classifyOf(net, s.x) === s.y)
+            ok++;
+    return ok / Math.max(1, data.length);
+}
+// Cross-entropy loss + the cotangent dL/dlogits (the seed of the backward
+// pass). Binary: BCE-with-logits, dz = σ(z) − y. Multi: softmax CE, dz = p − e_y.
+function lossCotangent(z, y) {
+    if (z.length === 1) {
+        const p = 1 / (1 + Math.exp(-z[0]));
+        const eps = 1e-12;
+        return {
+            loss: -(y * Math.log(p + eps) + (1 - y) * Math.log(1 - p + eps)),
+            cot: Float64Array.of(p - y),
+        };
+    }
+    const p = softmax(z);
+    const cot = new Float64Array(z.length);
+    for (let k = 0; k < z.length; k++)
+        cot[k] = p[k] - (k === y ? 1 : 0);
+    return { loss: -Math.log(p[y] + 1e-12), cot };
+}
+/** Mean cross-entropy over a dataset (no update) — for monitoring/tests. */
+export function meanLossOf(net, data) {
+    let total = 0;
+    for (const s of data)
+        total += lossCotangent(logitsOf(net, s.x), s.y).loss;
+    return total / Math.max(1, data.length);
+}
+/** Train one example with a single backward write: pin the input, read the
+ *  prediction (the forward pull), then write the output cotangent to `logits`.
+ *  The engine backpropagates and lands an SGD step on every weight cell. The
+ *  step is forced before returning (while the input still holds this example),
+ *  so callers may move on immediately. Returns the loss before the step. */
+export function trainExample(net, x, y) {
+    net.cfg.frozen = false;
+    net.input.value = toF64(x);
+    const { loss, cot } = lossCotangent(net.logits.value, y);
+    net.logits.value = cot;
+    void net.logits.peek(); // force the backward now, while input === this example
+    return loss;
+}
+// Fisher–Yates over [0, n) using the provided uniform source.
+function shuffled(n, r) {
+    const a = Array.from({ length: n }, (_, i) => i);
+    for (let i = n - 1; i > 0; i--) {
+        const j = Math.floor(r() * (i + 1));
+        const t = a[i];
+        a[i] = a[j];
+        a[j] = t;
+    }
+    return a;
+}
+/** Train one shuffled pass — one backward write per example (online SGD).
+ *  Returns the mean loss over the epoch. */
+export function trainEpoch(net, data, r) {
+    if (data.length === 0)
+        return 0;
+    let total = 0;
+    for (const idx of shuffled(data.length, r)) {
+        const s = data[idx];
+        total += trainExample(net, s.x, s.y);
+    }
+    return total / data.length;
+}
+/** Input-space gradient toward raising logit `cls`, by one frozen-weight
+ *  backward write: with the weights held fixed the cotangent flows past them to
+ *  the input cell, which then holds dL/dInput. Drives the "dream" / saliency. */
+export function inputGradient(net, x, cls = 0) {
+    net.cfg.frozen = true;
+    net.input.value = toF64(x);
+    const z = net.logits.value; // forward
+    const seed = new Float64Array(z.length);
+    seed[Math.min(cls, z.length - 1)] = 1;
+    net.logits.value = seed;
+    void net.logits.peek(); // force the backward; the gradient lands on `input`
+    const g = net.input.peek();
+    net.cfg.frozen = false;
+    return g;
+}

package/dist/learn/mlp.d.ts

@@ -0,0 +1,77 @@
+/** Hidden/output nonlinearity. The output layer is `linear`; its squashing
+ *  (sigmoid/softmax) is folded into the loss for numerically-stable grads. */
+export type Activation = "tanh" | "relu" | "sigmoid" | "linear";
+/** Deterministic PRNG (mulberry32) so init and data are reproducible. */
+export declare function rng(seed: number): () => number;
+/** Standard normal via Box–Muller, driven by a uniform source. */
+export declare function gaussian(r: () => number): number;
+interface Layer {
+    inDim: number;
+    outDim: number;
+    act: Activation;
+    W: Float64Array;
+    b: Float64Array;
+    gW: Float64Array;
+    gb: Float64Array;
+    mW: Float64Array;
+    vW: Float64Array;
+    mb: Float64Array;
+    vb: Float64Array;
+    inBuf: Float64Array;
+    preBuf: Float64Array;
+    outBuf: Float64Array;
+}
+/** A multilayer perceptron: a `pipe` of dense layers plus an Adam step clock. */
+export interface MLP {
+    layers: Layer[];
+    /** Adam timestep (for bias correction). */
+    t: number;
+    lr: number;
+    beta1: number;
+    beta2: number;
+    l2: number;
+}
+/** Build an MLP. `dims` is `[in, h1, …, out]`; hidden layers use `hidden`
+ *  activation, the output layer is `linear` (loss folds in the squashing). */
+export declare function mlp(dims: readonly number[], opts?: {
+    seed?: number;
+    hidden?: Activation;
+    lr?: number;
+    l2?: number;
+}): MLP;
+/** Pointwise activation `a = σ(z)`. */
+export declare function applyAct(act: Activation, z: number): number;
+/** Activation derivative `σ'`, given the *output* `a` (cheap for tanh/sigmoid). */
+export declare function actGrad(act: Activation, a: number): number;
+/** Forward pass: logits (pre-squash output) for one input vector. */
+export declare function forward(net: MLP, x: Float64Array | number[]): Float64Array;
+/** Softmax of a logit vector (numerically stabilised). */
+export declare function softmax(logits: Float64Array): Float64Array;
+/** Class probabilities: sigmoid for a 1-logit (binary) net, else softmax.
+ *  A binary net returns `[P(class 1)]`. */
+export declare function predict(net: MLP, x: Float64Array | number[]): Float64Array;
+/** Argmax class for a multi-logit net, or `prob ≥ 0.5` for a binary net. */
+export declare function classify(net: MLP, x: Float64Array | number[]): number;
+/** A labelled example: input vector + integer class. */
+export interface Sample {
+    x: Float64Array | number[];
+    y: number;
+}
+/** One full-batch gradient step over `batch`. Returns the mean loss before
+ *  the update. This is the dynamical step on the weights — call it from a
+ *  clock to train. */
+export declare function trainStep(net: MLP, batch: readonly Sample[]): number;
+/** Mean cross-entropy over a dataset (no update) — for monitoring/tests. */
+export declare function meanLoss(net: MLP, data: readonly Sample[]): number;
+/** Fraction of `data` classified correctly. */
+export declare function accuracy(net: MLP, data: readonly Sample[]): number;
+/** Flattened parameter buffers `[W0, b0, W1, b1, …]` (live views). */
+export declare function parameters(net: MLP): Float64Array[];
+/** Mean-loss gradients over `batch` with no update and no weight decay,
+ *  aligned with `parameters(net)`. For gradient checking / inspection. */
+export declare function gradients(net: MLP, batch: readonly Sample[]): Float64Array[];
+/** Input-space gradient of a chosen logit, by one backward pass with a unit
+ *  seed. Drives the "dream" view (ascend pixels toward a class) and saliency.
+ *  Leaves parameter-gradient accumulators dirty; not for use mid-train-step. */
+export declare function inputGradient(net: MLP, x: Float64Array | number[], cls?: number): Float64Array;
+export {};