### Install Dependencies and Build Rust Addon

Source: https://github.com/akhyar11/oxide-js/blob/main/README.md

Use these commands to install project dependencies and compile the native Rust addon.

```bash
npm install
```

```bash
npm run build:rust
```

--------------------------------

### Install Oxide-JS Packages

Source: https://github.com/akhyar11/oxide-js/blob/main/README.md

Install the core, layers, and models packages for Oxide-JS using npm.

```bash
npm install @oxide-js/core @oxide-js/layers @oxide-js/models
```

--------------------------------

### SGD Optimizer Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/optimizer.md

Demonstrates the basic usage of the Stochastic Gradient Descent (SGD) optimizer. Ensure weights have a gradient property before applying.

```typescript
import { SGD, mj } from "@oxide-js/core";

const weights = mj.matrix([[1.0, 2.0]]);
weights.grad = mj.matrix([[0.1, -0.2]]);

const opt = new SGD();
opt.apply(weights, 0.01);
weights.print(); // [[0.99, 2.002]]
```

--------------------------------

### AdaGrad Optimizer Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/optimizer.md

Provides an example of using the AdaGrad optimizer, which adapts learning rates globally per feature. Initialization requires the shape and an optional epsilon value.

```typescript
import { AdaGrad, mj } from "@oxide-js/core";

const shape: [number, number] = [1, 2];
const weights = mj.matrix([[1.0, 2.0]], shape);
weights.grad = mj.matrix([[0.1, 0.1]], shape);

const opt = new AdaGrad(shape, 1e-8);
opt.apply(weights, 0.01);
```

--------------------------------

### Adam Optimizer Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/optimizer.md

Illustrates the initialization and application of the Adam optimizer. Requires specifying the shape of the weights matrix and optionally beta1, beta2, and epsilon values.

```typescript
import { Adam, mj } from "@oxide-js/core";

const shape: [number, number] = [2, 2];
const weights = mj.zeros(shape);
weights.grad = mj.ones(shape);

const opt = new Adam(shape, 0.9, 0.999, 1e-8);
opt.apply(weights, 0.001);
```

--------------------------------

### Dataset Splitting, Batching, and Metric Calculation in TypeScript

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/models/metrics.md

Use this example to understand how to prepare data for model training and evaluation. It includes setting up raw data, splitting it into training and validation sets, creating mini-batches, and computing accuracy, MAE, and MSE.

```typescript
import { Matrix } from "@oxide-js/core";
import { trainValidationSplit, createBatches } from "@oxide-js/models/data";
import { accuracy, mae, mse } from "@oxide-js/models";

// 1. Setup raw input dataset [6 samples, 2 classes]
const inputs = Matrix.fromFlat(new Float32Array([
  0.1, 0.9,  // argmax index = 1
  0.8, 0.2,  // argmax index = 0
  0.3, 0.7,  // argmax index = 1
  0.9, 0.1,  // argmax index = 0
  0.2, 0.8,  // argmax index = 1
  0.7, 0.3   // argmax index = 0
]), [6, 2]);

const targets = Matrix.fromFlat(new Float32Array([
  0, 1,      // index 1
  1, 0,      // index 0
  1, 0,      // index 0 (prediction mismatch!)
  1, 0,      // index 0
  0, 1,      // index 1
  0, 1       // index 1 (prediction mismatch!)
]), [6, 2]);

// 2. Perform train/validation split (33% validation -> 4 train, 2 val)
console.log("Splitting dataset...");
const { xTrain, yTrain, xVal, yVal } = trainValidationSplit(inputs, targets, 0.33, false);
console.log(`xTrain shape: [${xTrain._shape}], xVal shape: [${xVal._shape}]`);

// 3. Partition training data into mini-batches (size=2)
const batches = createBatches(xTrain, yTrain, 2, false);
console.log(`Created ${batches.length} training batches.`);

// 4. Calculate metrics directly on the entire dataset
const acc = accuracy(inputs, targets);
const maeVal = mae(inputs, targets);
const mseVal = mse(inputs, targets);

console.log("\nComputed Dataset Metrics:");
console.log(`- Multi-Class Accuracy : ${(acc * 100).toFixed(2)}% (Expected: 4/6 correct = 66.67%)
`);
console.log(`- Mean Absolute Error  : ${maeVal.toFixed(4)}`);
console.log(`- Mean Squared Error   : ${mseVal.toFixed(4)}`);

```

--------------------------------

### Self-Attention Block Example with MultiHeadAttention

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/attention.md

An example demonstrating a complete self-attention pass using the MultiHeadAttention layer. It shows instantiation with specific dimensions and a forward pass with sample input matrices.

```typescript
import { MultiHeadAttention } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate MultiHeadAttention (heads=2, keyDim=4, inputDim=8)
const mha = new MultiHeadAttention({
  name: "self_attention",
  numHeads: 2,
  keyDim: 4,
  valueDim: 4,
  sequenceLength: 3,
  inputDim: 8
});

// 2. Feed sequence inputs [batch * seqLen, inputDim] -> [2 * 3, 8] = [6, 8]
const inputs = Matrix.fromFlat(new Float32Array(6 * 8).map((_, i) => i * 0.05), [6, 8]);

const outputs = mha.forward(inputs);
console.log("MHA Output Shape (batch * seqLen, outputDim):", outputs._shape); // [6, 8]
outputs.print();
```

--------------------------------

### Momentum Optimizer Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/optimizer.md

Shows how to use the Momentum optimizer, which accelerates SGD by tracking velocity. The constructor requires the shape of the weights and an optional momentum value.

```typescript
import { Momentum, mj } from "@oxide-js/core";

const shape: [number, number] = [1, 2];
const weights = mj.matrix([[1.0, 2.0]], shape);
weights.grad = mj.matrix([[0.1, 0.1]], shape);

const opt = new Momentum(shape, 0.9);
opt.apply(weights, 0.01);
```

--------------------------------

### Build Oxide-JS Project

Source: https://github.com/akhyar11/oxide-js/blob/main/README.md

Install dependencies, build Rust kernels, and compile TypeScript packages for the Oxide-JS monorepo.

```bash
# Install dependencies for all packages
npm install

# Build the native Rust kernels for @oxide-js/core
npm run build:rust

# Build all TypeScript packages (core, layers, models)
npm run build
```

--------------------------------

### Usage Example: Custom CSV Logging & EarlyStopping

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/models/callbacks.md

Demonstrates how to create a custom CSV logging callback and integrate it with the built-in EarlyStopping callback during model training.

```APIDOC
## Usage Example (Custom Logging & EarlyStopping)

This example demonstrates how to build and register a custom CSV logging callback alongside the built-in `EarlyStopping` callback to safely train a model.

```ts
import { Sequential, EarlyStopping, ProgressLogger } from "@oxide-js/models";
import { Dense } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";
import type { Callback, CallbackLogs } from "@oxide-js/models";

// 1. Create a Custom CSV Training File Logger Callback
class CSVModelLogger implements Callback {
  private logRows: string[] = [];

  onTrainBegin(): void {
    console.log("[CSV Logger] Initializing log registry...");
    this.logRows.push("epoch,loss,val_loss");
  }

  onEpochEnd(epoch: number, logs?: CallbackLogs): void {
    const loss = logs?.loss !== undefined ? logs.loss.toFixed(6) : "";
    const valLoss = logs?.val_loss !== undefined ? logs.val_loss.toFixed(6) : "";
    
    const row = `${epoch},${loss},${valLoss}`;
    this.logRows.push(row);
    console.log(`[CSV Logger] Recorded: ${row}`);
  }

  onTrainEnd(): void {
    console.log("\n[CSV Logger] Training completed. Generated CSV Log file content:");
    console.log(this.logRows.join("\n"));
  }
}

// 2. Build the Model
const model = new Sequential();
model.add(new Dense({ units: 2, outputUnits: 1 }));

model.compile({
  optimizer: "sgd",
  loss: "mse",
  learningRate: 0.1
});

// Prepare mock inputs [batch=4, features=2] -> Targets [batch=4, output=1]
const inputs = Matrix.fromFlat(new Float32Array([1.0, 1.0, 2.0, 2.0, 3.0, 3.0, 4.0, 4.0]), [4, 2]);
const targets = Matrix.fromFlat(new Float32Array([2.0, 4.0, 6.0, 8.0]), [4, 1]);

// 3. Register Callbacks inside the fitting pipeline
model.fit(inputs, targets, {
  epochs: 100,
  batchSize: 2,
  verbose: 0, // disable default logs to show custom logger outputs
  validationData: [inputs, targets], // pass validation data to trigger val_loss metrics
  callbacks: [
    new CSVModelLogger(),
    new EarlyStopping({
      monitor: "val_loss",
      patience: 2,
      minDelta: 0.0001
    })
  ]
});
```
```

--------------------------------

### Start Tape Recording - Tape.watch()

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/autodiff.md

Initiates operation recording on the tape. Clears any previous history. Ensure this is called before operations you want to track.

```typescript
import { Tape } from "@oxide-js/core";
const tape = new Tape();
tape.watch();
```

--------------------------------

### AveragePooling1D Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/convolution.md

Shows how to use AveragePooling1D to calculate the average of elements within a specified window size. Ensure inputLength and inputDim match the input data.

```typescript
import { AveragePooling1D } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate Average Pooling 1D
const avgPool1d = new AveragePooling1D({
  name: "avgpool_1d",
  poolSize: 2,
  strides: 2,
  inputLength: 4,
  inputDim: 1
});

const inputs = Matrix.fromFlat(new Float32Array([
  1, 3, 5, 7
]), [4, 1]);

const outputs = avgPool1d.forward(inputs);
outputs.print(); // Displays averages: [[2], [6]]
```

--------------------------------

### NAG Optimizer Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/optimizer.md

Demonstrates the Nesterov Accelerated Gradient (NAG) optimizer. Similar to Momentum, it requires the shape and an optional momentum value for initialization.

```typescript
import { NAG, mj } from "@oxide-js/core";

const shape: [number, number] = [1, 2];
const weights = mj.matrix([[1.0, 2.0]], shape);
weights.grad = mj.matrix([[0.1, 0.1]], shape);

const opt = new NAG(shape, 0.9);
opt.apply(weights, 0.01);
```

--------------------------------

### Decoder Cross-Attention Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/attention.md

Demonstrates how to set up and use the Attention layer for cross-attention. This involves instantiating the layer, preparing query and key-value matrices, registering the external database, and performing a forward pass.

```typescript
import { Attention } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate standard Attention layer
const crossAttention = new Attention({
  name: "cross_attention",
  units: 6,
  sequenceLength: 2, // Query sequence length
  inputDim: 6
});

// 2. Set up Query [batch * seqLenQ, inputDim] -> [2 * 2, 6] = [4, 6]
const query = Matrix.fromFlat(new Float32Array(4 * 6).fill(0.8), [4, 6]);

// 3. Set up External Keys/Values database [batch * seqLenK, inputDim] -> [2 * 3, 6] = [6, 6]
const keyValDatabase = Matrix.fromFlat(new Float32Array(6 * 6).fill(0.2), [6, 6]);

// 4. Register external database on the attention layer
crossAttention.setExternal({
  key: keyValDatabase,
  trainableKey: false
});

// 5. Run forward pass (Query attends to the External database)
const outputs = crossAttention.forward(query);
console.log("Cross Attention Output Shape (batch * seqLenQ, units):", outputs._shape); // [4, 6]
outputs.print();
```

--------------------------------

### Complete E2E Classification Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/README.md

This script prepares synthetic data, composes a neural network, compiles it, trains it with callbacks, and evaluates the results. It includes data preparation, model architecture definition, compilation settings, fitting with callbacks like EarlyStopping and ProgressLogger, prediction, and model summary.

```typescript
import { mj, Matrix } from "@oxide-js/core";
import { Dense, Dropout } from "@oxide-js/layers";
import { Sequential, EarlyStopping, ProgressLogger } from "@oxide-js/models";

// 1. Prepare Synthetic Data (Binary Classification)
const inputs = Matrix.fromFlat(
  new Float32Array([
    0.1, 0.2,
    0.8, 0.9,
    0.2, 0.1,
    0.9, 0.8
  ]),
  [4, 2] // 4 samples, 2 features
);

const targets = Matrix.fromFlat(
  new Float32Array([
    0.0, 1.0,
    1.0, 0.0,
    0.0, 1.0,
    1.0, 0.0
  ]),
  [4, 2] // 4 samples, 2 classes (one-hot)
);

// 2. Compose the Neural Network Architecture
const model = new Sequential();
model.add(new Dense({ name: "dense_in", units: 2, outputUnits: 4, activation: "relu" }));
model.add(new Dropout({ name: "drop", rate: 0.1 }));
model.add(new Dense({ name: "dense_out", units: 4, outputUnits: 2, activation: "softmax" }));

// 3. Compile Model Settings
model.compile({
  optimizer: "adam",
  loss: "softmaxCrossEntropy",
  alpha: 0.01,
  metrics: ["accuracy"]
});

// 4. Fit the Model with Callbacks
console.log("Starting model training...");
model.fit(inputs, targets, {
  epochs: 100,
  batchSize: 2,
  shuffle: true,
  callbacks: [
    new ProgressLogger(),
    new EarlyStopping({ patience: 10, monitor: "loss" })
  ]
});

// 5. Predict and Evaluate Results
console.log("\nEvaluating model parameters...");
const prediction = model.predict(inputs);
console.log("Inputs Shape:", inputs._shape);
console.log("Prediction Output:");
prediction.print();

// 6. View Keras-Style Model Summary
console.log("\nModel Architecture Summary:");
model.summary();

```

--------------------------------

### MaxPooling1D Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/convolution.md

Demonstrates the usage of MaxPooling1D for finding the maximum value within a sliding window. The input shape should be [batch * seqLen, inputDim].

```typescript
import { MaxPooling1D } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate Max Pooling 1D
const maxPool1d = new MaxPooling1D({
  name: "maxpool_1d",
  poolSize: 2,
  strides: 2,
  inputLength: 6,
  inputDim: 2
});

// 2. Feed inputs [batch * seqLen, inputDim] -> [6, 2]
const inputs = Matrix.fromFlat(new Float32Array([
  1, 10,  2, 20,
  3, 30,  4, 40,
  5, 50,  6, 60
]), [6, 2]);

const outputs = maxPool1d.forward(inputs);
console.log("MaxPooling1D output shape:", outputs._shape); // [3, 2]
outputs.print();
```

--------------------------------

### Example Usage of Cost Type

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/types.md

Demonstrates how to import and assign a specific cost type to a variable. Ensure the imported type matches one of the defined string literals.

```typescript
import { Cost } from "@oxide-js/core";
const costType: Cost = "softmaxCrossEntropy";
```

--------------------------------

### Example Usage of StatusLayer Type

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/types.md

Shows how to import and assign a StatusLayer tag to a variable. Use these tags to denote the role of a layer within a network architecture.

```typescript
import { StatusLayer } from "@oxide-js/core";
const layerState: StatusLayer = "train";
```

--------------------------------

### Train a BPE Tokenizer in TypeScript

Source: https://github.com/akhyar11/oxide-js/blob/main/README.md

Initialize and train a Byte Pair Encoding (BPE) tokenizer with specified vocabulary size and minimum frequency. Includes encoding, padding, and decoding examples.

```typescript
import { BPETokenizer } from "@oxide-js/core";

const tokenizer = new BPETokenizer({ vocabSize: 120, minFrequency: 2 });
tokenizer.train(["hello world", "hello there"]);
const ids = tokenizer.encodeWithSpecial("hello world");
const padded = tokenizer.padSequence(ids, 12);
console.log(ids, padded, tokenizer.decode(ids));
```

--------------------------------

### GRU for Recurrent Gated Modeling

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/recurrent.md

This example shows how to use the GRU layer for recurrent gated modeling. Setting `returnSequences: true` provides outputs for each time step. Ensure the input matrix dimensions match the layer's configuration.

```typescript
import { GRU } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate GRU
const gru = new GRU({
  name: "gru_layer",
  units: 6,
  returnSequences: true,
  sequenceLength: 3,
  inputDim: 5
});

// 2. Feed inputs [batch=2 * seq=3, inputDim=5] -> [6, 5]
const inputs = Matrix.fromFlat(new Float32Array(6 * 5).fill(0.2), [6, 5]);

const outputs = gru.forward(inputs);
console.log("GRU output shape:", outputs._shape); // [6, 6]
outputs.print();
```

--------------------------------

### Initialization Methods

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/math.md

Methods for creating and initializing matrices.

```APIDOC
## Initialization Methods

### `matrix(array: number[][]): Matrix`
Alias constructor. Creates a matrix from a 2D array.

### `zeros(shape: [number, number]): Matrix`
Generates a new zero-initialized matrix of the given shape.

### `ones(shape: [number, number]): Matrix`
Generates a new matrix filled with ones.

### Example (matrix)
`const m = mj.matrix([[1, 2], [3, 4]])`

### Example (zeros)
`mj.zeros([2, 3]).print(); // 2 rows, 3 columns of zeros`

### Example (ones)
`mj.ones([1, 4]).print(); // [[1, 1, 1, 1]]`
```

--------------------------------

### LSTM Example: Sentence Encoding

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/recurrent.md

Example demonstrating how to configure an LSTM layer to process sequential token representations and return the final sentence summary encoding vector.

```APIDOC
### Example (LSTM - Sentence Encoding)
This example shows how to configure an LSTM layer to process sequential token representations and return the final sentence summary encoding vector.

```ts
import { LSTM } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate LSTM layer (sequenceLength = 3, inputDim = 4, hiddenUnits = 8)
const lstm = new LSTM({
  name: "sentence_encoder",
  units: 8,
  returnSequences: false, // returns only the final hidden state vector
  sequenceLength: 3,
  inputDim: 4
});

// 2. Feed sequence inputs [batch * sequenceLength, inputDim] -> [2 * 3, 4] = [6, 4]
const inputs = Matrix.fromFlat(new Float32Array(6 * 4).fill(0.5), [6, 4]);

const outputs = lstm.forward(inputs);
console.log("Outputs Shape (batch, units):", outputs._shape); // [2, 8]
outputs.print();
```
```

--------------------------------

### Instantiate and Use Dense Layer

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/core.md

Demonstrates how to instantiate a Dense layer with specific units and activation, and then use it to process input data. Ensure Matrix and Dense are imported.

```typescript
import { Dense } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate dense layer with ReLU activation
const denseLayer = new Dense({
  name: "dense_1",
  units: 4,
  activation: "relu",
  useBias: true
});

// 2. Feed inputs matrix [batch=2, features=3]
const inputs = Matrix.fromFlat(new Float32Array([
  0.5, -1.0,  2.0,
  1.0,  0.0, -0.5
]), [2, 3]);

const outputs = denseLayer.forward(inputs);
outputs.print(); // Displays shape [2, 4] with ReLU applied
```

--------------------------------

### Run All Tests

Source: https://github.com/akhyar11/oxide-js/blob/main/README.md

Execute the full test and benchmark suite for Oxide.js using this command.

```bash
npm test
```

--------------------------------

### Build Rust Native Extension

Source: https://github.com/akhyar11/oxide-js/blob/main/README.md

Run this command to build the Rust native extension for Oxide.js. This is often required when the `.node` binary does not match your current platform.

```bash
npm run build:rust
```

--------------------------------

### MultiHeadAttention Usage Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/attention.md

Demonstrates a complete self-attention pass over sequence embeddings using the MultiHeadAttention layer.

```APIDOC
## Example (Self-Attention Block)

This example demonstrates a complete self-attention pass over sequence embeddings.

```ts
import { MultiHeadAttention } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate MultiHeadAttention (heads=2, keyDim=4, inputDim=8)
const mha = new MultiHeadAttention({
  name: "self_attention",
  numHeads: 2,
  keyDim: 4,
  valueDim: 4,
  sequenceLength: 3,
  inputDim: 8
});

// 2. Feed sequence inputs [batch * seqLen, inputDim] -> [2 * 3, 8] = [6, 8]
const inputs = Matrix.fromFlat(new Float32Array(6 * 8).map((_, i) => i * 0.05), [6, 8]);

const outputs = mha.forward(inputs);
console.log("MHA Output Shape (batch * seqLen, outputDim):", outputs._shape); // [6, 8]
outputs.print();
```
```

--------------------------------

### Softmax Activation Function Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/activation.md

Computes normal probability distributions over columns or batches. Requires importing the `mj` object from `@oxide-js/core`.

```typescript
import { mj } from "@oxide-js/core";
const inputs = mj.matrix([[1.0, 2.0, 3.0]]);
const out = mj.softmax(inputs);
out.print(); // Prints normalized probabilities sum = 1.0
```

--------------------------------

### Instantiate and Use Activation Layer

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/core.md

Shows how to create an Activation layer with a specified activation function (e.g., sigmoid) and apply it to input data. Requires importing Activation and Matrix.

```typescript
import { Activation } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate activation layer
const sigmoidLayer = new Activation({ activation: "sigmoid" });

// 2. Feed inputs matrix [batch=1, features=3]
const inputs = Matrix.fromFlat(new Float32Array([-1.0, 0.0, 1.0]), [1, 3]);
const outputs = sigmoidLayer.forward(inputs);

outputs.print(); // Output elements mapped between (0, 1)
```

--------------------------------

### Encode Text with Special Tokens

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/tokenizer.md

Encodes input text and appends sequence indicator tokens, such as start (<s>) and end (</s>) tokens.

```typescript
const ids = tokenizer.encodeWithSpecial("hello"); // [1, 12, 45, 2]
```

--------------------------------

### compile(config: CompileConfig): void

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/models/base.md

Prepares the model for training by configuring the optimizer, loss function, learning rate, and metrics.

```APIDOC
## compile(config: CompileConfig): void

### Description
Prepares the model for training by resolving loss functions, optimizers, and monitoring metrics.

### Parameters
#### Request Body
- **config** (CompileConfig) - Required - Configuration object for compilation.
  - **optimizer** (string | Optimizer) - Required - The optimization algorithm to use (e.g., "adam", "sgd").
  - **loss** (string | LossFunction) - Required - The loss function to minimize (e.g., "softmaxCrossEntropy", "mse").
  - **learningRate** (number) - Optional - The learning rate for the optimizer.
  - **metrics** (string[]) - Optional - An array of metrics to monitor during training (e.g., ["accuracy", "mae"]).

### Request Example
```ts
model.compile({
  optimizer: "adam",
  loss: "softmaxCrossEntropy",
  learningRate: 0.001,
  metrics: ["accuracy", "mae"]
});
```
```

--------------------------------

### Matrix Element Access using get()

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/matrix.md

Retrieves the value of a matrix element at specified row and column indices. This operation is O(1).

```typescript
const m = new Matrix({ array: [[10, 20], [30, 40]] });
console.log(m.get(0, 1)); // 20
console.log(m.get(1, 0)); // 30
```

--------------------------------

### Initialize and Use Embedding Layer

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/embedding.md

Demonstrates initializing an Embedding layer, feeding token sequences, and performing a forward pass. It also shows how to wrap the forward pass in an autograd tape for gradient computation and verification.

```ts
import { Embedding } from "@oxide-js/layers";
import { Matrix, engine } from "@oxide-js/core";

// 1. Instantiate the Embedding layer (vocabSize = 10, embedDim = 4)
const embedLayer = new Embedding({
  name: "token_embeddings",
  inputDim: 10,
  outputDim: 4,
  embeddingsInitializer: "random"
});

// 2. Feed sequence inputs [batch=2, seqLen=3] containing token indices
// Batch 1: [2, 0, 5]
// Batch 2: [1, 9, 2]
const tokenInputs = Matrix.fromFlat(new Float32Array([
  2, 0, 5,
  1, 9, 2
]), [2, 3]);

// 3. Compute forward pass (builds the embedding weight matrix internally)
const outputs = embedLayer.forward(tokenInputs);
console.log("Output Shape (flat batch * seqLen, embedDim):", outputs._shape); // [6, 4]

// 4. Wrap inside autograd tape to trace gradient propagation
const tape = engine.grad(() => {
  const lookups = embedLayer.forward(tokenInputs);
  return lookups; // standard representation
});

// Assume upstream gradient is ones of shape [6, 4]
const upstreamGrad = Matrix.fromFlat(new Float32Array(6 * 4).fill(1.0), [6, 4]);
tape.backward(tape.result, upstreamGrad);

// Verify computed weight gradients for the embedding matrix
console.log("\nEmbedding Table Weights Gradient:");
embedLayer.embeddings?.grad?.print(); // Accumulates derivatives for indices [0, 1, 2, 5, 9]
```

--------------------------------

### Softplus Activation Function Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/activation.md

Applies the Softplus function, a smooth approximation of the ReLU function. Requires importing the `mj` object from `@oxide-js/core`.

```typescript
import { mj } from "@oxide-js/core";
const inputs = mj.matrix([[0.0]]);
j.softplus(inputs).print(); // [[0.693147]]
```

--------------------------------

### Mish Activation Function Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/activation.md

Applies the Mish activation function, a smooth self-gated function. Requires importing the `mj` object from `@oxide-js/core`.

```typescript
import { mj } from "@oxide-js/core";
const inputs = mj.matrix([[1.0]]);
j.mish(inputs).print();
```

--------------------------------

### Instantiate and Use Flatten Layer

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/core.md

Demonstrates how to instantiate the Flatten layer and use it to reshape input matrices. Ensure inputs are compatible with the expected shape for flattening.

```typescript
import { Flatten } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate flattening layer
const flattenLayer = new Flatten({ name: "flat" });

// 2. Assume inputs came from a layer with shape [batch=2, seq=3, features=2]
// Total features per sample = 3 * 2 = 6
const inputs = Matrix.fromFlat(new Float32Array([
  1.0, 2.0,  3.0, 4.0,  5.0, 6.0,   // sample 1
  7.0, 8.0,  9.0, 0.0,  1.0, 2.0    // sample 2
]), [2, 6]);

// Set logical inputs dimensions representation
inputs._shape = [2, 6]; 

const outputs = flattenLayer.forward(inputs);
console.log("Flattened shape:", outputs._shape); // [2, 6]
outputs.print();
```

--------------------------------

### Instantiate and Use Conv2D Layer

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/convolution.md

Demonstrates how to instantiate a Conv2D layer with specified parameters and feed input data to it. Ensure input dimensions and image shape are correctly configured.

```typescript
import { Conv2D } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate Conv2D layer
const convLayer = new Conv2D({
  name: "conv2d_1",
  filters: 8,
  kernelSize: 3,
  strides: 1,
  padding: "same",
  activation: "relu",
  imageShape: [8, 8], // 8x8 input image
  inputDim: 3         // RGB channels
});

// 2. Feed inputs [batch * height * width, channels] -> [1 * 64, 3]
const inputs = Matrix.fromFlat(new Float32Array(64 * 3).fill(0.5), [64, 3]);
const outputs = convLayer.forward(inputs);

console.log("Outputs Shape (batch * H_out * W_out, filters):", outputs._shape); // [64, 8]
```

--------------------------------

### Linear Activation Function Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/activation.md

Applies the linear activation function, which returns the input values unchanged. Requires importing the `mj` object from `@oxide-js/core`.

```typescript
import { mj } from "@oxide-js/core";
const inputs = mj.matrix([[5.0]]);
const out = mj.linear(inputs);
out.print(); // [[5.0]]
```

--------------------------------

### BPETokenizer Initialization

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/tokenizer.md

Creates a new BPE Tokenizer instance with optional configuration for vocabulary size, minimum frequency, and pre-tokenization.

```APIDOC
## `new BPETokenizer(options?: BPETokenizerOptions)`

Creates a new BPE Tokenizer instance.

- **`BPETokenizerOptions`**:
  - `vocabSize?: number` - The maximum vocabulary limit. Default is standard `1000`.
  - `minFrequency?: number` - Minimum occurrences of a character pair required to trigger subword merges. Default is `2`.
  - `preTokenizer?: BuiltInPreTokenizer | PreTokenizer` - Pre-tokenization behavior. Can be a string identifier or a custom callback function: `(text: string) => string[]`.

### Request Example (Standard Init)
```ts
import { BPETokenizer } from "@oxide-js/core";
const tokenizer = new BPETokenizer({ vocabSize: 5000, preTokenizer: "whitespace" });
```

### Request Example (Custom Callback Init)
```ts
import { BPETokenizer } from "@oxide-js/core";

// Custom pre-tokenizer that splits text by dash boundaries
const myCustomPre = (text: string) => text.split("-");
const tokenizer = new BPETokenizer({ vocabSize: 1000, preTokenizer: myCustomPre });
```
```

--------------------------------

### Initialize BPETokenizer with Standard Options

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/tokenizer.md

Create a new BPETokenizer instance with a specified vocabulary size and a built-in 'whitespace' pre-tokenizer.

```typescript
import { BPETokenizer } from "@oxide-js/core";
const tokenizer = new BPETokenizer({ vocabSize: 5000, preTokenizer: "whitespace" });
```

--------------------------------

### BPETokenizer Basic Usage and Training

Source: https://context7.com/akhyar11/oxide-js/llms.txt

Demonstrates basic initialization, training, encoding, decoding, and incremental updates of the BPETokenizer. Ensure the vocabulary size and minimum frequency are set appropriately for your corpus.

```typescript
import {
  BPETokenizer,
  charPreTokenizer,
  whitespacePreTokenizer,
  unicodeGraphemePreTokenizer,
  unicodeWordPreTokenizer,
  scriptAwarePreTokenizer
} from "@oxide-js/core";

// --- Basic usage ---
const tokenizer = new BPETokenizer({ vocabSize: 5000, minFrequency: 2 });
tokenizer.train(["hello world", "hello there", "welcome to oxide-js"]);

const ids = tokenizer.encode("hello world");          // without special tokens
const idsSpecial = tokenizer.encodeWithSpecial("hello world"); // with <s>, </s>
const padded = tokenizer.padSequence(ids, 10);         // [id, id, 0, 0, 0, 0, 0, 0]
const text = tokenizer.decode(ids);                    // "hello world"
console.log({ ids, idsSpecial, padded, text });

// Incremental update (adds new merges without resetting existing vocab)
tokenizer.update(["deep learning", "neural networks"]);
```

--------------------------------

### SELU Activation Function Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/activation.md

Applies the Scaled Exponential Linear Unit function, designed for self-normalizing networks. Requires importing the `mj` object from `@oxide-js/core`.

```typescript
import { mj } from "@oxide-js/core";
const inputs = mj.matrix([[-1.0, 1.0]]);
j.selu(inputs).print();
```

--------------------------------

### Sigmoid Activation Function Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/activation.md

Applies the sigmoid function, mapping inputs to a logistic range between 0 and 1. Requires importing the `mj` object from `@oxide-js/core`.

```typescript
import { mj } from "@oxide-js/core";
const inputs = mj.matrix([[0.0]]);
const out = mj.sigmoid(inputs);
out.print(); // [[0.5]]
```

--------------------------------

### Instantiate and Use BatchNormalization

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/layers/normalization.md

Instantiate BatchNormalization with epsilon and momentum. Demonstrates both training and evaluation passes, showing column-wise normalization and the use of moving statistics during evaluation.

```typescript
import { BatchNormalization } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Instantiate batch normalization layer
const bnLayer = new BatchNormalization({
  epsilon: 1e-5,
  momentum: 0.9
});

// 2. Feed inputs [batch=3, features=2]
const inputs = Matrix.fromFlat(new Float32Array([
  1.0, 10.0,
  2.0, 20.0,
  3.0, 30.0
]), [3, 2]);

// 3. Train pass (normalizes column-wise and updates moving stats)
bnLayer.train();
const trainOut = bnLayer.forward(inputs);
console.log("Training Outputs (normalized per column):");
trainOut.print();

// 4. Eval pass (uses moving statistics)
bnLayer.eval();
const evalOut = bnLayer.forward(inputs);
console.log("Evaluation Outputs (uses moving stats):");
evalOut.print();
```

--------------------------------

### Troubleshooting: Native Backend Not Available

Source: https://github.com/akhyar11/oxide-js/blob/main/README.md

If you encounter the 'Native backend not available' error, try rebuilding the Rust extension or ensuring the `.node` binary is compatible with your system.

```text
| Problem | Solution |
|---| --- |
| `Native backend not available` | Run `npm run build:rust`, or verify that the `.node` binary matches your current platform. |
```

--------------------------------

### Global Engine Singleton Core Instance Methods

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/autodiff.md

High-level functions for managing tapes and performing gradient calculations globally.

```APIDOC
## Global Engine Singleton Core Instance Methods

### `grad<T>(fn: () => T): Tape & { result: T }`

Starts a tape, runs the forward function `fn()`, stops the tape, and returns the tape container coupled with the function's returned value (`result`).

- **Best Use**: Custom training steps.

#### Example
```typescript
import { engine, mj } from "@oxide-js/core";

const x = mj.matrix([[2.0]]);
x.requiresGrad = true;

const tape = engine.grad(() => {
  // Operations inside this closure will be recorded
  return mj.add(mj.mul(x, x), 10); // x^2 + 10
});

tape.backward(tape.result);
console.log("x gradient:", x.grad?.get(0, 0)); // 4.0 (2 * x)
```

### `noGrad<T>(fn: () => T): T`

Global wrapper to execute code without recording gradients on any active tape.

#### Example
```typescript
import { engine } from "@oxide-js/core";

const outputs = engine.noGrad(() => {
  return model.forward(inputs);
});
```
```

--------------------------------

### Build, Compile, Train, Evaluate, and Predict with Sequential Model

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/models/sequential.md

Demonstrates the complete lifecycle of a classification network using the Sequential model. Includes adding layers, compiling settings, preparing data, fitting the model, evaluating performance, and making predictions. Ensure necessary imports are included.

```typescript
import { Sequential } from "@oxide-js/models";
import { Dense, Dropout } from "@oxide-js/layers";
import { Matrix } from "@oxide-js/core";

// 1. Compose the Sequential model stack
const model = new Sequential();
model.add(new Dense({ name: "dense_input", units: 4, outputUnits: 8, activation: "relu" }));
model.add(new Dropout({ name: "dropout_regularizer", rate: 0.1 }));
model.add(new Dense({ name: "dense_output", units: 8, outputUnits: 2, activation: "softmax" }));

// 2. Compile settings
model.compile({
  optimizer: "adam",
  loss: "softmaxCrossEntropy",
  learningRate: 0.05,
  metrics: ["accuracy"]
});

// 3. Prepare synthetic classification inputs
// 4 samples, 4 features
const trainInputs = Matrix.fromFlat(new Float32Array([
  0.1, 0.2, 0.7, 0.9,
  0.9, 0.8, 0.1, 0.2,
  0.2, 0.1, 0.8, 0.8,
  0.8, 0.9, 0.2, 0.1
]), [4, 4]);

// 4 samples, 2 classes (one-hot vectors)
const trainTargets = Matrix.fromFlat(new Float32Array([
  0.0, 1.0,
  1.0, 0.0,
  0.0, 1.0,
  1.0, 0.0
]), [4, 2]);

// 4. Fit the model stack
console.log("Fitting Sequential Stack...");
model.fit(trainInputs, trainTargets, {
  epochs: 10,
  batchSize: 2,
  verbose: 1
});

// 5. Evaluate the model stack
console.log("\nEvaluating Sequential Stack...");
const evalResult = model.evaluate(trainInputs, trainTargets);
console.log(`Evaluation loss: ${evalResult.loss?.toFixed(6)}`);
console.log("Accuracy metric:", evalResult.metrics.accuracy);

// 6. Predict results
console.log("\nPredicting values...");
const outputs = model.predict(trainInputs);
console.log("Predictions shape:", outputs._shape);
outputs.print();

// 7. Output architecture diagnostics summary
console.log("\nSequential Diagnostics Summary:");
model.summary();
```

--------------------------------

### Swish Activation Function Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/activation.md

Applies the Swish activation function, a self-gated function. An optional `beta` parameter can be provided. Requires importing the `mj` object from `@oxide-js/core`.

```typescript
import { mj } from "@oxide-js/core";
const inputs = mj.matrix([[2.0]]);
j.swish(inputs).print();
```

--------------------------------

### Tape Class Core Instance Methods

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/autodiff.md

Methods for controlling and interacting with the automatic differentiation tape.

```APIDOC
## Tape Class Core Instance Methods

### `watch(): void`

Starts recording operations. Clears any historical nodes.

#### Example
```typescript
import { Tape } from "@oxide-js/core";
const tape = new Tape();
tape.watch();
```

### `stop(): void`

Stops recording operations.

#### Example
```typescript
tape.stop();
```

### `noGrad<T>(fn: () => T): T`

Temporarily halts the tape recording to execute a block of code without calculating or saving gradient graphs. Highly useful during evaluation, prediction, and parameter updates to save execution memory.

#### Example
```typescript
// Evaluate loss without recording any operations on the tape
const valLoss = tape.noGrad(() => {
  return evaluateModel(valData);
});
```

### `record(inputs: Matrix[], outputs: Matrix[], backward: GradientFunc, options?: TapeRecordOptions): void`

Registers a mathematical operation on the active tape.

- **`TapeRecordOptions`**:
  - `saveInput?: boolean` - If `true`, snapshots input matrix elements to prevent post-mutation corruption during backpropagation. Default `true`.
  - `saveOutput?: boolean` - If `true`, snapshots output matrix elements. Default `true`.
  - `requireInputStability?: boolean` - If `true`, throws an error if an input matrix is mutated without a saved snapshot. Default `false`.
  - `requireOutputStability?: boolean` - If `true`, throws an error if an output matrix is mutated without a saved snapshot. Default `false`.

#### Example
```typescript
import { Matrix } from "@oxide-js/core";

const x = Matrix.fromFlat([2], [1, 1]);
x.requiresGrad = true;
const y = Matrix.fromFlat([4], [1, 1]); // y = x * 2

// Register custom forward multiplication
tape.record([x], [y], (grad) => {
  // dy/dx = 2 -> multiply by upstream gradient
  const dx = Matrix.fromFlat([grad.get(0, 0) * 2], [1, 1]);
  return [dx];
}, { saveInput: true, saveOutput: true });
```

### `backward(loss: Matrix, upstreamGrad?: Matrix): void`

Triggers backpropagation. Traverses recorded execution nodes in reverse order (LIFO), calculating gradients via analytic derivative callbacks and updating parameter `grad` properties in-place.

- **Data Swapping (Snapshot Time Travel)**: To support operations where inputs/outputs are mutated in-place, `backward` swaps historical snapshots back into the tensor objects during derivative evaluations, restoring current runtime buffers immediately afterward.

#### Example
```typescript
// y is the final computed loss matrix
tape.backward(y);
console.log("x gradient:", x.grad?.get(0, 0));
```
```

--------------------------------

### GELU Activation Function Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/activation.md

Applies the Gaussian Error Linear Unit function, commonly used in Transformer architectures. Requires importing the `mj` object from `@oxide-js/core`.

```typescript
import { mj } from "@oxide-js/core";
const inputs = mj.matrix([[0.0, 2.0]]);
j.gelu(inputs).print();
```

--------------------------------

### Tanh Activation Function Example

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/activation.md

Applies the hyperbolic tangent function, mapping inputs to a symmetric range between -1 and 1. Requires importing the `mj` object from `@oxide-js/core`.

```typescript
import { mj } from "@oxide-js/core";
const inputs = mj.matrix([[0.0]]);
const out = mj.tanh(inputs);
out.print(); // [[0.0]]
```

--------------------------------

### Matrix.fromFlat Static Initializer

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/core/matrix.md

Constructs a matrix from a flat memory array (Float32Array or number array) and a shape tuple.

```APIDOC
## `Matrix.fromFlat(data: Float32Array | number[], shape: [number, number]): Matrix`

### Description
Constructs a matrix from a flat memory array, saving performance by avoiding nested array allocations.

### Arguments
- `data` - A flat typed array or array-like containing linear elements.
- `shape` - A dimension tuple `[rows, cols]`.

### Example
```ts
import { Matrix } from "@oxide-js/core";
const m = Matrix.fromFlat(new Float32Array([1, 2, 3, 4]), [2, 2]);
```
```

--------------------------------

### Compile Model Configuration

Source: https://github.com/akhyar11/oxide-js/blob/main/docs/api/models/base.md

Prepares the model for training by specifying the optimizer, loss function, learning rate, and metrics.

```typescript
model.compile({
  optimizer: "adam", // or sgd, momentum, nag, adagrad
  loss: "softmaxCrossEntropy", // or mse, mae, huber, logCosh, hinge, crossEntropy, binaryCrossEntropy
  learningRate: 0.001,
  metrics: ["accuracy", "mae"]
});
```