Who is this skill for, and what can it do?

Built for engineers who need strongly-typed structured output from LLMs: information extraction, form parsing, JSON APIs returning Pydantic models directly, agent tool-call argument parsing. Consistent API across 20 providers. See doramagic.ai/r/instructor.

What environment and dependencies are required?

Python 3.9+ (instructor declares >=3.9 in pyproject). Pydantic v2 is effectively required (function_calls.py uses model_validate_json + TypeAdapter, both v2-only — v1 hits AttributeError on Partial paths). At least one provider SDK (openai / anthropic / google-generativeai / etc.). Optional jiter (faster JSON streaming); tenacity is always installed for the retry loop.

Instructor (Structured Output via Pydantic)

Q: What are the common pitfalls, and how does this skill guard?

This skill embeds 47 constraints (4 fatal). Typical pitfalls: (1) failed_attempts XML grows linearly per retry — max_retries=5 can exceed context window; (2) from_openai mode validation uses assert — silently stripped under python -O;

Instructor: declare a Pydantic BaseModel and receive a typed instance back from any of 20 LLM providers. Core mechanism is a monkey-patch (instructor.patch / from_*) that intercepts create(), injects schema-aware kwargs, runs the call inside a tenacity retry loop, and rewrites fa

API AI Machine Learning

✓ 0 reported success·v0.1.0·Updated 2026-04-25

Overview

Instructor is a Python framework that binds Pydantic BaseModels directly to LLM output (github.com/jxnl/instructor). Core mechanism: monkey-patch (instructor.patch / instructor.from_*) intercepts the provider client's create() call, injects schema-aware kwargs, runs the call inside a tenacity retry loop, validates the JSON response against the model, and on ValidationError rewrites the prompt with failed_attempts as XML before retrying. Supports 20 providers × 36 Mode enum values = 720 (provider, mode) combinations dispatched via two dict tables. OpenAI is the default monkey-patch target (Mode.TOOLS default); Anthropic / Google (gemini / vertexai / genai) / 9 SaaS providers each ship a from_* factory. This skill embeds 47 constraints (4 fatal) covering typical pitfalls: failed_attempts XML grows linearly per retry (max_retries=5 can exceed context window), from_openai mode validation uses assert (silently stripped under python -O), and ollama / azure_openai / google / litellm fall to Provider.UNKNOWN (neither assert nor ModeError fires).

Blueprint Source

finance-bp-139

jxnl/instructor3f1d6dd1 source file

Constraints

4total

4fatal

4 must-not-violate

Evidence Quality

Confidence90%

High confidence — strong evidence base

4 non-negotiable constraints

FATALdomain_ruleinstructor-C-001

WHENWhen deploying instructor with from_openai (or routes converging on it: OpenAI / OpenRouter / Anyscale / Together / Databricks) to production

ACTIONrun the Python interpreter with the -O optimization flag, because from_openai validates the (provider, mode) pair via Python assert statements that -O strips silently

CONSEQUENCEUnder python -O, the assert mode in {...} blocks in from_openai are removed; invalid (provider, mode) combinations reach the LLM call producing malformed kwargs, undefined provider responses, or silently wrong-shaped completions across 5 OpenAI-family base_urls

domain-constraint

FATALdomain_ruleinstructor-C-003

WHENWhen pointing instructor at self-hosted OpenAI-compatible endpoints (vLLM / TGI / Ollama / LiteLLM proxy) or providers whose base_url is not in the 16-substring table (azure_openai / google / litellm / ollama)

ACTIONrely on instructor's automatic mode validation, because get_provider() will return Provider.UNKNOWN — neither the from_openai assert blocks nor the raise ModeError branches fire, leaving the (provider, mode) pair entirely unchecked

CONSEQUENCESelf-hosted endpoints fall to Provider.UNKNOWN; assert blocks dispatch on Provider enum values (OPENROUTER/ANYSCALE/TOGETHER/OPENAI/DATABRICKS) so all assertions silently pass, and provider-specific optimizations are skipped — debugging wrong-shaped responses requires reading the dispatch table source

domain-constraint

FATALdomain_ruleinstructor-C-007

WHENWhen passing max_retries to instructor (especially via from_provider)

ACTIONtreat max_retries as a single semantic — it appears at three independent code points with different defaults: patch.py default=1 (reask only), Instructor.create default=3 (reask only), and auto_client.py:180-185 transparently passes it to openai.OpenAI(max_retries=...) which is the SDK's HTTP-level retry (network only) — a single max_retries=5 to from_provider can yield 5 reasks × 5 SDK HTTP retries = 25 worst-case API calls

CONSEQUENCEPassing one max_retries through from_provider transparently amplifies into both instructor reask and SDK HTTP retry layers, producing up to N×N API calls; on rate-limited or pay-per-call providers this drains the cost budget and triggers vendor throttling cascades within a single user request

domain-constraint

FAQ

Discussion (0)

Type

📎Attach a .md file (optional, ≤500KB)

No comments yet. Be the first to share!

Changelog

v0.1.02026-04-25·Contributors: tangweigang-jpg

v0.1.0: Initial release on Doramagic.ai. Pydantic structured-output framework on jxnl/instructor with bilingual metadata, 47 anti-pattern constraints (4 fatal), and 3 FAQs.

v0.1.02026-04-25·Contributors: tangweigang-jpg

v0.1.0: Initial release on Doramagic.ai. Pydantic structured-output framework on jxnl/instructor with bilingual metadata, 47 anti-pattern constraints (4 fatal), and 3 FAQs.