handwired

Handwired

The Problem

JavaScript programs are written as imperative control flow – if/else, loops, mutable state – but we often want the same logic as a differentiable model that can be evaluated on a GPU. Existing neural‑net libraries require training, whereas many use‑cases need an exact, hand‑crafted mapping from code to tensors.

What This Does

Handwired rewrites a plain JavaScript program into a small set of differentiable primitives: addition, multiplication, and ReLU. The resulting expression is a single matrix multiplication that can be executed on the CPU or WebGPU with no training required. Key files:

• src/ – core transformation engine (handwired.ts, compiler.ts)
• lab/ – experimental notebooks that import the engine (lab/cascade-argmax/cascade-argmax.ts, lab/json-search/million/run.ts)
• assets/ – demo front‑ends (assets/index.html, assets/json-search.html) that wire the engine to a UI.

How It Is Wired

Entry Point

The demo server starts from package.json (bun start). It serves assets/index.html. That page loads template/main.ts via a <script type="module">. template/main.ts imports src/handwired and registers a run handler on the demo UI.

Core Flow

1. User interaction – selecting a code snippet or data set in the UI triggers run() in template/main.ts.
2. Transformation – run() calls src/handwired.compile(code, options). * compile() parses the AST (via acorn), walks the tree, and emits a Program object containing a list of TensorOp nodes.
3. Execution – Program is fed to src/engine.ts. * engine.execute(program, { backend: "webgpu" }) builds a GPU compute pipeline: each TensorOp becomes a shader kernel; the kernels are fused into a single pass where possible.
4. Result – The GPU returns a typed array that is mapped back to the original JavaScript types and displayed in the UI.

Dependencies Outside the Repo

The only external effect is the WebGPU API, accessed through the browser; no network or file system side‑effects occur during a run.

Responsibility Map

The src modules are the single source of truth for the transformation logic; any change to handwired.compile will ripple through all demos. The experiments in lab/ exercise the API but do not alter the core.

How To Use It

# Clone the repo verbatim
git clone https://github.com/moses-y/handwired
cd handwired

# Install dependencies with bun (the repo uses bun)
bun install

# Run the local demo server
bun start

Open http://localhost:3000 to see the demo UI. No additional configuration files are required; all options are passed in‑browser via template/main.ts.

If you wish to run an experiment from the command line, e.g. the cascade‑argmax demo, use the script in lab/cascade-argmax/README.md:

bun run lab/cascade-argmax/cascade-argmax.ts

Real‑World Use

A data‑science team can embed Handwired in a web‑based analytics dashboard. They write a small JavaScript filter (e.g., x => x > 10) and, via handwired.compile, obtain a GPU‑accelerated predicate that can be applied to millions of rows in real time, without training a separate model.

Code Health & Issues

• Low – package.json declares dependencies but no lockfile (bun.lock is present, but pnpm.lock/yarn.lock missing).
• Low – docs/ contains 234 markdown files, but no README.md in src/.
• Low – No test suite for the core src/ directory; tests live only in lab/.

The Bottom Line

Handwired offers a niche but powerful way to turn imperative JavaScript into a differentiable, GPU‑ready tensor expression. The core logic is neatly isolated in src/, and demos are straightforward to run. The lack of a lockfile and missing unit tests for the library are minor operational concerns. Engineers needing exact, zero‑training neural‑net equivalents for small code snippets will find this useful.