Instructor JS for schema-validated TypeScript responses

How it works

The TypeScript client accepts a schema for the model response and wraps a compatible provider interaction. Validation turns a response into a value downstream code can use with an explicit contract.

What you need

Start with a provider integration documented for JavaScript and a small output schema. Put retry limits and timeout handling in the same test that checks parsed values.

What to try first

Start with a schema for one support-ticket classification. Feed the tool an empty ticket and an unfamiliar category, then see how retries and error reporting behave.

Test a provider that returns incomplete responses under a small output limit. The application needs a visible error path for inputs that remain invalid across attempts.

Where to look for failures

Keep the output schema and retry limits narrow. Check the documented provider support and handle exhausted retries as a distinct outcome in your application.

Related Franklin pages

Test both a valid structured response and one that requires recovery. A good application contract specifies what happens after the allowed attempts are exhausted.

• Build Python agents with typed dependencies, tools and model outputs. Pydantic AI for typed agent applications
• Parse model responses into typed Python objects and retry when validation fails. Instructor for validating model responses in Python

For the distinction between requesting structured output and enforcing its format, see Franklin’s glossary. Structured output

Project documentation

• Current project README
• README at the reviewed revision