@dniskav/neuron 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# @dniskav/neuron
+
+A minimal, dependency-free neural network library built from scratch in TypeScript. Designed for learning and experimentation — every line of math is readable.
+
+## What's inside
+
+| Class | Description |
+|-------|-------------|
+| `Neuron` | Single-input neuron. The simplest possible unit: one weight, one bias. |
+| `NeuronN` | N-input neuron with Xavier initialization and sigmoid activation. |
+| `Layer` | A group of `NeuronN` neurons that share the same inputs. |
+| `Network` | Two-layer network (hidden + output) with backpropagation. |
+| `NetworkN` | Deep network of arbitrary depth. Define your architecture as `[inputs, ...hidden, outputs]`. |
+
+## Install
+
+```bash
+npm install @dniskav/neuron
+```
+
+## Usage
+
+### Single neuron — learn a threshold
+
+```ts
+import { Neuron } from "@dniskav/neuron";
+
+const neuron = new Neuron();
+
+// Train: output 1 if input >= 18, else 0
+for (let epoch = 0; epoch < 1000; epoch++) {
+  neuron.train(20, 1, 0.1); // adult
+  neuron.train(15, 0, 0.1); // minor
+}
+
+console.log(neuron.predict(17)); // ~0.1 (minor)
+console.log(neuron.predict(25)); // ~0.9 (adult)
+```
+
+### N-input neuron — multi-feature classification
+
+```ts
+import { NeuronN } from "@dniskav/neuron";
+
+const neuron = new NeuronN(3); // 3 inputs: R, G, B
+
+// Teach it to detect bright colors (luminance > 0.65)
+neuron.train([1, 1, 1], 1, 0.05); // white → bright
+neuron.train([0, 0, 0], 0, 0.05); // black → dark
+
+console.log(neuron.predict([0.9, 0.9, 0.9])); // close to 1
+```
+
+### Network — non-linear classification
+
+```ts
+import { Network } from "@dniskav/neuron";
+
+// 2 inputs → 8 hidden neurons → 1 output
+const net = new Network(2, 8, 1);
+
+// Train on XOR (not linearly separable — needs hidden layer)
+const data = [[0,0,0], [0,1,1], [1,0,1], [1,1,0]];
+
+for (let epoch = 0; epoch < 5000; epoch++) {
+  for (const [x, y, t] of data) {
+    net.train([x, y], t, 0.3);
+  }
+}
+
+console.log(net.predict([0, 1])); // ~0.97
+console.log(net.predict([1, 1])); // ~0.03
+```
+
+### NetworkN — deep network with custom architecture
+
+```ts
+import { NetworkN } from "@dniskav/neuron";
+
+// 3 inputs → 24 hidden → 16 hidden → 2 outputs
+const net = new NetworkN([3, 24, 16, 2]);
+
+// Train with multiple targets
+net.train([0.5, 0.3, 0.8], [1, 0], 0.05);
+
+// Predict returns an array — one value per output neuron
+const [out1, out2] = net.predict([0.5, 0.3, 0.8]);
+```
+
+### trainWithDeltas — custom loss / physics-based gradients
+
+`NetworkN` also exposes `trainWithDeltas` for when you compute your own output-layer deltas (e.g., from a physics simulation or a custom loss function):
+
+```ts
+net.trainWithDeltas(inputs, [0.4, -0.2], 0.05);
+```
+
+## How it works
+
+Every class uses **sigmoid** as its activation function and **gradient descent** to update weights:
+
+```
+weight += lr × error × input
+bias   += lr × error
+```
+
+`NetworkN` implements full **backpropagation** across all layers, propagating deltas from the output back to the first layer using the chain rule.
+
+`NeuronN` uses simplified **Xavier initialization** — weights start in `[-√(1/n), +√(1/n)]` — so gradients flow well from the start of training.
+
+## Build
+
+```bash
+npm run build   # outputs CJS + ESM + type declarations to dist/
+npm run dev     # watch mode
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,40 @@
+declare class Neuron {
+    weight: number;
+    bias: number;
+    constructor();
+    predict(input: number): number;
+    train(input: number, target: number, lr: number): void;
+}
+
+declare class NeuronN {
+    weights: number[];
+    bias: number;
+    constructor(nInputs: number);
+    predict(inputs: number[]): number;
+    train(inputs: number[], target: number, lr: number): void;
+}
+
+declare class Layer {
+    neurons: NeuronN[];
+    constructor(nNeurons: number, nInputs: number);
+    predict(inputs: number[]): number[];
+}
+
+declare class Network {
+    hiddenLayer: Layer;
+    outputLayer: Layer;
+    constructor(nInputs: number, nHidden: number, nOutputs: number);
+    predict(inputs: number[]): number;
+    train(inputs: number[], target: number, lr: number): number;
+}
+
+declare class NetworkN {
+    readonly structure: number[];
+    layers: Layer[];
+    constructor(structure: number[]);
+    predict(inputs: number[]): number[];
+    train(inputs: number[], targets: number[], lr: number): number;
+    trainWithDeltas(inputs: number[], outputDeltas: number[], lr: number): void;
+}
+
+export { Layer, Network, NetworkN, Neuron, NeuronN };

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+declare class Neuron {
+    weight: number;
+    bias: number;
+    constructor();
+    predict(input: number): number;
+    train(input: number, target: number, lr: number): void;
+}
+
+declare class NeuronN {
+    weights: number[];
+    bias: number;
+    constructor(nInputs: number);
+    predict(inputs: number[]): number;
+    train(inputs: number[], target: number, lr: number): void;
+}
+
+declare class Layer {
+    neurons: NeuronN[];
+    constructor(nNeurons: number, nInputs: number);
+    predict(inputs: number[]): number[];
+}
+
+declare class Network {
+    hiddenLayer: Layer;
+    outputLayer: Layer;
+    constructor(nInputs: number, nHidden: number, nOutputs: number);
+    predict(inputs: number[]): number;
+    train(inputs: number[], target: number, lr: number): number;
+}
+
+declare class NetworkN {
+    readonly structure: number[];
+    layers: Layer[];
+    constructor(structure: number[]);
+    predict(inputs: number[]): number[];
+    train(inputs: number[], targets: number[], lr: number): number;
+    trainWithDeltas(inputs: number[], outputDeltas: number[], lr: number): void;
+}
+
+export { Layer, Network, NetworkN, Neuron, NeuronN };

package/dist/index.js

@@ -0,0 +1,177 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Layer: () => Layer,
+  Network: () => Network,
+  NetworkN: () => NetworkN,
+  Neuron: () => Neuron,
+  NeuronN: () => NeuronN
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/Neuron.ts
+function sigmoid(x) {
+  return 1 / (1 + Math.exp(-x));
+}
+var Neuron = class {
+  constructor() {
+    this.weight = Math.random() * 0.1;
+    this.bias = Math.random() * 0.1;
+  }
+  predict(input) {
+    return sigmoid(input * this.weight + this.bias);
+  }
+  train(input, target, lr) {
+    const prediction = this.predict(input);
+    const error = target - prediction;
+    this.weight += lr * error * input;
+    this.bias += lr * error;
+  }
+};
+
+// src/NeuronN.ts
+function sigmoid2(x) {
+  return 1 / (1 + Math.exp(-x));
+}
+var NeuronN = class {
+  constructor(nInputs) {
+    const limit = Math.sqrt(1 / nInputs);
+    this.weights = Array.from({ length: nInputs }, () => (Math.random() * 2 - 1) * limit);
+    this.bias = 0;
+  }
+  predict(inputs) {
+    const sum = inputs.reduce((acc, e, i) => acc + e * this.weights[i], this.bias);
+    return sigmoid2(sum);
+  }
+  train(inputs, target, lr) {
+    const prediction = this.predict(inputs);
+    const error = target - prediction;
+    this.weights = this.weights.map((w, i) => w + lr * error * inputs[i]);
+    this.bias += lr * error;
+  }
+};
+
+// src/Layer.ts
+var Layer = class {
+  constructor(nNeurons, nInputs) {
+    this.neurons = Array.from({ length: nNeurons }, () => new NeuronN(nInputs));
+  }
+  predict(inputs) {
+    return this.neurons.map((n) => n.predict(inputs));
+  }
+};
+
+// src/Network.ts
+var Network = class {
+  constructor(nInputs, nHidden, nOutputs) {
+    this.hiddenLayer = new Layer(nHidden, nInputs);
+    this.outputLayer = new Layer(nOutputs, nHidden);
+  }
+  predict(inputs) {
+    const hiddenOut = this.hiddenLayer.predict(inputs);
+    return this.outputLayer.predict(hiddenOut)[0];
+  }
+  // Trains on a single example. Returns the squared error.
+  train(inputs, target, lr) {
+    const hiddenOut = this.hiddenLayer.predict(inputs);
+    const prediction = this.outputLayer.predict(hiddenOut)[0];
+    const outputError = target - prediction;
+    const outputDelta = outputError * prediction * (1 - prediction);
+    const outputNeuron = this.outputLayer.neurons[0];
+    outputNeuron.weights = outputNeuron.weights.map(
+      (w, i) => w + lr * outputDelta * hiddenOut[i]
+    );
+    outputNeuron.bias += lr * outputDelta;
+    this.hiddenLayer.neurons.forEach((neuron, i) => {
+      const hiddenOut_i = hiddenOut[i];
+      const hiddenError = outputDelta * outputNeuron.weights[i];
+      const hiddenDelta = hiddenError * hiddenOut_i * (1 - hiddenOut_i);
+      neuron.weights = neuron.weights.map((w, j) => w + lr * hiddenDelta * inputs[j]);
+      neuron.bias += lr * hiddenDelta;
+    });
+    return outputError * outputError;
+  }
+};
+
+// src/NetworkN.ts
+var NetworkN = class {
+  constructor(structure) {
+    this.structure = structure;
+    this.layers = [];
+    for (let i = 1; i < structure.length; i++) {
+      this.layers.push(new Layer(structure[i], structure[i - 1]));
+    }
+  }
+  predict(inputs) {
+    return this.layers.reduce((acc, layer) => layer.predict(acc), inputs);
+  }
+  // Generalized backpropagation across L layers.
+  // Returns the mean squared error for the example.
+  train(inputs, targets, lr) {
+    const act = [inputs];
+    for (const layer of this.layers) act.push(layer.predict(act[act.length - 1]));
+    const pred = act[act.length - 1];
+    let deltas = pred.map((p, i) => (targets[i] - p) * p * (1 - p));
+    for (let l = this.layers.length - 1; l >= 0; l--) {
+      const layer = this.layers[l];
+      const layerIn = act[l];
+      const prevDeltas = layerIn.map((out, j) => {
+        const errProp = layer.neurons.reduce((s, n, k) => s + deltas[k] * n.weights[j], 0);
+        return errProp * out * (1 - out);
+      });
+      layer.neurons.forEach((n, k) => {
+        n.weights = n.weights.map((w, j) => w + lr * deltas[k] * layerIn[j]);
+        n.bias += lr * deltas[k];
+      });
+      deltas = prevDeltas;
+    }
+    return pred.reduce((s, p, i) => s + (targets[i] - p) ** 2, 0) / pred.length;
+  }
+  // Backprop with externally provided output-layer deltas.
+  // Useful for custom loss functions (e.g. physics-based gradients).
+  trainWithDeltas(inputs, outputDeltas, lr) {
+    const act = [inputs];
+    for (const layer of this.layers) act.push(layer.predict(act[act.length - 1]));
+    let deltas = outputDeltas;
+    for (let l = this.layers.length - 1; l >= 0; l--) {
+      const layer = this.layers[l];
+      const layerIn = act[l];
+      const prevDeltas = layerIn.map((out, j) => {
+        const errProp = layer.neurons.reduce((s, n, k) => s + deltas[k] * n.weights[j], 0);
+        return errProp * out * (1 - out);
+      });
+      layer.neurons.forEach((n, k) => {
+        n.weights = n.weights.map((w, j) => w + lr * deltas[k] * layerIn[j]);
+        n.bias += lr * deltas[k];
+      });
+      deltas = prevDeltas;
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Layer,
+  Network,
+  NetworkN,
+  Neuron,
+  NeuronN
+});

package/dist/index.mjs

@@ -0,0 +1,146 @@
+// src/Neuron.ts
+function sigmoid(x) {
+  return 1 / (1 + Math.exp(-x));
+}
+var Neuron = class {
+  constructor() {
+    this.weight = Math.random() * 0.1;
+    this.bias = Math.random() * 0.1;
+  }
+  predict(input) {
+    return sigmoid(input * this.weight + this.bias);
+  }
+  train(input, target, lr) {
+    const prediction = this.predict(input);
+    const error = target - prediction;
+    this.weight += lr * error * input;
+    this.bias += lr * error;
+  }
+};
+
+// src/NeuronN.ts
+function sigmoid2(x) {
+  return 1 / (1 + Math.exp(-x));
+}
+var NeuronN = class {
+  constructor(nInputs) {
+    const limit = Math.sqrt(1 / nInputs);
+    this.weights = Array.from({ length: nInputs }, () => (Math.random() * 2 - 1) * limit);
+    this.bias = 0;
+  }
+  predict(inputs) {
+    const sum = inputs.reduce((acc, e, i) => acc + e * this.weights[i], this.bias);
+    return sigmoid2(sum);
+  }
+  train(inputs, target, lr) {
+    const prediction = this.predict(inputs);
+    const error = target - prediction;
+    this.weights = this.weights.map((w, i) => w + lr * error * inputs[i]);
+    this.bias += lr * error;
+  }
+};
+
+// src/Layer.ts
+var Layer = class {
+  constructor(nNeurons, nInputs) {
+    this.neurons = Array.from({ length: nNeurons }, () => new NeuronN(nInputs));
+  }
+  predict(inputs) {
+    return this.neurons.map((n) => n.predict(inputs));
+  }
+};
+
+// src/Network.ts
+var Network = class {
+  constructor(nInputs, nHidden, nOutputs) {
+    this.hiddenLayer = new Layer(nHidden, nInputs);
+    this.outputLayer = new Layer(nOutputs, nHidden);
+  }
+  predict(inputs) {
+    const hiddenOut = this.hiddenLayer.predict(inputs);
+    return this.outputLayer.predict(hiddenOut)[0];
+  }
+  // Trains on a single example. Returns the squared error.
+  train(inputs, target, lr) {
+    const hiddenOut = this.hiddenLayer.predict(inputs);
+    const prediction = this.outputLayer.predict(hiddenOut)[0];
+    const outputError = target - prediction;
+    const outputDelta = outputError * prediction * (1 - prediction);
+    const outputNeuron = this.outputLayer.neurons[0];
+    outputNeuron.weights = outputNeuron.weights.map(
+      (w, i) => w + lr * outputDelta * hiddenOut[i]
+    );
+    outputNeuron.bias += lr * outputDelta;
+    this.hiddenLayer.neurons.forEach((neuron, i) => {
+      const hiddenOut_i = hiddenOut[i];
+      const hiddenError = outputDelta * outputNeuron.weights[i];
+      const hiddenDelta = hiddenError * hiddenOut_i * (1 - hiddenOut_i);
+      neuron.weights = neuron.weights.map((w, j) => w + lr * hiddenDelta * inputs[j]);
+      neuron.bias += lr * hiddenDelta;
+    });
+    return outputError * outputError;
+  }
+};
+
+// src/NetworkN.ts
+var NetworkN = class {
+  constructor(structure) {
+    this.structure = structure;
+    this.layers = [];
+    for (let i = 1; i < structure.length; i++) {
+      this.layers.push(new Layer(structure[i], structure[i - 1]));
+    }
+  }
+  predict(inputs) {
+    return this.layers.reduce((acc, layer) => layer.predict(acc), inputs);
+  }
+  // Generalized backpropagation across L layers.
+  // Returns the mean squared error for the example.
+  train(inputs, targets, lr) {
+    const act = [inputs];
+    for (const layer of this.layers) act.push(layer.predict(act[act.length - 1]));
+    const pred = act[act.length - 1];
+    let deltas = pred.map((p, i) => (targets[i] - p) * p * (1 - p));
+    for (let l = this.layers.length - 1; l >= 0; l--) {
+      const layer = this.layers[l];
+      const layerIn = act[l];
+      const prevDeltas = layerIn.map((out, j) => {
+        const errProp = layer.neurons.reduce((s, n, k) => s + deltas[k] * n.weights[j], 0);
+        return errProp * out * (1 - out);
+      });
+      layer.neurons.forEach((n, k) => {
+        n.weights = n.weights.map((w, j) => w + lr * deltas[k] * layerIn[j]);
+        n.bias += lr * deltas[k];
+      });
+      deltas = prevDeltas;
+    }
+    return pred.reduce((s, p, i) => s + (targets[i] - p) ** 2, 0) / pred.length;
+  }
+  // Backprop with externally provided output-layer deltas.
+  // Useful for custom loss functions (e.g. physics-based gradients).
+  trainWithDeltas(inputs, outputDeltas, lr) {
+    const act = [inputs];
+    for (const layer of this.layers) act.push(layer.predict(act[act.length - 1]));
+    let deltas = outputDeltas;
+    for (let l = this.layers.length - 1; l >= 0; l--) {
+      const layer = this.layers[l];
+      const layerIn = act[l];
+      const prevDeltas = layerIn.map((out, j) => {
+        const errProp = layer.neurons.reduce((s, n, k) => s + deltas[k] * n.weights[j], 0);
+        return errProp * out * (1 - out);
+      });
+      layer.neurons.forEach((n, k) => {
+        n.weights = n.weights.map((w, j) => w + lr * deltas[k] * layerIn[j]);
+        n.bias += lr * deltas[k];
+      });
+      deltas = prevDeltas;
+    }
+  }
+};
+export {
+  Layer,
+  Network,
+  NetworkN,
+  Neuron,
+  NeuronN
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@dniskav/neuron",
+  "version": "0.1.0",
+  "description": "Minimal neural network from scratch — neuron, layer, network, backpropagation. No dependencies.",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "keywords": ["neural-network", "machine-learning", "backpropagation", "typescript"],
+  "author": "dniskav",
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0"
+  }
+}