pub struct AudioEncode<'config, 'arena, Recordings>Calls uform_audio_encode.
One verb per input form, each spelled as in C, and each taking its inputs, the Outputs to keep, a config, and last the arena:
text_encode(texts, ..)takes UTF-8 texts, a byte per token, since models are tokenizer-free.image_encode(files, ..)takes JPEG, PNG or WebP files.image_encode_pixels(pixels, heights, widths, ..)takes interleaved 8-bit RGB,heights[i]rows ofwidths[i]pixels per item.video_encode(files, ..)takes MP4 or WebM clips.audio_encode(files, ..)takes WAV, FLAC, MP3 or Opus recordings.audio_encode_samples(samples, sample_rate, ..)takes monof32samples.
A batch is a slice, array or Vec of separate items, &str, String, &[u8] or Vec<u8>, or &[f32] and Vec<f32> for samples, gathered into one tape with one copy.
A (data, offsets) pair, the data and count + 1 offsets, is lent to the library as a tape without a copy, once the binding checks the offsets stay inside the data:
let tape = (b"first documentthe second".as_slice(), [0usize, 14, 24]);
let encoded = model.text_encode(tape, Outputs::STATES, Scalar::BF16, &mut arena)?;
let states = encoded.states.expect("STATES were asked for");
let offsets = states.offsets()?; // item `i` spans rows `offsets[i]` up to `offsets[i + 1]`
let second = states.item(1)?; // the rows of one item, as `Rows`Outputs::EMBEDDINGS is the default, | joins it with Outputs::STATES and Outputs::TOKEN_VECTORS, and a surface left out answers None and costs nothing past the final norm.
Token vectors are the token head’s unit rows, one per state, which late-interaction rerankers score; a model without the head answers Status::Unsupported.
Every bare Scalar converts into the verb’s config, the scalar every output lands as; the config’s other fields reach the knobs:
let mut stats = TextEncodeStats::default();
let mut handler = |completed, total| if completed * 2 < total { ControlFlow::Continue(()) } else { ControlFlow::Break(()) };
let config = TextEncodeConfig { stats: Some(&mut stats), progress: Some(&mut handler), ..TextEncodeConfig::from(Scalar::F32) };
let encoded = model.text_encode(&texts, Outputs::EMBEDDINGS, config, &mut arena);Rows reports its count, columns, stride and scalar, and reads as bytes through as_bytes or as values through values::<f32>(), refused when the rows hold another scalar type. RowsTape adds the offsets and an item per input.
A handler answering ControlFlow::Break stops the call, which fails with Status::Cancelled and publishes nothing.
text_choose(texts, choices, ..) scores each item’s legal choices, one byte each, through one forward, and answers a Tape of one f32 probability per choice that sums to one per item:
let config = TextChooseConfig { temperature_groups: &[0, 1], ..TextChooseConfig::default() };
let probabilities = model.text_choose(&["keep this candidate?", "expand which neighbour?"], &["yn", "ABCD"], config, &mut arena)?;
let expand: &[f32] = probabilities.item(1)?; // the probabilities of 'A' through 'D'Each group is a question type below the model’s choice_temperature_groups, and a model without the byte decoder answers Status::Unsupported.
API
StructAudioEncodeAn audio forward over encoded recordings; see EncodeVerbs::audio_encode.
StructAudioEncodeConfigThe scalar and the knobs of EncodeVerbs::audio_encode; a bare Scalar is the whole config.
pub struct AudioEncodeConfig<'config>Mirrors uform_audio_encode_t.
Fields
outputs_scalar | Scalar | The scalar type every output lands as. |
|---|---|---|
progress | Option<&'config mut ProgressCallback<'config>> | Reports the items encoded and stops wherever it says to. |
progress_steps | usize | Reports the call makes at most, the last at completion; zero derives to ten. |
stats | Option<&'config mut AudioEncodeStats> | Where the truncation report lands, overwritten by the call. |
Implements
From<Scalar>StructAudioEncodeSamplesAn audio forward over decoded samples; see EncodeVerbs::audio_encode_samples.
pub struct AudioEncodeSamples<'config, 'arena, Samples>Calls uform_audio_encode_samples.
StructAudioEncodeSamplesConfigThe scalar and the knobs of EncodeVerbs::audio_encode_samples; a bare Scalar is the whole config.
pub struct AudioEncodeSamplesConfig<'config>Mirrors uform_audio_encode_samples_t.
Fields
outputs_scalar | Scalar | The scalar type every output lands as. |
|---|---|---|
progress | Option<&'config mut ProgressCallback<'config>> | Reports the items encoded and stops wherever it says to. |
progress_steps | usize | Reports the call makes at most, the last at completion; zero derives to ten. |
stats | Option<&'config mut AudioEncodeStats> | Where the truncation report lands, overwritten by the call. |
Implements
From<Scalar>StructAudioEncodeStatsWhat an audio call reports beside its outputs, overwritten by the call.
pub struct AudioEncodeStatsMirrors uform_audio_encode_stats_t.
Fields
truncated | usize | Items cut at the model's context in frames. |
|---|---|---|
tokens | usize | Frames the call encoded, after truncation. |
Implements
Clone, Copy, StructuralPartialEq, PartialEq, Eq, Debug, DefaultTraitEncodeVerbsEvery encode verb, written once for every receiver: &Model blocks on the calling thread, and the On that Model::on or Model::deferred makes runs on an executor.7
pub trait EncodeVerbs<'model>: ModelVerbs<'model>Every verb takes its inputs, the Outputs to keep, a config every bare Scalar
converts into, and last the Arena its Encoded result borrows. A blocking receiver
answers what the call produced; a deferring one answers a Deferred and
takes owned inputs.
Rust-only; implemented for every receiver of ModelVerbs.
Implementors
impl<'model, Receiver: ModelVerbs<'model>> EncodeVerbs<'model> for Receiver
text_encodeEncodes UTF-8 texts through one forward, a token per byte.
fn text_encode<'config, 'arena, Texts: TapeView<u8>>(
self,
texts: Texts,
outputs: Outputs,
config: impl Into<TextEncodeConfig<'config>>,
arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, TextEncode<'config, 'arena, Texts>>
where
Self::Completion: Accepts<Texts> + Accepts<TextEncodeConfig<'config>>,Calls uform_text_encode.
text_chooseScores each item's legal choices through one forward: texts are UTF-8 states, each ending where its choice goes, and choices holds each item's legal bytes, one choice per byte.
fn text_choose<'config, 'arena, Texts: TapeView<u8>, Choices: TapeView<u8>>(
self,
texts: Texts,
choices: Choices,
config: impl Into<TextChooseConfig<'config>>,
arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, TextChoose<'config, 'arena, Texts, Choices>>
where
Self::Completion: Accepts<Texts> + Accepts<Choices> + Accepts<TextChooseConfig<'config>>,Answers one probability per choice in choices order, a softmax over the item's choices
alone at its question type's calibrated inverse temperature.
A state longer than the model's context loses its head, never its end, and a model without
the byte decoder fails the call with Status::Unsupported.
Calls uform_text_choose.
image_encodeDecodes and encodes JPEG, PNG or WebP files; an undecodable file fails the call with Status::Malformed.
fn image_encode<'config, 'arena, Images: TapeView<u8>>(
self,
images: Images,
outputs: Outputs,
config: impl Into<ImageEncodeConfig<'config>>,
arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, ImageEncode<'config, 'arena, Images>>
where
Self::Completion: Accepts<Images> + Accepts<ImageEncodeConfig<'config>>,Calls uform_image_encode.
image_encode_pixelsEncodes decoded images of interleaved 8-bit RGB, item i holding heights[i] rows of widths[i] pixels; an item of another length fails with Status::ShapeMismatch.
fn image_encode_pixels<'config, 'arena, Pixels: TapeView<u8>, Heights: AsRef<[u32]>, Widths: AsRef<[u32]>>(
self,
pixels: Pixels,
heights: Heights,
widths: Widths,
outputs: Outputs,
config: impl Into<ImageEncodePixelsConfig<'config>>,
arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, ImageEncodePixels<'config, 'arena, Pixels, Heights, Widths>>
where
Self::Completion: Accepts<Pixels> + Accepts<Heights> + Accepts<Widths> + Accepts<ImageEncodePixelsConfig<'config>>,Calls uform_image_encode_pixels.
video_encodeDecodes and encodes MP4 or WebM clips.
fn video_encode<'config, 'arena, Videos: TapeView<u8>>(
self,
videos: Videos,
outputs: Outputs,
config: impl Into<VideoEncodeConfig<'config>>,
arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, VideoEncode<'config, 'arena, Videos>>
where
Self::Completion: Accepts<Videos> + Accepts<VideoEncodeConfig<'config>>,Calls uform_video_encode.
audio_encodeDecodes and encodes WAV, FLAC, MP3 or Opus recordings, resampled to mono.
fn audio_encode<'config, 'arena, Recordings: TapeView<u8>>(
self,
recordings: Recordings,
outputs: Outputs,
config: impl Into<AudioEncodeConfig<'config>>,
arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, AudioEncode<'config, 'arena, Recordings>>
where
Self::Completion: Accepts<Recordings> + Accepts<AudioEncodeConfig<'config>>,Calls uform_audio_encode.
audio_encode_samplesEncodes decoded mono recordings sharing one sample_rate, resampled to the model's rate where it differs.
fn audio_encode_samples<'config, 'arena, Samples: TapeView<f32>>(
self,
samples: Samples,
sample_rate: u32,
outputs: Outputs,
config: impl Into<AudioEncodeSamplesConfig<'config>>,
arena: &'arena mut Arena,
) -> <<Self as ModelVerbs<'model>>::Completion as Completion>::Answer<'model, AudioEncodeSamples<'config, 'arena, Samples>>
where
Self::Completion: Accepts<Samples> + Accepts<AudioEncodeSamplesConfig<'config>>,Calls uform_audio_encode_samples.
StructEncodedWhat an encode verb wrote into the arena it borrows: the surfaces its Outputs named.
pub struct Encoded<'arena>Rust-only.
Fields
embeddings | Option<Rows<'arena>> | One pooled embedding of the model's dimensions per item, without normalization. |
|---|---|---|
states | Option<RowsTape<'arena>> | One final-norm state per token left after truncation, item by item. |
token_vectors | Option<RowsTape<'arena>> | One unit vector of the model's token width per token left after truncation, the prefix included, item by item. |
StructImageEncodeAn image forward over encoded files; see EncodeVerbs::image_encode.
StructImageEncodeConfigThe scalar and the knobs of EncodeVerbs::image_encode; a bare Scalar is the whole config.
pub struct ImageEncodeConfig<'config>Mirrors uform_image_encode_t.
Fields
outputs_scalar | Scalar | The scalar type every output lands as. |
|---|---|---|
progress | Option<&'config mut ProgressCallback<'config>> | Reports the items encoded and stops wherever it says to. |
progress_steps | usize | Reports the call makes at most, the last at completion; zero derives to ten. |
stats | Option<&'config mut ImageEncodeStats> | Where the truncation report lands, overwritten by the call. |
Implements
From<Scalar>StructImageEncodePixelsAn image forward over decoded pixels; see EncodeVerbs::image_encode_pixels.
pub struct ImageEncodePixels<'config, 'arena, Pixels, Heights, Widths>Calls uform_image_encode_pixels.
StructImageEncodePixelsConfigThe scalar and the knobs of EncodeVerbs::image_encode_pixels; a bare Scalar is the whole config.
pub struct ImageEncodePixelsConfig<'config>Mirrors uform_image_encode_pixels_t.
Fields
outputs_scalar | Scalar | The scalar type every output lands as. |
|---|---|---|
progress | Option<&'config mut ProgressCallback<'config>> | Reports the items encoded and stops wherever it says to. |
progress_steps | usize | Reports the call makes at most, the last at completion; zero derives to ten. |
stats | Option<&'config mut ImageEncodeStats> | Where the truncation report lands, overwritten by the call. |
Implements
From<Scalar>StructImageEncodeStatsWhat an image call reports beside its outputs, overwritten by the call.
pub struct ImageEncodeStatsMirrors uform_image_encode_stats_t.
Fields
truncated | usize | Items whose patch grid was cut at the model's context. |
|---|---|---|
tokens | usize | Patches the call encoded, after truncation. |
Implements
Clone, Copy, StructuralPartialEq, PartialEq, Eq, Debug, DefaultStructOutputsThe surfaces an encode verb keeps from its one forward, named after the C fields they fill; Outputs::default keeps the embeddings alone.4
pub struct Outputs(_);Rust-only; decides which of the C embeddings, states and token_vectors pointers
a verb passes.
Implements
Clone, Copy, StructuralPartialEq, PartialEq, Eq, Hash, Default, BitOr, BitOrAssign, DebugEMBEDDINGSOne pooled embedding per item, past the attention pool and the projection head.
pub const EMBEDDINGS: Outputs = _;STATESOne final-norm state per token left after truncation.
pub const STATES: Outputs = _;TOKEN_VECTORSOne unit vector of the token head per token left after truncation, the surface late-interaction rerankers score; a model without a token head fails the call with Status::Unsupported.
pub const TOKEN_VECTORS: Outputs = _;containsWhether every surface other names is kept.
pub const fn contains(self, other: Outputs) -> boolStructTextEncodeA text forward; see EncodeVerbs::text_encode.
StructTextEncodeConfigThe scalar and the knobs of EncodeVerbs::text_encode; a bare Scalar is the whole config.
pub struct TextEncodeConfig<'config>Mirrors uform_text_encode_t.
Fields
outputs_scalar | Scalar | The scalar type every output lands as. |
|---|---|---|
progress | Option<&'config mut ProgressCallback<'config>> | Reports the items encoded and stops wherever it says to; a stopped call reports
Status::Cancelled and leaves no outputs. |
progress_steps | usize | Reports the call makes at most, the last at completion; zero derives to ten. |
stats | Option<&'config mut TextEncodeStats> | Where the truncation report lands, overwritten by the call. |
Implements
From<Scalar>StructTextEncodeStatsWhat a text call reports beside its outputs, overwritten by the call.
pub struct TextEncodeStatsMirrors uform_text_encode_stats_t.
Fields
truncated | usize | Items cut at the model's context. |
|---|---|---|
tokens | usize | Tokens the call encoded, after truncation. |
Implements
Clone, Copy, StructuralPartialEq, PartialEq, Eq, Debug, DefaultStructVideoEncodeA video forward over encoded clips; see EncodeVerbs::video_encode.
StructVideoEncodeConfigThe scalar and the knobs of EncodeVerbs::video_encode; a bare Scalar is the whole config.
pub struct VideoEncodeConfig<'config>Mirrors uform_video_encode_t.
Fields
outputs_scalar | Scalar | The scalar type every output lands as. |
|---|---|---|
progress | Option<&'config mut ProgressCallback<'config>> | Reports the items encoded and stops wherever it says to. |
progress_steps | usize | Reports the call makes at most, the last at completion; zero derives to ten. |
stats | Option<&'config mut VideoEncodeStats> | Where the truncation report lands, overwritten by the call. |
Implements
From<Scalar>StructVideoEncodeStatsWhat a video call reports beside its outputs, overwritten by the call.
pub struct VideoEncodeStatsMirrors uform_video_encode_stats_t.
Fields
truncated | usize | Items cut at the model's context in tubes. |
|---|---|---|
tokens | usize | Tubes the call encoded, after truncation. |
Implements
Clone, Copy, StructuralPartialEq, PartialEq, Eq, Debug, DefaultTraitElementA scalar type a tape holds or a run of rows reads as, tied to the Scalar the C interface tags its buffers with.1
pub unsafe trait Element: Copy + 'staticRust-only.
Safety The associated scalar must describe the type's in-memory encoding exactly; the library
reads raw buffers under that tag.
Implementors
SCALARThe tag the C interface knows this type by.
const SCALAR: Scalar;StructRowsRows a call wrote into the arena it borrows, one per item, packed.7
countRows the call wrote.
pub fn count(&self) -> usizecolumnsValues per row, the model's embedding dimensions.
pub fn columns(&self) -> usizestrideBytes between the starts of consecutive rows.
pub fn stride(&self) -> usizescalarThe scalar type the rows hold.
pub fn scalar(&self) -> Option<Scalar>as_ptrThe first row, in host or device memory, for handing to another library as it is.
pub fn as_ptr(&self) -> *const c_voidas_bytesEvery row's bytes end to end, refused with Status::Device over device memory.
pub fn as_bytes(&self) -> Result<&'arena [u8]>valuesEvery row's values end to end, refused with Status::InvalidArgument when the rows hold another scalar type, and with Status::Device over device memory.
pub fn values<Value: Element>(&self) -> Result<&'arena [Value]>StructRowsTapeRows a call wrote into the arena it borrows, as many per item as the item had tokens left after truncation, end to end, with one more offset than items.4
countItems the call encoded.
pub fn count(&self) -> usizeoffsetsThe call's count plus one non-decreasing offsets, in rows, refused with Status::Device over device memory.
pub fn offsets(&self) -> Result<&'arena [usize]>rowsEvery item's rows end to end, refused with Status::Device over device memory.
pub fn rows(&self) -> Result<Rows<'arena>>itemThe rows of one item, refused with Status::InvalidArgument when item is not below RowsTape::count, and with Status::Device over device memory.
pub fn item(&self, item: usize) -> Result<Rows<'arena>>EnumScalarScalar types a model computes in and its outputs land as, numbered as USearch numbers them, so a run of embeddings is a run USearch indexes without conversion.
pub enum ScalarSub-byte kinds pack several dimensions per byte, as their xN suffixes spell. The C enum
reserves the numbering gaps for kinds that have not landed yet, so this one is open.
Mirrors uform_scalar_t.
Values
F64 | 1 | IEEE-754 binary64. |
|---|---|---|
F32 | 2 | IEEE-754 binary32. |
BF16 | 3 | Truncated f32 with an 8-bit exponent and a 7-bit mantissa. |
F16 | 4 | IEEE-754 binary16. |
E5M2 | 5 | FP8 with a 5-bit exponent: ±57344, with infinities and NaNs. |
E4M3 | 6 | FP8 with a 4-bit exponent: ±448, no infinities, and two NaN codes. |
E3M2 | 7 | FP6 with a 3-bit exponent, byte-aligned with two padding bits. |
E2M3 | 8 | FP6 with a 2-bit exponent, byte-aligned with two padding bits. |
I8 | 10 | 8-bit signed integer. |
I4x2 | 11 | Two signed nibbles per byte, even dimensions in the low nibble. |
I32 | 12 | 32-bit signed integer. |
U8 | 20 | 8-bit unsigned integer - the element of UTF-8 text and of encoded files. |
U4x2 | 21 | Two unsigned nibbles per byte, even dimensions in the low nibble. |
U1x8 | 22 | Eight single-bit dimensions per byte, the sign of each embedding dimension - the form USearch's Hamming and Jaccard metrics score. |
Implements
StructTapeValues a call wrote into the arena it borrows, a ragged run per item, end to end, with one more offset than items.5
countItems the call wrote.
pub fn count(&self) -> usizescalarThe scalar type the values are.
pub fn scalar(&self) -> Option<Scalar>offsetsThe call's count plus one non-decreasing offsets, in values, refused with Status::Device over device memory.
pub fn offsets(&self) -> Result<&'arena [usize]>valuesEvery item's values end to end, refused with Status::InvalidArgument when the tape holds another scalar type, and with Status::Device over device memory.
pub fn values<Value: Element>(&self) -> Result<&'arena [Value]>itemThe values of one item, refused with Status::InvalidArgument when item is not below Tape::count or the tape holds another scalar type, and with Status::Device over device memory.
pub fn item<Value: Element>(&self, item: usize) -> Result<&'arena [Value]>