C · Choices

Choices

#include <uform/encode.h>#include <uform/train.h> 4.0.0-rc.1 · 3ee5e534

uform_text_choose scores each text’s legal choices, one byte each, through one forward of the byte decoder. The call appends the mask byte to every text, and a text longer than the model’s context loses its head, never its end. Each item’s probabilities are a softmax over its own choices alone, at the calibrated inverse temperature of its temperature_groups entry, and land in the arena as one f32 tape in choices order. A model whose choice_temperature_groups is zero carries no byte decoder and reports uform_status_unsupported_k.

uform_tape_view_t probabilities = {0};
uform_text_choose(&(uform_text_choose_t){
    .model = model, .executor = executor, .outcome = &outcome, .count = n,
    .texts = {bytes, offsets, uform_scalar_u8_k}, .choices = {letters, letter_offsets, uform_scalar_u8_k},
    .probabilities = &probabilities, .arena = arena});

A checkpoint stores one inverse temperature per question type as choices.inverse_temperatures, and one without them chooses at an inverse temperature of one. uform_eval <checkpoint> --calibrate <choices.jsonl> --output <calibrated.safetensors> fits them on held-out choices, prints each group’s negative log-likelihood and the top-choice calibration error before and after, and writes the calibrated copy.

API

Types

uform_choices_tSearchJev's calibrated choices over the byte decoder, the masked head's untied byte logits read at a mask byte appended to a state and restricted to the item's legal bytes.
train.h:347 ↗
struct uform_choices_t

Each choice item scores −Σt · log(p) + brier_weight · Σ(p − t)², with p that restricted softmax and t its targets.

Fields

weightfloatThe loss weight; zero trains no choices.
brier_weightfloatThe Brier term's weight beside the soft cross-entropy; 0.5.

Functions

uform_text_chooseScores each item's legal choices through one forward, a softmax over them alone at the item's group's calibrated inverse temperature; a model without the byte decoder reports uform_status_unsupported_k.
encode.h:153 ↗
void uform_text_choose(uform_text_choose_t *arguments);

Parameters

modeluform_model_tThe model to choose with; it must carry the byte decoder, its choice_temperature_groups nonzero.
executoruform_executor_tThe executor the call runs on; it must share the model's residency.
outcomeuform_outcome_t *Output for the outcome, final once its status leaves uform_status_deferred_k.
completionuform_completion_tWhether the call blocks or returns once queued; zero blocks.
countsize_tItems in texts, and the batch axis of every input and output.
textsuform_tape_view_tUTF-8 states, one per item, each ending where the choice goes; the call appends the mask byte, and a state longer than the model's context loses its head, never its end.
choicesuform_tape_view_tEach item's legal choices, one byte each, uform_scalar_u8_k; an item with none chooses nothing.
temperature_groupsuint32_t const *The optional question type of each item, count of them, below the model's choice_temperature_groups; NULL puts every item in group zero.
probabilitiesuform_tape_view_t *Output for one probability per choice in choices order, uform_scalar_f32_k, inside arena: the shape a training step reads its choice_targets in.
arenauform_arena_tMemory for every output, rewound by the call.
progressuform_progress_tThe optional handler, called with items scored.
statsuform_text_encode_stats_t *The optional report; NULL skips it.