# Quick start

> [!NOTE]
> gpu-engine is pre-release and not published on npm yet (`package.json` is marked `private: true`). Build a local tarball from the repository as shown in step 1; every step below runs today. WebGPU parity has been tested on a software adapter (llvmpipe) only; real GPUs and real browsers have not been run. You can also typecheck example model files in the browser on the [playground](https://gpu-engine.dev/playground) (typechecking only; it does not run `defineModel`). See [Status](https://gpu-engine.dev/docs/start/status).

| Step | What it does |
| --- | --- |
| 1. Build tarball and scaffold | Packs gpu-engine locally, runs `gpu-engine new` for a `tag`, `pooled` or `retrieve` starter, installs the tarball and checks with `doctor` |
| 2. Define the model | Declares features, `net`, head, int6 QAT and budgets; validates at define time |
| 3. Define evaluation | Declares data folders, dataset rules, training options, metric, baselines, gate, parity and optional ship options |
| 4. Tune on dev | Runs level 1 scan, data checks, training and dev gate; writes `.gpu-engine/candidate.bin` and logs one try |
| 5. Promote and verify | Performs the one counted test read, gates dev and test, writes weights and reports, and verifies without reading test data |
| 6. Check parity | Compares trainer, CPU and WGSL on dev and edge fixtures and writes `parity.json` |
| 7. Build, load and run | Bundles `dist/index.mjs` with zero dependencies, or loads the weights file with `loadModel` on CPU or WebGPU |

::tutorial-step{title="Build the tarball and scaffold a model package"}
## Build the tarball and scaffold a model package

Until gpu-engine is published on npm, build and pack a local tarball from the repository, scaffold a package with `gpu-engine new`, and install the tarball as a devDependency:

```sh
# build and pack gpu-engine
git clone https://github.com/onmax/gpu-engine && cd gpu-engine
pnpm install && pnpm build && pnpm pack --pack-destination ..
cd ..

# scaffold a model package (head: tag, pooled or retrieve)
node gpu-engine/dist/cli.mjs new my-model --head tag
cd my-model
npm install --save-dev ../gpu-engine-0.0.0.tgz
npx gpu-engine doctor
```

`gpu-engine new` creates `<name>.model.ts`, `<name>.eval.ts`, `src/decode.ts`, `src/index.ts`, `src/weights.ts`, `scripts/build.ts`, `AGENTS.md`, `SPEC.md`, `skills/gpu-engine/SKILL.md`, `.github/workflows/ci.yml`, `package.json`, `tsconfig.json` and `.gitignore` (plus `data/table.jsonl` and `src/table.ts` for `--head retrieve`). It writes no data files: the starter's generators run on the first `loop`, and a fresh package passes `doctor`.
::

::tutorial-step{title="Define the model"}
## Define the model

Put one `*.model.ts` file in the package root and default-export `defineModel(...)`. `defineModel` runs define-time checks immediately and throws a `GpuEngineError` with a fix if layer order, shapes, labels or budgets are invalid. Keep the starter `my-model.model.ts`, `my-model.eval.ts` and `src/decode.ts` from step 1 to run steps 4 through 7 right away; if you replace them for your own task like the minimal examples in steps 2 and 3, also update `src/decode.ts` for your labels, supply data files or `generate` functions, and keep `ship` so `doctor` runs the packed-file and ship-size checks.

```ts [my-model.model.ts]
import { defineModel, features as f, int6, layers as l } 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 },
})
```

All fields, head kinds (`tag`, `pooled`, `retrieve`) and define-time error codes are documented on [Define a model](https://gpu-engine.dev/docs/build/define-a-model).
::

::tutorial-step{title="Define evaluation and data splits"}
## Define evaluation and data splits

Put one `*.eval.ts` file beside the model file. Every section is written out explicitly: `sets`, `data`, `train`, `metric`, `baselines`, `gate` and `parity` (plus optional `decode`, `ship`, and `table` for `retrieve` heads). `defineEval` rejects any set path that points outside `data/train/`, `data/dev/` or `data/test/` (or any `table` path inside them) with `DEFINE_SET_FOLDER`.

```ts [my-model.eval.ts]
import { defineDataset, defineEval, sealed, tokenize } from 'gpu-engine'
import type { ModelOutput } from 'gpu-engine'
import type model from './my-model.model.ts'

type Tags = ModelOutput<typeof model>

export default defineEval<Tags>({
  sets: { train: 'data/train/*.jsonl', dev: 'data/dev/*.jsonl', test: sealed('data/test/*.jsonl') },
  data: defineDataset<Tags>({ seed: 1, minSize: { train: 2_000, dev: 300, test: 300 } }),
  train: { seeds: [1, 2, 3], epochs: 20, batch: 32, learningRate: 0.01, warmup: 0.1, budgetSeconds: 40 },
  metric: (pred, gold) => (pred.length === gold.length && pred.every((tag, i) => tag === gold[i]) ? 1 : 0),
  baselines: { rules: (input) => tokenize(input).map((): Tags[number] => 'none') },
  gate: { floors: 'promoted', noise: 0.05 },
  parity: { tolerance: 1e-3 },
})
```

Because this eval defines no `generate` functions, add JSONL files to `data/train/`, `data/dev/` and `data/test/` before running step 4, with at least 2,000 rows per file in `data/train/`, 300 per file in `data/dev/` and 300 per file in `data/test/` (matching `minSize`). Otherwise `gpu-engine loop` exits 1 with `DATA_SET_MISSING`. If you kept the starter from `gpu-engine new`, it already declares `generate: { train, dev, test }`, so the starter's generators fill the empty sets on the first `loop`. Run `npx gpu-engine doctor` to verify the package statically before training.
::

::tutorial-step{title="Tune on dev"}
## Tune on dev

`gpu-engine loop` scans the codebase for stray test-folder references, runs the data step (generating empty sets if declared, running section 7 checks and recording `data.lock.json`), trains all seeds with int6 QAT, scores the candidate on dev, checks the dev gate, writes `.gpu-engine/candidate.bin` and appends one row to `tries.jsonl`.

```sh
npx gpu-engine loop --log "starter"
npx gpu-engine loop --fail
npx gpu-engine loop --mark kept
```

Use `loop --fail` to inspect every dev example where the candidate scores below the oracle, and `loop --mark kept` or `--mark dropped` to record your decision on the last try once its dev score is known. You can inspect a single input at any time with `npx gpu-engine inspect "call me tomorrow at 5pm"`. None of these commands read `data/test/`.
::

::tutorial-step{title="Promote and verify"}
## Promote and verify

Once dev scores look ready, promote the candidate:

```sh
npx gpu-engine promote
npx gpu-engine promote --verify
```

`promote` is the only command that reads `data/test/`. It logs the read in `reads.jsonl`, mutes package output while scoring test sets, checks all gate floors and budgets, scans every outgoing string for test inputs, and on a pass writes `weights/<name>.bin`, `src/weights.ts`, `gate.json`, `report.json`, `MODEL_CARD.md` and `RESULTS.md`.

`promote --verify` is the CI gate. It checks the committed promotion, re-scores dev and regenerates `MODEL_CARD.md`, `RESULTS.md` and `src/weights.ts` byte for byte without reading test data. To encrypt `data/test/` so only CI can decrypt it (level 3), run `npx gpu-engine promote --seal`; see [Evaluate and promote](https://gpu-engine.dev/docs/build/evaluate-and-promote#level-3-sealing).
::

::tutorial-step{title="Check backend parity"}
## Check backend parity

Install the `webgpu` package as a devDependency of the model package (on Linux without a GPU, also install `mesa-vulkan-drivers` for Mesa lavapipe), then run `gpu-engine parity`:

```sh
npm install --save-dev webgpu@^0.6.2
npx gpu-engine parity
```

`parity` loads the promoted weights from `weights/<name>.bin`, compares trainer vs CPU (must be bitwise identical) and CPU vs WGSL on every dev input plus four edge inputs, enforces `eval.parity.tolerance`, writes `parity.json` and regenerates `MODEL_CARD.md`. It never reads the test set.
::

::tutorial-step{title="Build, load and run the model"}
## Build, load and run the model

In a scaffolded package, build the zero-dependency ES module (`dist/index.mjs`, containing `src/index.ts`, the gpu-engine runtime, `src/decode.ts` and the promoted weights):

```sh
npm run build
npx gpu-engine doctor
```

Running `doctor` after `npm run build` also runs the ship checks against `dist/`.

To load the weights file directly with `loadModel`, pass `weights/<name>.bin` (or `.gpu-engine/candidate.bin` before promotion) and set `backend` explicitly (`'auto'`, `'webgpu'` or `'cpu'`). `run` returns `[error, data]` and never throws.

```ts
import { readFile } from 'node:fs/promises'
import { loadModel } from 'gpu-engine'
import definition from './my-model.model.ts'

const model = await loadModel(await readFile('weights/my-model.bin'), { backend: 'auto', definition })
const [error, tags] = await model.run('call me tomorrow at 5pm')
console.log(error ?? tags, model.inspect())
```

See [Run a model](https://gpu-engine.dev/docs/build/run-a-model) for WebGPU setup in Node, `retrieve` tables, backend selection rules and the weights file format.
::

Source: SPEC sections 5, 6, 7, 9, 10, 11 and 12, and README.

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

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

Next: [Rules for agents](https://gpu-engine.dev/raw/docs/start/agents.md)

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