# Train a tiny model in seconds. Ship it in kilobytes.

[Pre-release: models train with loop and run on the CPU or WebGPU, promote is landing](https://gpu-engine.dev/docs/start/status)

# Train a tiny model in seconds. Ship it in kilobytes.

A framework to build, tune and ship models from a few kilobytes to 1 MB, on WebGPU with a CPU fallback and zero runtime dependencies.

- [Read the quick start](https://gpu-engine.dev/docs/start/quick-start)
- [Train your own](https://gpu-engine.dev/playground)

> [!NOTE]
> gpu-engine is pre-release and not on npm yet. Today the definitions run their define-time checks, `gpu-engine loop` checks the data, trains a `tag` or `pooled` model with int6 quantization, scores it on dev and logs the try, and `loadModel` runs the weights file on the CPU or on WebGPU. `promote`, the `parity` command, the scaffold and the `retrieve` head are planned for milestones M2 to M6. See [Status](https://gpu-engine.dev/docs/start/status).

## Define a model in TypeScript

A model definition names its token features, every layer in `net`, its head, quantization and budgets. `defineModel` checks it today and throws an error with a fix when the layout cannot work.

```ts [my-model.model.ts]
import { defineModel, features as f, layers as l, int6 } from 'gpu-engine'

export default defineModel({
  name: 'my-model',
  input: f.tokens({ max: 64, rows: [f.shape(), f.hash({ buckets: 128, k: 2 })] }),
  net: [l.embed(20), l.conv({ taps: 3 }), l.biScan(20), l.dense(20, 'relu')],
  head: { kind: 'tag', labels: ['start', 'inside', 'none'] },
  quant: int6({ qatFrom: 0.7 }),
  budgets: { brotliBytes: 5_000, macsPerToken: 3_200 },
})
```

## The pipeline

A model runs in four steps: `featurize -> net (closed layer catalog) -> head -> decode`.

| Step | Who writes it | Output |
| --- | --- | --- |
| `featurize` | gpu-engine, configured by the model definition | Feature rows per token |
| `net` | gpu-engine, from the layer catalog | A hidden vector per token |
| `head` | gpu-engine, one of the head kinds | Tags or scores |
| `decode` | You, in plain code | Your typed result |

The decode step is always your own plain code. gpu-engine never owns it.

## Design targets

### [An explicit net, with no presets](https://gpu-engine.dev/docs/build/define-a-model)

You list every layer from the closed catalog in `net`. The library does not hide the model behind presets.

### [A score from a sealed test set](https://gpu-engine.dev/docs/build/evaluate-and-promote)

The tune loop scores on dev in under a minute. Only `promote` reads `data/test/`, and every read is counted and reported.

### [One weights file on every backend](https://gpu-engine.dev/docs/build/run-a-model)

The same int6 weights file runs on WebGPU with hand-written WGSL and on the CPU fallback, with zero runtime dependencies.

## Written for coding agents

The primary user is a coding agent, with a developer directing it. This site serves agent-readable copies today:

- `/llms.txt` lists every page in the site, and `/llms-full.txt` puts every page in one file.
- `/raw/<page>.md` serves the Markdown source of any page.

In M4, `gpu-engine new` scaffolds an `AGENTS.md` and the npm package ships `skills/gpu-engine/SKILL.md`. See [Rules for agents](https://gpu-engine.dev/docs/start/agents).

## Milestones

| Milestone | Scope | Status |
| --- | --- | --- |
| M0 | Repository skeleton, SPEC.md, AGENTS.md, public types | Done |
| M1 | Model kit for `tag` on CPU: featurizer, layers, trainer, QAT, weights format | Done |
| M2 | Harness: datasets, loop, gate, sealed test set, promote | In progress: `loop` and the gate work |
| M3 | WGSL runtime and parity | In progress: the WebGPU runtime works |
| M4 | Scaffold, skill and docs | Planned |
| M5 | `pooled` head | In progress: the head is done |
| M6 | `retrieve` head | Planned |

See [Status](https://gpu-engine.dev/docs/start/status) for done criteria and open questions.

Source: SPEC sections 1, 4, 5, 8, 12 and 15.

<!-- vitehub-docs:section-links -->
All pages: [llms.txt](https://gpu-engine.dev/llms.txt)
