From 'please return JSON' to guaranteed Pydantic models
Before Instructor: `response = openai.chat(prompt='Extract name and price from this text. Return JSON.')` → parse `response.content` → catch `json.JSONDecodeError` → retry with stronger prompt → still sometimes fails. After Instructor: `class Product(BaseModel): name: str; price: float; product = openai.chat.create(messages=[...], response_model=Product)` → returns a `Product(name='Widget', price=9.99)` instance. The LLM API now returns a typed object, not a string.
Validation and retry: the secret sauce
When the LLM generates output that does not match the Pydantic model (wrong type, missing field, failed validation), Instructor automatically retries with the validation error in the prompt: 'You said price is free, but I need a float. Please correct.' It retries up to 3 times by default. For my review extraction pipeline, this reduced JSON parsing errors from 12% to 0.5%. The 0.5% failure rate was on inputs where the LLM genuinely could not extract the requested information.
Multiple modes: function calling, JSON mode, and raw prompting
Instructor supports 3 extraction modes. Function calling: uses the LLM's native tool/function API (OpenAI, Anthropic). Most reliable. JSON mode: uses the LLM's JSON mode parameter (forces JSON output, no function calling needed). Works with DeepSeek, Groq, any OpenAI-compatible API. Raw prompting: adds 'return JSON matching this schema' to the prompt. Works with any LLM including local models. The mode is auto-selected based on the provider.
Streaming structured output
Instructor supports streaming structured output: the Pydantic model is built field-by-field as tokens arrive. This means you can show partial results to users while the LLM is still generating. For a form autofill feature, each field (name, email, phone) fills in live as the model generates. The user sees progress instead of waiting 3 seconds for the full response.
Instructor vs LangChain OutputParser vs raw JSON
Instructor: typed Pydantic output, auto-validation, retry, streaming. Best for production structured extraction. LangChain OutputParser: more flexible, supports non-Pydantic formats, less reliable validation. Best for complex parsing chains. Raw JSON prompting: simplest, no dependencies, least reliable. Best for one-off scripts where 95% accuracy is acceptable.
