Structured Output Contracts

Problema y utilidad para agentes

JSON válido puede contener una respuesta falsa. Una salida truncada, un rechazo y un error de esquema tampoco son el mismo fallo. Mezclarlos en una tasa de éxito única impide entender qué está pasando.

El proyecto implementa una frontera entre generación y consumo de datos: clasifica cada intento, limita los reintentos y conserva las respuestas inválidas para poder inspeccionarlas.

Arquitectura

1. Esquemas acotados. Objetos anidados, uniones discriminadas y límites de strings y arrays dentro de un subconjunto de JSON Schema Draft 2020-12. El parser rechaza entradas inválidas sin reparación silenciosa.
2. Política explícita. Acepta, reconoce un rechazo explícito, reintenta o agota el presupuesto. El experimento limita cada tarea a dos intentos y usa metadatos reales de finalización.
3. Evaluación separada. Qwen2-0.5B-Instruct y Qwen2.5-0.5B-Instruct fijados por revisión generan localmente. La exactitud semántica se calcula aparte, sin usar etiquetas para decidir reintentos.

• Diseño y metodología

Qué demuestra

• Contratos con límites de estructura y tratamiento explícito de rechazo y truncamiento.
• Contabilidad por esquema de intentos, tokens, tiempo y validez separada de corrección.
• Preservación de fallos originales y replay de la política sobre trazas congeladas.

Resultados publicados

Doce tareas reservadas por modelo, cuatro por familia de esquema. Medición CPU float32 en Intel Xeon W-3223 con cuatro hilos. Qwen2 y Qwen2.5 en la tabla son las versiones Instruct de 0,5B parámetros.

Las flechas comparan primer intento y resultado final. Validez y corrección usan todas las tareas como denominador, incluidas abstenciones esperadas. La latencia por tarea suma todos sus intentos y excluye cargar los modelos.

Qwen2 terminó con 2/12 respuestas válidas y 4/12 resultados correctos, incluidas dos abstenciones correctas. Qwen2.5 obtuvo 6/12 y 6/12, con una abstención correcta. Qwen2.5 también produjo un cero inventado que pasó el esquema: validar estructura no verifica hechos.

Los 33 intentos reales incluyen 12 rechazos, siete respuestas malformadas, cuatro violaciones de esquema y dos truncamientos. Los 14 casos inyectados son controles de política separados, no muestras adicionales de modelos. Análisis de errores.

Reproducir

El replay instala dependencias de validación, sin modelos. La reproducción neural descarga aproximadamente 1,9 GiB de snapshots públicos y usa el lock del entorno Intel macOS medido.

Ejecutá primero el bloque de replay para crear y activar el entorno. Usá directorios de salida nuevos y una medición a la vez. Las respuestas originales no se reparan ni se reemplazan.

git clone https://github.com/lucioduran/structured-output-contracts.git
cd structured-output-contracts
git checkout ac8680a5b15731932da446694b8a0a5ced00d12a
python3.11 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-dev.txt
python -m contracts verify --output results/dev
python -m contracts verify --output results/eval

python -m pip install -r requirements-local.lock
python -m contracts download
OMP_NUM_THREADS=4 MKL_NUM_THREADS=4 OPENBLAS_NUM_THREADS=4 python -m contracts run --split dev --output build/reproduced-dev
OMP_NUM_THREADS=4 MKL_NUM_THREADS=4 OPENBLAS_NUM_THREADS=4 python -m contracts run --split eval --output build/reproduced-eval
python -m contracts verify --output build/reproduced-dev
python -m contracts verify --output build/reproduced-eval
python -m scripts.injected --output build/injected.json

Alcance y límites

• Dos modelos pequeños de una familia y doce tareas por modelo no establecen confiabilidad de producción ni un ranking general. No hubo revisión humana independiente.
• Se evalúa JSON solicitado por prompt con validación y reintentos. No incluye decodificación restringida por gramática ni productos alojados de structured output.
• La igualdad exacta de JSON es una métrica conservadora, no una medida general de factualidad. Los límites de estructura no implementan un timeout duro ni un sandbox.
• Una observación temporal por tarea. API paga: USD 0; electricidad, hardware y tiempo de operación no medidos.

• Function calling y contratos de salida de agentes

Fuentes y revisión

Los valores de esta ficha provienen del informe enlazado. No son una medición en vivo. El informe conserva la revisión ejecutada; la revisión consultada incluye la publicación posterior de ese informe.

• Revisión consultada: ac8680a5b15731932da446694b8a0a5ced00d12a
• Revisión registrada por el experimento: b73bec6fab382a96691e91a8b39af1491f53da0d
• Fecha del informe (UTC): 2026-10-21T22:58:44.050791+00:00
• Release publicada: v0.1.0 · 2026-10-21T23:02:50Z

• README y uso
• Evidencia original
• Resumen de resultados
• Respuestas y trazas originales
• Evidencia de desarrollo
• Diseño y metodología
• Análisis de errores
• Datos y procedencia
• Configuración congelada
• Modelos, revisiones y licencias
• Dependencias del entorno medido
• Licencia MIT