instructor

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

1|Updated Mar 5, 2026
One-click install
npx skills add https://github.com/Clay-HHK/claude-skills --skill instructor-clay-hhk
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: instructor
Source: https://github.com/Clay-HHK/claude-skills/tree/main/instructor
Command: npx skills add https://github.com/Clay-HHK/claude-skills --skill instructor-clay-hhk

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve? Getting reliable, structured data from LLM responses is error-prone: raw JSON parsing breaks on malformed output, and manual validation requires repetitive boilerplate. This Skill guides you through using Instructor to enforce Pydantic schemas on LLM outputs, automatically retry failed extractions, and stream partial results. ## Core Features & Use Cases - Schema-Validated Extraction: Define Pydantic response models with field constraints, enums, and custom validators so LLM outputs are type-checked automatically. - Automatic Retries with Error Feedback: When validation fails, Instructor sends the error back to the LLM and 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 consistent APIs. - Use Case: Extract company information (name, founding year, industry, employee count) from unstructured text into a validated CompanyInfo model, with automatic retry if any field fails validation. ## Quick Start Ask the AI to write Python code using Instructor and a Pydantic model to extract structured fields from a given text with Claude or OpenAI.

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?▼

Use Instructor with a Pydantic BaseModel defining your output schema, then pass it as response_model to client.messages.create or client.chat.completions.create. Instructor validates the LLM output against your model and returns a typed Python object.

How does Instructor handle invalid LLM output?▼

Instructor validates output with Pydantic and, on failure, sends the validation error back to the LLM and retries automatically. The default is 3 retries, configurable via the max_retries parameter.

Instructor vs LangChain for structured output?▼

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 retries, but suits complex chain orchestration.

Does Instructor work with local models like Ollama?▼

Yes. Point an OpenAI client at the local Ollama server (base_url http://localhost:11434/v1) and wrap it with instructor.from_openai using Mode.JSON. You can then use response_model with models like llama3.1.

Can I stream partial structured results with Instructor?▼

Yes. Use client.messages.create_partial to stream incremental updates of a Pydantic object, or create_iterable to stream list items one by one as the LLM generates them, enabling real-time UI updates.

What validation constraints can I add to Pydantic response models?▼

You can use Field constraints like ge, le, min_length, max_length, and regex patterns, plus EmailStr and HttpUrl types, enums for fixed categories, custom field_validator functions, and model_validator for cross-field checks.