instructor

By 567 Labs

Structured, validated outputs from any LLM — define a Pydantic model and get a typed object back.

Website ↗ Repository ↗ Docs ↗

v1.15.42026-06-28PythonMIT

#structured-output #pydantic #validation #python

13.6k Completely free Open source

Doc version 1.0 · Updated June 28, 2026

Related tools

LiteLLM

Gateways & Routers

LangGraph

Multi-Agent Orchestration

Overview

instructor turns an LLM into a typed function: you describe the output with a Pydantic model and get a validated Python object back instead of free-form text.
It wraps the call — routing through LiteLLM — and reprompts until the response fits your schema, so downstream code can rely on the types.

flowchart LR
  schema[Pydantic model] --> inst[instructor]
  msg[messages] --> inst
  inst --> llm[LLM via LiteLLM]
  llm --> obj[typed object]

The Code samples tab shows a basic extraction and a validated-with-retry example — pick from the selector to compare.

When to use it

Reach for instructor whenever an LLM’s output feeds code that expects structure — extraction, classification, routing — and you want validation and retries instead of brittle JSON parsing.

Example

Python · response_model

When to use

Reach for instructor when you need the model's output as a typed object, not free text.

How it flows

You pass a Pydantic response_model; instructor coaxes the LLM into JSON that matches it, validates, and returns the instance.

Structure

flowchart LR
  schema[Pydantic model] --> inst[instructor]
  msg[messages] --> inst
  inst --> llm[LLM via LiteLLM]
  llm --> obj[typed object]

import instructor
from pydantic import BaseModel


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


# from_provider routes through LiteLLM, so any provider works by string.
client = instructor.from_provider("anthropic/claude-opus-4-8")

user = client.chat.completions.create(
    response_model=User,
    messages=[{"role": "user", "content": "Extract: Alice is 30 years old."}],
)
print(user.name, user.age)  # -> Alice 30

When to use

Use validators with max_retries when the output must satisfy rules, not just a shape.

How it flows

A failing Pydantic validator is fed back to the model, which retries until it passes or hits the limit.

Structure

flowchart LR
  call[create] --> llm[LLM]
  llm --> val{valid?}
  val -->|no| call
  val -->|yes| obj[typed object]

import instructor
from pydantic import BaseModel, field_validator


class Answer(BaseModel):
    sentiment: str

    @field_validator("sentiment")
    @classmethod
    def known(cls, v: str) -> str:
        if v not in {"positive", "negative", "neutral"}:
            raise ValueError("must be positive, negative, or neutral")
        return v


client = instructor.from_provider("openai/gpt-4o")
answer = client.chat.completions.create(
    response_model=Answer,
    max_retries=3,  # re-ask the model when validation fails
    messages=[{"role": "user", "content": "Classify: 'It was fine.'"}],
)
print(answer.sentiment)

Example

instructor — structured output from an LLM

A real, runnable mini-project. Download it and run with Docker.

View samples/instructor_1 on GitHub ↗

June 28, 2026

instructor — structured output from an LLM

A tiny instructor script: it extracts a typed Person (name, age, occupation) from free text. You define a Pydantic model and get a validated object back — not a string to parse. from_litellm routes the call, so MODEL picks the provider.

Configure

cd samples/instructor_1
cp .env.sample .env
# edit .env: set MODEL and the matching provider key

MODEL is a LiteLLM-style name:

Provider	`MODEL` example	Key in `.env`
Anthropic Claude	`anthropic/claude-opus-4-8`	`ANTHROPIC_API_KEY`
OpenAI	`openai/gpt-4o`	`OPENAI_API_KEY`
Google AI Studio	`gemini/gemini-2.5-flash`	`GEMINI_API_KEY`

.env is gitignored — only .env.sample is committed.

Run with Docker

cd samples/instructor_1
docker build -t aas-instructor .
docker run --rm --env-file .env aas-instructor \
  "Ada Lovelace, 36, was a mathematician and the first programmer."

Run with Docker (in a devcontainer with DooD)

In a dev container that talks to the host Docker daemon (Docker-outside-of-Docker), the foreground docker run above often prints nothing and exits 0 — but the run itself succeeds. The script runs to completion and Docker captures all of its output; only the live attached stream drops it over the VM boundary. Run detached and follow the logs instead:

cd samples/instructor_1
docker build -t aas-instructor .
docker logs -f "$(docker run -d --env-file .env aas-instructor \
  "Ada Lovelace, 36, was a mathematician and the first programmer.")"

Run locally

cd samples/instructor_1
pip install -r requirements.txt
python app.py "Ada Lovelace, 36, was a mathematician and the first programmer."

python-dotenv loads .env automatically.

Example run

Output varies by model and run — LLMs are non-deterministic. The shape is fixed by the Pydantic model; the values are extracted. Below is one run with anthropic/claude-opus-4-8.

{'name': 'Ada Lovelace', 'age': 36, 'occupation': 'Mathematician'}

Files

.env.sample

# Copy this file to `.env` and fill in the key for the provider you want.
#   cp .env.sample .env
#
# instructor's from_provider routes via LiteLLM, so MODEL picks the provider.

# Pick the model. Examples:
#   anthropic/claude-opus-4-8    Anthropic Claude   -> needs ANTHROPIC_API_KEY
#   openai/gpt-4o                OpenAI             -> needs OPENAI_API_KEY
#   gemini/gemini-2.5-flash      Google AI Studio   -> needs GEMINI_API_KEY
MODEL=anthropic/claude-opus-4-8

# Set only the key for the provider you chose; leave the rest blank.
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GEMINI_API_KEY=

app.py

"""instructor: structured, validated output from an LLM.

Extracts a typed `Person` from free text. `from_provider` routes through
LiteLLM, so MODEL in `.env` picks the provider (claude / gpt / gemini) without
touching the code; instructor returns a validated Pydantic object, not text.

Run:
    docker build -t aas-instructor .
    docker run --rm --env-file .env aas-instructor "Ada Lovelace, 36, was a mathematician."
"""

import os
import sys

import instructor
import litellm
from dotenv import load_dotenv
from pydantic import BaseModel

# Load .env when running locally; in Docker the keys come from --env-file.
load_dotenv()

MODEL = os.environ.get("MODEL", "anthropic/claude-opus-4-8")


class Person(BaseModel):
    name: str
    age: int
    occupation: str


def main() -> None:
    text = " ".join(sys.argv[1:]) or "Ada Lovelace, 36, was a mathematician and the first programmer."

    # from_litellm keeps dependencies to litellm only (no per-provider SDKs).
    client = instructor.from_litellm(litellm.completion)
    person = client.chat.completions.create(
        model=MODEL,
        response_model=Person,
        messages=[{"role": "user", "content": f"Extract the person from: {text}"}],
    )

    print(person.model_dump())


if __name__ == "__main__":
    main()

Dockerfile

# Minimal image for the instructor sample.
FROM python:3.13-slim

ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

# Provide your config at run time (.env is NOT baked into the image):
#   docker run --rm --env-file .env aas-instructor "<text to extract from>"
ENTRYPOINT ["python", "app.py"]

Related tools

Overview

When to use it

Pricing

When to use

How it flows

When to use

How it flows

Configure

Run with Docker

Run with Docker (in a devcontainer with DooD)

Run locally

Example run