# Models

> UForm for Swift

Residency is the constructor's name, as in the C lifecycle verbs, so a residency a build lacks has no constructor to call.

```swift
let inRam = try Model.loadRam(path: "model.safetensors", memoryDomains: [0], quantization: .bf16)
let inVram = try Model.loadVram(path: "model.safetensors", executor: deviceStreams, devices: [0, 1])
let fromBytes = try Model.loadRamBuffer(checkpoint.span.bytes, quantization: .e4m3)
let description = try inRam.describe()
print(description.dimensions, description.context, description.quantization, description.memoryUsage)
print(description.cpuClass, description.tokenWidth, description.choiceTemperatureGroups)
```

`quantization` is the scalar the transformer blocks run in: `bf16` as the checkpoint stores it, or `e4m3` quantized at load.
Every RAM load and executor takes a `cpuClass` pin, and every VRAM one a `gpuClass`, dispatching as if the hardware were of that class; nil derives its own.
`describe()` reports the class the model runs as, nil on the other residency, the `tokenWidth` of its token head, and its `choiceTemperatureGroups`, each zero when the checkpoint carries no such head.
`gpuDevices()` lists every GPU the process can drive, and a device's position in it is the ordinal `devices` names it by.

```swift
let pinned = try Model.loadRam(path: "model.safetensors", cpuClass: CPUClass(name: "intel-haswell"))
for (ordinal, device) in try gpuDevices().enumerated() { print(ordinal, device.name, device.gpuClass!) }
```

`import UForm`

## ModelDescription

What a loaded model reports about itself.

```swift
struct ModelDescription
```

Mirrors `uform_model_description_t`.

Conforms to: `Sendable`

## dimensions

Scalars per embedding row; Matryoshka prefixes of it are embeddings too.

```swift
var dimensions: Int
```

## context

Tokens one item may span before it is truncated.

```swift
var context: Int
```

## quantization

The scalar the transformer blocks run in.

```swift
var quantization: Scalar
```

## memoryUsage

Bytes the model holds; activations are the executor's.

```swift
var memoryUsage: Int
```

## cpuClass

The class a RAM model's tower was packed for, or nil for a VRAM model.

```swift
var cpuClass: CPUClass?
```

## gpuClass

The class every replica of a VRAM model runs as, or nil for a RAM model.

```swift
var gpuClass: GPUClass?
```

## tokenWidth

Scalars per token vector; zero when the checkpoint carries no token head.

```swift
var tokenWidth: Int
```

## choiceTemperatureGroups

Question types the choice temperatures were calibrated over: zero without the byte decoder, one when uncalibrated.

```swift
var choiceTemperatureGroups: Int
```

## Model

A loaded encoder: its weights, their packed copies, and on a GPU the session its attention runs on.

```swift
final class Model
```

One model serves every modality it was trained on and is freely shareable across threads. Every
verb called on the model runs on the calling thread and blocks until final; `on(_:)` runs the
same verbs on an executor, and `deferred(_:)` submits them there.

Conforms to: `Sendable`

## textEncode

Encodes UTF-8 texts, a byte per token.

```swift
func textEncode(
    _ texts: [String],
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

Calls `uform_text_encode`.

## imageEncode

Decodes and encodes JPEG, PNG or WebP files.

```swift
func imageEncode(
    _ images: [[UInt8]],
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

Calls `uform_image_encode`.

## imageEncodePixels

Encodes decoded images of interleaved 8-bit RGB, item `i` holding `heights[i]` rows of `widths[i]` pixels.

```swift
func imageEncodePixels(
    _ pixels: [[UInt8]],
    heights: [UInt32],
    widths: [UInt32],
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

Calls `uform_image_encode_pixels`.

## videoEncode

Decodes and encodes MP4 or WebM clips.

```swift
func videoEncode(
    _ videos: [[UInt8]],
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

Calls `uform_video_encode`.

## audioEncode

Decodes and encodes WAV, FLAC, MP3 or Opus recordings.

```swift
func audioEncode(
    _ recordings: [[UInt8]],
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

Calls `uform_audio_encode`.

## audioEncodeSamples

Encodes decoded mono recordings sharing one [`sampleRate`](https://www.unum.cloud/docs/uform/swift/training.md#sampleRate), resampled to the model's where it differs.

```swift
func audioEncodeSamples(
    _ samples: [[Float]],
    sampleRate: UInt32,
    outputs: Outputs = .embeddings,
    arena: Arena,
    config: EncodeConfig = EncodeConfig()
) throws(UFormError) -> Encoded
```

Calls `uform_audio_encode_samples`.

## textChoose

Scores each text's legal `choices`, one byte each, through one forward, a softmax over them alone at the calibrated inverse temperature of the item's [`temperatureGroups`](https://www.unum.cloud/docs/uform/swift/training.md#temperatureGroups) entry; nil puts every item in group zero.

```swift
func textChoose(
    _ texts: [String],
    choices: [[UInt8]],
    temperatureGroups: [UInt32]? = nil,
    arena: Arena,
    progress: Progress? = nil,
    progressSteps: Int = 0
) throws(UFormError) -> Chosen
```

The call appends the mask byte, and a text longer than the
context loses its head. A model without the byte decoder reports [`unsupported`](https://www.unum.cloud/docs/uform/swift/errors.md#unsupported). [`progress`](https://www.unum.cloud/docs/uform/swift/encoding.md#progress)
hears items scored. Calls `uform_text_choose`.

## loadRam

Copies a safetensors checkpoint file into host memory on `memoryDomains`, an empty list deriving every node the process may allocate on, and packs it for the CPU.

```swift
static func loadRam(
    path: String,
    executor: Executor? = nil,
    memoryDomains: [Int32] = [],
    cpuClass: CPUClass? = nil,
    quantization: Scalar = .bf16,
    progress: Progress? = nil,
    progressSteps: Int = 0
) throws(UFormError) -> Model
```

[`quantization`](#quantization) is
the scalar the blocks run in: [`bf16`](https://www.unum.cloud/docs/uform/swift/encoding.md#bf16) as stored, or [`e4m3`](https://www.unum.cloud/docs/uform/swift/encoding.md#e4m3) quantized at load. A [`cpuClass`](#cpuClass)
packs as if the CPU were of that class; nil derives its own. [`progress`](https://www.unum.cloud/docs/uform/swift/encoding.md#progress) hears tensors
placed. Calls `uform_model_load_ram`.

## loadRamBuffer

Copies a checkpoint held in memory into host memory, as [`loadRam`](#loadRam) does a path; nothing of `buffer` is kept.

```swift
static func loadRamBuffer(
    _ buffer: RawSpan,
    executor: Executor? = nil,
    memoryDomains: [Int32] = [],
    cpuClass: CPUClass? = nil,
    quantization: Scalar = .bf16,
    progress: Progress? = nil,
    progressSteps: Int = 0
) throws(UFormError) -> Model
```

Calls `uform_model_load_ram_buffer`.

## loadVram

Copies a checkpoint file onto the named GPUs, replicated on each, an empty list deriving one free device, and packs it there.

```swift
static func loadVram(
    path: String,
    executor: Executor? = nil,
    devices: [Int32] = [],
    gpuClass: GPUClass? = nil,
    quantization: Scalar = .bf16,
    progress: Progress? = nil,
    progressSteps: Int = 0
) throws(UFormError) -> Model
```

A [`gpuClass`](#gpuClass) dispatches every device as that class; nil
derives theirs. Calls `uform_model_load_vram`.

## loadVramBuffer

Copies a checkpoint held in memory onto the named GPUs, as [`loadVram`](#loadVram) does a path.

```swift
static func loadVramBuffer(
    _ buffer: RawSpan,
    executor: Executor? = nil,
    devices: [Int32] = [],
    gpuClass: GPUClass? = nil,
    quantization: Scalar = .bf16,
    progress: Progress? = nil,
    progressSteps: Int = 0
) throws(UFormError) -> Model
```

Calls
`uform_model_load_vram_buffer`.

## on

The same verbs, blocking on `executor` after every call submitted there before them.

```swift
func on(_ executor: Executor) -> ModelOn
```

Binding-only: names the executor every call passes.

## deferred

The same verbs, submitted to `executor` and answered at once as a [`Deferred`](https://www.unum.cloud/docs/uform/swift/receivers-and-deferred-calls.md#Deferred).

```swift
func deferred(_ executor: Executor) -> ModelDeferredOn
```

Binding-only:
names the executor and the deferred completion every call passes.

## describe

Reports the model's geometry and placement.

```swift
func describe() throws(UFormError) -> ModelDescription
```

Calls `uform_model_describe`.