npm - mini-jstorch - Versions diffs - 1.7.1 → 1.8.0 - Mend

mini-jstorch 1.7.1 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,100 +1,367 @@
-# Mini-JSTorch
+## Mini-JSTorch
-A lightweight JavaScript neural network library for rapid frontend AI experimentation on low-resource devices, inspired by PyTorch.
-## Overview
+Mini-JSTorch is a lightweight, `dependency-free` JavaScript neural network library designed for `education`, `experimentation`, and `small-scale models`.
+It runs in Node.js and modern browsers, with a simple API inspired by PyTorch-style workflows.
-Mini-JSTorch is a high-performance, minimalist JavaScript library for building neural networks. It runs efficiently in Frontend environments, including low-end devices. The library enables quick experimentation and learning in AI without compromising stability, accuracy, or training reliability.
+This project prioritizes `clarity`, `numerical correctness`, and `accessibility` over performance or large-scale production use.
+In this version `1.8.0`, we Introduce the **SoftmaxCrossEntropyLoss**, and **BCEWithLogitsLoss**
-This release, **1.7.1** allows users to access the JST package from the `browser global scope` or `via HTML` (Sorry I was forgot this feature for a long time).
 ---
-## New Features Highlights
+# Overview
+**Mini-JSTorch provides a minimal neural network engine implemented entirely in plain JavaScript.**
+*It is intended for:*
+- learning how neural networks work internally
+- experimenting with small models
+- running simple training loops in the browser
+- environments where large frameworks are unnecessary or unavailable
-- **Softmax Layer:** Professional classification output with proper gradient computation
-- **Tokenizer:** Lightweight text preprocessing for NLP tasks
-- **AdamW Optimizer:** Modern optimizer with decoupled weight decay
+`Mini-JSTorch is NOT a replacement for PyTorch, TensorFlow, or TensorFlow.js.`
+`It is intentionally scoped to remain small, readable, and easy to debug.`
+---
+# Key Characteristics
+- Zero dependencies
+- ESM-first (`type: module`)
+- Works in Node.js and browser environments
+- Explicit, manual forward and backward passes
+- Focused on 2D training logic (`[batch][features]`)
+- Designed for educational and experimental use
+---
+# Browser Support
+Now, Mini-JSTorch can be used directly in browsers:
+- via ESM imports
+- via CDN / `<script>` with a global `JST` object
+This makes it suitable for:
+- demos
+- learning environments
+- lightweight frontend experiments
+Here example code to make a simple Model with JSTorch.
+In Browser/Website:
+```html
+<!DOCTYPE html>
+<html>
+<body>
+    <div id="output">
+        <p>Status: <span id="status">Initializing...</span></p>
+        <div id="training-log"></div>
+        <div id="results" style="margin-top: 20px;"></div>
+    </div>
+    <script type="module">
+        import { Sequential, Linear, ReLU, MSELoss, Adam, StepLR, Tanh } from 'https://unpkg.com/jstorch'; // DO NOT CHANGE
+        const statusEl = document.getElementById('status');
+        const trainingLogEl = document.getElementById('training-log');
+        const resultsEl = document.getElementById('results');
+        async function trainModel() {
+            try {
+                statusEl.textContent = 'Creating model...';
+                const model = new Sequential([
+                    new Linear(2, 16),
+                    new Tanh(),
+                    new Linear(16, 8),
+                    new ReLU(),
+                    new Linear(8, 1)
+                ]);
+                const X = [[0,0], [0,1], [1,0], [1,1]];
+                const y = [[0], [1], [1], [0]];
+                const criterion = new MSELoss();
+                const optimizer = new Adam(model.parameters(), 0.1);
+                const scheduler = new StepLR(optimizer, 25, 0.5);
+                trainingLogEl.innerHTML = '<h4>Training Progress:</h4>';
+                const logList = document.createElement('ul');
+                trainingLogEl.appendChild(logList);
+                statusEl.textContent = 'Training...';
+                for (let epoch = 0; epoch < 1000; epoch++) {
+                    const pred = model.forward(X);
+                    const loss = criterion.forward(pred, y);
+                    const grad = criterion.backward();
+                    model.backward(grad);
+                    optimizer.step();
+                    scheduler.step();
+                    if (epoch % 100 === 0) {
+                        const logItem = document.createElement('li');
+                        logItem.textContent = `Epoch ${epoch}: Loss = ${loss.toFixed(6)}`;
+                        logList.appendChild(logItem);
+                        // Update status every 100 epochs
+                        statusEl.textContent = `Training... Epoch ${epoch}/1000 (Loss: ${loss.toFixed(6)})`;
+                        await new Promise(resolve => setTimeout(resolve, 10));
+                    }
+                }
+                statusEl.textContent = 'Training completed!';
+                statusEl.style.color = 'green';
+                resultsEl.innerHTML = '<h4>XOR Predictions:</h4>';
+                const resultsTable = document.createElement('table');
+                resultsTable.style.border = '1px solid #ccc';
+                resultsTable.style.borderCollapse = 'collapse';
+                resultsTable.style.width = '300px';
+                // Table header
+                const headerRow = document.createElement('tr');
+                ['Input A', 'Input B', 'Prediction', 'Target'].forEach(text => {
+                    const th = document.createElement('th');
+                    th.textContent = text;
+                    th.style.border = '1px solid #ccc';
+                    th.style.padding = '8px';
+                    headerRow.appendChild(th);
+                });
+                resultsTable.appendChild(headerRow);
+                const predictions = model.forward(X);
+                predictions.forEach((pred, i) => {
+                    const row = document.createElement('tr');
+                    const cell1 = document.createElement('td');
+                    cell1.textContent = X[i][0];
+                    cell1.style.border = '1px solid #ccc';
+                    cell1.style.padding = '8px';
+                    cell1.style.textAlign = 'center';
+                    const cell2 = document.createElement('td');
+                    cell2.textContent = X[i][1];
+                    cell2.style.border = '1px solid #ccc';
+                    cell2.style.padding = '8px';
+                    cell2.style.textAlign = 'center';
+                    const cell3 = document.createElement('td');
+                    cell3.textContent = pred[0].toFixed(4);
+                    cell3.style.border = '1px solid #ccc';
+                    cell3.style.padding = '8px';
+                    cell3.style.textAlign = 'center';
+                    cell3.style.fontWeight = 'bold';
+                    cell3.style.color = Math.abs(pred[0] - y[i][0]) < 0.1 ? 'green' : 'red';
+                    const cell4 = document.createElement('td');
+                    cell4.textContent = y[i][0];
+                    cell4.style.border = '1px solid #ccc';
+                    cell4.style.padding = '8px';
+                    cell4.style.textAlign = 'center';
+                    row.appendChild(cell1);
+                    row.appendChild(cell2);
+                    row.appendChild(cell3);
+                    row.appendChild(cell4);
+                    resultsTable.appendChild(row);
+                });
+                resultsEl.appendChild(resultsTable);
+                const summary = document.createElement('div');
+                summary.style.marginTop = '20px';
+                summary.style.padding = '10px';
+                summary.style.backgroundColor = '#f0f0f0';
+                summary.style.borderRadius = '5px';
+                summary.innerHTML = `
+                    <p><strong>Model Architecture:</strong> 2 → 16 → 8 → 1</p>
+                    <p><strong>Activation:</strong> Tanh → ReLU</p>
+                    <p><strong>Loss Function:</strong> MSE</p>
+                    <p><strong>Optimizer:</strong> Adam (LR: 0.1)</p>
+                    <p><strong>Epochs:</strong> 1000</p>
+                `;
+                resultsEl.appendChild(summary);
+            } catch (error) {
+                statusEl.textContent = `Error: ${error.message}`;
+                statusEl.style.color = 'red';
+                console.error(error);
+            }
+        }
+        trainModel();
+    </script>
+</body>
+</html>
+```
 ---
-## Core Features
+# Core Features
-- **Layers:** Linear, Flatten, Conv2D
-- **Activations:** ReLU, Sigmoid, Tanh, LeakyReLU, GELU, Mish, SiLU, ELU
-- **Loss Functions:** MSELoss, CrossEntropyLoss
-- **Optimizers:** Adam, SGD, LION, AdamW
-- **Schedulers:** StepLR, LambdaLR, ReduceLROnPlateau
-- **Regularization:** Dropout, BatchNorm2D
-- **Utilities:** zeros, randomMatrix, softmax, crossEntropy, dot, addMatrices, reshape, stack, flatten, eye, concat
-- **Model Container:** Sequential (for stacking layers with forward/backward passes)
+# Layers
-# Others
+- Linear
+- Flatten
+- Conv2D (*experimental*)
-- **Tokenizer**
-- **Softmax Layer**
+# Activations
+- ReLU
+- Sigmoid
+- Tanh
+- LeakyReLU
+- GELU
+- Mish
+- SiLU
+- ELU
+# Loss Functions
+- MSELoss
+- CrossEntropyLoss (*legacy*)
+- SoftmaxCrossEntropyLoss (**recommended**)
+- BCEWithLogitsLoss (**recommended**)
+# Optimizers
+- SGD
+- Adam
+- AdamW
+- Lion
+# Learning Rate Schedulers
+- StepLR
+- LambdaLR
+- ReduceLROnPlateau
+- Regularization
+- Dropout (*basic*, *educational*)
+- BatchNorm2D (*experimental*)
+# Utilities
+- zeros
+- randomMatrix
+- dot
+- addMatrices
+- reshape
+- stack
+- flatten
+- concat
+- softmax
+- crossEntropy
+# Model Container
+- Sequential
 ---
-## Installation
+# Installation
 ```bash
 npm install mini-jstorch
-# Node.js v20+ recommended for best performance
 ```
+Node.js v18+ or any modern browser with ES module support is recommended.
 ---
-## Quick Start Example
+# Quick Start (Recommended Loss)
+# Multi-class Classification (SoftmaxCrossEntropy)
 ```javascript
-import { Sequential, Linear, ReLU, Sigmoid, CrossEntropyLoss, Adam, StepLR } from './src/jstorch.js';
+import {
+  Sequential,
+  Linear,
+  ReLU,
+  SoftmaxCrossEntropyLoss,
+  Adam
+} from "./src/jstorch.js";
-// Build model
 const model = new Sequential([
-  new Linear(2,4),
+  new Linear(2, 4),
   new ReLU(),
-  new Linear(4,2),
-  new Sigmoid()
+  new Linear(4, 2) // logits output
 ]);
-// Sample XOR dataset
 const X = [
   [0,0], [0,1], [1,0], [1,1]
 ];
 const Y = [
   [1,0], [0,1], [0,1], [1,0]
 ];
-// Loss & optimizer
-const lossFn = new CrossEntropyLoss();
+const lossFn = new SoftmaxCrossEntropyLoss();
 const optimizer = new Adam(model.parameters(), 0.1);
-const scheduler = new StepLR(optimizer, 20, 0.5); // Halve LR every 20 epochs
-// Training loop
-for (let epoch = 1; epoch <= 100; epoch++) {
-  const pred = model.forward(X);
-  const loss = lossFn.forward(pred, Y);
-  const gradLoss = lossFn.backward();
-  model.backward(gradLoss);
+for (let epoch = 1; epoch <= 300; epoch++) {
+  const logits = model.forward(X);
+  const loss = lossFn.forward(logits, Y);
+  const grad = lossFn.backward();
+  model.backward(grad);
   optimizer.step();
-  scheduler.step();
-  if (epoch % 20 === 0) console.log(`Epoch ${epoch}, Loss: ${loss.toFixed(4)}, LR: ${optimizer.lr.toFixed(4)}`);
+  if (epoch % 50 === 0) {
+    console.log(`Epoch ${epoch}, Loss: ${loss.toFixed(4)}`);
+  }
 }
+```
+Do not combine `SoftmaxCrossEntropyLoss` with a `Softmax` layer.
+# Binary Classifiaction (BCEWithLogitsLoss)
-// Prediction
-const predTest = model.forward(X);
-predTest.forEach((p,i) => {
-  const predictedClass = p.indexOf(Math.max(...p));
-  console.log(`Input: ${X[i]}, Predicted class: ${predictedClass}, Raw output: ${p.map(v => v.toFixed(3))}`);
-});
+```javascript
+import {
+  Sequential,
+  Linear,
+  ReLU,
+  BCEWithLogitsLoss,
+  Adam
+} from "./src/jstorch.js";
+const model = new Sequential([
+  new Linear(2, 4),
+  new ReLU(),
+  new Linear(4, 1) // logit
+]);
+const X = [
+  [0,0], [0,1], [1,0], [1,1]
+];
+const Y = [
+  [0], [1], [1], [0]
+];
+const lossFn = new BCEWithLogitsLoss();
+const optimizer = new Adam(model.parameters(), 0.1);
+for (let epoch = 1; epoch <= 300; epoch++) {
+  const logits = model.forward(X);
+  const loss = lossFn.forward(logits, Y);
+  const grad = lossFn.backward();
+  model.backward(grad);
+  optimizer.step();
+}
 ```
+Do not combine `BCEWithLogitsLoss` with a `Sigmoid` layer.
 ---
-## Save & Load Models
+# Save & Load Models
 ```javascript
-import { saveModel, loadModel, Sequential } from '.jstorch.js';
+import { saveModel, loadModel, Sequential } from "mini-jstorch";
 const json = saveModel(model);
 const model2 = new Sequential([...]); // same architecture
@@ -103,13 +370,12 @@ loadModel(model2, json);
 ---
-## Demos & Testing
+# Demos
-Check the `demo/` directory for ready-to-run demos:
-- **demo/MakeModel.js:** Build and run a simple neural network.
-- **demo/scheduler.js:** Experiment with learning rate schedulers.
-- **demo/fu_fun.js:** Test all user-friendly (fu or For Users/Friendly Users) functions
-- Add your own scripts for quick prototyping!
+See the `demo/` directory for runnable examples:
+- `demo/MakeModel.js` – simple training loop
+- `demo/scheduler.js` – learning rate schedulers
+- `demo/fu_fun.js` – utility functions
 ```bash
 node demo/MakeModel.js
@@ -119,17 +385,30 @@ node demo/fu_fun.js
 ---
-## Intended Use Cases
+# Design Notes & Limitations
- - Rapid prototyping of neural networks in frontend.
- - Learning and teaching foundational neural network concepts.
- - Experimentation on low-end devices or mobile browsers.
- - Lightweight AI projects without GPU dependency.
+- Training logic is 2D-first: `[batch][features]`
+- Higher-dimensional data is reshaped internally by specific layers (e.g. Conv2D, Flatten)
+- No automatic broadcasting or autograd graph
+- Some components (Conv2D, BatchNorm2D, Dropout) are educational / experimental
+- Not intended for large-scale or production ML workloads
 ---
+# Intended Use Cases
+- Learning how neural networks work internally
+- Teaching ML fundamentals
+- Small experiments in Node.js or the browser
+- Lightweight AI demos without GPU or large frameworks
+---
 # License
-`MIT License`
+MIT License
+Copyright (c) 2024
+rizal-editors
-**Copyright (c) 2024 rizal-editors**
+---

package/index.js CHANGED Viewed

@@ -1,7 +1,6 @@
 // package root
-// ugh, i forgot provide JST can use in browser global scope...
-// now we provided JST use in browser global scope
+// provide JST in browser global scope
 import * as JST from './src/jstorch.js';
 if (typeof window !== 'undefined') {

package/package.json CHANGED Viewed

@@ -1,29 +1,19 @@
 {
   "name": "mini-jstorch",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "type": "module",
   "description": "A lightweight JavaScript neural network library for learning AI concepts and rapid Frontend experimentation. PyTorch-inspired, zero dependencies, perfect for educational use.",
   "main": "index.js",
   "keywords": [
-    "neural-network",
-    "JST",
-    "javascript",
-    "lightweight-torch",
-    "lightweight",
-    "small-torch",
+    "lightweight-ml",
     "javascript-torch",
-    "jstorch",
     "front-end-torch",
-    "machine-learning",
     "tiny-ml",
-    "frontend-nn",
-    "frontend-ai",
-    "mini-neural-network"
+    "mini-neural-network",
+    "mini-ml-library",
+    "mini-js-ml",
+    "educational-ml"
   ],
   "author": "Rizal",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/rizal-editors/mini-jstorch.git"
-  }
+  "license": "MIT"
 }

package/src/jstorch.js CHANGED Viewed

@@ -1,9 +1,8 @@
 /*!
- * Project: mini-jstorch
  * File: jstorch.js
- * Author: Rizal-editors
+ * Author: rizal-editors
  * License: MIT
- * Copyright (C) 2025 Rizal-editors
+ * Copyright (C) 2025 rizal-editors
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -30,7 +29,7 @@
 // See the Documentation for more details.
 // --------------------------------------------------------------
-// ---------------------- DONOT USE THESE (ENGINE INTERNALS) ----------------------
+// ---------------------- DONOT USE THESE (ENGINE INTERNALS) ERROR/BUG ARE EXPECTED ----------------------
 export function zeros(rows, cols) {
     return Array.from({length:rows},()=>Array(cols).fill(0));
 }
@@ -80,7 +79,7 @@ export function crossEntropy(pred,target){
     return -target.reduce((sum,t,i)=>sum+t*Math.log(pred[i]+eps),0);
 }
-// ---------------------- USERS FRIENDLY UTILS (USE THIS!) ----------------
+// ---------------------- USERS FRIENDLY UTILS (USE THIS FOR YOUR UTILS!) ----------------
 export function fu_tensor(data, requiresGrad = false) {
     if (!Array.isArray(data) || !Array.isArray(data[0])) {
         throw new Error("fu_tensor: Data must be 2D array");
@@ -751,6 +750,69 @@ export class Dropout{ constructor(p=0.5){ this.p=p; } forward(x){ return x.map(r
 export class MSELoss{ forward(pred,target){ this.pred=pred; this.target=target; const losses=pred.map((row,i)=>row.reduce((sum,v,j)=>sum+(v-target[i][j])**2,0)/row.length); return losses.reduce((a,b)=>a+b,0)/pred.length; } backward(){ return this.pred.map((row,i)=>row.map((v,j)=>2*(v-this.target[i][j])/row.length)); } }
 export class CrossEntropyLoss{ forward(pred,target){ this.pred=pred; this.target=target; const losses=pred.map((p,i)=>crossEntropy(softmax(p),target[i])); return losses.reduce((a,b)=>a+b,0)/pred.length; } backward(){ return this.pred.map((p,i)=>{ const s=softmax(p); return s.map((v,j)=>(v-this.target[i][j])/this.pred.length); }); } }
+export class SoftmaxCrossEntropyLoss {
+  forward(logits, targets) {
+    this.targets = targets;
+    const batch = logits.length;
+    // stable softmax
+    this.probs = logits.map(row => {
+      const max = Math.max(...row);
+      const exps = row.map(v => Math.exp(v - max));
+      const sum = exps.reduce((a,b)=>a+b, 0);
+      return exps.map(v => v / sum);
+    });
+    let loss = 0;
+    for (let i = 0; i < batch; i++) {
+      for (let j = 0; j < this.probs[i].length; j++) {
+        if (targets[i][j] === 1) {
+          loss -= Math.log(this.probs[i][j] + 1e-12);
+        }
+      }
+    }
+    return loss / batch;
+  }
+  backward() {
+    const batch = this.targets.length;
+    return this.probs.map((row,i) =>
+      row.map((p,j) => (p - this.targets[i][j]) / batch)
+    );
+  }
+}
+export class BCEWithLogitsLoss {
+  forward(logits, targets) {
+    this.logits = logits;
+    this.targets = targets;
+    const batch = logits.length;
+    let loss = 0;
+    for (let i = 0; i < batch; i++) {
+      for (let j = 0; j < logits[i].length; j++) {
+        const x = logits[i][j];
+        const y = targets[i][j];
+        // stable BCE
+        loss += Math.max(x, 0) - x*y + Math.log(1 + Math.exp(-Math.abs(x)));
+      }
+    }
+    return loss / batch;
+  }
+  backward() {
+    const batch = this.logits.length;
+    return this.logits.map((row,i) =>
+      row.map((x,j) => {
+        const sigmoid = 1 / (1 + Math.exp(-x));
+        return (sigmoid - this.targets[i][j]) / batch;
+      })
+    );
+  }
+}
 // ---------------------- Optimizers ----------------------
 export class Adam{
     constructor(params, lr = 0.001, b1 = 0.9, b2 = 0.999, eps = 1e-8, max_grad_norm = 1.0){