Technology · Agentic → Structured Output · Open Source · wiki:deep

Instructor

Taxonomy

Instructor gives reliable structured outputs from LLMs via Pydantic: define a response_model, call instructor.from_provider(...), and get validated typed objects — with automatic retries on validation failure, streaming partials, nested models, and the same API across major providers (OpenAI, Anthropic, Google, Ollama, …). Multi-language ports exist (TS, Go, Ruby, Elixir, Rust). MIT. Authors position it for fast schema-first extraction; richer agent runtimes point to PydanticAI.

RepoDocsStack: agentic-structured-output

Why it matters here

Default research pick for cheap schema gates before anything hits durable state or side-effecting tools. Prefer Outlines/Guidance when you need decode-time guarantees on self-hosted models; prefer LMQL for research query/constraint languages; keep Instructor when the install is mostly cloud chat APIs.

How it works

Patch or wrap a provider client; each completion requests a Pydantic model. On validation errors, Instructor retries with error context until success or max_retries.

  1. pip install instructor; define Pydantic models.
  2. client = instructor.from_provider("…").
  3. create(response_model=…, messages=…).
  4. Use the typed object; fail closed if retries exhaust.

Related: guidance · lmql · outlines · topics/12-central-nervous-system

Flow

Scroll inside the canvas to pan

When to reach for it

  • Use when: Python (or ports) need schema-validated LLM extraction across providers.
  • Skip when: you need logit-level grammar guarantees on open models (outlines, guidance) or a full agent framework (PydanticAI / LangGraph).
  • Prefer instead: Outlines for self-hosted guaranteed JSON; Guidance for interleaved constrained prompting.

Limits

  • Retries cost tokens and can still fail — plan a hard abort.
  • API JSON mode ≠ proof: provider cooperation varies; not a formal guarantee like some local engines.
  • Not IAM/policy: typed output can still be an unauthorized action.
  • Not the company ledger.

Linked from

Catalog backlinks — what points here (wiki “what links here”).

Features

Stacks

Peers

Document management

What we checked

Claims below are backed by science sources on disk.

Structured extraction role

567-labs/instructor · MODERATE

“Get reliable JSON from any LLM. Built on Pydantic for validation, type safety, and IDE support.”

Docs / API

Instructor documentation home · MODERATE

“Extract structured data from any LLM with type safety, validation, and automatic retries.”

Feature notes

Key features list · MODERATE

“Automatic Retries: Built-in retry logic when validation fails - no more manual error handling”

In this research stack

Features and peers linked from the catalog map — not a second product surface.

Features it supports

Same cell

Stack

Document management

Source

Primary repo github.com/567-labs/instructor · Open Source

technologies/instructor/README.md

Research inventory

9 tags · 42 out · 43 in · 3 artifacts · 0 gaps · 28 corpus docs

Catalog tags

landscape.layer
Agentic
landscape.subcategory
Structured Output
license_tag
Open Source
maps.dm
present
maps.features
6
one_liner
Agentic
review.depth
science
slug
instructor
title
Instructor

Artifacts

  • dm_map · present · technologies/instructor/document-management.md
  • features_map · present · technologies/instructor/features.md
  • readme · present · technologies/instructor/README.md

Out · alternative_to

Out · dm_axis

Out · maps_to

In · alternative_to

In · dm_axis

In · in_stack

In · maps_to

Corpus tags

category
Agentic → Structured Output
dedication
open-source
feature
closed-execution-loop
job-finance
job-insurance
outcome-verification
testing-debugging-optimization
wt-intelligence
kind
map_edge
tech_features
tech_quote
tech_readme
tech_science_source
tech_section
needs_deepen
false
quality
ok
section
Document management map
Evidence
Features map
GitHub map
How it works
Limits & failure modes
Links
Scientific notes
What it is
When to use / skip
Why it matters here
slug
instructor
source_id
instructor-docs
instructor-features
instructor-github
technology
instructor

Corpus documents (28)

map_edge · 6

  • instructor → closed-execution-loop
  • instructor → job-finance
  • instructor → job-insurance
  • instructor → outcome-verification
  • instructor → testing-debugging-optimization
  • instructor → wt-intelligence

tech_features · 1

  • Instructor · features

tech_quote · 6

  • Instructor · instructor-docs
  • Instructor · instructor-docs
  • Instructor · instructor-docs
  • Instructor · instructor-features
  • Instructor · instructor-features
  • Instructor · instructor-github

tech_readme · 1

  • Instructor

tech_science_source · 3

  • Instructor · instructor-docs
  • Instructor · instructor-features
  • Instructor · instructor-github

tech_section · 11

  • Instructor · Document management map
  • Instructor · Evidence
  • Instructor · Features map
  • Instructor · GitHub map
  • Instructor · How it works
  • Instructor · Limits & failure modes
  • Instructor · Links
  • Instructor · Scientific notes
  • … +3 more