TypeLLM
Browse docs

DOCUMENTATION

Output types

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

TypeSchemaReturns
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

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.

  • maxLength limits the Unicode character count of text. The separate text_max_tokens client setting controls its generation budget.
  • minimum and maximum validate open numeric outputs. An out-of-range result raises an error.
  • Text fields support maxLength, but not minLength, pattern or format.

The examples below use the client initialized in Quick start.

String

Generate text without a predefined list of candidates. This example also limits the character count with maxLength.

  • Without enum, the return value is a Python str. JSON quotes and escapes are decoded before returning it.
  • maxLength is optional and must be a non-negative integer. It counts Unicode characters, not tokens; omitting it sets no character limit.
  • text_max_tokens defaults to 512 per field and must be a positive integer. Incomplete, invalid or over-length text raises SGLangError; it is not silently truncated.
  • minLength, pattern and format are not supported for open text fields.
Example request
result = client.generate(
    context="Receipt from Hilton London.",
    questions={
        "merchant": {
            "type": "string",
            "maxLength": 80,
            "instructions": "Return only the merchant name.",
        },
    },
)
print(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.
  • numeric_max_digits defaults to 32 and must be a positive integer. The minus sign does not count toward this digit limit.
  • Optional minimum and maximum bounds must be finite numbers, with minimum no greater than maximum. Bounds are shown in the prompt and checked after decoding; an out-of-range result raises ValueError rather than being clamped.
Example request
result = client.generate(
    context="The order contains 3 notebooks.",
    questions={
        "quantity": {
            "type": "integer",
            "instructions": "How many notebooks were ordered?",
        },
    },
)
print(result)
Example return
{"quantity": 3}

Number

Extract a decimal value. Optional minimum and maximum bounds validate the returned number.

  • Returns a Python float for an open number field. Negative values are supported; output uses plain decimal notation without exponents.
  • numeric_max_digits defaults to 32 across the integer and fractional parts; the sign and decimal point are not counted.
  • minimum and maximum are inclusive post-decoding checks, not a guarantee that the model will find a value inside the range. A violation raises ValueError.
  • A Python float uses binary floating-point precision. This API does not return a decimal.Decimal value.
Example request
result = client.generate(
    context="The receipt total is £324.50.",
    questions={
        "total": {
            "type": "number",
            "minimum": 0,
            "instructions": "Extract the total amount in GBP.",
        },
    },
)
print(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
result = client.generate(
    context="Invoice INV-42 has been paid in full.",
    questions={
        "paid": {
            "type": "boolean",
            "instructions": "Has the invoice been paid in full?",
        },
    },
)
print(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.

  • Set permutations to a positive integer or "all" to average option orderings. This option requires an explicit enum; at most 720 orderings can be evaluated per field.
  • Each enum must be a non-empty list with at most 24 distinct candidates. This is a per-field limit. More than 24 values raises SchemaError before inference; candidates are not automatically split into groups.
  • 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.
  • For a string enum, maxLength must accommodate every candidate. Use return_probabilities=True to also obtain the full candidate distribution.
Example request
result = client.generate(
    context="The expense was a train ticket.",
    questions={
        "category": {
            "type": "string",
            "enum": ["meal", "travel", "equipment"],
            "instructions": "Classify the expense.",
        },
    },
)
print(result)
Example return
{"category": "travel"}

Schema scope

All declared fields are evaluated, including fields not listed in required. This is a flat object schema: nested objects, arrays and null-valued fields are not supported output types. Do not assume arbitrary JSON Schema keywords are enforced.

Use instructions, then description as its fallback. The old question and x-question keys are rejected. x-score and x-other are also unsupported; use a closed enum.

You can also pass a JSON Schema object with schema= instead of questions=. Supply one interface per request.