mini-jstorch 1.7.0 → 1.8.0

package/Docs/About.md

@@ -4,19 +4,19 @@
 
 ## General Information
 
-- **Project Name:** Mini-JSTorch  
-- **Internal Name:** JST (JSTorch)
+- **Project Name:** mini-jstorch  
+- **Internal Name:** JST (JST-orch)
 
 > Note:  
-> Early versions of Mini-JSTorch do not strictly follow semantic versioning conventions  
+> Early versions of JST do not strictly follow semantic versioning conventions  
 > (e.g. `0.0.1` for patches, `0.1.0` for minor releases, `1.0.0` for major releases).  
 > This inconsistency reflects the early learning and experimental phase of the project.
 
 ---
 
-## 1. Engine Architecture Limitations (JSTorch Core)
+## 1. Engine Architecture Limitations (JST Core)
 
-This section outlines the known structural weaknesses of the JSTorch engine.  
+This section outlines the known structural weaknesses of the JST engine.  
 Although the architecture may appear complex, it is currently sensitive and tightly coupled.
 
 ### Identified Limitations
@@ -68,7 +68,7 @@ In short, `fu_` exists to ensure safety, clarity, and consistency for end users
 
 ## 3. SJK (Shortcut JST Keywords) Reference
 
-This section lists commonly used abbreviations and keywords within the Mini-JSTorch ecosystem.
+This section lists commonly used abbreviations and keywords within the mini-jstorch ecosystem.
 
 **Format:** `"KEYWORD" : "Full Name / Meaning"`
 

package/README.md

@@ -1,101 +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.
 
-This release, **version 1.7.0:** We introduce **Softmax Layer**, **Tokenizer**, **AdamW Optimizer**, and enhanced NLP capabilities.
+In this version `1.8.0`, we Introduce the **SoftmaxCrossEntropyLoss**, and **BCEWithLogitsLoss**
 
 ---
 
-## New Features Highlights
+# Overview
 
-- **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 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
+
+`Mini-JSTorch is NOT a replacement for PyTorch, TensorFlow, or TensorFlow.js.`
+
+`It is intentionally scoped to remain small, readable, and easy to debug.`
 
 ---
 
-## Core Features
+# Key Characteristics
 
-- **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)  
+- 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
 
-# Others
+---
 
-- **Tokenizer**
-- **Softmax Layer**
+# 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>
+```
 
 ---
 
-## Installation
+# Core Features
+
+# Layers
+
+- Linear
+- Flatten
+- Conv2D (*experimental*)
+
+# 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 
 
 ```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
@@ -104,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
@@ -120,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

@@ -1,3 +1,10 @@
 // package root
-// * = all exports from src/jstorch.js
-export * from "./src/jstorch.js";
+
+// provide JST in browser global scope
+import * as JST from './src/jstorch.js';
+
+if (typeof window !== 'undefined') {
+    window.JST = JST; // Global JST (JSTorch) object
+}
+
+export * from './src/jstorch.js';

package/package.json

@@ -1,29 +1,19 @@
 {
   "name": "mini-jstorch",
-  "version": "1.7.0",
+  "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",
-    "javascript",
-    "lightweight-torch",
-    "lightweight",
-    "small-torch",
+    "lightweight-ml",
     "javascript-torch",
-    "ai-model",
-    "jstorch",
-    "pytorch",
-    "front-end",
-    "machine-learning",
+    "front-end-torch",
     "tiny-ml",
-    "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

@@ -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
@@ -24,7 +23,13 @@
  * SOFTWARE.
  */
 
-// ---------------------- DONOT USE THESE (ENGINE INTERNALS) ----------------------
+// --------------------------------------------------------------
+// PLEASE READ THE README.md FILE BEFORE USING THIS PACKAGE!
+// This package is designed to be used in a Node.js/browser environment.
+// See the Documentation for more details.
+// --------------------------------------------------------------
+
+// ---------------------- DONOT USE THESE (ENGINE INTERNALS) ERROR/BUG ARE EXPECTED ----------------------
 export function zeros(rows, cols) { 
     return Array.from({length:rows},()=>Array(cols).fill(0)); 
 }
@@ -74,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");
@@ -745,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){