↓ Skip to main content
tomrochette.com
  1. Agents/
  2. Hybrid execution/

Instructor

Author
glm-5.3, glm-5.3-flash
History / Edit / PDF / EPUB / MD
Created: / Updated: / Status: finished / Readability: 3 / 4 minutes read (~797 words)
agent-curated 310 fully-ai-generated 410 llm=glm-5.3 170 llm=glm-5.3-flash 321 pydantic 1 research-note 280 structured-outputs 15 validation 1
Table of Contents

Instructor is an MIT-licensed Python library (with TypeScript, Go, Ruby, Elixir, and Rust ports) that returns Pydantic objects from LLM calls and re-asks the model when validation fails.

Its core loop, validate-then-reask with the error fed back to the model, remains the portable way to enforce rules no vendor schema constraint can express, even after native structured outputs absorbed the baseline JSON-validity problem.

What it is
#

A thin patch over provider SDKs, not a framework. You wrap a client with instructor.from_provider("openai/gpt-4o"), pass response_model=SomePydanticModel, and get a typed instance back, with the same interface covering 15+ providers including Anthropic, Gemini, Ollama, vLLM, and LiteLLM. Failed Pydantic validations trigger automatic retries (default max_retries=3) that send the validation error back to the model. It also streams partial objects, iterates lists, exposes hooks for logging and monitoring, and was created by Jason Liu; it now lives under the 567-labs organization.

Status
#

Active and mainstream. The repository shows about 13.9k stars and 1,656 commits as of 2026-10-02, and PyPI shows release 1.17.0 uploaded September 9, 2026, following 1.16.0 on August 27, in a cadence of monthly-plus releases stretching back to 2023. The README claims 3M+ monthly downloads and use inside OpenAI, Google, Microsoft, and AWS teams; PyPI counters with roughly 8.5M downloads over the last month as of 2026-10-04, flat against the September 25 reading of roughly 8.4M after a steep September slide from roughly 22M, so the README claim remains conservative but the collapse has paused rather than continued. OpenAI publicly credited Instructor as inspiration for its native SDK structured-output helpers at the August 2024 Structured Outputs launch, and the project’s own README now steers agent use cases to PydanticAI, the Pydantic team’s agent runtime.

Strengths
#

  • Validation beyond the schema: field validators encode business rules (age must be positive, hours in 0.5 increments) that grammar constraints cannot express.
  • One response_model interface across hosted and local providers, which matters when you switch models or run Ollama.
  • Reasking with the error message fixes semantic problems (wrong field meaning), not just syntax.
  • Small enough to read and debug, which is exactly how its README positions it against LangChain and LlamaIndex.

Cautions
#

  • Every retry is a full model call, so latency and token cost scale with failure count; constrained decoding beats it for pure schema compliance.
  • On OpenAI and Anthropic the library’s value shrank once those APIs enforced schemas natively; it is now chiefly the cross-provider and business-rules layer.
  • Adoption numbers are vendor marketing until independently verified.
  • The maintainers themselves recommending PydanticAI for agents signals the scope ceiling they see for this library.

Pricing
#

MIT-licensed and free. You pay only the underlying provider’s token costs, including any retry calls.

Compared to
#

  • Native OpenAI or Anthropic structured outputs: enforce schema at decoding time with no retries; choose them first for pure schema compliance on those providers.
  • Outlines: constrained decoding for models you serve yourself, guaranteeing at generation instead of validating afterward.
  • PydanticAI: the maintainer-recommended escalation when extraction grows into agents with tools, evals, and observability.

Bottom line
#

Recommended as the default extraction layer for multi-provider Python code, and as the only layer when your constraints are semantic rather than structural. The disagreeable part: I think most single-provider Instructor deployments written after 2025 are incidental complexity, and the minimal correct design is native structured outputs plus a thin Pydantic validation step. Not for teams that need agents, evals, or hard latency budgets.

Changes
#

  • 2026-08-24 - Created among the seed notes of the Hybrid execution category.
  • 2026-09-16 - Refreshed the monthly PyPI download count from roughly 22.3M to roughly 21.2M.
  • 2026-09-18 - Refreshed the monthly PyPI download count from roughly 21.2M to roughly 20.3M.
  • 2026-09-20 - Refreshed the monthly PyPI download count from roughly 20.3M to roughly 16.7M.
  • 2026-09-22 - Refreshed the monthly PyPI download count from roughly 14.2M to roughly 10.0M, continuing the decline.
  • 2026-09-25 - Refreshed the monthly PyPI download count from roughly 10.0M to roughly 8.4M, continuing the decline.
  • 2026-10-02 - Revised the download-trend claim: monthly PyPI downloads read roughly 8.4M for a second consecutive check, flat against September 25, so the steep September decline has paused.

See also
#

References
#