Structured Output

Models love to write long paragraphs. Programs hate that.

Structured output makes the model answer in a fixed shape, like a form with named boxes.

You draw the form. The model fills in the boxes. You get a Python object back, not a wall of text.

Draw the form with Pydantic

Pydantic is a library for describing data shapes. Each field has a name, a type, and a short description.

This class is the form. The descriptions are read by the model, so write them clearly.

Hand the form to the model

with_structured_output wraps the model. Now every answer must fit the form.

The result is a Quiz object, not an AIMessage. You use dot access, and the types are already right.

A list of items

You cannot pass a bare list as the form. Wrap the list inside another model.

The wrapper has one field that holds the list. The model fills in each item of the list.

TypedDict: a lighter option

If you do not want Pydantic, a TypedDict works too. You get a plain dictionary back.

Pydantic checks the values for you. TypedDict does not. Pick Pydantic when you want safety.

Seeing the raw message too

Sometimes you want the parsed object and the original AIMessage. Add include_raw=True.

You get a dictionary with three keys. This is handy for counting tokens or catching parse errors.

When to use it

Remember: with_structured_output turns the model into a form filler. Describe each field well and the model fills it in correctly.