instructor

Extract structured LLM outputs validated against Pydantic schemas with automatic retries.

Updated Aug 22, 2026
One-click install
npx skills add https://github.com/vivekgoquest/hermes-agent-stable --skill instructor-vivekgoquest
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: instructor
Source: https://github.com/vivekgoquest/hermes-agent-stable/tree/main/optional-skills/mlops/instructor
Command: npx skills add https://github.com/vivekgoquest/hermes-agent-stable --skill instructor-vivekgoquest

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 uses the Instructor library to force LLM outputs into typed Pydantic models, validating every field and automatically retrying with error feedback when validation fails. ## Core Features & Use Cases - Schema-Validated Extraction: Define Pydantic response models with field constraints, enums, and custom validators so LLM outputs always match your expected structure. - Automatic Retry on Validation Failure: When output fails validation, the error message is sent back to the LLM and generation retries up to a configurable limit. - Streaming and Multi-Provider Support: Stream partial objects or iterables in real time, and switch between Anthropic, OpenAI, and local Ollama models with a consistent API. - Use Case: Extract company name, founding year, industry, and employee count from a paragraph of text into a typed CompanyInfo model, with invalid values automatically corrected through retries. ## Quick Start Use the instructor skill to extract a person's name, age, and email from a block of 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 get structured JSON output from an LLM in Python?▼

Use the instructor library with a Pydantic response model passed as response_model to the chat call. The LLM output is parsed and validated against your schema, returning a typed Python object instead of raw text.

Instructor vs LangChain for structured output parsing?▼

Instructor provides type safety, automatic Pydantic validation, automatic retries, and streaming with a low learning curve. LangChain suits complex chain orchestration but lacks built-in validation and retry for structured outputs.

Does instructor work with local models like Ollama?▼

Yes, point the OpenAI client base_url to http://localhost:11434/v1 and use instructor.Mode.JSON. You can then call models like llama3.1 with a response_model for validated structured output.

What happens when LLM output fails Pydantic validation?▼

Instructor catches the ValidationError and sends the error message back to the LLM, which regenerates the output with that feedback. This repeats up to max_retries, defaulting to 3 attempts.

Can I stream partial structured outputs with instructor?▼

Yes, use create_partial to stream incremental updates of a model as the LLM generates, or create_iterable to receive list items one at a time. This supports real-time UI updates during generation.