Instructor: Pydantic structured outputs for any LLM

June 14, 2026·AI Newsroom·5 min read·8 sources
open-sourcepythonpydanticstructured-outputsllminstructor+5
Instructor open-source repository social preview card
Image: GitHub / 567-labs/instructor repository (MIT)

On 2026-06-14, the public repository 567-labs/instructor — maintained by the 567-labs organization under the MIT license (LICENSE, copyright 2023 Jason Liu) — counts 13.2k stars, 1.1k forks, 108 releases, 1,560 commits and presents itself as “structured outputs for llms” (README, 2026-06-14). The stable version on PyPI is 1.15.1 (released 2026-04-03), followed by 1.15.2 on 2026-05-10 which added redaction of sensitive fields (including Authorization and x-api-key) in debug logs (CHANGELOG, 2026-05-10; PyPI, 2026-06-14).

What it does

Instructor extracts structured, validated data from any LLM using Pydantic v2 models as the output schema. The modern API is a single factory: instructor.from_provider("provider/model") returns a client compatible with the provider’s chat API, with the response_model=BaseModel parameter replacing the manual tools=[...] approach (README, 2026-06-14):

import instructor
from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int

client = instructor.from_provider("openai/gpt-4o-mini")
user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "John is 25 years old"}],
)
print(user)  # User(name='John', age=25)

Repository numbers

From the GitHub homepage, 2026-06-14: 13.2k stars, 1.1k forks, 54 watchers, 14 open issues, 36 open pull requests, 0 published security advisories, 108 releases, 1,560 total commits. Python 99.9%. The Security Advisories page is empty as of 2026-06-14, but CHANGELOG.md documents security fixes in release notes — a process inconsistency discussed in “Risks.”

Supported providers

At least 15: OpenAI, Anthropic, Google Gemini, Google Vertex AI, Mistral, Cohere, Ollama, llama-cpp-python, Groq, xAI, AWS Bedrock, Cerebras, Fireworks, Perplexity, Writer, DeepSeek, LiteLLM (docs; CHANGELOG). PyPI Provides-Extra confirms 22+ optional extras. Python >=3.9, <4.0.

Recent release roadmap (CHANGELOG, 2026-06-14)

The [Unreleased] section announces V2 Gemini cleanup, Cohere templating, and a ty 0.0.44 type checker pass.

Why it matters

1. The pain point is real. Native provider APIs require writing the JSON schema for tools=, parsing response.choices[0].message.tool_calls[0].function.arguments, handling json.JSONDecodeError, re-handling validation errors, and retrying. The README shows 25 lines without Instructor vs 5 lines with Instructor for the same extraction. For classification, entity extraction, scoring, or mapping LLM output to internal APIs, response_model=BaseModel is a real productivity multiplier.

2. Pydantic v2 propagates everywhere. class User(BaseModel) gives static type checking, IDE autocompletion, @field_validator, llm_validator, nested models, and serialization. The “BaseModel as contract” pattern is established in FastAPI, SQLModel, and LangChain — for those teams, Instructor is a drop-in surface.

3. Provider coverage is broad and current. v1.15.0 added Claude 4, GPT-4.1, o3/o4, Grok 3, DeepSeek R1/V3 to KnownModelName. Mode management maps Pydantic response_model to the provider’s native mechanism. from_provider("openai/gpt-4o-mini") and from_provider("anthropic/claude-3-5-sonnet") expose the identical API.

4. Production-ready patterns are present. Automatic retries on validation failure (max_retries=3), partial object streaming (Partial[User]), LLM-assisted validators (llm_validator), Jinja templates, logging hooks, async/await, raw completion access via create_with_completion(). All in main.

5. A sibling product exists for agents. The README and docs say: “Use Instructor for fast extraction, reach for PydanticAI when you need agents.” The same Pydantic models work in both.

Practical implications

Risks and caveats

  1. Mode-dependence across providers. response_model= behavior depends on the mode selected per provider (TOOLS, JSON, JSON_SCHEMA, ANTHROPIC_TOOLS, GEMINI_TOOLS, etc.). Reliability varies: Mode.TOOLS on Anthropic and Mode.JSON_SCHEMA on OpenAI may not produce equal success rates for complex schemas. “Works with all providers” means “uniform API,” not “uniform reliability.”
  2. Token budget risk. A deeply nested Pydantic schema serialized as tools=[...] can consume a significant fraction of the context window before the user message arrives.
  3. Retry loop risk. If the schema is semantically too strict, retries burn tokens without producing output. Mitigations: relax constraints, raise max_retries, use Optional[T] or Union[A, B], accept a free raw: str fallback. No automatic dead-letter is documented.
  4. GHSA page is empty, but releases document security fixes. Scanners (e.g., osv-scanner, Snyk) may miss formal advisories for diskcache (CVE-2025-69872) or litellm 1.82.7/1.82.8 in apps using Instructor. Pin instructor>=1.15.0 if you use litellm or diskcache as dependencies.
  5. README adoption numbers are maintainer claims. “100k developers,” “3M+ monthly downloads,” “10k+ stars” are README statements, not independently verifiable. Current 13.2k stars are verifiable.
  6. instructor.pydantic.dev doesn’t resolve as of 2026-06-14. The active docs are at python.useinstructor.com.

What to watch

Verdict

Instructor is a mature, MIT, well-maintained Python library with 13.2k stars, 108 releases, and a clear answer to a recurring problem: extracting validated Pydantic objects from LLMs without reinventing the schema → tool call → parse → validation → retry cycle. The from_provider + response_model API is a productivity multiplier, Pydantic v2 brings type safety, and provider coverage is broad and current. The maintainer’s honest “extraction vs agents” separation is a maturity signal.

The caveats matter: formal advisories are missing, mode behavior varies across providers, schema weight must be measured, and the retry loop isn’t a robustness guarantee. The active docs are at python.useinstructor.com, not instructor.pydantic.dev. If your use case is exactly “extract validated Pydantic objects from LLMs with automatic retries, multi-provider, in Python,” Instructor is the right choice as of 2026-06-14; for agent loops, observability, or eval pipelines, start with PydanticAI or LangGraph.

Sources