¿Qué hace Constructor de Resúmenes Gráficos?
Convierte material de investigación (PDF, notas, registros) en un resumen gráfico
de una sola página donde cada elemento es trazable hasta el material, además de un
result.json completo según el contrato.
División del trabajo — tú haces la ciencia, los scripts hacen el dibujo:
- Tú (el agente): lees el material real, extraes entidades/relaciones/datos, eliges la codificación visual, decides qué va al lienzo vs. al pie de figura, verificas la figura contra el material.
- Los scripts (
scripts/, Python puro + matplotlib): diseño, renderizado, comprobaciones, ensamblaje del resultado. Deterministas: mismo modelo de entrada → misma figura de salida.
Entorno y rutas
- Raíz de la skill:
/skills/weekly-skill(scripts bajoscripts/, documento de esquema bajoreferences/). Trabaja bajo/app/work; los entregables finales van a/app/output. - Entrada:
/input/case.json(+ task.md; archivos de material referenciados por el caso). - Se espera Python con matplotlib; si falta, la exportación PNG recurre automáticamente a Pillow y la exportación PDF falla con un remedio indicado — consulta el manual.
- Coste típico: 10–20 solicitudes al modelo, dentro del presupuesto de 64 solicitudes / 900 segundos. Cada ejecución de script de construcción/verificación es una llamada de herramienta.
Flujo de trabajo
Paso 0 — Lee el caso y crea el esqueleto de result.json (haz esto primero)
Lee /input/case.json completamente. Anota case_id y cada campo de
output_contract — estas son tus obligaciones de entrega. Luego inmediatamente:
python scripts/make_result.py --stage init \
--case /input/case.json --out /app/output/result.json
Esto escribe cada campo del contrato como un null explícito con una razón pendiente.
A partir de ahora, incluso un fallo deja un entregable completo según contrato. Vuelve a ejecutarlo
con --stage final (Paso 6) para rellenarlo.
Paso 1 — Lee el material real
Abre los archivos reales a los que apunta el caso (nunca asumas el contenido a partir de las etiquetas).
Para PDFs usa la herramienta pdf-text-tool / scientific-python; escanea páginas solo si es necesario
OCR. Guarda un archivo sources.json que asocie cada archivo de material con su texto extraído
— los pasos posteriores verifican las citas contra él automáticamente:
{ "materials/paper.pdf": "<texto extraído completo>" }
Paso 2 — Extrae la ciencia (tu criterio, no el de un script)
Rellena una hoja de trabajo (plantilla: templates/agent_worksheet.md) directamente a partir
del material:
- Pregunta — ¿qué problema plantea el material? Cítala textualmente.
- Entidades — las cosas que deben aparecer (moléculas, células, dispositivos, métodos, cohortes...). Para cada una: etiqueta, una cita textual, localizador (archivo + página/sección/oración).
- Relaciones — conexiones direccionales que el material indica (A activa B, la dosificación motiva la pregunta...). Registra la dirección y la oración que la indica.
- Datos — cada número que puedas dibujar: valor, unidad, condición, y la
oración de la que proviene. Si un número que deseas no está en el material,
no lo dibujes; enuméralo en
uncertainty/limitsen su lugar. - Conclusión — afirmaciones que el propio material hace.
Reglas de evidencia: las citas son subcadenas textuales del material; los localizadores son lo suficientemente precisos para que un humano los encuentre en segundos; cualquier cosa que no puedas referenciar va al pie/notas, nunca al lienzo como datos.
Paso 3 — Redacta figure_model.json
Escribe /app/work/figure_model.json siguiendo el esquema en
references/model_schema.md (ejemplo completo: examples/transformer-1706.03762/).
Decisiones clave que tomas:
- Plan de paneles: normalmente 4–6 paneles en orden de lectura pregunta → método → resultados (1–2) → conclusión; un hallazgo por panel.
- Diseño por panel:
flow(cajas + flechas para entidades/relaciones),chart(barras/barras horizontales/barras agrupadas/líneas para datos),stats(destacados de números grandes para 2–4 valores principales),text(conclusiones con viñetas). - Canales visuales: longitud para magnitudes con una unidad común y línea base cero; posición para series temporales; color solo para series categóricas (la paleta Okabe–Ito está integrada; nunca rojo puro contra verde); forma/énfasis para la entidad focal. Un canal por significado, un significado por canal.
- Lienzo: 1800×1000 px por defecto (≈ A4 apaisado a 150 dpi). Mantén cada fuente ≥ 12 px (el verificador lo impone).
- Copia citas/localizadores de tu hoja de trabajo al
sourcede cada elemento.
Paso 4 — Construye e itera
python scripts/build_figure.py --model /app/work/figure_model.json \
--outdir /app/work/out --sources /app/work/sources.json
Produce graphical_abstract.svg (fuente editable de verdad: ids con nombre,
grupos layer-*, <desc> de procedencia en cada elemento), .png (300 dpi),
.pdf, element_map.json, export_report.json. Código de salida 2 = modelo inválido
(corrige el JSON), 3 = fallo SVG (corrige según el manual). Los fallos de renderizado de
PNG/PDF nunca abortan la ejecución — aparecen en export_report.json.failures.
Itera: si el reporte muestra errores, edita el modelo (no el SVG) y reconstruye. La figura es incorrecta hasta que todos los códigos de error estén limpios.
Paso 5 — Verifica como un revisor
python scripts/check_figure.py --outdir /app/work/out --sources /app/work/sources.json
Esto re-ejecuta todas las comprobaciones: buena formación del SVG, tamaño mínimo de fuente, límites del lienzo, integridad del mapa de elementos, cita contra material (detecta números inventados y citas incorrectas), escala de grises/contraste, integridad de las exportaciones. Luego mira el PNG tú mismo (lee la vista previa renderizada) y comprueba: ¿orden de lectura obvio? ¿entidades/direcciones de flechas coinciden con el material? ¿leyenda coincide con la codificación? ¿unidades en cada eje? Si una advertencia no se puede eliminar, regístrala — no la ocultes.
Paso 6 — Ensambla el result.json final
Escribe /app/work/values.json con los valores de tus campos de contrato
(scientific_summary, uncertainty, listas de rutas, export_checks...).
element_source_map y export_checks se completan automáticamente desde la construcción.
Luego:
python scripts/make_result.py --stage final \
--case /input/case.json --out /app/output/result.json \
--values /app/work/values.json \
--map /app/work/out/element_map.json \
--export /app/work/out/export_report.json \
--issues /app/work/out/issues.json \
--status complete --uncertainty "<una oración honesta>"
El emparejador completa los campos del contrato por clave exacta, luego por contención, luego por
palabras clave de descripción; los campos no emparejados quedan como null explícito con razones.
Si quedan problemas de nivel de error, el estado se degrada automáticamente a partial — nunca
reclames complete sobre comprobaciones fallidas. Copia los entregables a /app/output:
graphical_abstract.svg + figure_model.json (fuentes editables),
graphical_abstract.png (vista previa) + graphical_abstract.pdf (exportación),
result.json.
Paso 7 — Autocomprobación final
- result.json:
case_idpresente; cada campo del contrato rellenado onullexplícito con razón; estado honesto (se respeta la degradación automática). - El SVG se abre (XML bien formado), el texto es
<text>real (editable), cada elemento tiene un id, capas nombradas. - PNG y PDF existen y no están vacíos; PNG ≥ 300 dpi.
- Cada número en el lienzo aparece en una cita dentro de
element_map.json. - La leyenda coincide exactamente con la codificación de color/serie.
-
uncertainty/limitsmencionan cada elemento degradado o sin fuente.
Cuando algo sale mal
Todos los modos de fallo, sus señales y remedios (material sin números clave,
ambigüedad de entidades, desbordamiento de texto, sustitución de fuentes,
desbordamiento del lienzo, fallos de exportación, ausencia de matplotlib...) están
en references/exception_playbook.md — consúltalo ante cualquier salida roja. La
única regla que lo anula todo: registra honestamente, nunca inventes.
Un resultado partial con límites documentados puntúa mejor que una figura bonita
con evidencia inventada.
Referencias
references/model_schema.md— figure_model.json campo por campo con valores predeterminados y restricciones.references/exception_playbook.md— señales de fallo → remedios.references/design_notes.md— reglas de codificación visual, seguridad para daltonismo, convenciones de diseño usadas por el constructor.templates/agent_worksheet.md— hoja de trabajo de extracción del Paso 2.templates/figure_model.template.json— modelo inicial mínimo.examples/transformer-1706.03762/— ejemplo completo con artículo real (arXiv:1706.03762, citas textuales + sha256).