axon Tensors, autograd, convolution,
and training loops in readable JavaScript.

01Why this exists

Most JavaScript deep-learning libraries are wrappers around TensorFlow.js, ONNX, or a native backend. You cannot easily inspect backpropagation, set a breakpoint inside a gradient, or understand the full path without installing a large dependency tree.

axon takes the opposite approach: keep the machinery small enough to read.

• Zero dependencies — clone it and run it
• Verifiable gradients — every operator has a finite-difference check
• Actual training — layers, losses, optimizers, batching, and epochs
• Browser and Node — the same source runs in both environments

02Built-in gradient checks

Most frameworks trust a passing training run. axon compares analytical gradients against numerical gradients directly.

// Validate an operator while you implement it
const r = checkGradient(() => myOp(a, b).sum(), [a, b]);
if (!r.passed) throw new Error(r.report);

This caught three silent numerical bugs: a matmul weight gradient that only accumulated the first output column, an optimizer momentum buffer overrun, and an incorrect mse reduction axis. Forward passes looked fine in every case.

03It actually trains

The goal is not merely “no runtime error.” It is reproducible convergence.

Linear regression recovers w = 2.511 and b = -1.2115 against targets of 2.5 and -1.2.

04Performance is a deliberate tradeoff

Pure CPU, no SIMD, no multithreading, and no WASM. Measured on Node v24 arm64; numbers vary by machine.

05Quick start

npm install github:wulier-arch/axon

Or clone the repository. There are no dependencies, and src/ is the complete library.

git clone https://github.com/wulier-arch/axon.git
cd axon && npm test

For smaller training examples, open the XOR classifier or linear regression. Both pages load src/ directly without a bundler.

Train a neural network in 11 lines:

import { Linear, Sequential, Adam, Trainer, crossEntropy, accuracy, makeSpiral } from "axon-net";

const { x, y } = makeSpiral({ samples: 300 });

const model = new Sequential()
  .add(new Linear(2, 32, { activation: "relu", seed: 1 }))
  .add(new Linear(32, 2, { seed: 2 }));

const trainer = new Trainer({
  model,
  optimizer: new Adam({ lr: 0.01 }),
  lossFn: crossEntropy,
  metricFn: accuracy,
  epochs: 400,
  batchSize: 32,
});

trainer.fit(x, y, y);
console.log(trainer.history.at(-1));
// { epoch: 399, loss: 0.0248, metric: 1 }

06What is implemented

07Roadmap

Shipped: layers and Sequential, optimizers, losses, and training loops (v0.2.0); browser demo (v0.2.1); LayerNorm, Embedding, MultiHeadAttention, and TransformerBlock (v0.3.0); XOR and linear-regression browser examples plus JSON model serialization and loading (v0.3.1). Batched conv2d is complete with 114 passing tests and will ship in the next version.

• BPE tokenizer
• BatchNorm