Tools · SPBoucher
Menu

Instructor

by Jason Liu and contributors (567 Labs) · Library · also known as instructor (PyPI), python-instructor

Python library for extracting validated structured data from LLM responses using Pydantic models, with automatic retries, streaming partials and support for many providers

MIT licenseOpen sourceFreeLocalSelf-hostable
Visit official site Compare

Link verified Nov 2, 2026

Overview

Instructor is an MIT-licensed Python library for getting structured, validated output from language models. You define the desired schema as a Pydantic model, patch or wrap a provider client, and request that type; Instructor converts the schema into the provider's tool-calling or JSON mode, validates the response and automatically retries with the validation errors when the model's output does not conform. Streaming of partial objects and of lists of objects, hooks for logging and both sync and async clients round out the core. It supports more than fifteen providers including OpenAI, Anthropic, Google Gemini, Mistral, Cohere, DeepSeek, Vertex AI and local models through Ollama or llama-cpp-python, and ports exist in TypeScript, Ruby, Go, Elixir and Rust.

The library is small and composable, which makes it a frequent choice for extraction pipelines (entities from filings, fields from invoices) where a full agent framework would be excessive. Its scope is deliberately narrow: it does not orchestrate multi-step agents, and provider JSON-mode quirks occasionally require schema adjustments.

Capabilities

  • Pydantic-typed outputs from LLM calls
  • Automatic validation-driven retries
  • Streaming partial objects and iterables
  • Support for 15+ providers and local models
  • Hooks for logging and error handling; sync and async clients
  • Ports in TypeScript, Ruby, Go, Elixir and Rust

Typical workflows

  1. Extract typed records from unstructured documents
  2. Classify text into an enum with validation
  3. Stream a list of extracted items to a UI as they arrive

Strengths

  • Minimal API built on Pydantic
  • Provider-agnostic
  • MIT license

Limitations

  • Not an orchestration framework
  • Depends on provider JSON or tool-calling behavior
  • Python-first; ports lag the main library

Prerequisites

  • Python 3.9+ with Pydantic
  • Provider API key or local model

Who it is for

  • Developers building extraction pipelines
  • Data teams structuring text at scale

Alternatives & comparison

  • DSPy

    Python framework for programming language-model pipelines with typed signatures and modules, then optimizing prompts and weights automatically against a metric

    Open sourceOpen source
  • LangChain

    Open-source Python and JavaScript framework whose create_agent harness builds tool-using agents on the LangGraph runtime with swappable model providers and middleware

    Open sourceOpen source
  • OpenAI API

    OpenAI's hosted developer platform: Responses and Chat Completions APIs, Realtime voice, embeddings, images, audio, fine-tuning, evals and managed agents

    ProprietaryUsage-based
  • Pydantic

    Python data-validation library using type hints to parse, validate and serialize models, with a Rust core; the schema layer behind FastAPI and many LLM SDKs

    Open sourceOpen source
  • Pydantic AI

    Type-safe Python agent framework from the Pydantic team with validated structured outputs, dependency injection, swappable model providers, MCP, durable execution and evals

    Open sourceOpen source
Compare Instructor with its alternatives →

Sources & verification

Primary sources consulted for this record. Claims are tied to the fields each source supports; the automated link checker re-verifies every URL on a schedule.

Confidence
High
Reviewed
Nov 1, 2026
Links
Verified · Nov 2, 2026

Spotted an error?

Broken link, outdated license, wrong category, or a tool that no longer exists? Tell us; reports are reviewed by the editor.

Apify

Apify Technologies s.r.o. · Data collection & crawling

In-depth entry

Cloud platform and marketplace for running web-scraping and automation programs (Actors), with storages, proxies, scheduling, an API and an MCP server for agents

Apache-2.0FreemiumUsage-basedNov 2, 2026

Claude Code

Anthropic · Coding agents & AI IDEs

In-depth entry

Anthropic's agentic coding tool that reads a codebase, edits files and runs commands from the terminal, IDEs, a desktop app, the web and CI, with MCP, hooks, skills and subagents

ProprietaryPaidUsage-basedLocalNov 2, 2026

Claude Platform

Anthropic · Model providers & APIs

In-depth entry

Anthropic's developer platform for the Claude models: Messages API, tool use, structured outputs, prompt caching, batch processing and Managed Agents, plus cloud availability

ProprietaryUsage-basedEnterpriseNov 2, 2026

LangGraph

LangChain, Inc. · Agent frameworks & orchestration

In-depth entry

Low-level orchestration framework and runtime for stateful, long-running agents expressed as graphs, with durable execution, checkpointing, human-in-the-loop and streaming

MITOpen sourceFreeLocalSelf-hostedNov 2, 2026

Model Context Protocol

Model Context Protocol, a Series of LF Projects, LLC (originated by Anthropic) · Agent frameworks & orchestration

In-depth entry

Open JSON-RPC standard for connecting AI applications to tools, data and prompts through servers, now stewarded under the Linux Foundation with SDKs in many languages

Open sourceOpen sourceFreeLocalSelf-hostedNov 2, 2026

OpenAI Agents SDK

OpenAI · Agent frameworks & orchestration

Lightweight open-source Python and TypeScript framework for agents, handoffs, guardrails, sessions and tracing, defaulting to OpenAI's Responses API with adapters for other providers

MITOpen sourceFreeLocalSelf-hostedNov 2, 2026