Instructor Ai

Instructor is the most widely-used library for getting structured, typed data out of LLMs — wrap your OpenAI/Anthropic client with instructor.patch(), define a Pydantic model for the output schema, and call client.chat.completions.create() as normal. Instructor handles the function-calling schema generation, LLM response parsing, Pydantic validation, and automatic retry on validation failure. For agents: extract structured entities (User, Task, CalendarEvent) from natural language, validate LLM outputs before acting on them, and stream partial objects for low-latency UX. Pure Python library — no external API, no auth, no network hop. Confidence is docs-derived.

Python SDK: pip install instructor. OpenAI integration: import instructor; from openai import OpenAI; client = instructor.from_openai(OpenAI()). Define schema: from pydantic import BaseModel; class User(BaseModel): name: str; age: int. Extract: user = client.chat.completions.create(model="gpt-4o", response_model=User, messages=[{"role": "user", "content": "Extract: John is 30 years old"}]). Returns typed User(name="John", age=30). Anthropic: client = instructor.from_anthropic(anthropic.Anthropic()). Validation: Pydantic validators run on extracted data — Field(gt=0) for positive integers, @validator for custom logic. Retry on failure: max_retries=3 parameter auto-retries with error feedback on validation failure. Streaming: create_partial() returns generator of partial objects. Async: AsyncInstructor for async/await patterns. Nested models: fully supported (Task with subtasks: List[SubTask]).

No external auth — Instructor is a pure Python library that wraps existing LLM clients. Auth is handled by the underlying LLM client (OpenAI API key, Anthropic API key, etc.) — Instructor does not add its own auth layer. No network calls beyond what the underlying LLM client makes. Data: prompts/responses go directly to the LLM provider — no Instructor intermediary. Provider-specific modes: instructor.Mode.TOOLS (default for OpenAI), instructor.Mode.JSON (for providers without function calling), instructor.Mode.ANTHROPIC_TOOLS (Anthropic).

Automatic retry: on Pydantic ValidationError, Instructor re-prompts the LLM with the error message (up to max_retries). This increases LLM API calls but dramatically improves extraction reliability. Token cost: structured extraction uses more tokens (schema + retry overhead) vs. unstructured. Streaming with create_partial(): yields incomplete Pydantic objects — validate before acting on partial data. Provider quirks: some providers (Gemini, Cohere) have less reliable function-calling — use instructor.Mode.JSON with clear schema descriptions. Complex nested schemas: deeply nested models may confuse weaker LLMs — simplify schemas or break into multiple extraction calls. Rate limits: managed by underlying LLM client.

python.useinstructor.com covers API reference, Pydantic integration guide, provider-specific setup (OpenAI, Anthropic, Google, Cohere, local Ollama), streaming, and advanced patterns. Getting started: pip install instructor — first structured extraction in 5 minutes (requires LLM provider API key). GitHub: instructor-ai/instructor (10k+ stars). Community via Discord (active) + GitHub Issues. Excellent documentation with extensive examples. Instructor is a near-essential utility for any agent doing structured data extraction from LLMs.