13.8k stars · MIT · v1.16.0 (2026-08-27)
Pydantic-validated structured output from any LLM, with automatic retry on malformed responses — so the subtopic map cannot fail to parse.
▶Repo detailsthe review · specs · pros & cons · install
What it is
A thin library that makes a language model return data matching a Pydantic model instead of free text: you declare the shape you want, and it handles the schema, the validation and the automatic retry when the model gets it wrong. It works across the major providers rather than binding you to one.
Why it matters
Grasppy's output is structured by definition — a tree of named subtopics, each with a label, a summary and a set of source references — and every one of those labels comes out of a model that will occasionally return prose, invent a field, or wrap the JSON in an apology. Parsing that by hand is where the "sometimes the map just fails to load" class of bug comes from, and that bug is fatal in a product whose entire promise is that it makes a mess legible. Instructor turns a malformed response into an automatic retry with the validation error fed back to the model, which is exactly the loop you would otherwise write badly yourself. It also makes your prompt changes safe: the Pydantic model is the contract, so a reworded prompt cannot quietly change the shape the React canvas is expecting.
- The schema is a Pydantic class, which is the same thing FastAPI already uses — no new vocabulary to learn
- Automatic retry with the validation error returned to the model, which fixes most malformed responses without your code seeing them
- MIT, very active — v1.16.0 shipped three days before this report — and provider-agnostic, so it sits happily behind LiteLLM (09)
- Retries cost money and latency. A strict schema against a weak model can quietly triple the price of an import — which is precisely why 09 belongs in front of it
- It guarantees the shape of the answer, never the quality. A confidently wrong subtopic label validates perfectly
- One more layer between you and the provider API, so an odd failure now has two places to look
source venv/bin/activate pip install instructor