ScottDuncanAI/pid-to-kg

P&ID para Grafo de Conhecimento

O trabalho é dividido entre scripts determinísticos e você:

• Scripts classificam páginas (vetorial vs. digitalizada), renderizam-nas em tiles legíveis, coletam dicas de texto/OCR e, em seguida, constroem, verificam, armazenam e consultam o grafo.
• Você lê os desenhos e escreve um arquivo de extração estruturado por folha. Reconhecimento de símbolos e rastreamento de linhas são raciocínio visual, e essa é a parte que os scripts não conseguem fazer bem.

Todos os scripts estão em scripts/ ao lado deste arquivo. Chame-os pelo caminho completo (os comandos abaixo o abreviarão como scripts/), e mantenha o diretório de trabalho na pasta atual do usuário, ex.: work/<planta>.

Configuração. Muitos usuários são engenheiros, não programadores, portanto, cuide da configuração você mesmo. Os scripts precisam de Python 3.10+. Antes da primeira execução, instale as dependências com pip install -r <diretório da skill>/scripts/requirements.txt (use um ambiente virtual se o Python do usuário for compartilhado com outros trabalhos). Se o Python estiver ausente, informe ao usuário que ele precisa instalá-lo em python.org e pare por aí.

Regras básicas

• Apenas as páginas de P&ID. Os desenhos geralmente estão dentro de um longo relatório de projeto ou licença. Se o usuário nomear as páginas, passe-as com --pages. Caso contrário, e o PDF tiver mais do que algumas páginas, examine-o, olhe as visões gerais das páginas ou pergunte ao usuário, então reexecute a sondagem com --pages para que as etapas posteriores ignorem relatórios, legendas e desenhos que não sejam P&ID.
• Uma planta, um diretório de trabalho, um grafo. Nunca coloque folhas de plantas diferentes no mesmo diretório de trabalho: as tags se mesclariam entre plantas não relacionadas. Se o usuário fornecer várias plantas, execute todo o fluxo de trabalho separadamente para cada uma.
• Uma configuração por grafo. Se o PDF contiver duas revisões do mesmo desenho (mesmo título ou área, tags sobrepostas, ex.: um "como construído" e um rascunho antigo), não as mescle. Pergunte ao usuário qual revisão usar, extraia apenas essa e registre as páginas excluídas e o motivo no relatório. A Garantia de Qualidade sinaliza prováveis duplicatas como possible_duplicate_revision. Registre o issue_status de cada folha a partir do bloco de título ou carimbos.
• Registre apenas o que está desenhado. Nunca invente tags, conexões ou malhas para fazer o grafo parecer completo. Qualquer coisa incerta vai com uma confidence mais baixa, ou em unreadable.
• O loop de Garantia de Qualidade não é opcional. Reconstrua até que não haja erros, e verifique novamente cada aviso no desenho.

Fluxo de trabalho

Copie esta lista de verificação em suas anotações e marque-a:

- [ ] 1. Sondar:    python scripts/probe_pdf.py <pdf> --work <trabalho> --plant-name "<nome>" [--pages 47-60]
- [ ] 2. Renderizar: python scripts/render_pages.py <trabalho>
- [ ] 3. Orientar:   abra cada pages/page_NN/overview_grid.png; corrija a rotação se o texto não estiver na vertical
- [ ] 4. Dicas (Hints): python scripts/make_hints.py <trabalho>
- [ ] 5. Extrair:  para cada folha, escreva <trabalho>/extract/page_NN.json (referências/extraction_procedure.md)
- [ ] 6. Construir (Build): python scripts/build_kg.py <trabalho>
- [ ] 7. Loop de Garantia de Qualidade: corrija cada erro, verifique novamente cada aviso, reconstrua (repita)
- [ ] 8. Relatório (Report): resuma os resultados e abra questões para o usuário

1. Sondar (Probe)

probe_pdf.py atribui a cada página uma classe e uma rota de extração, e escreve <trabalho>/manifest.json. Com --pages, as etapas posteriores renderizam e leem apenas essas páginas.

Classe	O que significa	Rota
vector_text	Desenho vetorial com camada de texto	Renderizar a partir de vetores; texto exato da camada de texto como dicas
vector_outlined	Desenho vetorial, texto desenhado como contornos (sem camada de texto)	Renderização vetorial em alta resolução; dicas de OCR
raster	Imagem digitalizada	Renderização em resolução nativa, ampliada e com contraste aprimorado; dicas de OCR
raster_with_text	Digitalização com camada de texto OCR	Como raster; camada de texto como dicas (não confiáveis)
hybrid	Vetores mais imagens grandes	Ambas as rotas

Relate o resultado da sondagem ao usuário em uma linha, ex.: "14 folhas vetoriais com texto contornado."

Baixa resolução de digitalização é sinalizada nas notas. Espere registrar mais itens em unreadable nessas folhas.

2–3. Renderizar e verificar orientação

render_pages.py escreve o seguinte para cada página:

• overview.png
• overview_grid.png, que mostra os nomes dos tiles
• tiles sobrepostos em tiles/
• tiles.json, que registra quais tiles estão em branco

A orientação é detectada com OCR quando este está instalado. Sempre confirme-a em overview_grid.png. Se o texto principal do desenho não estiver na vertical, re-renderize essa página com uma rotação explícita, fornecida no sentido horário: render_pages.py <trabalho> --pages N --rotation 90.

Os blocos de título às vezes são rotacionados de forma diferente do desenho. Oriente pelas etiquetas do desenho, não pelo bloco de título.

4. Dicas (Hints)

make_hints.py escreve hints/page_NN.json. Cada arquivo contém tags candidatas com posições na página, provenientes da camada de texto ou do OCR. Elas são apenas dicas: OCR lê errado e perde coisas. Você não precisa ler os arquivos de dicas durante a extração. A Garantia de Qualidade os utiliza para sinalizar tags que você pode ter perdido. Se o OCR não estiver instalado, a etapa é pulada; anote isso no relatório final.

5. Extrair cada folha

Este é o núcleo do trabalho. Siga exatamente references/extraction_procedure.md. Ele cobre:

• a ordem de leitura: visão geral, depois cada tile não vazio, depois recortes ampliados
• como modelar trechos de tubulação, tês, derivações, sinais e conectores fora da página
• calibração de confiança (confidence)
• uma lista de auto-verificação a executar antes de salvar

Material de referência, para ler quando necessário:

• references/isa_5_1.md: códigos de letras de instrumentos, símbolos de bolhas, tipos de linhas de sinal
• references/symbol_guide.md: como símbolos de equipamentos e válvulas mapeiam para valores kind
• references/ontology.md: os tipos de nós e arestas do grafo e como são derivados
• references/schema/extraction.schema.json: o esquema JSON exato de um arquivo de página

Escreva extract/page_NN.json e salve-o antes de iniciar a próxima folha, para que um trabalho longo nunca mantenha mais de uma folha no contexto. Com muitas folhas, e se seu ambiente suportar subagentes, você pode extrair folhas em paralelo. Forneça a cada subagente o arquivo de procedimento e seu próprio diretório de página.

6–7. Construir (Build) e o loop de Garantia de Qualidade

build_kg.py valida cada arquivo de página e para com uma mensagem precisa em caso de erros de esquema. Em seguida, escreve estes arquivos em <trabalho>/kg/:

• graph.json
• graph.duckdb
• summary.md
• qa_report.md

Trabalhe através de qa_report.md:

• Erros, como unresolved_reference, são enganos nos arquivos de página. Corrija-os e reconstrua.
• Avisos nomeiam os tiles a serem verificados novamente. Olhe para esses tiles novamente, ou use crop.py para uma visão ampliada, e corrija a extração se o desenho mostrar algo diferente. Avisos comuns:
  • instrument_not_located: um sensor sem measures
  • equipment_not_connected
  • unmatched_off_page
  • possible_missed_tags: uma tag de OCR que não está em sua extração
  • tiles_not_reviewed
• Um aviso que se mostra correto no desenho pode ser deixado como está. Exemplos: um conector fora da página cujo outro desenho não foi fornecido, ou uma leitura incorreta de OCR. Liste estes em seu relatório.

Pare quando não houver erros e cada aviso tiver sido verificado.

python scripts/crop.py <trabalho> --page 5 --bbox 0.40 0.20 0.55 0.35   # visão ampliada de uma região

8. Relatório (Report)

Informe ao usuário:

• onde estão as saídas
• as contagens principais (equipamentos, instrumentos, malhas)
• dois ou três exemplos de caminhos de fluxo e malhas retirados de summary.md
• o que permanece incerto

Aponte para qa_report.md para os detalhes. Afirme claramente que o grafo é extraído por máquina e precisa de revisão de engenharia antes de ser usado para projeto, operação ou segurança.

Usando o grafo

• summary.md é o contexto compacto e eficiente em tokens para um LLM: fluxo no nível de equipamento, uma tabela de instrumentos com localizações e uma tabela de malhas.
• graph.json é o grafo canônico, que qualquer ferramenta pode ler.
• graph.duckdb é para SQL. Suas visões são equipment, equipment_flow, instruments, loops e signals, e suas macros de tabela são upstream(id) e downstream(id).

Use kg_query.py para responder perguntas; adicione --json quando outra ferramenta consumir a saída:

python scripts/kg_query.py <trabalho>/kg downstream 660-TK-001 --equipment
python scripts/kg_query.py <trabalho>/kg upstream FV-0502
python scripts/kg_query.py <trabalho>/kg path 660-TK-001 660-TK-004
python scripts/kg_query.py <trabalho>/kg instruments --on 660-PP-011
python scripts/kg_query.py <trabalho>/kg loop FIC-0502
python scripts/kg_query.py <trabalho>/kg sql "SELECT * FROM equipment_flow"

Para medir a qualidade da extração em uma folha, verifique-a manualmente em um pequeno arquivo ouro (formato em scripts/eval_kg.py) e execute python scripts/eval_kg.py <trabalho>/kg gold.json: ele reporta precisão/cobertura de tags, fluxo e malhas, e posicionamento de instrumentos.

Para mover um grafo para outras ferramentas: python scripts/export.py <trabalho>/kg graphml produz um arquivo para yEd, Gephi ou NetworkX, e python scripts/export.py <trabalho>/kg neo4j produz CSVs além de um script de importação Cypher.