Building with LLMs (TypeScript) · Chapter 12 of 24
Structured output
By the end of this chapter you can describe the reply you want as a zod schema, have the API hold the model to it with a strict JSON schema, get back a typed object, validate what comes back, and repair a bad reply by telling the model what was wrong. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Reliable output
- 4 tasks
- TypeScript
- In the all labs plan
The first 2 chapters of Building with LLMs (TypeScript) are free. This one comes with the all labs plan.
Why you need this
Chapter 11 ended on a warning: JSON mode promises valid JSON, not your keys or your types, and as Booking checks neither. Nikhil has seen what that costs. A reply with "seats": "2" passes every test with the number 2 and breaks on the day someone adds it to another number ("2" + 1 is "21"); a reply with an extra key or a renamed one fails three functions away from the request that caused it.
You already know the tool that fixes this in TypeScript: zod. A schema says what each field is, checks data at run time, and gives you the type with z.infer. Structured output takes the same schema to the API, so the model is held to it while it writes.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
parse-booking.ts: a booking as a typed object
Write a zod schema Booking with the fields origin, destination and name (text) and seats (a whole number), each of which may be null. Ask lab-chat for it with client.chat.completions.parse and response_format: zodResponseFormat(Booking, 'booking'): a system message saying to extract the booking, and Dhruv's message (in the starter) as the user message.
Print one line from the parsed booking: the name, a colon, a space, the seats, the words seat(s), a comma, then origin -> destination, for example:
Asha Rao: 2 seat(s), Pune -> Goa
- Task 2
triage.ts: enums for labels
Write a zod schema Triage: intent, exactly one of booking_request, cancellation, refund_status, delay_complaint, fare_query, lost_item, date_change, praise; urgency, exactly one of high and normal; pnr, text or null; language, text.
For each of the first 10 messages in /workspace/data/messages.jsonl, ask lab-chat with parse and zodResponseFormat(Triage, 'triage') (a system message saying to triage the message, the text as the user message). Print the id, intent, urgency, the PNR (or - when it is null) and the language, separated by spaces, for example:
M200 lost_item normal SL7K2Q9M en
- Task 3
repair.ts: repair by asking again
Write a zod schema Booking (name and phone: text or null; seats: a whole number or null) and export async function getBooking(client: OpenAI, text: string): Promise<[Booking, number]> that asks lab-chat-sloppy (no response format; a system message to extract the booking and reply in JSON with the keys name, phone and seats; the text as the user message), checks the reply with JSON.parse and Booking.safeParse, and on a failure adds the bad reply as an assistant message and a user message saying the reply was not valid JSON, with the error's text, and asks again with the whole array. It returns the booking and the attempt number, and throws after 3 attempts. Do not clean the reply in code.
When the file is run, call it for Dhruv's message and print attempt, its number, a colon, a space and the booking as JSON, for example:
attempt 2: {"name":"Asha Rao","phone":null,"seats":2}
- Task 4 · interview question
Interview: fix-schema.ts, fix the strict schema
fix-schema.ts sends a hand-written strict schema and checks each reply with the Booking zod schema, printing the booking as JSON for two messages. It has three mistakes: two the API refuses and one zod refuses. Fix them until it prints two lines; a message with no seat count must still work, with seats null.
Keep the messages, strict mode and the three keys.
What you will learn
- JSON schemas and the json_schema response format.
- Strict mode and its two rules.
- zod with .parse: a schema in, a typed object out; z.enum for labels; why .nullable() and not .optional().
- Validation and repair: what the schema cannot promise, and asking again.
More in Reliable output
Build "Structured output" yourself
SafarLine, an intercity bus company, drowns in WhatsApp messages. You build its first AI assistant, in TypeScript. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of Building with LLMs (TypeScript) are free. This one comes with the all labs plan.