Construtor de Resumo Gráfico
Transforme material de pesquisa (PDF, anotações, registros) em um resumo
gráfico de página única cujo cada elemento seja rastreável ao material, além
de um result.json completo de contrato.
Divisão de trabalho — você faz a ciência, os scripts fazem o desenho:
- Você (o agente): lê o material real, extrai entidades/relações/dados, escolhe a codificação visual, decide o que vai no canvas vs. na legenda, verifica a figura contra o material.
- Os scripts (
scripts/, Python puro + matplotlib): layout, renderização, verificações, montagem do resultado. Determinístico: mesmo modelo de entrada → mesma figura de saída.
Ambiente e caminhos
- Raiz do skill:
/skills/weekly-skill(scripts emscripts/, documento de esquema emreferences/). Trabalhe em/app/work; entregáveis finais vão para/app/output. - Entrada:
/input/case.json(+ task.md; arquivos de material referenciados pelo caso). - Espera-se Python com matplotlib; se faltar, a exportação PNG recai automaticamente para Pillow e a exportação PDF gera erro com uma solução — consulte o playbook.
- Custo típico: 10–20 requisições do modelo, bem dentro do orçamento de 64 requisições / 900 segundos. Cada execução de script de construção/verificação é uma chamada de ferramenta.
Fluxo de trabalho
Passo 0 — Leia o caso e prepare o result.json (faça isso primeiro)
Leia /input/case.json por completo. Anote o case_id e cada campo do
output_contract — estas são suas obrigações de entrega. Em seguida, imediatamente:
python scripts/make_result.py --stage init \
--case /input/case.json --out /app/output/result.json
Isso escreve cada campo do contrato como um null explícito com um motivo pendente.
A partir de agora, uma falha ainda deixa um entregável completo de contrato.
Reexecute com --stage final (Passo 6) para preenchê-lo.
Passo 1 — Leia o material real
Abra os arquivos reais que o caso aponta (nunca suponha o conteúdo a partir de rótulos).
Para PDFs, use a ferramenta pdf-text-tool / scientific-python; escaneie páginas apenas se
OCR for necessário. Salve um sources.json mapeando cada arquivo de material para seu texto
extraído — etapas posteriores verificam citações contra ele automaticamente:
{ "materials/paper.pdf": "<texto extraído completo>" }
Passo 2 — Extraia a ciência (seu julgamento, não de um script)
Preencha uma planilha (modelo: templates/agent_worksheet.md) diretamente a partir
do material:
- Pergunta — que problema o material apresenta? Cite-o literalmente.
- Entidades — as coisas que devem aparecer (moléculas, células, dispositivos, métodos, coortes...). Para cada uma: rótulo, uma citação literal, localizador (arquivo + página/seção/frase).
- Relações — conexões direcionais que o material afirma (A ativa B, dosagem motiva a pergunta...). Registre a direção e a frase que a afirma.
- Dados — todo número que você pode desenhar: valor, unidade, condição, e
a frase de onde vem. Se um número que você deseja não está no material,
não o desenhe; liste-o em
uncertainty/limits. - Conclusão — afirmações que o próprio material faz.
Regras de evidência: citações são subcadeias literais do material; localizadores são precisos o suficiente para um humano encontrar em segundos; qualquer coisa que você não possa referenciar vai para a legenda/anotações, nunca para o canvas como dado.
Passo 3 — Crie figure_model.json
Escreva /app/work/figure_model.json seguindo o esquema em
references/model_schema.md (exemplo completo: examples/transformer-1706.03762/).
Decisões-chave que você toma:
- Plano de painéis: geralmente 4–6 painéis em ordem de leitura pergunta → método → resultados (1–2) → conclusão; um achado por painel.
- Layout por painel:
flow(caixas + setas para entidades/relações),chart(barras/barras horizontais/barras agrupadas/linhas para dados),stats(destaques de números grandes para 2–4 valores principais),text(conclusões em tópicos). - Canais visuais: comprimento para magnitudes com unidade comum e linha de base zero; posição para séries temporais; cor apenas para séries categóricas (paleta Okabe–Ito é integrada; nunca vermelho puro vs. verde); forma/ênfase para a entidade focal. Um canal por significado, um significado por canal.
- Canvas: padrão 1800×1000 px (≈ A4 paisagem a 150 dpi). Mantenha toda fonte ≥ 12 px (o verificador impõe).
- Copie citações/localizadores da sua planilha para o
sourcede cada elemento.
Passo 4 — Construa e itere
python scripts/build_figure.py --model /app/work/figure_model.json \
--outdir /app/work/out --sources /app/work/sources.json
Produz graphical_abstract.svg (fonte da verdade editável: IDs nomeados,
grupos layer-*, <desc> de proveniência em cada elemento), .png (300 dpi),
.pdf, element_map.json, export_report.json. Código de saída 2 = modelo inválido
(corrija o JSON), 3 = falha no SVG (corrija conforme o playbook). Falhas de renderização de
PNG/PDF nunca abortam a execução — elas vão para export_report.json.failures.
Itere: se o relatório mostrar erros, edite o modelo (não o SVG) e reconstrua. A figura está errada até que todo código de erro seja limpo.
Passo 5 — Verifique como um revisor
python scripts/check_figure.py --outdir /app/work/out --sources /app/work/sources.json
Isso reexecuta todas as verificações: boa formação do SVG, tamanho mínimo de fonte, limites do canvas, completude do mapa de elementos, citação vs. material (detecta números inventados e citações incorretas), tons de cinza/contraste, integridade das exportações. Em seguida, olhe o PNG você mesmo (leia a prévia renderizada) e verifique: ordem de leitura óbvia? entidades/direções das setas correspondem ao material? legenda corresponde à codificação? unidades em cada eixo? Se um aviso não puder ser eliminado, registre-o — não o oculte.
Passo 6 — Monte o result.json final
Escreva /app/work/values.json com os valores dos campos do contrato
(scientific_summary, uncertainty, listas de caminhos, export_checks...).
element_source_map e export_checks são preenchidos automaticamente a partir da construção.
Em seguida:
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 "<uma frase honesta>"
O combinador preenche campos do contrato por chave exata, depois por contenção, depois por
palavras-chave de descrição; campos não correspondidos permanecem null explícitos com motivos.
Se problemas de nível de erro permanecerem, o status é automaticamente rebaixado para partial — nunca
reivindique complete sobre verificações falhas. Copie os entregáveis para /app/output:
graphical_abstract.svg + figure_model.json (fontes editáveis),
graphical_abstract.png (prévia) + graphical_abstract.pdf (exportação),
result.json.
Passo 7 — Auto-verificação final
- result.json:
case_idpresente; cada campo do contrato preenchido ounullexplícito com motivo; status honesto (rebaixamento automático respeitado). - SVG abre (XML bem formado), texto é
<text>real (editável), cada elemento possui um id, camadas nomeadas. - PNG e PDF existem e não estão vazios; PNG ≥ 300 dpi.
- Todo número no canvas aparece em uma citação dentro de
element_map.json. - Legenda corresponde exatamente à codificação de cor/série.
-
uncertainty/limitsmencionam todo item degradado ou não referenciado.
Quando algo dá errado
Todos os modos de falha, suas assinaturas e soluções (material faltando números
chave, ambiguidade de entidade, estouro de texto, substituição de fonte, estouro de
canvas, falhas de exportação, matplotlib ausente...) estão em
references/exception_playbook.md — consulte-o em qualquer saída vermelha. A
única regra que se sobrepõe a tudo: registre honestamente, nunca fabrique.
Um resultado partial com limitações documentadas vale mais do que uma figura bonita
com evidências inventadas.
Referências
references/model_schema.md— figure_model.json campo por campo com padrões e restrições.references/exception_playbook.md— assinaturas de falha → soluções.references/design_notes.md— regras de codificação visual, segurança para daltonismo, convenções de layout usadas pelo construtor.templates/agent_worksheet.md— planilha de extração do Passo 2.templates/figure_model.template.json— modelo inicial mínimo.examples/transformer-1706.03762/— exemplo completo com artigo real (arXiv:1706.03762, citações literais + sha256).