# Models

> UForm for JavaScript

Dispatch picks a CPU or GPU class on its own, and `cpuClass` or `gpuClass` pins one by its name:

```javascript
for (const { name, gpuClass, memoryBytes } of gpuDevices()) console.log(name, gpuClass, memoryBytes);
const portable = Model.loadRam("model.safetensors", { cpuClass: "intel-haswell" });
console.log(portable.describe().cpuClass); // "intel-haswell"
```

`import * as uform from 'uform';`

`import { Model } from 'uform';`

## ModelLoadRamConfig

Where a checkpoint loaded into host memory lands.

```typescript
interface ModelLoadRamConfig
```

Mirrors `uform_model_load_ram_t`.

- `executor?` `Executor`: The executor the load runs on; absent loads on the calling thread.
- `memoryDomains?` `number[]`: NUMA node IDs to place the weights in; absent derives every node.
- `cpuClass?` `string`: The CPU class to pack the tower for, spelled like "intel-haswell"; absent derives the CPU's own.
- `quantization?` `Scalar`: The scalar the transformer blocks run in: `bf16` as the checkpoint stores it, the default, or `e4m3`.

## ModelLoadVramConfig

Where a checkpoint loaded into device memory lands.

```typescript
interface ModelLoadVramConfig
```

Mirrors `uform_model_load_vram_t`.

- `executor?` `Executor`: The executor the upload runs on, one stream per device; absent uploads on the calling thread.
- `devices?` `number[]`: Device ordinals, positions in `gpuDevices()`, to replicate the weights on; absent takes one free device.
- `gpuClass?` `string`: The GPU class every replica runs as, spelled like "nvidia-hopper"; absent derives the devices' own.
- `quantization?` `Scalar`: The scalar the transformer blocks run in: `bf16` as the checkpoint stores it, the default, or `e4m3`.

## ModelDescription

What a loaded model reports about itself.

```typescript
interface ModelDescription
```

Mirrors `uform_model_description_t`.

- `dimensions` `number`: Scalars per embedding row; Matryoshka prefixes of it are embeddings too.
- `context` `number`: Tokens one item may span before it is truncated.
- `quantization` `Scalar`: The scalar the transformer blocks run in.
- `memoryUsage` `number`: Bytes the model holds; activations are the executor's.
- `cpuClass` `string | null`: The CPU class a RAM model's tower was packed for, like "intel-haswell"; `null` for a VRAM model.
- `gpuClass` `string | null`: The GPU class every replica of a VRAM model runs as, like "nvidia-hopper"; `null` for a RAM model.
- `tokenWidth` `number`: Scalars per token vector; zero when the checkpoint carries no token head.
- `choiceTemperatureGroups` `number`: Question types the choice temperatures were calibrated over: zero without the byte decoder, one uncalibrated.

## Model

A loaded encoder, running every verb on the calling thread.

```typescript
class Model extends ModelOn implements Disposable
```

`on(executor)` and `deferred(executor)` reach the same verbs on an executor. One model serves every modality it was trained on.

## loadRam

Copies a safetensors checkpoint file into host memory and packs it for the CPU.

```typescript
static loadRam(
    path: string,
    config: ModelLoadRamConfig = {},
): Model
```

Calls `uform_model_load_ram`.

- `path`: The checkpoint, read in full and closed before the load completes.
- `config`: The executor, the NUMA nodes, and the block scalar.

## loadRamBuffer

Copies a checkpoint held in memory into host memory, which is how a page loads one it fetched.

```typescript
static loadRamBuffer(
    buffer: ArrayBuffer | ArrayBufferView,
    config: ModelLoadRamConfig = {},
): Model
```

Calls `uform_model_load_ram_buffer`.

- `buffer`: The checkpoint bytes, copied before the load completes.
- `config`: The executor, the NUMA nodes, and the block scalar.

## loadVram

Copies a checkpoint file onto the named GPUs and packs it there.

```typescript
static loadVram(
    path: string,
    config: ModelLoadVramConfig = {},
): Model
```

Calls `uform_model_load_vram`.

- `path`: The checkpoint, read in full and closed before the load completes.
- `config`: The executor, the devices, and the block scalar.

## loadVramBuffer

Copies a checkpoint held in memory onto the named GPUs.

```typescript
static loadVramBuffer(
    buffer: ArrayBuffer | ArrayBufferView,
    config: ModelLoadVramConfig = {},
): Model
```

Calls `uform_model_load_vram_buffer`.

- `buffer`: The checkpoint bytes, copied before the load completes.
- `config`: The executor, the devices, and the block scalar.

## on

The same verbs, each blocking on [`executor`](#executor), after every earlier submission to it.

```typescript
on(executor: Executor): ModelOn
```

Binding-only.

- `executor`: The threads or streams to run on; its residency must match the model's.

## deferred

The same verbs, each submitted to [`executor`](#executor) and answered as a [`Deferred`](https://www.unum.cloud/docs/uform/javascript/errors.md#Deferred).

```typescript
deferred(executor: Executor): ModelDeferredOn
```

Binding-only.

- `executor`: The threads or streams to run on; its residency must match the model's.

## free

Releases the weights now, waiting for every deferred call naming the model; a second [`free`](https://www.unum.cloud/docs/uform/javascript/training.md#free) does nothing.

```typescript
free(): void
```

Calls `uform_model_free`.

## describe

Reports the model's geometry and placement in one call.

```typescript
describe(): Answer<Receiving, ModelDescription>
```

Calls `uform_model_describe`.

## textEncode

Encodes texts through one forward; every UTF-8 byte is a token.

```typescript
textEncode(
    texts: readonly (string | Uint8Array)[] | Tape<Uint8Array>,
    arena: Arena,
    config: EncodeConfig = {},
): Answer<Receiving, Encoded>
```

Calls `uform_text_encode`.

- `texts`: Strings, UTF-8 bytes already encoded, or a tape of them.
- `arena`: The memory the outputs land in, rewound by the call.
- `config`: The surfaces, their scalar, and a progress handler.

## textChoose

Scores each item's legal choices through one forward, a softmax over them alone at the item's group's calibrated inverse temperature; a model without the byte decoder reports `unsupported`.

```typescript
textChoose(
    texts: readonly (string | Uint8Array)[] | Tape<Uint8Array>,
    choices: readonly (string | Uint8Array)[] | Tape<Uint8Array>,
    arena: Arena,
    config: ChooseConfig = {},
): Answer<Receiving, Chosen>
```

Calls `uform_text_choose`.

- `texts`: The states, each ending where its choice goes.
- `choices`: Each item's legal choices, one byte each, like "yn".
- `arena`: The memory the probabilities land in, rewound by the call.
- `config`: The question types and a progress handler.

## imageEncode

Decodes and encodes JPEG, PNG or WebP files; the browser build reports `unsupported`.

```typescript
imageEncode(
    images: readonly Uint8Array[] | Tape<Uint8Array>,
    arena: Arena,
    config: EncodeConfig = {},
): Answer<Receiving, Encoded>
```

Calls `uform_image_encode`.

- `images`: One encoded file per item, or a tape of them.
- `arena`: The memory the outputs land in, rewound by the call.
- `config`: The surfaces, their scalar, and a progress handler.

## imageEncodePixels

Encodes decoded images, resized on the executor's side.

```typescript
imageEncodePixels(
    images: readonly Pixels[],
    arena: Arena,
    config: EncodeConfig = {},
): Answer<Receiving, Encoded>
```

Calls `uform_image_encode_pixels`.

- `images`: `ImageData`, or RGB or RGBA bytes with their width and height.
- `arena`: The memory the outputs land in, rewound by the call.
- `config`: The surfaces, their scalar, and a progress handler.

## videoEncode

Decodes and encodes MP4 or WebM clips; the browser build reports `unsupported`.

```typescript
videoEncode(
    videos: readonly Uint8Array[] | Tape<Uint8Array>,
    arena: Arena,
    config: EncodeConfig = {},
): Answer<Receiving, Encoded>
```

Calls `uform_video_encode`.

- `videos`: One encoded file per item, or a tape of them.
- `arena`: The memory the outputs land in, rewound by the call.
- `config`: The surfaces, their scalar, and a progress handler.

## audioEncode

Decodes and encodes WAV, FLAC, MP3 or Opus files; the browser build reports `unsupported`.

```typescript
audioEncode(
    recordings: readonly Uint8Array[] | Tape<Uint8Array>,
    arena: Arena,
    config: EncodeConfig = {},
): Answer<Receiving, Encoded>
```

Calls `uform_audio_encode`.

- `recordings`: One encoded file per item, or a tape of them.
- `arena`: The memory the outputs land in, rewound by the call.
- `config`: The surfaces, their scalar, and a progress handler.

## audioEncodeSamples

Encodes decoded mono recordings, resampled to the model's rate where `sampleRate` differs.

```typescript
audioEncodeSamples(
    recordings: readonly Float32Array[] | Tape<Float32Array>,
    sampleRate: number,
    arena: Arena,
    config: EncodeConfig = {},
): Answer<Receiving, Encoded>
```

Calls `uform_audio_encode_samples`.

- `recordings`: One run of samples per item, or a tape of them.
- `sampleRate`: Samples per second shared by every recording.
- `arena`: The memory the outputs land in, rewound by the call.
- `config`: The surfaces, their scalar, and a progress handler.

## executor

The executor the verbs run on; absent runs them on the calling thread.

```typescript
readonly executor: Executor | undefined
```