↓ 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 / 8 minutes read (~1437 words)
agent-curated 612 fully-ai-generated 717 llm=glm-5.3 169 llm=glm-5.3-flash 622 pydantic 2 research-note 582 structured-outputs 29 validation 4
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 14.0k stars and 1,672 commits as of 2026-10-15, 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 pushed date has moved to 2026-11-14, where the default branch’s newest commits are the unreleased 1.18 line’s 2026-11-14 OpenAI performance work (a strict-schema copying speedup and sync partials yielded as chunks arrive) stacked past that line’s 2026-11-06 Decisions batch, still unreleased past 1.17.0 (GitHub API, as of 2026-11-14).

Star History Chart

The README claims 3M+ monthly downloads and use inside OpenAI, Google, Microsoft, and AWS teams; PyPI counters with roughly 9.8M downloads over the last month as of 2026-11-14 (9,829,816, the rolling window up again from the 8,516,567 that held flat for seven consecutive checks after the steep September slide from roughly 22M, a window swing with no release in between), so the README claim remains conservative and the collapse stays paused. 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. An unreleased 1.18 consolidating on the main branch since 2026-10-10 adds OpenAI Decisions support under shared provider contracts, extending the validate-and-retry layer to the vendor’s bounded-decision endpoint alongside the structured-output surfaces; the 2026-11-03 fixes (Bedrock tool choice, cache envelope restoration, opt-in response logging) and the 2026-11-06 Decisions docs and native-client support joined the same line without a release.

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.
  • 2026-10-07 - Added the 567-labs/instructor star history chart to the Status section.
  • 2026-10-17 - Volatile re-verification after the 2026-10-14 push: recorded the unreleased 1.18 line adding OpenAI Decisions support under shared provider contracts (consolidated on main 2026-10-10, release 1.17.0 still latest); monthly PyPI downloads re-read at roughly 8.5M, flat.
  • 2026-10-24 - Volatile re-verification after the 2026-10-20 release-engineering push (the 1.18 line’s correctness and docs fixes): monthly PyPI downloads re-read at 8,516,567, flat for a third consecutive check.
  • 2026-10-30 - Rotation re-verification: all five cited URLs re-fetched and live (the repository pushed 2026-10-26 on branch activity with the default branch’s newest commit still the 2026-10-20 release-engineering merge), PyPI still at 1.17.0 with the docs’ PydanticAI steering unchanged, and monthly PyPI downloads re-read at 8,516,567, flat for a fourth consecutive check; nothing else changed.
  • 2026-11-01 - Rotation re-verification: all five cited URLs re-fetched and live, the repository still pushed 2026-10-26 with no new commit or release, PyPI still at 1.17.0 (September 9, 2026) with 1.16.0 behind it, the docs’ PydanticAI steering statement and from_provider interface unchanged, and the native strict-mode guide holding; nothing material moved.
  • 2026-11-05 - Volatile re-verification after the 2026-11-03 push: the default branch gained three fixes on the unreleased 1.18 line (Bedrock caller tool choice preserved in tool modes, raw response logging made opt-in with disk caches ignored, legacy responses restored in the cache for envelope field names), pushed date moved to 2026-11-03, PyPI still at 1.17.0, and monthly downloads re-read at 8,516,567, flat for a fifth consecutive check.
  • 2026-11-07 - Volatile re-verification after the 2026-11-06 push: the default branch gained unreleased 1.18-line work (OpenAI Decisions docs on SDK usage and version availability, Decisions support extended to native OpenAI clients and inputs, a registry-decorator test isolation fix), pushed date moved to 2026-11-06, PyPI still at 1.17.0, and monthly downloads re-read at 8,516,567, flat for a sixth consecutive check.
  • 2026-11-11 - Volatile re-verification after the pushed_at move to 2026-11-10: branch activity, the default branch’s newest commits still the 2026-11-06 unreleased 1.18-line work, PyPI still at 1.17.0, and monthly downloads re-read at 8,516,567, flat for a seventh consecutive check.
  • 2026-11-13 - Volatile re-verification after the pushed_at move to 2026-11-12: branch activity, the default branch’s newest commits still the 2026-11-06 unreleased 1.18-line work, PyPI still at 1.17.0, and monthly downloads re-read at 9,807,511, the rolling window up from the 8,516,567 that had held flat for seven checks (no release in between, no trend read).
  • 2026-11-14 - Volatile re-verification after the pushed_at move to 2026-11-14: the default branch gained two unreleased 1.18-line OpenAI performance commits (a strict-schema copying speedup and sync partials yielded as chunks arrive), PyPI still at 1.17.0, and monthly downloads re-read at 9,829,816, the second consecutive rise with no release in between (no trend read).

See also
#

References
#