Instructor: salida estructurada validada de cualquier LLM

Le pides JSON a un modelo y la mayoría de las veces te llega JSON. El problema empieza en los casos borde. Un campo que falta. Un score que debería ir de 0 a 100 y regresa en 120. Un valor de enum que el modelo se inventó. Una frase suelta envolviendo las llaves. En un script de una sola vez lo revisas a ojo y sigues. En un pipeline que alimenta una base de datos o una decisión de enrutamiento, esos bordes son justo donde todo se rompe, en silencio, en producción. Instructor es una librería pequeña que cierra esa brecha. Hace que la salida del modelo tenga que responder a un schema de Pydantic y vuelve a preguntarle al modelo, con el error de validación encima, cuando se equivoca. Te llevas objetos tipados en los que puedes confiar y una idea clara de lo que cuesta esa confiabilidad.

01 · Qué es en realidad

Instructor parchea el cliente LLM que ya tienes para que la respuesta tome la forma de un modelo Pydantic en vez de un string pelado. Defines la estructura que quieres como una clase, la pasas como response_model y recibes una instancia validada. Si el modelo no logra cumplir el schema dentro de tu presupuesto de reintentos, recibes una excepción limpia.

Es ligero a propósito. No reemplaza el SDK del proveedor, no te esconde los mensajes ni se inventa su propio DSL de prompts. Envuelve el cliente que ya usas, se apoya por debajo en el tool-calling nativo o el modo JSON del proveedor, y le suma dos cosas encima: traducir el schema a prompt y un bucle de reintentos guiado por la validación.

import instructor
from pydantic import BaseModel, Field

class Lead(BaseModel):
    score: int = Field(ge=0, le=100, description="Intención de compra, 0 (frío) a 100 (caliente)")
    intent: str
    needs_human: bool

client = instructor.from_provider("anthropic/claude-sonnet-4-5")

lead = client.chat.completions.create(
    response_model=Lead,
    messages=[{"role": "user", "content": transcript}],
    max_retries=2,
)

Ese campo score resume todo el asunto en pequeño. «ge=0, le=100» no es una pista, es una restricción dura. Si el modelo devuelve 120, Instructor atrapa el error de Pydantic y vuelve a preguntar adjuntando el fallo. No te entrega un objeto malo.

02 · Por qué importa

La forma ingenua de sacar salida estructurada es pedir JSON en el prompt, llamar a json.loads y escribir código defensivo para cada forma en que puede salir mal. Ese código defensivo crece sin parar. Quitar los fences de markdown. Lidiar con el modelo disculpándose antes del JSON. Forzar tipos. Validar rangos. Decidir qué hacer ante un fallo. Acabas manteniendo una capa frágil de parsear-y-reparar que en el fondo es un validador disfrazado.

Instructor le da la vuelta. Tus validadores son el contrato, escritos una sola vez en Pydantic:

• Tipos y rangos. «int», «Field(ge=0, le=100)», «datetime», atrapados sin esfuerzo.
• Enums. Un campo «Literal["low", "medium", "high"]» significa que el modelo no puede inventarse un cuarto valor y colártelo.
• Chequeos a tu medida. Un «@field_validator» puede rechazar un número de teléfono que no sea E.164, o una cita que no aparece en el texto fuente.

Cuando cualquiera de esos falla, el mensaje de error vuelve al modelo en el siguiente intento. Así el reintento va con información, "el campo score debe ser ≤ 100", no es una tirada a ciegas. Ese único bucle reemplaza casi todo el código de parsear-y-rezar que la gente escribe a mano.

03 · Más allá de objetos planos: anidación, listas y streaming

La extracción real casi nunca es un solo registro plano. Instructor maneja las formas con las que de verdad te topas.

Modelos anidados

Compones modelos de Pydantic y el schema se anida junto con ellos. Una «Meeting» con una lista de hijos «ActionItem» regresa completamente tipada, con cada hijo validado.

from typing import Literal

class ActionItem(BaseModel):
    owner: str
    task: str
    priority: Literal["low", "medium", "high"]

class Meeting(BaseModel):
    summary: str
    action_items: list[ActionItem]

notes = client.chat.completions.create(
    response_model=Meeting,
    messages=[{"role": "user", "content": transcript}],
)

Partials por streaming e iterables

Dos funciones distintas que la gente suele confundir:

1. Partial[Model] con «stream=True» transmite un solo objeto que va creciendo. Útil para ir pintando un formulario o una card a medida que se llenan los campos, para que la UI no quede en blanco tres segundos.
2. Iterable[Model] transmite una secuencia de objetos completos. Sacas una lista de registros y procesas cada uno según va llegando, en vez de esperar el lote entero.

Para una extracción tipo feed, como sacar cada línea de factura de un documento, la forma iterable deja que el trabajo siguiente arranque de inmediato y mantiene el pico de memoria bajo.

04 · Cuándo usarlo (y cuándo no)

Usa Instructor cuando el código que viene después necesita una forma garantizada y estás en Python:

• Extracción: convertir un correo, una transcripción o una página de PDF en registros tipados.
• Clasificación y enrutamiento: un modelo decide una categoría o un score en el que luego un switch confía.
• Enriquecimiento: llenar un schema conocido a partir de entrada desordenada antes de que llegue a la base de datos.

Sáltalo, o usa otra cosa, cuando:

• Estás en TypeScript. «generateObject» del Vercel AI SDK con un schema de Zod cubre el mismo terreno de forma nativa, así que no metas una dependencia de Python solo por eso.
• Necesitas generación libre: un ensayo, una respuesta de chat, código. Meter prosa a la fuerza por un schema pelea contra el modelo sin ningún beneficio.
• La forma es trivial y el volumen es enorme. Un solo booleano sobre millones de filas puede salir más barato con un prompt restringido más un parse de una línea que con un round-trip completo de validación.

Instructor es fácil de arrancar y da un retorno serio, pero no es gratis. La pregunta de fondo es: ¿necesito una forma validada, garantizada? Si la respuesta es sí, se gana su lugar. Si es no, es puro adorno.

05 · Cómo cambia la forma en que armas pipelines

Acá es donde deja de ser una comodidad para parsear y empieza a ser una herramienta de diseño. Una vez que la salida del modelo es un objeto tipado, la frontera entre la IA y el resto del sistema se vuelve nítida. Todo lo que viene después, el worker de la cola, el insert en la base de datos, la lógica de enrutamiento, programa contra el tipo de Pydantic, no contra un prompt. El schema pasa a ser la API entre la parte difusa y la parte determinista.

En mi propio trabajo me apoyo justo en esa costura. En Proyección, la herramienta de práctica de negociación, un turno de diálogo tiene que convertirse en una lectura estructurada (concesiones ofrecidas, posiciones que se mantienen, una postura estimada) antes de que cualquier lógica de deliberación pueda razonar sobre él. Un schema validado es lo que vuelve seguro ese traspaso. La capa de razonamiento nunca ve la prosa cruda del modelo, solo un objeto tipado que ya pasó sus restricciones. El mismo patrón aparece donde sea que un modelo alimente una decisión: extrae a un schema, valida en la frontera y deja que el código normal tome el control.

También vuelve legible el fallo. Como un error sale como un «ValidationError» de Pydantic con el campo y la regla exactos que fallaron, puedes registrar por qué el modelo no pudo cumplir el contrato. Eso es mucho más útil que "el JSON venía mal formado". Con el tiempo esos logs te dicen si el problema es tu prompt, tu schema o entrada que es genuinamente ambigua.

06 · Las concesiones, dichas sin rodeos

El bucle de reintentos es la fuente tanto del valor como del costo. Cada reintento es otra llamada completa al modelo: más tokens, más latencia, más dinero. Unas pocas reglas honestas mantienen eso a raya:

1. Haz tus validadores precisos pero alcanzables. Una restricción que el modelo nunca puede cumplir, como un regex que no coincide con entradas reales o un rango que deja afuera valores válidos, manda cada llamada a dar vueltas hasta el tope de reintentos y luego a lanzar error. Prueba tu schema contra muestras reales antes de confiar en él.
2. Pon un tope bajo de reintentos. Con dos suele alcanzar. Si un prompt necesita cuatro intentos para pasar, lo que hay que arreglar es el prompt o el schema, no subir el tope.
3. Registra cada reintento agotado. Un pico de fallos es tu aviso temprano de que la entrada cambió o de que el schema está mal. Trátalo como cualquier otro presupuesto de errores.
4. Vigila la costura de la abstracción. Instructor se apoya en el modo de salida estructurada nativo del proveedor. Las funciones propias del proveedor que te importan, como prompt caching, extended thinking o semánticas exóticas de tools, quizá necesiten configuración explícita para pasar. Así que verifica que las que usas funcionen de punta a punta en vez de dar por hecho que el wrapper reenvía todo.

Ninguna de estas es razón para descartarlo. Son el costo normal de cambiar el parseo escrito a mano por un bucle de validación, y para la mayoría del trabajo de extracción y clasificación, ese cambio vale claramente la pena.

Instructor es una de esas herramientas pequeñas que se pagan solas la primera vez que un objeto mal formado habría corrompido una fila aguas abajo sin que nadie se diera cuenta. Define el schema que de verdad necesitas, mantén los validadores honestos, pon un tope bajo a los reintentos y vigila los logs. Conviertes "el modelo casi siempre devuelve JSON" en "el modelo devuelve un objeto tipado sobre el que puedo construir". Para extracción y clasificación en Python es un default razonable. Solo recuerda que el schema cuida la forma, y tus evals todavía cuidan la verdad.