@dniskav/neuron 0.2.0 → 0.2.2

package/README.md

@@ -19,7 +19,7 @@ A minimal, dependency-free neural network library built from scratch in TypeScri
 | `MultiHeadAttention` | N parallel attention heads concatenated and projected to `d_model`. |
 | `AttentionHead` | Single scaled dot-product self-attention head (Q / K / V projections + backprop). |
 | `LayerNorm` | Layer normalization with learnable γ / β per feature. |
-| `WeightMatrix` | 2D weight matrix with per-scalar Adam optimizers. |
+| `WeightMatrix` | 2D weight matrix with per-scalar Adam optimizers. Optional per-element gradient clipping via `update(dW, lr, clipValue)`. |
 | `EmbeddingMatrix` | Lookup-table embedding matrix with SGD updates. |
 | `sigmoid` `relu` `tanh` `linear` | Built-in activation functions. |
 | `SGD` `Momentum` `Adam` | Optimizers. Each instance tracks its own state per weight. |
@@ -258,6 +258,7 @@ const targets  = [...];   // 81*9 one-hot values
 const mask     = puzzle.map(v => v === 0);   // only train on empty cells
 
 const loss = net.train(puzzle, targets, 0.001, mask);
+// loss is cross-entropy (not MSE) — decreases from ~2.2 toward 0 as training progresses
 const logits = net.predict(puzzle);   // 729 logits (81 × 9)
 
 // Attention weights from all blocks for visualization
@@ -270,8 +271,10 @@ Each head in each block learns a different type of relationship (row, column,
 
 ## Possible improvements
 
-1. **Support for batches** in training to improve efficiency.
-2. **Improve documentation** with more advanced examples and use cases.
+1. **Support for batches** in training to improve efficiency and gradient stability.
+2. **Global gradient norm clipping** — `WeightMatrix.update` supports per-element clipping; a utility to clip across all matrices by total norm would be more principled.
+3. **Learning rate warmup** — standard practice for Transformers; ramp LR from 0 to target over the first N steps.
+4. **Pre-norm architecture** — LayerNorm before the residual add (instead of after) is more stable for deep stacks.
 
 ## License
 

package/dist/index.d.mts

@@ -173,7 +173,7 @@ declare class WeightMatrix {
     W: number[][];
     private opts;
     constructor(rows: number, cols: number);
-    update(dW: number[][], lr: number): void;
+    update(dW: number[][], lr: number, clipValue?: number): void;
 }
 declare class EmbeddingMatrix {
     W: number[][];
@@ -274,10 +274,36 @@ declare class NetworkTransformer {
     private _forward;
 }
 
+interface NetworkTransformerRLOptions {
+    d_model?: number;
+    nHeads?: number;
+    d_ff?: number;
+    nBlocks?: number;
+    nActions?: number;
+}
+declare class NetworkTransformerRL {
+    readonly seqLen: number;
+    readonly inputDim: number;
+    readonly d_model: number;
+    readonly nActions: number;
+    inputProj: WeightMatrix;
+    blocks: TransformerBlock[];
+    outputProj: WeightMatrix;
+    outputBias: number[];
+    private outBiasOpts;
+    private _projected;
+    constructor(seqLen: number, inputDim: number, options?: NetworkTransformerRLOptions);
+    predict(sequence: number[][]): number[];
+    train(sequence: number[][], target: number[], lr: number): number;
+    getAttentionWeights(): (number[][] | null)[][];
+    private _forward;
+    private _pool;
+}
+
 declare function mse(predicted: number[], actual: number[]): number;
 declare function crossEntropy(predicted: number[], actual: number[]): number;
 declare function mseDelta(predicted: number, actual: number): number;
 declare function crossEntropyDelta(predicted: number, actual: number): number;
 declare function crossEntropyDeltaRaw(predicted: number, actual: number): number;
 
-export { type Activation, Adam, AttentionHead, EmbeddingMatrix, LSTMLayer, Layer, LayerNorm, Momentum, MultiHeadAttention, Network, NetworkLSTM, type NetworkLSTMOptions, NetworkN, type NetworkNOptions, NetworkTransformer, type NetworkTransformerOptions, Neuron, NeuronN, type Optimizer, type OptimizerFactory, SGD, TransformerBlock, type TransformerBlockOptions, WeightMatrix, crossEntropy, crossEntropyDelta, crossEntropyDeltaRaw, elu, leakyRelu, linear, makeElu, makeLeakyRelu, matMul, mse, mseDelta, relu, sigmoid, softmax, softmaxBackward, tanh, transpose };
+export { type Activation, Adam, AttentionHead, EmbeddingMatrix, LSTMLayer, Layer, LayerNorm, Momentum, MultiHeadAttention, Network, NetworkLSTM, type NetworkLSTMOptions, NetworkN, type NetworkNOptions, NetworkTransformer, type NetworkTransformerOptions, NetworkTransformerRL, type NetworkTransformerRLOptions, Neuron, NeuronN, type Optimizer, type OptimizerFactory, SGD, TransformerBlock, type TransformerBlockOptions, WeightMatrix, crossEntropy, crossEntropyDelta, crossEntropyDeltaRaw, elu, leakyRelu, linear, makeElu, makeLeakyRelu, matMul, mse, mseDelta, relu, sigmoid, softmax, softmaxBackward, tanh, transpose };

package/dist/index.d.ts

@@ -173,7 +173,7 @@ declare class WeightMatrix {
     W: number[][];
     private opts;
     constructor(rows: number, cols: number);
-    update(dW: number[][], lr: number): void;
+    update(dW: number[][], lr: number, clipValue?: number): void;
 }
 declare class EmbeddingMatrix {
     W: number[][];
@@ -274,10 +274,36 @@ declare class NetworkTransformer {
     private _forward;
 }
 
+interface NetworkTransformerRLOptions {
+    d_model?: number;
+    nHeads?: number;
+    d_ff?: number;
+    nBlocks?: number;
+    nActions?: number;
+}
+declare class NetworkTransformerRL {
+    readonly seqLen: number;
+    readonly inputDim: number;
+    readonly d_model: number;
+    readonly nActions: number;
+    inputProj: WeightMatrix;
+    blocks: TransformerBlock[];
+    outputProj: WeightMatrix;
+    outputBias: number[];
+    private outBiasOpts;
+    private _projected;
+    constructor(seqLen: number, inputDim: number, options?: NetworkTransformerRLOptions);
+    predict(sequence: number[][]): number[];
+    train(sequence: number[][], target: number[], lr: number): number;
+    getAttentionWeights(): (number[][] | null)[][];
+    private _forward;
+    private _pool;
+}
+
 declare function mse(predicted: number[], actual: number[]): number;
 declare function crossEntropy(predicted: number[], actual: number[]): number;
 declare function mseDelta(predicted: number, actual: number): number;
 declare function crossEntropyDelta(predicted: number, actual: number): number;
 declare function crossEntropyDeltaRaw(predicted: number, actual: number): number;
 
-export { type Activation, Adam, AttentionHead, EmbeddingMatrix, LSTMLayer, Layer, LayerNorm, Momentum, MultiHeadAttention, Network, NetworkLSTM, type NetworkLSTMOptions, NetworkN, type NetworkNOptions, NetworkTransformer, type NetworkTransformerOptions, Neuron, NeuronN, type Optimizer, type OptimizerFactory, SGD, TransformerBlock, type TransformerBlockOptions, WeightMatrix, crossEntropy, crossEntropyDelta, crossEntropyDeltaRaw, elu, leakyRelu, linear, makeElu, makeLeakyRelu, matMul, mse, mseDelta, relu, sigmoid, softmax, softmaxBackward, tanh, transpose };
+export { type Activation, Adam, AttentionHead, EmbeddingMatrix, LSTMLayer, Layer, LayerNorm, Momentum, MultiHeadAttention, Network, NetworkLSTM, type NetworkLSTMOptions, NetworkN, type NetworkNOptions, NetworkTransformer, type NetworkTransformerOptions, NetworkTransformerRL, type NetworkTransformerRLOptions, Neuron, NeuronN, type Optimizer, type OptimizerFactory, SGD, TransformerBlock, type TransformerBlockOptions, WeightMatrix, crossEntropy, crossEntropyDelta, crossEntropyDeltaRaw, elu, leakyRelu, linear, makeElu, makeLeakyRelu, matMul, mse, mseDelta, relu, sigmoid, softmax, softmaxBackward, tanh, transpose };

package/dist/index.js

@@ -32,6 +32,7 @@ __export(index_exports, {
   NetworkLSTM: () => NetworkLSTM,
   NetworkN: () => NetworkN,
   NetworkTransformer: () => NetworkTransformer,
+  NetworkTransformerRL: () => NetworkTransformerRL,
   Neuron: () => Neuron,
   NeuronN: () => NeuronN,
   SGD: () => SGD,
@@ -579,10 +580,15 @@ var WeightMatrix = class {
     );
   }
   // Apply pre-computed gradient (same shape as W).
-  update(dW, lr) {
+  // clipValue: optional per-element gradient clipping before the Adam step.
+  // Prevents gradient explosion in deep networks (e.g. Transformers without
+  // global norm clipping). Pass e.g. 1.0 to clip to [-1, 1].
+  update(dW, lr, clipValue = Infinity) {
     for (let i = 0; i < this.W.length; i++)
-      for (let j = 0; j < this.W[0].length; j++)
-        this.W[i][j] = this.opts[i][j].step(this.W[i][j], dW[i][j], lr);
+      for (let j = 0; j < this.W[0].length; j++) {
+        const g = isFinite(clipValue) ? Math.max(-clipValue, Math.min(clipValue, dW[i][j])) : dW[i][j];
+        this.W[i][j] = this.opts[i][j].step(this.W[i][j], g, lr);
+      }
   }
 };
 var EmbeddingMatrix = class {
@@ -1036,14 +1042,14 @@ var NetworkTransformer = class {
     const dLogits = Array.from({ length: this.seqLen }, (_, i) => {
       if (mask && !mask[i]) return new Array(this.nClasses).fill(0);
       count++;
-      return Array.from({ length: this.nClasses }, (_2, c) => {
+      const probs = softmax(logits[i]);
+      for (let c = 0; c < this.nClasses; c++) {
         const t = targets[i * this.nClasses + c];
-        const p = logits[i][c];
-        loss += (p - t) ** 2;
-        return 2 * (p - t);
-      });
+        if (t > 0) loss -= Math.log(Math.max(probs[c], 1e-7));
+      }
+      return probs.map((p, c) => p - targets[i * this.nClasses + c]);
     });
-    if (count > 0) loss /= count * this.nClasses;
+    if (count > 0) loss /= count;
     const dH = Array.from(
       { length: this.seqLen },
       (_, i) => Array.from(
@@ -1093,6 +1099,124 @@ var NetworkTransformer = class {
   }
 };
 
+// src/NetworkTransformerRL.ts
+var NetworkTransformerRL = class {
+  constructor(seqLen, inputDim, options = {}) {
+    // Forward caches para backprop
+    this._projected = null;
+    const {
+      d_model = 32,
+      nHeads = 2,
+      d_ff = 64,
+      nBlocks = 2,
+      nActions = 2
+    } = options;
+    this.seqLen = seqLen;
+    this.inputDim = inputDim;
+    this.d_model = d_model;
+    this.nActions = nActions;
+    this.inputProj = new WeightMatrix(d_model, inputDim);
+    this.blocks = Array.from(
+      { length: nBlocks },
+      () => new TransformerBlock({ d_model, nHeads, d_ff })
+    );
+    this.outputProj = new WeightMatrix(nActions, d_model);
+    this.outputBias = new Array(nActions).fill(0);
+    this.outBiasOpts = Array.from({ length: nActions }, () => new Adam());
+  }
+  // ── Forward ────────────────────────────────────────────────────────────────
+  // sequence: seqLen × inputDim → nActions Q-values
+  predict(sequence) {
+    const h = this._forward(sequence);
+    const pooled = this._pool(h);
+    return this.outputProj.W.map(
+      (row, c) => row.reduce((s, w, m) => s + w * pooled[m], this.outputBias[c])
+    );
+  }
+  // ── Training ────────────────────────────────────────────────────────────────
+  // sequence: seqLen × inputDim
+  // target:   nActions Q-values (one-hot style para Q-learning)
+  // lr:       learning rate
+  // Returns: MSE loss
+  train(sequence, target, lr) {
+    const h = this._forward(sequence);
+    const pooled = this._pool(h);
+    const pred = this.outputProj.W.map(
+      (row, c) => row.reduce((s, w, m) => s + w * pooled[m], this.outputBias[c])
+    );
+    const n = this.nActions;
+    let loss = 0;
+    for (let c = 0; c < n; c++) {
+      const diff = pred[c] - target[c];
+      loss += diff * diff;
+    }
+    loss /= n;
+    const dPred = pred.map((p, c) => 2 * (p - target[c]) / n);
+    const dPooled = Array.from(
+      { length: this.d_model },
+      (_, m) => dPred.reduce((s, dp, c) => s + dp * this.outputProj.W[c][m], 0)
+    );
+    const dWout = Array.from(
+      { length: this.nActions },
+      (_, c) => Array.from(
+        { length: this.d_model },
+        (_2, m) => dPred[c] * pooled[m]
+      )
+    );
+    const dBout = dPred.slice();
+    this.outputProj.update(dWout, lr);
+    for (let c = 0; c < this.nActions; c++)
+      this.outputBias[c] = this.outBiasOpts[c].step(this.outputBias[c], dBout[c], lr);
+    let dH = Array.from(
+      { length: this.seqLen },
+      (_, i) => dPooled.map((v) => v / this.seqLen)
+      // Gradiente dividido entre posiciones
+    );
+    for (let b = this.blocks.length - 1; b >= 0; b--)
+      dH = this.blocks[b].backward(dH, lr);
+    for (let i = 0; i < this.seqLen; i++) {
+      const dInputProj = Array.from(
+        { length: this.d_model },
+        (_, k) => Array.from(
+          { length: this.inputDim },
+          (_2, m) => dH[i][k] * sequence[i][m]
+        )
+      );
+      this.inputProj.update(dInputProj, lr);
+    }
+    return loss;
+  }
+  // Attention weights from every block for visualization.
+  getAttentionWeights() {
+    return this.blocks.map((b) => b.getAttentionWeights());
+  }
+  // ── Internal ────────────────────────────────────────────────────────────────
+  _forward(sequence) {
+    let h = sequence.map(
+      (step) => this.inputProj.W.map(
+        (row, k) => row.reduce((s, w, m) => s + w * step[m], 0)
+      )
+    );
+    for (const block of this.blocks)
+      h = block.predict(h);
+    this._projected = h;
+    return h;
+  }
+  _pool(h) {
+    const weights = Array.from(
+      { length: this.seqLen },
+      (_, i) => i === this.seqLen - 1 ? 2 : 1
+    );
+    const totalWeight = weights.reduce((a, b) => a + b, 0);
+    return Array.from({ length: this.d_model }, (_, m) => {
+      let sum = 0;
+      for (let i = 0; i < this.seqLen; i++)
+        sum += weights[i] * h[i][m];
+      return sum / totalWeight;
+    });
+  }
+};
+
 // src/losses.ts
 function mse(predicted, actual) {
   return predicted.reduce((sum, p, i) => sum + (actual[i] - p) ** 2, 0) / predicted.length;
@@ -1129,6 +1253,7 @@ function crossEntropyDeltaRaw(predicted, actual) {
   NetworkLSTM,
   NetworkN,
   NetworkTransformer,
+  NetworkTransformerRL,
   Neuron,
   NeuronN,
   SGD,

package/dist/index.mjs

@@ -520,10 +520,15 @@ var WeightMatrix = class {
     );
   }
   // Apply pre-computed gradient (same shape as W).
-  update(dW, lr) {
+  // clipValue: optional per-element gradient clipping before the Adam step.
+  // Prevents gradient explosion in deep networks (e.g. Transformers without
+  // global norm clipping). Pass e.g. 1.0 to clip to [-1, 1].
+  update(dW, lr, clipValue = Infinity) {
     for (let i = 0; i < this.W.length; i++)
-      for (let j = 0; j < this.W[0].length; j++)
-        this.W[i][j] = this.opts[i][j].step(this.W[i][j], dW[i][j], lr);
+      for (let j = 0; j < this.W[0].length; j++) {
+        const g = isFinite(clipValue) ? Math.max(-clipValue, Math.min(clipValue, dW[i][j])) : dW[i][j];
+        this.W[i][j] = this.opts[i][j].step(this.W[i][j], g, lr);
+      }
   }
 };
 var EmbeddingMatrix = class {
@@ -977,14 +982,14 @@ var NetworkTransformer = class {
     const dLogits = Array.from({ length: this.seqLen }, (_, i) => {
       if (mask && !mask[i]) return new Array(this.nClasses).fill(0);
       count++;
-      return Array.from({ length: this.nClasses }, (_2, c) => {
+      const probs = softmax(logits[i]);
+      for (let c = 0; c < this.nClasses; c++) {
         const t = targets[i * this.nClasses + c];
-        const p = logits[i][c];
-        loss += (p - t) ** 2;
-        return 2 * (p - t);
-      });
+        if (t > 0) loss -= Math.log(Math.max(probs[c], 1e-7));
+      }
+      return probs.map((p, c) => p - targets[i * this.nClasses + c]);
     });
-    if (count > 0) loss /= count * this.nClasses;
+    if (count > 0) loss /= count;
     const dH = Array.from(
       { length: this.seqLen },
       (_, i) => Array.from(
@@ -1034,6 +1039,124 @@ var NetworkTransformer = class {
   }
 };
 
+// src/NetworkTransformerRL.ts
+var NetworkTransformerRL = class {
+  constructor(seqLen, inputDim, options = {}) {
+    // Forward caches para backprop
+    this._projected = null;
+    const {
+      d_model = 32,
+      nHeads = 2,
+      d_ff = 64,
+      nBlocks = 2,
+      nActions = 2
+    } = options;
+    this.seqLen = seqLen;
+    this.inputDim = inputDim;
+    this.d_model = d_model;
+    this.nActions = nActions;
+    this.inputProj = new WeightMatrix(d_model, inputDim);
+    this.blocks = Array.from(
+      { length: nBlocks },
+      () => new TransformerBlock({ d_model, nHeads, d_ff })
+    );
+    this.outputProj = new WeightMatrix(nActions, d_model);
+    this.outputBias = new Array(nActions).fill(0);
+    this.outBiasOpts = Array.from({ length: nActions }, () => new Adam());
+  }
+  // ── Forward ────────────────────────────────────────────────────────────────
+  // sequence: seqLen × inputDim → nActions Q-values
+  predict(sequence) {
+    const h = this._forward(sequence);
+    const pooled = this._pool(h);
+    return this.outputProj.W.map(
+      (row, c) => row.reduce((s, w, m) => s + w * pooled[m], this.outputBias[c])
+    );
+  }
+  // ── Training ────────────────────────────────────────────────────────────────
+  // sequence: seqLen × inputDim
+  // target:   nActions Q-values (one-hot style para Q-learning)
+  // lr:       learning rate
+  // Returns: MSE loss
+  train(sequence, target, lr) {
+    const h = this._forward(sequence);
+    const pooled = this._pool(h);
+    const pred = this.outputProj.W.map(
+      (row, c) => row.reduce((s, w, m) => s + w * pooled[m], this.outputBias[c])
+    );
+    const n = this.nActions;
+    let loss = 0;
+    for (let c = 0; c < n; c++) {
+      const diff = pred[c] - target[c];
+      loss += diff * diff;
+    }
+    loss /= n;
+    const dPred = pred.map((p, c) => 2 * (p - target[c]) / n);
+    const dPooled = Array.from(
+      { length: this.d_model },
+      (_, m) => dPred.reduce((s, dp, c) => s + dp * this.outputProj.W[c][m], 0)
+    );
+    const dWout = Array.from(
+      { length: this.nActions },
+      (_, c) => Array.from(
+        { length: this.d_model },
+        (_2, m) => dPred[c] * pooled[m]
+      )
+    );
+    const dBout = dPred.slice();
+    this.outputProj.update(dWout, lr);
+    for (let c = 0; c < this.nActions; c++)
+      this.outputBias[c] = this.outBiasOpts[c].step(this.outputBias[c], dBout[c], lr);
+    let dH = Array.from(
+      { length: this.seqLen },
+      (_, i) => dPooled.map((v) => v / this.seqLen)
+      // Gradiente dividido entre posiciones
+    );
+    for (let b = this.blocks.length - 1; b >= 0; b--)
+      dH = this.blocks[b].backward(dH, lr);
+    for (let i = 0; i < this.seqLen; i++) {
+      const dInputProj = Array.from(
+        { length: this.d_model },
+        (_, k) => Array.from(
+          { length: this.inputDim },
+          (_2, m) => dH[i][k] * sequence[i][m]
+        )
+      );
+      this.inputProj.update(dInputProj, lr);
+    }
+    return loss;
+  }
+  // Attention weights from every block for visualization.
+  getAttentionWeights() {
+    return this.blocks.map((b) => b.getAttentionWeights());
+  }
+  // ── Internal ────────────────────────────────────────────────────────────────
+  _forward(sequence) {
+    let h = sequence.map(
+      (step) => this.inputProj.W.map(
+        (row, k) => row.reduce((s, w, m) => s + w * step[m], 0)
+      )
+    );
+    for (const block of this.blocks)
+      h = block.predict(h);
+    this._projected = h;
+    return h;
+  }
+  _pool(h) {
+    const weights = Array.from(
+      { length: this.seqLen },
+      (_, i) => i === this.seqLen - 1 ? 2 : 1
+    );
+    const totalWeight = weights.reduce((a, b) => a + b, 0);
+    return Array.from({ length: this.d_model }, (_, m) => {
+      let sum = 0;
+      for (let i = 0; i < this.seqLen; i++)
+        sum += weights[i] * h[i][m];
+      return sum / totalWeight;
+    });
+  }
+};
+
 // src/losses.ts
 function mse(predicted, actual) {
   return predicted.reduce((sum, p, i) => sum + (actual[i] - p) ** 2, 0) / predicted.length;
@@ -1069,6 +1192,7 @@ export {
   NetworkLSTM,
   NetworkN,
   NetworkTransformer,
+  NetworkTransformerRL,
   Neuron,
   NeuronN,
   SGD,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dniskav/neuron",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Minimal neural network from scratch — neuron, layer, network, backpropagation. No dependencies.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",