# Models

> UForm for Python

`uform.Model.load_ram(path)` and `uform.Model.load_vram(path, devices=[0])` copy a safetensors checkpoint into host memory or onto GPUs, and `load_ram_buffer` and `load_vram_buffer` take the checkpoint's bytes instead.
Each takes `quantization`, `Scalar.BF16` as stored or `Scalar.E4M3` quantized at load, an optional `executor` the load runs on, and a `progress` handler.
The RAM loads take a `cpu_class` pin and the VRAM loads a `gpu_class` pin, and a class the hardware cannot run raises `UnsupportedError`.
`model.describe()` answers a `uform.ModelDescription` of `dimensions`, `context`, `quantization`, `memory_usage`, `cpu_class`, `gpu_class`, `token_width` and `choice_temperature_groups`.

`from uform import ModelDescription, Model`

## ModelDescription

What a loaded model reports about itself, as `uform_model_description_t` holds it.

```python
class ModelDescription(structseq[Any], tuple[int, int, Scalar, int, CPUClass | None, GPUClass | None, int, int])
```

## dimensions

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

```python
dimensions: int
```

## context

Tokens one item may span before it is truncated.

```python
context: int
```

## quantization

The scalar the transformer blocks run in.

```python
quantization: Scalar
```

## memory_usage

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

```python
memory_usage: int
```

## cpu_class

The class a RAM model was packed for, or None for a VRAM model.

```python
cpu_class: CPUClass | None
```

## gpu_class

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

```python
gpu_class: GPUClass | None
```

## token_width

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

```python
token_width: int
```

## choice_temperature_groups

Question types [`text_choose`](#text_choose) was calibrated over: 0 without the byte decoder, 1 when uncalibrated.

```python
choice_temperature_groups: int
```

## Model

A loaded encoder serving every modality it was trained on; the receiver chooses where its verbs run.

```python
class Model
```

## load_ram

Copies a checkpoint into host memory.

```python
@classmethod
def load_ram(
    path: _PathLike,
    /,
    *,
    memory_domains: Sequence[int] | None = None,
    cpu_class: CPUClass | None = None,
    executor: Executor | None = None,
    quantization: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
) -> Model
```

Calls `uform_model_load_ram`.

## load_ram_buffer

Copies a checkpoint held in memory into host memory.

```python
@classmethod
def load_ram_buffer(
    buffer: Buffer,
    /,
    *,
    memory_domains: Sequence[int] | None = None,
    cpu_class: CPUClass | None = None,
    executor: Executor | None = None,
    quantization: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
) -> Model
```

Calls `uform_model_load_ram_buffer`.

## load_vram

Copies a checkpoint onto the named GPUs.

```python
@classmethod
def load_vram(
    path: _PathLike,
    /,
    *,
    devices: Sequence[int] | None = None,
    gpu_class: GPUClass | None = None,
    executor: Executor | None = None,
    quantization: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
) -> Model
```

Calls `uform_model_load_vram`.

## load_vram_buffer

Copies a checkpoint held in host memory onto the named GPUs.

```python
@classmethod
def load_vram_buffer(
    buffer: Buffer,
    /,
    *,
    devices: Sequence[int] | None = None,
    gpu_class: GPUClass | None = None,
    executor: Executor | None = None,
    quantization: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
) -> Model
```

Calls `uform_model_load_vram_buffer`.

## on

A receiver whose verbs block on `executor`.

```python
def on(executor: Executor, /) -> On[Model]
```

Python-only.

## deferred

A receiver whose verbs submit to `executor` and answer a [`Deferred`](https://www.unum.cloud/docs/uform/python/receivers-and-deferred-calls.md#Deferred).

```python
def deferred(executor: Executor, /) -> DeferredOn[Model]
```

Python-only.

## describe

The model's geometry and placement.

```python
def describe() -> ModelDescription
```

Calls `uform_model_describe`.

## text_encode

Encodes UTF-8 texts, a byte per token.

```python
def text_encode(
    texts: _Texts,
    arena: Arena,
    /,
    *,
    outputs: Outputs = ...,
    outputs_scalar: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: TextEncodeStats | None = None,
) -> Encoded
```

Calls `uform_text_encode`.

## image_encode

Decodes and encodes JPEG, PNG or WebP files.

```python
def image_encode(
    files: _Files,
    arena: Arena,
    /,
    *,
    outputs: Outputs = ...,
    outputs_scalar: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: ImageEncodeStats | None = None,
) -> Encoded
```

Calls `uform_image_encode`.

## image_encode_pixels

Encodes [height, width, 3] uint8 images.

```python
def image_encode_pixels(
    pixels: Sequence[Buffer],
    arena: Arena,
    /,
    *,
    outputs: Outputs = ...,
    outputs_scalar: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: ImageEncodeStats | None = None,
) -> Encoded
```

Calls `uform_image_encode_pixels`.

## video_encode

Decodes and encodes MP4 or WebM clips.

```python
def video_encode(
    files: _Files,
    arena: Arena,
    /,
    *,
    outputs: Outputs = ...,
    outputs_scalar: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: VideoEncodeStats | None = None,
) -> Encoded
```

Calls `uform_video_encode`.

## audio_encode

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

```python
def audio_encode(
    files: _Files,
    arena: Arena,
    /,
    *,
    outputs: Outputs = ...,
    outputs_scalar: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: AudioEncodeStats | None = None,
) -> Encoded
```

Calls `uform_audio_encode`.

## audio_encode_samples

Encodes 1-D float32 mono recordings.

```python
def audio_encode_samples(
    samples: Sequence[Buffer] | _Tape,
    sample_rate: int,
    arena: Arena,
    /,
    *,
    outputs: Outputs = ...,
    outputs_scalar: Scalar = ...,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: AudioEncodeStats | None = None,
) -> Encoded
```

Calls `uform_audio_encode_samples`.

## text_choose

Scores each text's single-byte choices, one probability each.

```python
def text_choose(
    texts: _Texts,
    choices: _Texts,
    arena: Arena,
    /,
    *,
    temperature_groups: _Words | None = None,
    progress: _Progress | None = None,
    progress_steps: int = 0,
    stats: TextEncodeStats | None = None,
) -> RowsTape
```

Calls `uform_text_choose`.