Structured extraction

Downstream code needs predictable fields and types. A free-form completion can contain prose, malformed JSON, omitted fields, or unexpected values. Parsing and schema validation make these failures explicit before the result becomes an entity-extraction payload.

A schema can require a postal code field or restrict an entity category. It cannot establish that the postal code exists or that the entity category correctly describes the source text.

The adapters use different mechanisms to obtain a validated result:

These are implementation paths, not a measured quality ranking. Provider errors, invalid output, or exhausted retries can still occur. See the adapter reference for the contract of each implementation.

A completion provider returns text; a structured extractor promises a value validated against a caller-supplied model. Separating these capabilities lets an adapter implement the operation it supports without pretending that all providers have the same native features.

LLMEntityExtractor checks for the structured protocol and dispatches accordingly. A runtime protocol check establishes the presence of the interface, not successful behavior for every schema or model. Provider conformance and extraction quality require separate verification.

The helper derives a JSON schema from a Pydantic model, adds it to the prompt, and calls the provider. It tries to parse the response, handling some common formatting problems such as markdown fences and trailing commas, then validates the object against the model.

A JSON parse or Pydantic validation failure can trigger feedback identifying the problem. The failed response and that feedback are added to the next attempt. After the configured number of retries, the helper raises StructuredExtractionError with diagnostic information.

This retry addresses output structure. It does not add evidence for a fact or guarantee that a later attempt will succeed.

A native schema or tool-output mode lets the adapter pass structure through the provider’s supported interface instead of relying only on prompt text. The library still validates the returned data and handles failures.

Preserving these paths avoids reducing every provider to the least specific completion interface. It does not establish that native output is always correct, that the first request always succeeds, or that a particular provider outperforms another on the application’s data.

InstructorProvider is one way to satisfy the structured-output contract. Keeping it optional lets applications already using Instructor adopt that adapter without requiring it for applications using a native provider or the library’s retry helper.

The design makes the structured contract the integration point. It does not depend on a universal performance comparison between Instructor, native adapters, and prompt-based retries.

A caller can use a provider’s structured interface for another supported Pydantic response model. A plain completion provider can instead be passed to the schema-aligned helper.

The provider API reference owns arguments, defaults, exceptions, and result types. Bring your own model shows how to configure a provider.

Suppose an application requires an address with street, city, and postal_code. A model returns an object with the first two fields only. The object may be valid JSON but fails the application’s schema because postal_code is missing.

The retry feedback identifies that missing field and asks for a corrected object. A later attempt either validates or fails again. This hypothetical example explains control flow; it is not a measured success rate or a promise that the model knows the missing value.

Exhausted structural retries raise StructuredExtractionError. Its attempt texts and validation errors let an application inspect what failed. Provider transport, authentication, and rate-limit errors belong to the provider error hierarchy and are distinct from invalid JSON.

An application should decide how to handle an unavailable extraction result rather than treating a failed run as an empty, successful extraction. See Error behavior.

Increasing the retry limit permits more provider calls and adds latency and cost. It does not guarantee a valid result. Temperature and prompt choices also affect output, but a temperature of zero does not establish universal deterministic behavior.

Evaluate representative schemas and inputs, recording validation failures separately from factual extraction errors. Select the retry budget for the application’s tolerance for latency and failure.