ScottDuncanAI/pid-to-kg

P&ID in Wissensgraph umwandeln

Die Arbeit ist zwischen deterministischen Skripten und Ihnen aufgeteilt:

• Skripte klassifizieren Seiten (Vektor vs. gescannt), rendern sie in lesbare Kacheln, sammeln OCR/Text-Hinweise und erstellen, überprüfen, speichern und fragen den Graphen ab.
• Sie lesen die Zeichnungen und schreiben eine strukturierte Extraktionsdatei pro Blatt. Die Symbolerkennung und Linienverfolgung sind visuelle Denkaufgaben, und das ist der Teil, den Skripte nicht gut können.

Alle Skripte befinden sich in scripts/ neben dieser Datei. Rufen Sie sie mit ihrem vollständigen Pfad auf (die Befehle unten kürzen ihn als scripts/ ab) und behalten Sie das Arbeitsverzeichnis im aktuellen Ordner des Benutzers, z. B. work/<anlage>.

Setup. Viele Benutzer sind Ingenieure, keine Programmierer, also kümmern Sie sich selbst um das Setup. Die Skripte benötigen Python 3.10+. Installieren Sie vor der ersten Ausführung die Abhängigkeiten mit pip install -r <skill-verzeichnis>/scripts/requirements.txt (verwenden Sie eine virtuelle Umgebung, wenn das Python des Benutzers mit anderen Arbeiten geteilt wird). Wenn Python fehlt, sagen Sie dem Benutzer, er solle es von python.org installieren und brechen Sie dann ab.

Grundregeln

• Nur die P&ID-Seiten. Zeichnungen befinden sich oft in einem langen Genehmigungs- oder Designbericht. Wenn der Benutzer die Seiten benennt, übergeben Sie sie mit --pages. Wenn nicht und das PDF mehr als ein paar Seiten hat, untersuchen Sie es, sehen Sie sich die Seitenübersichten an oder fragen Sie den Benutzer und führen Sie die Untersuchung dann mit --pages erneut aus, damit spätere Schritte Berichte, Legenden und Nicht-P&ID-Zeichnungen überspringen.
• Eine Anlage, ein Arbeitsverzeichnis, ein Graph. Legen Sie niemals Blätter verschiedener Anlagen in dasselbe Arbeitsverzeichnis: Tags würden über nicht zusammenhängende Anlagen hinweg verschmelzen. Wenn der Benutzer mehrere Anlagen liefert, führen Sie den gesamten Workflow für jede einzeln aus.
• Eine Konfiguration pro Graph. Wenn das PDF zwei Revisionen derselben Zeichnung enthält (gleicher Titel oder Bereich, überlappende Tags, z. B. eine As-Built- und eine ältere Entwurfsversion), führen Sie sie nicht zusammen. Fragen Sie den Benutzer, welche Revision verwendet werden soll, extrahieren Sie nur diese und dokumentieren Sie die ausgeschlossenen Seiten und den Grund im Bericht. Die Qualitätssicherung kennzeichnet wahrscheinliche Duplikate als possible_duplicate_revision. Notieren Sie den issue_status jedes Blattes aus dem Schriftfeld oder den Stempeln.
• Dokumentieren Sie nur, was gezeichnet ist. Erfinden Sie niemals Tags, Verbindungen oder Kreise, um den Graphen vollständig erscheinen zu lassen. Alles, was unklar ist, wird mit einer niedrigeren confidence oder in unreadable eingetragen.
• Die QA-Schleife ist nicht optional. Bauen Sie neu auf, bis es keine Fehler mehr gibt, und überprüfen Sie jede Warnung anhand der Zeichnung.

Workflow

Kopieren Sie diese Checkliste in Ihre Notizen und haken Sie sie ab:

- [ ] 1. Untersuchen:    python scripts/probe_pdf.py <pdf> --work <work> --plant-name "<name>" [--pages 47-60]
- [ ] 2. Rendern:       python scripts/render_pages.py <work>
- [ ] 3. Ausrichten:    Öffnen Sie jedes pages/page_NN/overview_grid.png; korrigieren Sie die Drehung, wenn der Text nicht aufrecht steht
- [ ] 4. Hinweise:      python scripts/make_hints.py <work>
- [ ] 5. Extrahieren:   Schreiben Sie für jedes Blatt <work>/extract/page_NN.json (siehe references/extraction_procedure.md)
- [ ] 6. Erstellen:     python scripts/build_kg.py <work>
- [ ] 7. QA-Schleife:   Beheben Sie jeden Fehler, überprüfen Sie jede Warnung erneut, bauen Sie neu auf (wiederholen Sie den Vorgang)
- [ ] 8. Bericht:       Fassen Sie die Ergebnisse zusammen und eröffnen Sie Probleme für den Benutzer

1. Untersuchen

probe_pdf.py weist jeder Seite eine Klasse und eine Extraktionsroute zu und schreibt <work>/manifest.json. Mit --pages rendern und lesen die späteren Schritte nur diese Seiten.

Klasse	Bedeutung	Route
vector_text	Vektorzeichnung mit Textlage	Aus Vektoren rendern; genauen Text aus der Textlage als Hinweise
vector_outlined	Vektorzeichnung, Text als Konturen gezeichnet (keine Textlage)	Hochauflösende Vektorwiedergabe; OCR-Hinweise
raster	Gescanntes Bild	Native Auflösung rendern, hochskaliert und kontrastverstärkt; OCR-Hinweise
raster_with_text	Scan mit einer OCR-Textlage	Wie Raster; Textlage als (nicht vertrauenswürdige) Hinweise
hybrid	Vektoren plus große Bilder	Beide Routen

Melden Sie das Ergebnis der Untersuchung dem Benutzer in einer Zeile, z. B. „14 Vektorblätter mit konturiertem Text.“

Eine niedrige Scanauflösung wird in den Notizen vermerkt. Erwarten Sie, dass auf diesen Blättern mehr Elemente in unreadable eingetragen werden.

2–3. Rendern und Ausrichtung prüfen

render_pages.py schreibt für jede Seite:

• overview.png
• overview_grid.png, das die Kachelnamen anzeigt
• überlappende Kacheln in tiles/
• tiles.json, das aufzeichnet, welche Kacheln leer sind

Die Ausrichtung wird mit OCR erkannt, wenn es installiert ist. Bestätigen Sie sie immer auf overview_grid.png. Wenn der Hauptzeichnungstext nicht aufrecht steht, rendern Sie diese Seite mit einer expliziten Drehung neu, im Uhrzeigersinn angegeben: render_pages.py <work> --pages N --rotation 90.

Schriftfelder sind manchmal anders gedreht als die Zeichnung. Richten Sie sich nach den Beschriftungen der Zeichnung, nicht nach dem Schriftfeld.

4. Hinweise

make_hints.py schreibt hints/page_NN.json. Jede Datei enthält Kandidaten-Tags mit Seitenpositionen aus der Textlage oder OCR. Sie sind nur Hinweise: OCR liest falsch und übersieht Dinge. Sie müssen die Hinweisdateien während der Extraktion nicht lesen. Die Qualitätssicherung verwendet sie, um Tags zu kennzeichnen, die Sie möglicherweise übersehen haben. Wenn OCR nicht installiert ist, wird der Schritt übersprungen; vermerken Sie dies im Abschlussbericht.

5. Extrahieren Sie jedes Blatt

Dies ist der Kern der Aufgabe. Befolgen Sie genau die references/extraction_procedure.md. Sie behandelt:

• die Lesereihenfolge: Übersicht, dann jede nicht leere Kachel, dann gezoomte Ausschnitte
• wie Rohrleitungsverläufe, Abzweigungen, Stichleitungen, Signale und seitenübergreifende Verbinder modelliert werden
• Konfidenz-Kalibrierung
• eine Selbstüberprüfungsliste, die vor dem Speichern durchlaufen werden muss

Referenzmaterial, das bei Bedarf gelesen werden sollte:

• references/isa_5_1.md: Instrumenten-Buchstabencodes, Blasensymbole, Signalleitungsarten
• references/symbol_guide.md: wie Geräte- und Ventilsymbole auf kind-Werte abgebildet werden
• references/ontology.md: die Knoten- und Kantentypen des Graphen und wie sie abgeleitet werden
• references/schema/extraction.schema.json: das genaue JSON-Schema einer Seitendatei

Schreiben Sie extract/page_NN.json und speichern Sie es, bevor Sie mit dem nächsten Blatt beginnen, damit ein langer Auftrag nie mehr als ein Blatt im Kontext hält. Bei vielen Blättern, und wenn Ihre Umgebung Unteragenten unterstützt, können Sie Blätter parallel extrahieren. Geben Sie jedem Unteragenten die Prozedurdatei und sein eigenes Seitenverzeichnis.

6–7. Erstellen und die QA-Schleife

build_kg.py validiert jede Seitendatei und stoppt bei Schemafehlern mit einer präzisen Meldung. Anschließend schreibt es diese Dateien in <work>/kg/:

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

Arbeiten Sie sich durch qa_report.md:

• Fehler, wie unresolved_reference, sind Fehler in den Seitendateien. Beheben Sie sie und bauen Sie neu auf.
• Warnungen nennen die zu überprüfenden Kacheln. Sehen Sie sich diese Kacheln erneut an oder verwenden Sie crop.py für eine vergrößerte Ansicht und korrigieren Sie die Extraktion, wenn die Zeichnung etwas anderes zeigt. Häufige Warnungen:
  • instrument_not_located: ein Sensor ohne measures
  • equipment_not_connected
  • unmatched_off_page
  • possible_missed_tags: ein OCR-Tag, das sich nicht in Ihrer Extraktion befindet
  • tiles_not_reviewed
• Eine Warnung, die sich auf der Zeichnung als korrekt herausstellt, kann so bleiben. Beispiele: Ein seitenübergreifender Verbinder, dessen andere Zeichnung nicht geliefert wurde, oder ein OCR-Fehler. Listen Sie diese in Ihrem Bericht auf.

Stoppen Sie, wenn es keine Fehler gibt und jede Warnung überprüft wurde.

python scripts/crop.py <work> --page 5 --bbox 0.40 0.20 0.55 0.35   # gezoomte Ansicht einer Region

8. Bericht

Teilen Sie dem Benutzer mit:

• wo die Ausgaben sind
• die wichtigsten Zählwerte (Geräte, Instrumente, Kreise)
• zwei oder drei Beispiel-Durchflusswege und Kreise aus summary.md
• was unsicher bleibt

Verweisen Sie für Details auf qa_report.md. Geben Sie klar an, dass der Graph maschinell extrahiert wurde und vor der Verwendung für Design, Betrieb oder Sicherheit einer technischen Überprüfung bedarf.

Den Graphen verwenden

• summary.md ist der kompakte, token-effiziente Kontext für ein LLM: Durchfluss auf Geräteebene, eine Instrumententabelle mit Standorten und eine Kreistabelle.
• graph.json ist der kanonische Graph, den jedes Werkzeug lesen kann.
• graph.duckdb ist für SQL. Seine Ansichten sind equipment, equipment_flow, instruments, loops und signals, und seine Tabellenmakros sind upstream(id) und downstream(id).

Verwenden Sie kg_query.py, um Fragen zu beantworten; fügen Sie --json hinzu, wenn ein anderes Werkzeug die Ausgabe konsumieren wird:

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

Um die Extraktionsqualität auf einem Blatt zu messen, überprüfen Sie es manuell in eine kleine Goldstandard-Datei (Format in scripts/eval_kg.py) und führen Sie python scripts/eval_kg.py <work>/kg gold.json aus: es meldet Tag-, Durchfluss- und Kreis-Precision/Recall sowie Instrumentenplatzierung.

Um einen Graphen in andere Werkzeuge zu überführen: python scripts/export.py <work>/kg graphml erzeugt eine Datei für yEd, Gephi oder NetworkX, und python scripts/export.py <work>/kg neo4j erzeugt CSVs plus ein Cypher-Importskript.