@dniskav/neuron 0.2.2 → 0.2.5

package/README.md

@@ -15,6 +15,7 @@ A minimal, dependency-free neural network library built from scratch in TypeScri
 | `LSTMLayer` | Recurrent layer with persistent hidden and cell state. Learns sequences via BPTT. |
 | `NetworkLSTM` | Wraps an `LSTMLayer` + dense layers. Maintains memory across steps within an episode. |
 | `NetworkTransformer` | Full token-classification Transformer: embeddings → N blocks → per-token logits. |
+| `NetworkTransformerRL` | Transformer for RL agents: continuous input projection → causal attention → Q-values. Remembers the last N steps. |
 | `TransformerBlock` | One Transformer block: multi-head attention + FFN + LayerNorm × 2 with residuals. |
 | `MultiHeadAttention` | N parallel attention heads concatenated and projected to `d_model`. |
 | `AttentionHead` | Single scaled dot-product self-attention head (Q / K / V projections + backprop). |
@@ -269,6 +270,43 @@ const weights = net.getAttentionWeights();
 Each head in each block learns a different type of relationship (row, column,
 3×3 box). The network figures this out by itself through training.
 
+### NetworkTransformerRL — Transformer for reinforcement learning
+
+`NetworkTransformerRL` uses causal self-attention over a sliding window of past states to output Q-values. Unlike `NetworkLSTM`, the agent attends to specific past moments rather than compressing them into a single hidden vector.
+
+```ts
+import { NetworkTransformerRL } from "@dniskav/neuron";
+
+// Agent sees the last 8 steps, each step is a 7-value sensor vector → 4 actions
+const net = new NetworkTransformerRL(8, 7, {
+  d_model:  32,
+  nHeads:   2,
+  d_ff:     64,
+  nBlocks:  2,
+  nActions: 4,
+});
+
+// Each step: feed the last N states as a sequence
+const sequence = getLastNStates();      // number[][] — shape: [8, 7]
+const qValues  = net.predict(sequence); // number[4]
+
+// Q-learning update: train toward Bellman target
+const action  = argmax(qValues);
+const reward  = env.step(action);
+const targets = qValues.slice();
+targets[action] = reward + 0.99 * Math.max(...net.predict(nextSequence));
+
+const loss = net.train(sequence, targets, 0.001);
+```
+
+The last step in the sequence gets 2× pooling weight — the most recent state contributes more to the decision.
+
+```ts
+// Inspect what the agent is attending to
+const attnWeights = net.getAttentionWeights();
+// attnWeights[blockIdx][headIdx] → seqLen × seqLen matrix
+```
+
 ## Possible improvements
 
 1. **Support for batches** in training to improve efficiency and gradient stability.

package/dist/index.d.mts

@@ -34,6 +34,13 @@ declare class Momentum implements Optimizer {
     constructor(beta?: number);
     step(weight: number, gradient: number, lr: number): number;
 }
+declare class ClipOptimizer implements Optimizer {
+    readonly inner: Optimizer;
+    readonly clipValue: number;
+    constructor(inner: Optimizer, clipValue: number);
+    step(weight: number, gradient: number, lr: number): number;
+}
+declare function ClippedOptimizerFactory(innerFactory: OptimizerFactory, clipValue: number): OptimizerFactory;
 declare class Adam implements Optimizer {
     readonly beta1: number;
     readonly beta2: number;
@@ -68,22 +75,31 @@ declare class Network {
     constructor(nInputs: number, nHidden: number, nOutputs: number);
     predict(inputs: number[]): number;
     train(inputs: number[], target: number, lr: number): number;
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
 }
 
 interface NetworkNOptions {
     activations?: Activation[];
     optimizer?: OptimizerFactory;
+    residual?: boolean | ((layerIndex: number) => boolean);
+    dropoutRate?: number;
 }
 declare class NetworkN {
     readonly structure: number[];
     layers: Layer[];
+    private _dropouts;
+    private _residual;
     constructor(structure: number[], options?: NetworkNOptions);
-    predict(inputs: number[]): number[];
+    predict(inputs: number[], training?: boolean): number[];
     train(inputs: number[], targets: number[], lr: number): number;
     trainWithDeltas(inputs: number[], outputDeltas: number[], lr: number): void;
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
+    private _shouldResidual;
 }
 
-declare class Gate {
+declare class Gate$1 {
     W: number[][];
     b: number[];
     constructor(inputSize: number, hSize: number, initBias?: number);
@@ -94,12 +110,13 @@ declare class LSTMLayer {
     readonly hSize: number;
     h: number[];
     c: number[];
-    forgetGate: Gate;
-    inputGate: Gate;
-    cellGate: Gate;
-    outputGate: Gate;
+    forgetGate: Gate$1;
+    inputGate: Gate$1;
+    cellGate: Gate$1;
+    outputGate: Gate$1;
+    private _optimizers;
     private _traj;
-    constructor(inputSize: number, hiddenSize: number);
+    constructor(inputSize: number, hiddenSize: number, optimizerFactory?: OptimizerFactory);
     reset(): void;
     predict(inputs: number[]): number[];
     backprop(dh_seq: number[][], lr: number): void;
@@ -122,6 +139,8 @@ declare class LSTMLayer {
         };
     };
     setWeights(data: ReturnType<LSTMLayer["getWeights"]>): void;
+    getWeightsFlat(): number[];
+    setWeightsFlat(weights: number[]): void;
 }
 
 interface NetworkLSTMOptions {
@@ -163,6 +182,8 @@ declare class NetworkLSTM {
         }[][];
     };
     setWeights(data: ReturnType<NetworkLSTM["getWeights"]>): void;
+    getWeightsFlat(): number[];
+    setWeightsFlat(weights: number[]): void;
 }
 
 declare function matMul(A: number[][], B: number[][]): number[][];
@@ -174,38 +195,48 @@ declare class WeightMatrix {
     private opts;
     constructor(rows: number, cols: number);
     update(dW: number[][], lr: number, clipValue?: number): void;
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
 }
 declare class EmbeddingMatrix {
     W: number[][];
     constructor(vocabSize: number, d_model: number);
     get(idx: number): number[];
     update(idx: number, grad: number[], lr: number): void;
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
 }
 
 declare class AttentionHead {
     readonly d_k: number;
     readonly d_v: number;
+    readonly causal: boolean;
     Wq: WeightMatrix;
     Wk: WeightMatrix;
     Wv: WeightMatrix;
     private cache;
-    constructor(d_model: number, d_k: number, d_v: number);
+    constructor(d_model: number, d_k: number, d_v: number, causal?: boolean);
     predict(X: number[][]): number[][];
     backward(dOut: number[][], lr: number): number[][];
     getAttentionWeights(): number[][] | null;
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
 }
 
 declare class MultiHeadAttention {
     readonly nHeads: number;
     readonly d_model: number;
     readonly d_k: number;
+    readonly causal: boolean;
     heads: AttentionHead[];
     Wo: WeightMatrix;
     private _concat;
-    constructor(d_model: number, nHeads: number);
+    constructor(d_model: number, nHeads: number, causal?: boolean);
     predict(X: number[][]): number[][];
     backward(dOut: number[][], lr: number): number[][];
     getAttentionWeights(): (number[][] | null)[];
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
 }
 
 declare class LayerNorm {
@@ -217,12 +248,15 @@ declare class LayerNorm {
     resetCache(seqLen: number): void;
     predictOne(x: number[], pos: number): number[];
     backwardOne(dOut: number[], pos: number, lr: number): number[];
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
 }
 
 interface TransformerBlockOptions {
     d_model: number;
     nHeads: number;
     d_ff: number;
+    causal?: boolean;
 }
 declare class TransformerBlock {
     readonly d_model: number;
@@ -242,10 +276,12 @@ declare class TransformerBlock {
     private _ff1Pre;
     private _ff1Out;
     private _ff2Out;
-    constructor({ d_model, nHeads, d_ff }: TransformerBlockOptions);
+    constructor({ d_model, nHeads, d_ff, causal }: TransformerBlockOptions);
     predict(X: number[][]): number[][];
     backward(dOut: number[][], lr: number): number[][];
     getAttentionWeights(): (number[][] | null)[];
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
 }
 
 interface NetworkTransformerOptions {
@@ -271,6 +307,8 @@ declare class NetworkTransformer {
     predict(tokens: number[]): number[];
     train(tokens: number[], targets: number[], lr: number, mask?: boolean[]): number;
     getAttentionWeights(): (number[][] | null)[][];
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
     private _forward;
 }
 
@@ -280,6 +318,7 @@ interface NetworkTransformerRLOptions {
     d_ff?: number;
     nBlocks?: number;
     nActions?: number;
+    pooling?: 'avg' | 'max' | 'last' | 'weighted';
 }
 declare class NetworkTransformerRL {
     readonly seqLen: number;
@@ -292,12 +331,53 @@ declare class NetworkTransformerRL {
     outputBias: number[];
     private outBiasOpts;
     private _projected;
+    private _pooling;
+    private _argmax;
     constructor(seqLen: number, inputDim: number, options?: NetworkTransformerRLOptions);
     predict(sequence: number[][]): number[];
     train(sequence: number[][], target: number[], lr: number): number;
     getAttentionWeights(): (number[][] | null)[][];
+    getWeightsFlat(): number[];
+    setWeightsFlat(weights: number[]): void;
+    getWeightsStructured(): {
+        inputProj: number[][];
+        blocks: {
+            attn: {
+                heads: {
+                    Wq: number[][];
+                    Wk: number[][];
+                    Wv: number[][];
+                }[];
+                Wo: number[][];
+            };
+            norm1: {
+                gamma: number[];
+                beta: number[];
+            };
+            norm2: {
+                gamma: number[];
+                beta: number[];
+            };
+            ff1: number[][];
+            ff2: number[][];
+            b1: number[];
+            b2: number[];
+        }[];
+        outputProj: number[][];
+        outputBias: number[];
+    };
+    setWeightsStructured(data: ReturnType<NetworkTransformerRL['getWeightsStructured']>): void;
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
     private _forward;
     private _pool;
+    private _poolAvg;
+    private _poolMax;
+    private _poolLast;
+    private _poolWeighted;
+    /** Returns the current pooling type for inspection. */
+    getPoolingType(): string;
+    private _distributePoolGradient;
 }
 
 declare function mse(predicted: number[], actual: number[]): number;
@@ -306,4 +386,204 @@ 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, 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 };
+declare class Dropout {
+    readonly rate: number;
+    private _mask;
+    constructor(rate: number);
+    forward(x: number[], training?: boolean): number[];
+    backward(dOut: number[]): number[];
+    resetMask(): void;
+    getWeights(): number[];
+    setWeights(_weights: number[]): void;
+}
+
+declare class Gate {
+    W: number[][];
+    b: number[];
+    constructor(inputSize: number, hSize: number, initBias?: number);
+    linear(combined: number[]): number[];
+}
+declare class GRULayer {
+    readonly inputSize: number;
+    readonly hSize: number;
+    h: number[];
+    resetGate: Gate;
+    updateGate: Gate;
+    newGate: Gate;
+    private _optimizers;
+    private _traj;
+    constructor(inputSize: number, hiddenSize: number, optimizerFactory?: OptimizerFactory);
+    reset(): void;
+    predict(inputs: number[]): number[];
+    backprop(dh_seq: number[][], lr: number): void;
+    getWeightsFlat(): number[];
+    setWeightsFlat(weights: number[]): void;
+    getWeights(): {
+        resetGate: {
+            W: number[][];
+            b: number[];
+        };
+        updateGate: {
+            W: number[][];
+            b: number[];
+        };
+        newGate: {
+            W: number[][];
+            b: number[];
+        };
+    };
+    setWeights(data: ReturnType<GRULayer["getWeights"]>): void;
+}
+
+declare class BatchNorm {
+    readonly dim: number;
+    readonly momentum: number;
+    gamma: number[];
+    beta: number[];
+    runningMean: number[];
+    runningVar: number[];
+    private _xNorm;
+    private _std;
+    constructor(dim: number, momentum?: number);
+    forward(x: number[]): number[];
+    backward(dOut: number[]): number[];
+    trainParams(dOut: number[], lr: number): void;
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
+}
+
+declare class Conv1D {
+    readonly inputLength: number;
+    readonly kernelSize: number;
+    readonly filters: number;
+    readonly stride: number;
+    readonly padding: 'valid' | 'same';
+    readonly inputChannels: number;
+    kernels: number[][][];
+    biases: number[];
+    private _kOpts;
+    private _bOpts;
+    private _input;
+    private _paddedInput;
+    constructor(inputLength: number, kernelSize: number, filters: number, stride?: number, padding?: 'valid' | 'same', optimizerFactory?: OptimizerFactory, inputChannels?: number);
+    forward(input: number[] | number[][]): number[][];
+    backward(dOut: number[][], lr?: number): number[][];
+    getOutputLength(): number;
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
+    private _normalizeInput;
+}
+
+interface DataPair {
+    inputs: number[][];
+    targets: number[][];
+}
+declare class DataLoader {
+    readonly data: DataPair;
+    readonly batchSize: number;
+    private _indices;
+    private _trainIndices;
+    private _valIndices;
+    private _pos;
+    private _validationSplit;
+    constructor(data: DataPair, batchSize?: number, validationSplit?: number);
+    shuffle(): void;
+    hasNext(): boolean;
+    next(): DataPair;
+    reset(): void;
+    get length(): number;
+    getValidationData(): DataPair;
+    get validationLength(): number;
+    static sequences(data: number[][], seqLen: number, validationSplit?: number): DataLoader;
+}
+
+interface TrainMetrics {
+    accuracy: number;
+    precision: number;
+    recall: number;
+    f1: number;
+}
+interface TrainerOptions {
+    epochs?: number;
+    lr?: number;
+    lrDecay?: number;
+    verbose?: boolean;
+    weightDecay?: number;
+    earlyStopping?: {
+        patience: number;
+        minDelta: number;
+    };
+    computeMetrics?: boolean;
+    clipValue?: number;
+}
+interface TrainDataset {
+    inputs: number[][];
+    targets: number[][];
+}
+interface TrainableNetwork {
+    train(inputs: number[], targets: number[], lr: number): number;
+}
+/** Extended interface for networks that support weight access and prediction.
+ *  Required for weightDecay, earlyStopping, and computeMetrics features. */
+interface TrainableNetworkWithWeights extends TrainableNetwork {
+    predict(inputs: number[]): number[];
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
+}
+declare class Trainer {
+    readonly network: TrainableNetwork;
+    readonly epochs: number;
+    readonly lrInitial: number;
+    readonly lrDecay: number;
+    readonly verbose: boolean;
+    readonly weightDecay: number;
+    readonly clipValue: number;
+    private _history;
+    private _validationData?;
+    private _earlyStopping?;
+    private _bestLoss;
+    private _patienceCounter;
+    private _stopReason;
+    private _computeMetrics;
+    private _metrics;
+    constructor(network: TrainableNetwork, options?: TrainerOptions);
+    setValidationData(dataset: DataPair): void;
+    getBestLoss(): number;
+    getStopReason(): string;
+    getMetrics(): TrainMetrics[];
+    train(dataset: TrainDataset): number[];
+    getHistory(): number[];
+    /** Type guard: does this network support getWeights/setWeights/predict? */
+    private _hasWeights;
+    /** Mean squared error on a dataset (used for validation loss). */
+    private _computeLoss;
+    /** Heuristic: are targets classification-style (one-hot or single-class)? */
+    private _isClassification;
+    /** Compute classification metrics from predictions vs targets. */
+    private _computeMetricsArray;
+}
+
+declare class LRScheduler {
+    stepDecay(lr: number, epoch: number, dropRate: number, epochsDrop: number): number;
+    exponentialDecay(lr: number, epoch: number, decayRate: number): number;
+    plateauDecay(lr: number, currentLoss: number, history: number[], patience: number, factor: number): number;
+    cosineAnnealing(lr: number, epoch: number, maxEpochs: number, minLr?: number): number;
+}
+
+interface Serializable {
+    getWeights(): number[];
+    setWeights(weights: number[]): void;
+}
+declare class ModelSaver {
+    static toJSON(model: Serializable): string;
+    static fromJSON(model: Serializable, json: string): void;
+    static saveToFile(model: Serializable, path: string, writeFn: (path: string, data: string) => void): void;
+    static loadFromFile(model: Serializable, path: string, readFn: (path: string) => string): void;
+}
+
+declare function validateArray(arr: unknown, expectedLength: number, methodName: string): asserts arr is number[];
+declare function validateArrayMinLength(arr: unknown, minLength: number, methodName: string): asserts arr is number[];
+declare function validate2DArray(arr: unknown, expectedRows: number, expectedCols: number, methodName: string): asserts arr is number[][];
+declare function validateNumber(value: unknown, methodName: string): asserts value is number;
+
+export { type Activation, Adam, AttentionHead, BatchNorm, ClipOptimizer, ClippedOptimizerFactory, Conv1D, DataLoader, type DataPair, Dropout, EmbeddingMatrix, GRULayer, LRScheduler, LSTMLayer, Layer, LayerNorm, ModelSaver, Momentum, MultiHeadAttention, Network, NetworkLSTM, type NetworkLSTMOptions, NetworkN, type NetworkNOptions, NetworkTransformer, type NetworkTransformerOptions, NetworkTransformerRL, type NetworkTransformerRLOptions, Neuron, NeuronN, type Optimizer, type OptimizerFactory, SGD, type Serializable, type TrainDataset, type TrainMetrics, type TrainableNetwork, type TrainableNetworkWithWeights, Trainer, type TrainerOptions, TransformerBlock, type TransformerBlockOptions, WeightMatrix, crossEntropy, crossEntropyDelta, crossEntropyDeltaRaw, elu, leakyRelu, linear, makeElu, makeLeakyRelu, matMul, mse, mseDelta, relu, sigmoid, softmax, softmaxBackward, tanh, transpose, validate2DArray, validateArray, validateArrayMinLength, validateNumber };