Encoding

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:

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:

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.