Refactors for publishing on Source Academy

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "yarn"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    groups:
+      all-updates:
+        patterns:
+          - "*"

.github/workflows/build-test-publish.yml → .github/workflows/build-test.yml

@@ -1,10 +1,10 @@
-name: Build, Test, Publish
+name: Build and Test
 
 on: [push]
 
 jobs:
-  test-publish:
-    name: Build, test, and publish package
+  test:
+    name: Build, test, and prepare docs
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -36,15 +36,13 @@ jobs:
             mkdir -p docs/media
             [ -d "build" ] && cp -r build docs/build
             [ -d "build" ] && cp -r build docs/media/build
-            [ -d "examples" ] && cp -r examples docs/examples
-            [ -d "examples" ] && cp -r examples docs/media/examples
+            [ -d "examples" ] && cp -rL examples docs/examples
+            [ -d "examples" ] && cp -rL examples docs/media/examples
 
         - uses: actions/upload-pages-artifact@v4
           with:
             path: './docs'
 
-        - run: yarn pkg-pr-new publish
-
   deploy-docs:
     environment:
       name: github-pages
@@ -53,7 +51,7 @@ jobs:
     permissions:
       pages: write
       id-token: write
-    needs: test-publish
+    needs: test
     steps:
       - uses: actions/deploy-pages@v5
         id: deployment

.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Publish package preview
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    timeout-minutes: 10
+    steps:
+        - uses: actions/checkout@v6
+        - run: corepack enable
+        - uses: actions/setup-node@v6
+          with:
+            node-version: 24
+            cache: yarn
+
+        - run: yarn install --immutable
+        - run: yarn build
+        - run: yarn pkg-pr-new publish

CONTRIBUTING.md

@@ -1,9 +1,29 @@
+## Development Commands
+
+```bash
+yarn install          # Install dependencies
+yarn build            # Build for browser and node (runs clean first)
+yarn test             # Run tests against src/ (uses mocha + tsx)
+yarn test:build       # Run tests against built library in build/
+yarn test:coverage    # Run tests with coverage report
+yarn test:watch       # Watch mode for tests (alias: yarn watch)
+yarn lint             # Lint src/ with ESLint
+yarn serve            # Serve on localhost:8080
+yarn docs             # Build TypeDoc documentation
+yarn update-tests     # Regenerate test/testcases.gen.js from scripts/generate_tests.py
+```
+
+To run a single test file:
+```bash
+yarn mocha --node-option conditions=torch-src test/tensor.test.js
+```
+
 ## Codebase Structure
 
 - [`src`](src)
     - [`index.ts`](src/index.ts) is the entry point of the library.
     - [`tensor.ts`](src/tensor.ts) is the main tensor class.
-    - [`function`](function) contains all functions that tensors can perform.
+    - [`functions`](functions) contains all functions that tensors can perform.
     - [`nn`](nn) contains all neural network modules (for everything under `torch.nn`).
     - [`optim`](optim) contains all optimizers (for everything under `torch.optim`).
     - [`creation`](creation) contains all tensor creation functions (all functions that create a tensor not from scratch, including `zeros`, `randn`).
@@ -12,7 +32,7 @@
 
 ### Development Scripts
 
-You can use `yarn watch` to automatically test after each edit.
+Use `yarn watch` (or `yarn test:watch`) to automatically re-run tests on each edit.
 
 ### Adding a new Function
 

README.md

@@ -1,6 +1,18 @@
 # torch
 machine-learning libraries for Source Academy
 
+The primary objective of this project is to create a reimplementation of PyTorch in TypeScript, with an educational focus. This project is developed with Source Academy integration in mind.
+
+This project reimplements core parts of PyTorch while trying to keep the codebase simple, and the API as close to PyTorch as possible.
+
+Using Pyodide, we can run Python code in the browser. Using `pyodide_bridge.py` in a way similar to `examples/pyodide/` we can run PyTorch-like code in the browser.
+
+## Notable differences with PyTorch
+
+- This library exposes extra information for debuggers and visualizers to catch, as seen in `events` in [`src/util.ts`](src/util.ts). It is similar to hooks in PyTorch.
+- This library does not differentiate between LongTensors and FloatTensors. It uses `number` for all tensor elements.
+- This library does not currently support devices, such as GPUs.
+
 ## Getting Started
 
 Install yarn:
@@ -48,4 +60,10 @@ yarn serve
 
 ## Contributing
 
-For detailed information on the codebase and tests, see [CONTRIBUTING.md](CONTRIBUTING.md).
+Contributions are welcome. The short version:
+
+1. Run `yarn test` to verify everything passes.
+2. Add tests for new ops or behaviour changes.
+3. Follow the existing patterns — new ops go in [src/functions/ops.ts](src/functions/ops.ts).
+
+For full details on the codebase, how to add operations, and the testing setup, see [CONTRIBUTING.md](CONTRIBUTING.md).

examples/basic_backpropagation.js

@@ -1,4 +1,4 @@
-import { Tensor } from '../build/node/torch.node.es.js';
+import { Tensor } from '../build/node/torch.node.es.mjs';
 
 const x = new Tensor([2.0], { requires_grad: true });
 const y = x.pow(new Tensor([2.0]));

examples/pyodide/.gitignore

@@ -142,3 +142,6 @@ dist
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
 .vite/
+
+# Pyodide package cache
+.pyodide-packages/