# Encoding

> UForm for Python

One verb per input form, each spelled as in C:

- `text_encode(texts, arena)` takes UTF-8 texts, a byte per token, since models are tokenizer-free.
- `image_encode(files, arena)` takes JPEG, PNG or WebP files.
- `image_encode_pixels(pixels, arena)` takes C-contiguous `[height, width, 3]` `uint8` buffers.
- `video_encode(files, arena)` takes MP4 or WebM clips.
- `audio_encode(files, arena)` takes WAV, FLAC, MP3 or Opus recordings.
- `audio_encode_samples(samples, sample_rate, arena)` takes 1-D `float32` buffers.

A batch is a sequence of separate objects, `str` or bytes-like for texts and bytes-like for files, gathered into one tape with one copy.
A `(data, offsets)` tuple of buffers, the data and `count + 1` `size_t` offsets, is lent to the library as a tape without a copy:

```python
data = b"first documentthe second"
offsets = np.array([0, 14, 24], dtype=np.uint64)
encoded = model.text_encode((data, offsets), arena)
```

`outputs` names the surfaces a call keeps, and decides which C output pointers the binding passes:

```python
encoded = model.text_encode(texts, arena, outputs=uform.Outputs.EMBEDDINGS | uform.Outputs.STATES)
embeddings, states, token_vectors = encoded  # an `ArenaBuffer` of (count, dimensions), a `RowsTape`, and None
offsets = np.asarray(states.offsets)  # item `i` spans rows `offsets[i]` up to `offsets[i + 1]`
```

`Outputs.EMBEDDINGS` is the default, and a surface left out answers `None` and costs nothing past the final norm.
`Outputs.TOKEN_VECTORS` keeps the token head's unit vectors, a `RowsTape` of `(tokens, token_width)` on the states' offsets, for late-interaction reranking; a model whose `describe().token_width` is zero raises `UnsupportedError`.
`outputs_scalar` picks the scalar every output lands as, `Scalar.F32` by default; `Scalar.BF16` outputs export as raw bytes, a `(count, row_bytes)` run of `'B'`.
`stats=uform.TextEncodeStats()` and its siblings are overwritten with the truncated items and the encoded tokens.
`progress=handler` is called with `(completed, total)` items, and a handler returning `False` stops the call, which raises `uform.CancelledError`; one that raises stops it too, and its own exception reaches the caller.

`import uform`

`from uform import RowsTape, Encoded, TextEncodeStats, …`

## Scalar

A scalar type a model computes in or its outputs land as, valued as `uform_scalar_t`.

```python
class Scalar(IntEnum)
```

- `F64` = `1`
- `F32` = `2`
- `BF16` = `3`
- `F16` = `4`
- `E5M2` = `5`
- `E4M3` = `6`
- `E3M2` = `7`
- `E2M3` = `8`
- `I8` = `10`
- `I4X2` = `11`
- `I32` = `12`
- `U8` = `20`
- `U4X2` = `21`
- `U1X8` = `22`

## Outputs

Which surfaces an encoding keeps, deciding which of the C output pointers the binding passes.

```python
class Outputs(IntFlag)
```

- `EMBEDDINGS` = `1`
- `STATES` = `2`
- `TOKEN_VECTORS` = `4`

## RowsTape

A ragged run of rows in an [`Arena`](https://www.unum.cloud/docs/uform/python/arenas.md#Arena), one per token each item kept or one value per choice, split by offsets.

```python
class RowsTape(ArenaBuffer)
```

## offsets

(count + 1,) Apache Arrow offsets into the rows.

```python
offsets: ArenaBuffer
```

## Encoded

What an encoding wrote into its arena, unpacking as `embeddings, states, token_vectors = encoded`.

```python
class Encoded(structseq[Any], tuple[ArenaBuffer | None, RowsTape | None, RowsTape | None])
```

## embeddings

The (count, dimensions) pooled embeddings, or None when not asked for.

```python
embeddings: ArenaBuffer | None
```

## states

The (tokens, dimensions) final-norm states and their offsets, or None when not asked for.

```python
states: RowsTape | None
```

## token_vectors

The (tokens, token_width) unit vectors of the token head, offset as the states, or None.

```python
token_vectors: RowsTape | None
```

## TextEncodeStats

What [`text_encode`](https://www.unum.cloud/docs/uform/python/models.md#text_encode) and [`text_choose`](https://www.unum.cloud/docs/uform/python/models.md#text_choose) report, overwritten by every call it is passed to.

```python
class TextEncodeStats
```

## truncated

Items cut at the model's context.

```python
truncated: int
```

## tokens

Tokens the call encoded, after truncation.

```python
tokens: int
```

## ImageEncodeStats

What [`image_encode`](https://www.unum.cloud/docs/uform/python/models.md#image_encode) and [`image_encode_pixels`](https://www.unum.cloud/docs/uform/python/models.md#image_encode_pixels) report, overwritten by every call it is passed to.

```python
class ImageEncodeStats
```

## truncated

Items cut at the model's context.

```python
truncated: int
```

## tokens

Tokens the call encoded, after truncation.

```python
tokens: int
```

## VideoEncodeStats

What [`video_encode`](https://www.unum.cloud/docs/uform/python/models.md#video_encode) reports, overwritten by every call it is passed to.

```python
class VideoEncodeStats
```

## truncated

Items cut at the model's context.

```python
truncated: int
```

## tokens

Tokens the call encoded, after truncation.

```python
tokens: int
```

## AudioEncodeStats

What [`audio_encode`](https://www.unum.cloud/docs/uform/python/models.md#audio_encode) and [`audio_encode_samples`](https://www.unum.cloud/docs/uform/python/models.md#audio_encode_samples) report, overwritten by every call it is passed to.

```python
class AudioEncodeStats
```

## truncated

Items cut at the model's context.

```python
truncated: int
```

## tokens

Tokens the call encoded, after truncation.

```python
tokens: int
```