Choosing a capability
decision-machine-1 has seven capabilities. Each one returns a different shape. Start from the answer you want, not from the text you have.
The decision table
Two questions decide most cases. Do you supply the possible answers, or does the text supply them? Do you need character offsets? Supplied answers point to yes-no, classify and rate. Offsets point to answer and entities.
The near-miss pairs
Four pairs look interchangeable. They are not.
Yes / no against classify with two labels
Yes / no scores each statement on its own. Several statements can all be true of the same text. Classify forces one winner. The label scores are normalized and sum to 1, so a second label only wins by taking share from the first.
Use yes / no for independent flags. Write each flag as a statement about the text,
such as “The customer expresses urgency.” and “The message contains personal data.”
Send them in one statements array. Two statements in one call cost about 1.12 s,
inside the range of a single statement.
Use classify when the labels are mutually exclusive, such as a routing queue.
Classify also returns confidence, which yes / no does not.
Answer against extract
Answer returns one span of the input text, with start and end offsets. It returns
null when the text carries no answer. It never converts the value.
Extract returns a typed object. It coerces numbers, integers, booleans and enums, and it fills several fields in one call. It returns no offsets.
Pick answer when you must highlight the source text or show a citation. Pick extract when you write the values into a database or a form.
Entities against extract
Entities finds every span of a type. One text can return many entities of the same
type, sorted by start. Extract fills each field once.
Use entities for redaction, highlighting, and any count that is unknown in advance: people, dates, order numbers.
Use extract when the record has a known shape: one invoice number, one total, one vendor object. Extract also reads nested objects. An array-of-objects property is accepted and returned empty for now.
Verify against extract
Extract asks the text what the value is. Verify asks whether a value you already hold agrees with the text.
Verify returns matches, a probability, and found[] — the raw spans the model
read for that field. found[] is the debugging field: it shows what the text says
when the check fails.
The match rule lowercases both sides and removes every non-alphanumeric character. A value of 3 or more characters also matches when it appears inside the span. Run extract first, then verify the fields that carry risk.
Cost and latency as a tie-breaker
Two capabilities can both answer your question. Latency then decides.
Extra questions in one call add no inference call, only their own length. Three questions cost 0.56 s, the same as
one. Batching over texts costs one call per text. You pay $0.04 per million input
tokens and $0 per output token. See Pricing.
Split broad judgments. One rate call over a vague scale gives a weak
confidence. Several atomic calls, weighted in your own code, give a stable number, as
composite scoring does.
When no capability fits
decision-machine-1 does not generate prose. It does not summarize, translate, or reason across documents. It returns typed decisions over one text. For those tasks, use a large model, and keep decision-machine-1 as the cheap first pass in a cascade.