instructor

Extract structured data from LLM responses with Pydantic validation and automatic retries.

13.0k|930|Updated Nov 3, 2025
One-click install
npx skills add https://github.com/Orchestra-Research/AI-research-SKILLs --skill instructor-orchestra-research
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: instructor
Source: https://github.com/Orchestra-Research/AI-research-SKILLs/tree/main/16-prompt-engineering/instructor
Command: npx skills add https://github.com/Orchestra-Research/AI-research-SKILLs --skill instructor-orchestra-research

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires instructor, pydantic, openai, anthropic, and includes references (resource) components.

What problem does it solve? LLM responses arrive as unstructured text that breaks downstream code when parsed manually. This Skill wraps LLM API calls so outputs are validated against Pydantic schemas, automatically retried with error feedback when validation fails, and streamed as partial typed objects. ## Core Features & Use Cases - Schema-Validated Extraction: Define Pydantic response models with field constraints, enums, nested models, and custom validators so LLM outputs always match your expected structure. - Automatic Retry with Feedback: When validation fails, the error message is sent back to the LLM and generation retries up to a configurable limit. - Streaming Partial Results: Stream partial objects or iterables as the LLM generates them for real-time UI updates. - Multi-Provider Support: Works with Anthropic Claude, OpenAI, and local models via Ollama using a consistent API. - Use Case: Extract company name, founding year, industry, and employee count from hundreds of unstructured text snippets into typed Python objects ready for database insertion. ## Quick Start Use the instructor skill to extract a person's name, age, and email from this text into a validated Pydantic model.

Frequently Asked Questions about instructor

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I extract structured data from LLM responses in Python?▼

Define a Pydantic BaseModel describing the fields you want, then pass it as response_model to an instructor-wrapped client call. The library validates the LLM output against your schema and returns a typed Python object.

Instructor vs LangChain for structured LLM outputs?▼

Instructor provides full type safety, automatic Pydantic validation, automatic retries, and streaming with a low learning curve. LangChain offers partial type safety and no built-in validation or retry, but suits building complex multi-step chains.

Does Instructor work with local models like Ollama?▼

Yes. Point an OpenAI client at the local Ollama base URL and use instructor.Mode.JSON. You can then call chat.completions.create with your local model name and a response_model as usual.

What happens when LLM output fails Pydantic validation?▼

Instructor sends the validation error message back to the LLM and retries generation, up to max_retries (default 3). If all attempts fail, a ValidationError is raised that you can catch and inspect per field.

Can I stream partial structured results from an LLM?▼

Yes. Use create_partial to stream incremental updates of a single model, or create_iterable to stream list items as they are generated. This supports real-time UI updates while the LLM is still producing output.