Pydantic

Salidas estructuradas con Pydantic

Pydantic representa la evolución natural en el manejo de salidas estructuradas con OpenAI. Mientras que definir esquemas JSON manualmente requiere escribir estructuras complejas y propensas a errores, Pydantic permite definir modelos de datos usando clases Python nativas que se convierten automáticamente en esquemas JSON válidos.

Esta aproximación no solo simplifica el código, sino que añade validación automática de tipos, documentación integrada y una experiencia de desarrollo más robusta. Los modelos Pydantic actúan como contratos claros entre tu aplicación y la API de OpenAI.

Pydantic es una librería independiente y se usa en muchos otros sitios, por ejemplo en desarrollo de aplicaciones web con FastAPI.

Requiere instalación:

pip install pydantic pydantic[email]

Definición de modelos básicos

La creación de un modelo Pydantic es tan simple como definir una clase que herede de BaseModel. Cada atributo de clase representa un campo en la estructura de datos esperada:

De esta forma es fácil trabajar de manera intercambiable entre diccionarios de python y objetos de Pydantic.

Incluso obtener el JSON Schema correspondiente:

Después, ese esquema pydantic puede ser usado en peticiones a openai:

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class ProductReview(BaseModel):
    product_name: str
    rating: int
    sentiment: str
    key_points: list[str]

response = client.responses.parse(
    model="gpt-4.1",
    input=[
        {"role": "system", "content": "Analiza esta reseña de producto y extrae la información estructurada."},
        {"role": "user", "content": "El iPhone 15 es increíble. La cámara es espectacular y la batería dura todo el día. Lo recomiendo totalmente. 5 estrellas."}
    ],
    text_format=ProductReview
)

review = response.output_parsed
print(f"Producto: {review.product_name}")
print(f"Puntuación: {review.rating}/5")
print(f"Puntos clave: {', '.join(review.key_points)}")

El modelo ProductReview define exactamente qué campos esperamos y sus tipos. OpenAI convierte automáticamente este modelo en el esquema JSON correspondiente y garantiza que la respuesta cumpla con la estructura definida.

Otro ejemplo:

Modelos anidados y complejos

Pydantic brilla especialmente cuando necesitas estructuras de datos complejas con múltiples niveles de anidamiento. Puedes componer modelos usando otros modelos como tipos:

class Address(BaseModel):
    street: str
    city: str
    postal_code: str
    country: str

class Contact(BaseModel):
    name: str
    email: str
    phone: str

class Company(BaseModel):
    name: str
    industry: str
    address: Address
    contacts: list[Contact]
    founded_year: int

response = client.responses.parse(
    model="gpt-4.1",
    input=[
        {"role": "system", "content": "Extrae información de empresa del siguiente texto."},
        {"role": "user", "content": "TechCorp es una empresa de software fundada en 2010. Su oficina principal está en Calle Mayor 123, Madrid 28001, España. El contacto principal es Ana García (ana@techcorp.com, +34 91 123 4567) y también puedes contactar con Carlos López (carlos@techcorp.com, +34 91 765 4321)."}
    ],
    text_format=Company
)

company = response.output_parsed
print(f"Empresa: {company.name}")
print(f"Dirección: {company.address.street}, {company.address.city}")
print(f"Contactos: {len(company.contacts)} personas")

Esta composición de modelos permite crear estructuras de datos tan complejas como necesites, manteniendo el código legible y organizando la lógica de validación de forma modular.

Validación y tipos avanzados

Pydantic ofrece validación automática que va más allá de los tipos básicos. Puedes usar tipos especializados y añadir restricciones personalizadas:

from pydantic import BaseModel, Field, EmailStr
from typing import Literal
from datetime import datetime

class TaskPriority(BaseModel):
    level: Literal["low", "medium", "high", "urgent"]
    score: int = Field(ge=1, le=10, description="Puntuación numérica de prioridad")

class Task(BaseModel):
    title: str = Field(min_length=5, max_length=100)
    description: str
    priority: TaskPriority
    assignee_email: EmailStr
    due_date: str = Field(description="Fecha en formato YYYY-MM-DD")
    estimated_hours: float = Field(gt=0, le=40)

response = client.responses.parse(
    model="gpt-4.1",
    input=[
        {"role": "system", "content": "Convierte esta descripción en una tarea estructurada."},
        {"role": "user", "content": "Necesito que María (maria@empresa.com) revise el código del módulo de autenticación antes del viernes. Es muy urgente y probablemente le lleve unas 6 horas."}
    ],
    text_format=Task
)

task = response.output_parsed
print(f"Tarea: {task.title}")
print(f"Prioridad: {task.priority.level} (puntuación: {task.priority.score})")
print(f"Asignada a: {task.assignee_email}")

Los decoradores Field permiten definir restricciones específicas como rangos numéricos, longitudes de cadena y descripciones que ayudan al modelo a generar respuestas más precisas.

Manejo de datos opcionales y valores por defecto

En muchos casos reales, algunos campos pueden ser opcionales o tener valores por defecto. Pydantic maneja estas situaciones de forma elegante:

from typing import Optional

class ArticleAnalysis(BaseModel):
    title: str
    word_count: int
    reading_time_minutes: int
    main_topics: list[str]
    sentiment: Literal["positive", "negative", "neutral"] = "neutral"
    summary: Optional[str] = None
    keywords: list[str] = Field(default_factory=list)
    confidence_score: float = Field(default=0.8, ge=0.0, le=1.0)

response = client.responses.parse(
    model="gpt-4.1",
    input=[
        {"role": "system", "content": "Analiza este artículo y proporciona métricas detalladas."},
        {"role": "user", "content": "La inteligencia artificial está transformando la industria tecnológica. Las empresas invierten millones en desarrollar soluciones innovadoras que mejoren la productividad y la experiencia del usuario."}
    ],
    text_format=ArticleAnalysis
)

analysis = response.output_parsed
print(f"Título: {analysis.title}")
print(f"Temas principales: {', '.join(analysis.main_topics)}")
print(f"Resumen disponible: {'Sí' if analysis.summary else 'No'}")

Esta flexibilidad permite que el modelo adapte su respuesta según la información disponible, proporcionando valores por defecto sensatos cuando ciertos datos no están presentes en el texto de entrada.

Ventajas sobre esquemas JSON manuales

El uso de Pydantic aporta beneficios significativos comparado con la definición manual de esquemas JSON:

Legibilidad y mantenimiento: Los modelos Pydantic son código Python nativo, lo que los hace más fáciles de leer, documentar y mantener que estructuras JSON complejas.

Validación automática: Pydantic valida automáticamente los tipos de datos y restricciones, detectando errores antes de que lleguen a tu lógica de aplicación.

Autocompletado y detección de errores: Los IDEs modernos proporcionan autocompletado completo y detección de errores en tiempo real al trabajar con modelos Pydantic.

Reutilización: Los modelos pueden reutilizarse en diferentes partes de tu aplicación, no solo para OpenAI sino también para validación de APIs, serialización de datos y documentación automática.

# Ejemplo de reutilización del modelo
class UserProfile(BaseModel):
    name: str
    age: int
    interests: list[str]
    location: str

# Uso con OpenAI
response = client.responses.parse(
    model="gpt-4.1",
    input=[
        {"role": "user", "content": "Soy Juan, tengo 28 años, me gusta el fútbol y la programación, vivo en Barcelona"}
    ],
    text_format=UserProfile
)

# El mismo modelo se puede usar para validar datos de API
def create_user(data: dict) -> UserProfile:
    return UserProfile(**data)  # Validación automática

# O para serializar respuestas
user = response.output_parsed
user_json = user.model_dump()  # Conversión a diccionario

Esta integración natural con el ecosistema Python hace que Pydantic sea la opción preferida para aplicaciones profesionales que requieren salidas estructuradas robustas y mantenibles.