Output types — Docs

Use instructions to describe each field. Without instructions, TypeLLM uses its description or derives a prompt from the field name.

Type	Schema	Returns
Text	`{"type": "string"}`	`str`
Integer	`{"type": "integer"}`	`int`
Number	`{"type": "number"}`	`float`
Boolean	`{"type": "boolean"}`	`bool`
Enum	`{"type": "string", "enum": ["a", "b"]}`	A supplied value
Choices	`{"type": "string", "choices": [{"value": "a", "description": "..."}]}`	A supplied value
Score	`{"type": "number", "levels": [{"label": "Low"}, {"label": "High"}]}`	`float`
Box	`{"type": "box"}`	`dict` of edges
Object	`{"type": "object", "properties": {...}}`	`dict`
Array	`{"type": "array", "items": {...}}`	`list`

Primitives

Enum fields accept string, integer or number candidates. Boolean and enum fields select from finite candidates; text and numeric fields without an enum generate values token by token.

String

Generate text without a predefined list of candidates.

Without enum, the return value is a Python str. JSON quotes and escapes are decoded before returning it.
Describe the length you want in instructions, such as "in one sentence".
A string answer stops at 128 tokens.

Example request

response = client.generate(
    context="Receipt from Hilton London.",
    questions={
        "merchant": {
            "type": "string",
            "instructions": "Return only the merchant name.",
        },
    },
)
print(response.result)

Example return

{"merchant": "Hilton London"}

Integer

Extract a whole number directly, without enumerating possible answers.

Returns a Python int, including negative values. Decimal points and exponent notation are not generated.
An integer has at most 32 digits; the minus sign does not count.

Example request

response = client.generate(
    context="The order contains 3 notebooks.",
    questions={
        "quantity": {
            "type": "integer",
            "instructions": "How many notebooks were ordered?",
        },
    },
)
print(response.result)

Example return

{"quantity": 3}

Number

Extract a decimal value.

Returns a Python float for an open number field. Negative values are supported; output uses plain decimal notation without exponents.
A number has at most 32 digits across the integer and fractional parts; the sign and decimal point are not counted.
A Python float uses binary floating-point precision.

Example request

response = client.generate(
    context="The receipt total is £324.50.",
    questions={
        "total": {
            "type": "number",
            "instructions": "Extract the total amount in GBP.",
        },
    },
)
print(response.result)

Example return

{"total": 324.5}

Boolean

Return a Python True or False value for a yes/no question.

Returns Python True or False. By default both candidates are available.
An optional boolean enum can restrict the candidates, for example [True]. Numeric 0 and 1 are not accepted as boolean candidates.
return_probabilities=True returns a wrapper with value and probabilities instead of a bare bool.

Example request

response = client.generate(
    context="Invoice INV-42 has been paid in full.",
    questions={
        "paid": {
            "type": "boolean",
            "instructions": "Has the invoice been paid in full?",
        },
    },
)
print(response.result)

Example return

{"paid": True}

Enum choice

Select from supplied candidates. String, integer and number enums use the same interface; the declared type must match the candidates.

An enum lists 2 to 512 distinct candidates, inside an array's items too. This is a per-field limit; fewer or more values are refused before inference.
Candidates must match the declared type: string values for string, Python integers for integer, and finite integer or float values for number. Booleans are not numeric enum values.
Duplicate candidates are rejected. Numeric 1 and 1.0 count as the same candidate. NaN and infinity are not allowed.
The selected value is one of the supplied candidates. Unlike an open number field, a numeric enum preserves the selected candidate’s Python type.
Use return_probabilities=True to also obtain the full candidate distribution.
Probabilities are averaged over option orders by default, for a better distribution; see Probabilities.

Example request

response = client.generate(
    context="The expense was a train ticket.",
    questions={
        "category": {
            "type": "string",
            "enum": ["meal", "travel", "equipment"],
            "instructions": "Classify the expense.",
        },
    },
)
print(response.result)

Example return

{"category": "travel"}

Choices with descriptions

When the right answer depends on what each value means, write the candidates as choices, each with a description. The model reads every description next to its value.

Example request

response = client.generate(
    context="Please cancel my subscription at the end of this month.",
    questions={
        "team": {
            "type": "string",
            "instructions": "Which team should handle this ticket?",
            "choices": [
                {"value": "billing", "description": "Payments, invoices, refunds, and subscription changes."},
                {"value": "technical", "description": "Problems using the product, including login."},
                {"value": "account", "description": "Changes to name, email address, or company name."},
                {"value": "other"},
            ],
        },
    },
)

Example return

{"team": "billing"}

choices takes the place of enum: the same types and the same limits. A field has one or the other, not both.
Each choice is an object with a value and an optional, non-empty description.
The field returns the chosen value, and with return_probabilities its probabilities are keyed by value, as for an enum.
Choices work in objects and in array items.

Scores

A score rates the input on an ordered scale. List the levels from lowest to highest; the field returns the expected level, the average of the level positions weighted by their probabilities, from 0 for the first level to one less than the number of levels for the last.

Example request

response = client.generate(
    context="Export fails in Safari but works in Chrome.",
    questions={
        "severity": {
            "type": "number",
            "instructions": "How severe is this issue?",
            "levels": [
                {"label": "Cosmetic", "description": "Appearance only; no lost functionality."},
                {"label": "Workaround available", "description": "A task fails, but another way works."},
                {"label": "Fully blocked", "description": "A task fails with no workaround."},
            ],
            "return_probabilities": True,
        },
    },
)

Example return

{"severity": {
    "value": 0.97,
    "probabilities": {"Cosmetic": 0.06, "Workaround available": 0.91, "Fully blocked": 0.03},
    "confidence": 0.87,
}}

A score is a number field with 2 to 26 levels. Each level has a unique, non-empty label and an optional description.
Without return_probabilities, the field returns the score as a float. With it, the probabilities are keyed by label.
Levels keep the order you give them, since the order is the scale: a score does not take permutations.
when compares a score with gt, gte, lt or lte, such as {"severity": {"gte": 1.5}}.
A score cannot be nullable or be inside an array.

Boxes

A box finds something in the image and returns where it is: top, bottom, left and right, each from 0 to 1 across the image, from its top-left corner.

Example request

response = client.generate(
    context="Look at the attached photo.",
    images=["dog.jpg"],
    questions={
        "dog_head": {"type": "box", "instructions": "The dog's head, ears included."},
    },
)

Example return

{"dog_head": {"top": 0.352, "bottom": 0.652, "left": 0.344, "right": 0.628}}

Multiply by the image's width and height for pixels. Fractions fit the image at any size you draw it.
A call with a box needs an image. Use instructions to say what to find and where it ends, such as "ears included".
There is always a box. To check that the target is there, ask a boolean first and give the box a when on it, so the box is asked only when the target is there.
Several boxes in one call are found together. A field that depends_on a box sees it.
A box cannot be nullable, take enum, choices or return_probabilities, sit inside an object's or an array's items, or be tested by a when.

Arrays of boxes

An array of boxes finds every match in the image, from none to maxItems.

Example request

response = client.generate(
    context="Read the receipt photo.",
    images=["receipt.jpg"],
    questions={
        "items": {
            "type": "array",
            "items": {"type": "box"},
            "instructions": "Every line item, each the whole line from its name to its price.",
        },
    },
)

Example return

{"items": [{"top": 0.421, "bottom": 0.461, "left": 0.12, "right": 0.837},
           {"top": 0.449, "bottom": 0.493, "left": 0.12, "right": 0.834},
           {"top": 0.48, "bottom": 0.521, "left": 0.118, "right": 0.829}]}

It returns [] when the image has no match.
Its items take only {"type": "box"}: say what to find in the array's instructions.
minItems and maxItems bound it, up to 50 boxes. continue_from is not supported.
A field that depends_on it sees every box.

See the dog head example for the whole call, with the box drawn on the photo.

Nullable fields

Add "null" to the type to allow a missing value. The field returns None when the input has no value for it.

Example request

response = client.generate(
    context="Read the attached receipt.",
    images=["receipt.jpg"],
    questions={
        "tip": {"type": ["number", "null"], "instructions": "Tip amount."},
        "table": {"type": ["string", "null"], "instructions": "Table number."},
        "paid_in_cash": {"type": ["boolean", "null"], "instructions": "Was the bill paid in cash?"},
        "card": {"type": ["string", "null"], "enum": ["VISA", "MASTERCARD", None],
                 "instructions": "Card network, if paid by card."},
    },
)

Example return

{"tip": None, "table": "7A", "paid_in_cash": False, "card": None}

The type is one type plus "null", in either order. Other type lists are refused.
A nullable boolean adds null as a third choice. As in JSON Schema, a nullable enum returns null only if its enum lists None.
For numbers and strings, TypeLLM weighs the probability of null against the probability of starting a value, then decodes the value. The tokens it compares are read from the served model's tokenizer.
return_probabilities works for nullable booleans and enums, and its probabilities include None.

Objects

An object groups typed properties into one value.

Example request

response = client.generate(
    context="Alice Chen, 32, joined Acme as a data engineer in 2021.",
    questions={
        "profile": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "age": {"type": "integer"},
                "role": {"type": "string", "enum": ["engineer", "manager", "designer"]},
            },
        },
    },
)

Example return

{"profile": {"name": "Alice Chen", "age": 32, "role": "engineer"}}

A property takes what a field takes: instructions, enum, thinking, and depends_on or when on other properties of the same object.
Objects can hold objects. A field that depends_on an object sees all of it.
An object can itself have depends_on and when. Skipped, it is listed once in response.skipped; a property a when skipped is listed by its path, such as "profile.employer".

Arrays

An array returns as many items as the input calls for, each matching the items schema. Items can be strings, numbers, booleans, enum values or objects.

Example request

response = client.generate(
    context="Our team: Ada is the CTO, Lin is an engineer, and Sam runs sales.",
    questions={
        "employees": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "role": {"type": "string"},
                },
            },
            "instructions": "Return all employees.",
        },
        "skills": {
            "type": "array",
            "items": {"type": "string", "enum": ["leadership", "engineering", "sales"]},
            "instructions": "Skills the team covers.",
        },
    },
)

Example return

{"employees": [{"name": "Ada", "role": "CTO"},
               {"name": "Lin", "role": "engineer"},
               {"name": "Sam", "role": "sales"}],
 "skills": ["leadership", "engineering", "sales"]}

minItems and maxItems bound an array. Items may repeat: an array is a list, not a set, so four statements can come back as [true, false, true, false].
Use instructions to say which items belong, such as "Return all employees" or "Suggest three names".
An array can have depends_on and when, like any field. A field that depends_on an array sees all of it.
Inside an array's items, properties take instructions, enum, choices and null, but not thinking, depends_on, when or return_probabilities.
Not supported: arrays of arrays, arrays inside objects, return_probabilities and scores inside arrays, and when conditions that test an object or an array.

The properties of objects and of array items count toward the limit of 64 questions per call.
An array adds at most 200 items per call, and an array of boxes at most 50; minItems and maxItems may be at most the same.

Long inputs

When an input is too long for one call, split it into parts and carry the array over with continue_from. Each call starts from the items so far and returns the whole array, so pass each result to the next call.

Example request

items = []
for part in parts:
    response = client.generate(context=part, questions={
        "checks": {**checks, "continue_from": items},
    })
    items = response.result["checks"]

The items must match the array's items schema; anything else is refused before the call runs.
They come back first, unchanged.
Every step of the array sees them, so a part that starts in the middle of a record continues from the last item instead of starting over.
minItems and maxItems count them; the 200- or 50-item limit counts the items each call adds.
They are part of each call's input, so later parts of a long array take longer and count more input tokens.