Instructor is a Python library for getting structured, validated data out of large language models. You define the shape you want as a Pydantic model, pass it as responsemodel to a chat completion call, and receive a typed Python object instead of raw JSON to parse by hand. When Pydantic validation fails, the library resends the request with the validation error attached, up to a configurable maxretries.
A single instructor.from_provider("provider/model") call creates a client for any supported provider, with API keys passed directly or read from the environment, so the same extraction code runs against different models. Ports of the same API exist for TypeScript, Ruby, Go, Elixir, and Rust. For agent runtimes with typed tools, evals, and observability, the project points to PydanticAI, which reuses the same Pydantic models.
Features
- Pydantic response models: define the output schema as a BaseModel and get a validated instance back
- Automatic retries: failed validations are retried with the error message included in the follow-up request
- Streaming partials: Partial[Model] yields progressively filled objects as the response streams
- Nested structures: lists and nested models such as a user with a list of addresses are extracted in one call
- Provider coverage: OpenAI, Anthropic, Google, Groq, and local models through Ollama, selected by a provider/model string
- Custom validators: Pydantic field_validator rules drive both validation and the retry loop
- Multi-language ports: Python, TypeScript, Ruby, Go, Elixir, and Rust implementations
