# What is gpu-engine

> [!NOTE]
> gpu-engine is pre-release and not published on npm yet (`package.json` is marked `private: true`). All v1 milestones (M0 through M6) are done: `new`, `loop`, `promote` (with `--verify` and `--seal`), `parity`, `inspect`, `doctor`, ship checks, all four layers and all three heads (`tag`, `pooled`, `retrieve`) work on CPU and WebGPU. WebGPU tests, `parity` and the `auto` threshold ran on a software adapter (llvmpipe) only; real GPUs and real browsers have not been run. Later-version features in SPEC section 6 (provenance, blind second labels, warm start, distillation and sweeps) are not implemented yet. See [Status](https://gpu-engine.dev/docs/start/status).

## Goal

gpu-engine is a framework for building, tuning, evaluating and shipping tiny local models.

- **Small weights.** Models range from a few kilobytes to around 1 MB and train from scratch in seconds to minutes.
- **Browser first.** The primary runtime targets WebGPU with hand-written WGSL shaders.
- **CPU fallback.** The same weights file runs on the CPU in Node, on servers and in browsers without WebGPU.
- **Zero runtime dependencies.** Shipped models carry no external runtime packages.

## Package layout and entry points

The package combines two parts:

| Part | Covers |
| --- | --- |
| Model kit | Shared featurizer, closed layer catalog, trainer with int6 QAT, binary weights format, CPU runtime and WGSL runtime |
| Workflow harness | Commands and checks from definition to release: scaffolding, datasets, data locks, training loop, evaluation tables, sealed test set, parity and ship gates |

Those parts are exposed through two entry points:

| Entry | Target | Exports |
| --- | --- | --- |
| `gpu-engine` | Browser or Node | `defineModel`, `defineEval`, `defineDataset`, `features`, `layers`, `int6`, `sealed`, `tokenize`, `loadModel`, `availability`, `GpuEngineError`, and the public types |
| `gpu-engine/harness` | Node only | CLI command runners (`runNew`, `runLoop`, `runPromote`, `runParity`, `runInspect`, `runDoctor`), `loadProject`, `train`, `plan`, `forward`, weights helpers (`encode`, `decode`, `dequantize`, `toWeightsFile`), report renderers (`renderModelCard`, `renderResults`), diagnostic helpers (`diagnostics`, `diagnostic`, `engineError`, `formatDiagnostic`, `GpuEngineError`), and `TrainData` and `SealedDigest` types |

Nothing reachable from `gpu-engine` imports a `node:` module. The `gpu-engine` binary runs the [CLI](https://gpu-engine.dev/docs/reference/cli).

## The four-stage pipeline

Every model runs through four fixed stages:

```txt
featurize -> net (closed layer catalog) -> head -> decode
```

| Stage | Implemented by | Output |
| --- | --- | --- |
| `featurize` | gpu-engine, configured by `input` | Feature row indices for each token |
| `net` | gpu-engine, using the closed catalog | Hidden vector per token |
| `head` | gpu-engine, using one head kind | Token labels, whole-input scores or table rankings |
| `decode` | Your own plain TypeScript or JavaScript | Your application result |

gpu-engine stops at the head output. Turning tags, numbers or rankings into dates, filters, routes or structured objects always stays in your own `decode` function.

### Head kinds

| Kind | Output | Version and status |
| --- | --- | --- |
| `tag` | One label per token | v1. Implemented |
| `pooled` | One class label or a fixed array of numbers for the whole input | v1. Implemented |
| `retrieve` | One `{ id, score }` ranking per row of a candidate table | v1. Implemented |

## Designed for coding agents

The primary user is a coding agent working under a developer's direction.

The API stays low-level on purpose. `net` is always an explicit list of layers, with no presets or hidden defaults. In exchange, the library gives the reader four things:

| Guarantee | What it means |
| --- | --- |
| Exact layer docs | Every op lists its formula, byte cost, multiply-add cost, strengths and limits in the [layer catalog](https://gpu-engine.dev/docs/reference/layers). |
| Define-time errors with fixes | Invalid shapes, missing labels or impossible budgets throw inside `defineModel` with a code, why and fix. |
| A shipped skill | Starting layouts, tuning advice and agent rules bundled in `skills/gpu-engine/SKILL.md` and copied by `gpu-engine new`. |
| Fast iteration with an honest test score | `loop` tunes on dev in under a minute, and `promote` measures the final score on a sealed test set. |

## Non-goals

- Not a general-purpose deep-learning framework.
- No automatic differentiation. Every layer ships a hand-written backward pass.
- No large or pretrained weights.
- No hosted service or remote inference.
- No graph-to-shader compiler. Each layer carries its own WGSL template.

For the prior art that shaped this design, see SPEC section 13.

## Where to go next

- Walk through the workflow in [Quick start](https://gpu-engine.dev/docs/start/quick-start).
- Read the five rules in [Rules for agents](https://gpu-engine.dev/docs/start/agents).
- Check implemented exports and milestones in [Status](https://gpu-engine.dev/docs/start/status), or typecheck model definitions in the [playground](https://gpu-engine.dev/playground).

Source: SPEC sections 1 to 4, 11, 12 and 13.

<!-- vitehub-docs:section-links -->
## In this section

- [What is gpu-engine](https://gpu-engine.dev/raw/docs/start.md) (this page)
- [Quick start](https://gpu-engine.dev/raw/docs/start/quick-start.md)
- [Rules for agents](https://gpu-engine.dev/raw/docs/start/agents.md)
- [Status](https://gpu-engine.dev/raw/docs/start/status.md)

Next: [Quick start](https://gpu-engine.dev/raw/docs/start/quick-start.md)

All pages: [llms.txt](https://gpu-engine.dev/llms.txt)
