ScottDuncanAI/pid-to-kg

De P&ID a grafo de conocimiento

El trabajo se divide entre scripts deterministas y tú:

• Scripts: clasifican las páginas (vectorial vs. escaneado), las renderizan en mosaicos legibles, recopilan pistas de OCR/texto, y luego construyen, verifican, almacenan y consultan el grafo.
• Tú: lees los dibujos y escribes un archivo de extracción estructurado por cada lámina. El reconocimiento de símbolos y el trazado de líneas son razonamiento visual, y esa es la parte que los scripts no pueden hacer bien.

Todos los scripts están en scripts/ junto a este archivo. Llámalos por su ruta completa (los comandos de abajo la abrevian como scripts/), y mantén el directorio de trabajo en la carpeta actual del usuario, por ejemplo, trabajo/<planta>.

Configuración. Muchos usuarios son ingenieros, no programadores, así que maneja la configuración tú mismo. Los scripts necesitan Python 3.10+. Antes de la primera ejecución, instala las dependencias con pip install -r <directorio del skill>/scripts/requirements.txt (usa un entorno virtual si el Python del usuario se comparte con otro trabajo). Si falta Python, dile al usuario que lo instale desde python.org y detente ahí.

Reglas básicas

• Solo las páginas P&ID. Los dibujos suelen estar dentro de un informe largo de permisos o diseño. Si el usuario nombra las páginas, pásalas con --pages. Si no, y el PDF tiene más de unas pocas páginas, haz una prueba, mira las vistas previas o pregúntale al usuario, luego vuelve a ejecutar la prueba con --pages para que los pasos posteriores omitan informes, leyendas y dibujos que no sean P&ID.
• Una planta, un directorio de trabajo, un grafo. Nunca pongas láminas de diferentes plantas en el mismo directorio de trabajo: las etiquetas se fusionarían entre plantas no relacionadas. Si el usuario proporciona varias plantas, ejecuta todo el flujo de trabajo por separado para cada una.
• Una configuración por grafo. Si el PDF contiene dos revisiones del mismo dibujo (mismo título o área, etiquetas superpuestas, por ejemplo, un as-built y un borrador antiguo), no las fusiones. Pregunta al usuario qué revisión usar, extrae solo esa, y registra las páginas excluidas y el motivo en el informe. El control de calidad marca posibles duplicados como possible_duplicate_revision. Registra el issue_status de cada lámina desde el bloque de título o los sellos.
• Registra solo lo dibujado. Nunca inventes etiquetas, conexiones o lazos para que el grafo parezca completo. Cualquier cosa poco clara va con una confidence más baja, o en unreadable.
• El bucle de control de calidad no es opcional. Reconstruye hasta que no haya errores, y vuelve a verificar cada advertencia en el dibujo.

Flujo de trabajo

Copia esta lista de verificación en tus notas y márcala:

- [ ] 1. Prueba:    python scripts/probe_pdf.py <pdf> --work <trabajo> --plant-name "<nombre>" [--pages 47-60]
- [ ] 2. Renderiza:   python scripts/render_pages.py <trabajo>
- [ ] 3. Orienta:   abre cada pages/page_NN/overview_grid.png; corrige la rotación si el texto no está vertical
- [ ] 4. Pistas:    python scripts/make_hints.py <trabajo>
- [ ] 5. Extrae:  para cada lámina, escribe <trabajo>/extract/page_NN.json (consulta references/extraction_procedure.md)
- [ ] 6. Construye:    python scripts/build_kg.py <trabajo>
- [ ] 7. Bucle de QA:  corrige cada error, vuelve a verificar cada advertencia, reconstruye (repite)
- [ ] 8. Informe:   resume los resultados e informa de los problemas abiertos al usuario

1. Prueba

probe_pdf.py asigna a cada página una clase y una ruta de extracción, y escribe <trabajo>/manifest.json. Con --pages, los pasos posteriores renderizan y leen solo esas páginas.

Clase	Qué significa	Ruta
vector_text	Dibujo vectorial con capa de texto	Renderizar desde vectores; texto exacto de la capa de texto como pistas
vector_outlined	Dibujo vectorial, texto dibujado como contornos (sin capa de texto)	Renderizado vectorial de alta resolución; pistas de OCR
raster	Imagen escaneada	Renderizado a resolución nativa, ampliado y con realce de contraste; pistas de OCR
raster_with_text	Escaneo con capa de texto OCR	Como raster; capa de texto como pistas (no fiables)
hybrid	Vectores más imágenes grandes	Ambas rutas

Informa al usuario del resultado de la prueba en una línea, por ejemplo, "14 láminas vectoriales con texto contorneado."

La baja resolución de escaneo se señala en las notas. Espera registrar más elementos en unreadable en esas láminas.

2–3. Renderiza y verifica la orientación

render_pages.py escribe lo siguiente para cada página:

• overview.png
• overview_grid.png, que muestra los nombres de los mosaicos
• mosaicos superpuestos en tiles/
• tiles.json, que registra qué mosaicos están en blanco

La orientación se detecta con OCR cuando está instalado. Siempre confírmala en overview_grid.png. Si el texto principal del dibujo no está vertical, vuelve a renderizar esa página con una rotación explícita, dada en sentido horario: render_pages.py <trabajo> --pages N --rotation 90.

Los bloques de título a veces están rotados de forma diferente al dibujo. Orienta por las etiquetas del dibujo, no por el bloque de título.

4. Pistas

make_hints.py escribe hints/page_NN.json. Cada archivo contiene etiquetas candidatas con posiciones en la página, tomadas de la capa de texto o del OCR. Son solo pistas: el OCR lee mal y omite cosas. No es necesario leer los archivos de pistas durante la extracción. El control de calidad los usa para señalar etiquetas que podrías haber omitido. Si el OCR no está instalado, el paso se omite; anótalo en el informe final.

5. Extrae cada lámina

Esta es la parte central del trabajo. Sigue exactamente references/extraction_procedure.md. Cubre:

• el orden de lectura: vista general, luego cada mosaico no vacío, luego recortes ampliados
• cómo modelar tramos de tubería, tes, tomas, señales y conectores fuera de página
• calibración de confianza
• una lista de autoverificación que ejecutar antes de guardar

Material de referencia, para leer cuando sea necesario:

• references/isa_5_1.md: códigos de letras de instrumentos, símbolos de burbuja, tipos de líneas de señal
• references/symbol_guide.md: cómo se mapean los símbolos de equipos y válvulas a valores kind
• references/ontology.md: tipos de nodos y aristas del grafo y cómo se derivan
• references/schema/extraction.schema.json: el esquema JSON exacto de un archivo de página

Escribe extract/page_NN.json y guárdalo antes de comenzar la siguiente lámina, para que un trabajo largo nunca tenga más de una lámina en contexto. Con muchas láminas, y si tu entorno admite subagentes, puedes extraer láminas en paralelo. Dale a cada subagente el archivo de procedimiento y su propio directorio de página.

6–7. Construye y el bucle de control de calidad

build_kg.py valida cada archivo de página y se detiene con un mensaje preciso sobre errores de esquema. Luego escribe estos archivos en <trabajo>/kg/:

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

Trabaja con qa_report.md:

• Errores, como unresolved_reference, son errores en los archivos de página. Corrígelos y reconstruye.
• Advertencias nombran los mosaicos que deben volver a revisarse. Mira esos mosaicos de nuevo, o usa crop.py para una vista ampliada, y corrige la extracción si el dibujo muestra algo diferente. Advertencias comunes:
  • instrument_not_located: un sensor sin measures
  • equipment_not_connected
  • unmatched_off_page
  • possible_missed_tags: una etiqueta OCR que no está en tu extracción
  • tiles_not_reviewed
• Una advertencia que resulta correcta en el dibujo se puede dejar. Ejemplos: un conector fuera de página cuyo otro dibujo no se proporcionó, o una lectura errónea de OCR. Enuméralos en tu informe.

Detente cuando no haya errores y se haya verificado cada advertencia.

python scripts/crop.py <trabajo> --page 5 --bbox 0.40 0.20 0.55 0.35   # vista ampliada de una región

8. Informe

Informa al usuario:

• dónde están los resultados
• los recuentos principales (equipos, instrumentos, lazos)
• dos o tres rutas de flujo y lazos de ejemplo tomados de summary.md
• qué sigue siendo incierto

Señala qa_report.md para ver los detalles. Indica claramente que el grafo se extrajo automáticamente y necesita revisión por parte de ingenieros antes de usarse para diseño, operaciones o seguridad.

Uso del grafo

• summary.md es el contexto compacto y eficiente en tokens para un LLM: flujo a nivel de equipo, una tabla de instrumentos con ubicaciones y una tabla de lazos.
• graph.json es el grafo canónico, que cualquier herramienta puede leer.
• graph.duckdb es para SQL. Sus vistas son equipment, equipment_flow, instruments, loops y signals, y sus macros de tabla son upstream(id) y downstream(id).

Usa kg_query.py para responder preguntas; añade --json cuando otra herramienta vaya a consumir la salida:

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

Para medir la calidad de extracción en una lámina, compruébala manualmente en un pequeño archivo de referencia (formato en scripts/eval_kg.py) y ejecuta python scripts/eval_kg.py <trabajo>/kg gold.json: informa precisión/recuperación de etiquetas, flujo y lazos, y ubicación de instrumentos.

Para mover un grafo a otras herramientas: python scripts/export.py <trabajo>/kg graphml produce un archivo para yEd, Gephi o NetworkX, y python scripts/export.py <trabajo>/kg neo4j produce CSVs más un script de importación Cypher.