Esquemas de relacionamento: extrair → modelar → renderizar → verificar → exportar
Você está desenhando figuras cuja correção científica é julgada por um revisor LLM contra o material de origem. Os modos de falha dominantes da geração de imagem genérica são exatamente as coisas que este skill se recusa a fazer: inibição desenhada como ativação, montante/jusante invertido, contenção desenhada como caixas lado a lado, nomes de genes ou números inventados, alegações não rastreáveis. Cada mecanismo aqui existe para tornar essas falhas impossíveis de serem enviadas silenciosamente.
Inegociáveis
- Nada é desenhado que não esteja na tabela de relações. O modelo da figura (
model.json) é a única fonte da verdade; o SVG é gerado a partir dele e lido de volta contra ele. - Cada entidade e relação carrega uma citação literal + localizador do material de origem. Uma relação sem citação é recusada pela ferramenta (
relation_no_evidence). Se não puder citar, não pode desenhar. from/tocodificam a afirmação, não o layout. "A inibe B" ⇒from: A, to: B, type: inhibits. O renderizador decide a geometria; o verificador verifica se a ponta da seta realmente chega a B.- Desconhecido é desenhado como desconhecido. Se o material não afirma uma direção, use
direction: "unknown"— ele renderiza tracejado com um?e é sinalizado em result.json. Nunca adivinhe para deixar a figura mais limpa. - Entregue o result.json mínimo garantido primeiro, melhore depois. O passo 1 escreve um scaffold em formato de contrato com
nulls explícitos antes de qualquer extração, para que uma falha ainda deixe um entregável parcial válido.
Os scripts estão em scripts/ (Python 3 puro stdlib + cairosvg/PIL opcionais; auto-detecta headless de navegador para exportação). A semântica dos símbolos está em symbols/symbols.json e é documentada em references/symbol-conventions.md; o formato do modelo em references/model-schema.md. Leia ambas as referências antes da sua primeira execução.
Fluxo de trabalho (7 etapas)
Trabalhe em /app/work; os artefatos finais vão para /app/output.
Etapa 1 — Scaffold do entregável mínimo
python scripts/init_result.py --case /input/case.json --work /app/work --output /app/output
Lê o caso, cria diretórios, escreve /app/output/result.json com todos os campos output_contract presentes e null, status: "partial", e uma entrada partial_reasons. Se o arquivo de caso estiver ausente/ilegível, ainda escreve o scaffold e registra o problema. Também leia task.md e quaisquer arquivos de material você mesmo — nunca presuma conteúdo a partir de rótulos ou nomes de arquivos.
Etapa 2 — Extrair a tabela entidade–relação (seu julgamento, não de um script)
Leia o material real (texto PDF via ferramentas da plataforma, tabelas, texto do caso) e construa /app/work/model.json conforme references/model-schema.md:
- uma entidade por ator científico;
label= nome canônico conforme impresso na fonte;type= papel funcional mostrado como um pequeno subtítulo; - uma relação por interação declarada, com
typeda biblioteca de símbolos (activates inhibits binds modifies transports indirect precedes contains parallels) edirection(A_to_B/B_to_A/bidirectional/unknown); - contenção ("O complexo X consiste em A, B, C") torna-se um grupo com membros, mais relações
contains— nunca uma aresta, nunca justaposição; - ordem temporal/de processo ("primeiro … depois …") torna-se
precedescom rótulos de etapa; evidence= substring literal do material + localizador (seção, parágrafo, linha de tabela, página) + id da fonte (DOI/nome do arquivo).
Regras de extração para casos difíceis:
- Ambiguidade de entidade (sinônimos/abreviações, "β-catenina" vs "CTNNB1"): uma entidade, rótulo como a fonte imprime, anote a equivalência em result.json
uncertainty. Dois nomes que a fonte distingue permanecem duas entidades. - Direção não declarada:
direction: "unknown"(tracejado +?). Declare a ambiguidade emuncertainty; não a resolva por plausibilidade. - Evidência indireta ("X leva a Y via Z" para a alegação X→Y): use tipo
indirect(tracejado) ou modele a cadeia mecanicista X→Z→Y se cada salto for citado. Prefira a cadeia — revisores podem segui-la. - Números/unidades/concentrações no material (por exemplo, "3,3–10,4%"): mantenha-os nos rótulos de aresta/nó exatamente como impressos, nunca arredondados ou inventados.
- Se o caso solicitar um gráfico de valores de dados reais, isso está fora do núcleo deste skill (gráficos estatísticos) — ainda entregue o que se aplica (tabela de entidades, disciplina de mapeamento dados-para-legenda) e marque o resto como parcial com a razão.
Etapa 3 — Validar antes de desenhar
python scripts/model_check.py /app/work/model.json
Exit 0 = limpo (avisos permitidos). Corrija todos os erros — o renderizador recusa com erros de qualquer maneira. Avisos (entity_no_evidence, direction_uncertain, cycle_in_rank_graph, …) são estados científicos legítimos: mantenha-os e carregue-os para result.json em vez de "corrigi-los" por invenção.
Etapa 4 — Renderizar o SVG editável
python scripts/make_schematic.py /app/work/model.json -o /app/work/figure.svg --report /app/work/layout.json
Produz um SVG em camadas: grupos node-* / edge-* / group-* / legend, cada um carregando data-evidence-quote/-locator/-source. O layout é automático (empilhamento por caminho mais longo, então as arestas A_to_B apontam para baixo); se o conteúdo exceder canvas_width, a tela alarga e um aviso canvas_expanded é registrado — nada é jamais cortado.
Etapa 5 — Ler o desenho de volta e verificar
python scripts/verify_svg.py /app/work/model.json /app/work/figure.svg --out /app/work/verify.json
Esta é a porta de segurança central contra falhas. Verifica cobertura de entidade/relação, semântica de marcadores conforme a biblioteca de símbolos, direção geométrica da seta (a ponta deve estar mais perto do alvo semântico do que da fonte), caixas de contenção realmente envolvendo membros (e não prendendo não-membros), sobreposição de nós, ajuste de rótulo e cobertura da legenda. Exit 0 = aprovado.
Se falhar: corrija o modelo ou a edição, re-renderize, re-verifique. Nunca corrija o SVG manualmente para silenciar uma verificação. Duas iterações é normal; se uma verificação não puder passar porque o material é contraditório, mantenha a figura que as citações suportam e registre o conflito em result.json uncertainty.
Etapa 6 — Exportar e verificar conformidade
python scripts/export_svg.py /app/work/figure.svg -o /app/output --pdf
Escreve <nome>_300dpi.png e <nome>.pdf em /app/output, tentando backends em ordem (cairosvg → Edge headless → Chrome headless → rasterizador PIL embutido para PNG) e registrando cada falha de backend. O relatório inclui verificações por artefato (resolução, fundo branco, cabeçalho/aspecto da página PDF, fluxos de conteúdo vetorial). Copie figure.svg e model.json para /app/output como as fontes editáveis, e o PNG funciona como a pré-visualização renderizada.
Etapa 7 — Finalizar result.json (cobertura do contrato, honestamente)
Preencha todos os campos output_contract — um campo que você não puder preencher permanece null com uma razão em partial_reasons. Mapeamento típico (adapte os nomes ao contrato do caso):
editable_source→{svg, model, note: "SVG em camadas; cada elemento carrega data-evidence-*"}exported_artifacts→ os artefatos do relatório de exportação (caminho, formato, dpi, backend, verificações)rendered_preview→ o caminho do PNGentity_relation_table→ entidades + relações incl. citações/localizadores (ou um caminho para model.json mais contagens)verification_report→ resumo de verify.json (contagens de aprovação/falha, avisos)sources→ documentos fontes/DOIs usados, com a proveniência das citaçõesstatus→completeapenas se verify passou e todas as exportações estão ok; caso contráriopartialcom razões.uncertaintylista ambiguidades (identificação de entidades, direções desconhecidas, conflitos não resolvidos).
Editando um SVG existente (preservando a fonte)
Quando o caso fornece um SVG para modificar em vez de material para desenhar:
- Leia o SVG; localize grupos
node-*/edge-*e seus atributosdata-*(figuras deste skill são totalmente autodescritivas). - Alterações locais (renomear, recolorir, tipo/rótulo de aresta, título, deletar um elemento não anexado) → escreva um JSON de edições e execute
python scripts/edit_svg.py figure.svg edits.json -o figure_edited.svg. Cada operação precisa de umreason; o relatório prova que elementos não tocados são byte-idênticos (preserved.ok). Em seguida, re-exporte (Etapa 6). - Alterações estruturais (adicionar/remover entidades ou relações, inverter uma direção) → estas são RECUSADAS pelo edit_svg por design (um atributo invertido sem re-roteamento desenha uma seta mentirosa). Reconstrua/estenda model.json a partir dos atributos de dados do SVG, edite o modelo, re-renderize, re-verifique.
- Se o SVG existente for de outra ferramenta (sem atributos de dados), reconstrua o modelo a partir do material de origem e re-renderize — não hackeie manualmente SVG estrangeiro; registre o que fez em result.json
change_log.
Manual de falhas (caminhos reais, não prosa)
| situação | detecção | ação | result.json |
|---|---|---|---|
| caso/material ilegível | Etapa 1 ou sua própria leitura | scaffold escrito, partial_reasons nomeia o arquivo/problema | status partial, campos null |
| relação que não pode citar | erro model_check relation_no_evidence | descarte a relação ou encontre a citação; nunca desenhe não citado | ausente da figura (correto) |
| direção não declarada | sua extração | direction: "unknown" | tracejado + ?; entrada uncertainty |
| entidade sinônimo/abreviação | sua extração | entidade única, equivalência anotada | entrada uncertainty |
| material contraditório | duas citações conflitam | desenhe o que a citação mais forte/mais específica suporta | ambas as citações + conflito em uncertainty |
| rótulo transborda sua caixa | aviso verify text_fit | encurte o rótulo ou adicione \n, re-renderize; crescimento da caixa é uma decisão de re-renderização | aviso carregado |
| tela muito pequena | aviso canvas_expanded | já alargado automaticamente; ou aumente canvas_width | aviso carregado |
| DLL cairosvg ausente (Windows) | tentativa de backend de exportação registrada | fallback automático para headless do navegador, depois rasterizador PIL | backend + tentativas registradas |
| sem navegador, sem cairosvg | todos os backends falham | rasterizador PIL (caixas/linhas/texto; marcadores aproximados) + notes | status partial para qualidade PNG, PDF null com razão |
| aspecto PDF errado | verificação de exportação | corrigido pelo dimensionamento de @page; se um backend o ignorar, registrado como checks_fail | status partial |
| verify não pode passar | verify_svg exit 1 | loop de correção em nível de modelo; se impossível, entregue o subconjunto citado | verification_report mostra falhas honestamente |
Auto-verificação antes de finalizar
verify_svgexit 0 (ou falhas honestamente relatadas);/app/outputcontém: result.json (todas as chaves do contrato presentes, nulls explicados), figure.svg, model.json, PNG (300 dpi), PDF;- cada relação desenhada é citável — verifique pontualmente três valores aleatórios de
data-evidence-quotecontra o material; - nenhuma entidade/número aparece no SVG que não esteja em model.json;
- change_log conta a história do que você fez, incluindo as etapas deste skill.