pytrio.ModelInput

class ModelInput(BaseModel):
    chunks: list[EncodedTextChunk | ImageChunk]

ModelInput stores encoded text and image chunks in model-reading order. It is used by Datum, SamplingClient.sample(), and related APIs.

For text-only input, continue to use from_ints():

import pytrio as trio

model_input = trio.ModelInput.from_ints(tokens=input_ids[:-1])

datum = trio.Datum(
    model_input=model_input,
    loss_fn_inputs={"target_tokens": input_ids[1:]},
)

For multimodal input, arrange the text and image chunks explicitly. The following input order is “text before the image → image → text after the image”:

from pathlib import Path

import pytrio as trio

model_input = trio.ModelInput(
    chunks=[
        trio.types.EncodedTextChunk(tokens=[1, 2, 3]),
        trio.ImageChunk(
            data=Path("example.png").read_bytes(),
            format="png",
        ),
        trio.types.EncodedTextChunk(tokens=[4, 5, 6]),
    ]
)

Image inference only requires data and format. For training data or local len(model_input) calls, also pass expected_tokens calculated with the image processor for the corresponding model. See the multimodal guide for the complete construction flow.

Fields

Field	Type	Description
`chunks`	`list[EncodedTextChunk \| ImageChunk]`	Text and image chunks in model-reading order

Chunk types

Type	Main fields	Description
`EncodedTextChunk`	`tokens: list[int]`	Tokenizer-encoded text tokens; `type="encoded_text"`
`ImageChunk`	`data: bytes`, `format: "png" \| "jpeg"`, `expected_tokens: int \| None`	Raw PNG/JPEG bytes; `type="image"`

Properties

Property	Type	Description
`length`	`int`	Sum of text tokens and image `expected_tokens`, equivalent to `len()`
`has_images`	`bool`	Whether the input contains an `ImageChunk`
`is_empty`	`bool`	Whether the input contains neither text tokens nor images

If an ImageChunk does not define expected_tokens, length and len() raise ValueError.

Methods

from_ints

@classmethod
def from_ints(cls, tokens: list[int]) -> ModelInput

Build a text-only ModelInput containing one EncodedTextChunk from a list of token IDs.

model_input = trio.ModelInput.from_ints(tokens=[1, 2, 3, 4])

to_ints / tolist

def to_ints(self) -> list[int]
def tolist(self) -> list[int]

Flatten all text chunks and return the full token ID list. The two methods are equivalent and only support text-only input; they raise ValueError when the input contains an ImageChunk.

tokens = model_input.to_ints()
tokens = model_input.tolist()