ScottDuncanAI/PID-to-Knowledge-Graph

What it does

pid-to-kg is a Claude skill for process engineers working with piping and instrumentation diagrams (P&IDs) and process flow diagrams (PFDs). It reads digital or scanned PDFs and produces a connected knowledge graph covering process flow (what is upstream and downstream of each tank, pump, valve and pipe segment), instrumentation (which instrument measures which variable and where), and control loops from sensor through controller to final element, including I/P relays, cascades, interlocks and VFDs.

The design splits work between two parts: Claude reads each sheet and tiles visually to recognise symbols and trace lines, while tested Python scripts handle page preparation, graph construction and QA. Output is written as summary.md, graph.json and graph.duckdb, plus a qa_report.md of anything uncertain. The intended consumer is an LLM application that queries the graph as one layer of a chemical-manufacturing context layer.

Quick start

Preparation: install Claude Code (desktop or terminal) and Python 3.10+; Python 3.12 is recommended because 3.13 removes the OCR cross-check and automatic page orientation.

1. On the repository page, choose Code → Download ZIP and unzip it.
2. From the unzipped skills folder, copy pid-to-kg into your personal skills directory: C:\Users\<your user name>\.claude\skills\ on Windows or /Users/<your user name>/.claude/skills/ on macOS. Create the folder if needed; .claude is hidden by default.
3. Create a project folder, put the P&ID PDF in it, and open that folder in Claude Code.
4. Ask Claude to convert the drawings, for example: Convert haile.pdf into a knowledge graph. The P&IDs are on pages 47–60. The skill loads automatically; the first run installs needed Python packages and asks permission before running commands.
5. Verify with questions about details you can check on the sheet, such as What sensor measures the flow into TK-101, and where exactly is it? Results land in work/<plant name>/kg/ inside the project folder.

No drawings on hand? The author's public chemical manufacturing datasets list public P&ID sets, both digital and scanned, with page numbers.

Outputs and extension

The four default outputs are a readable summary.md for LLM context, a qa_report.md, the full graph.json conforming to the graph schema, and graph.duckdb for SQL, including recursive upstream/downstream searches. Larger projects can be asked to export to Neo4j or GraphML for yEd, Gephi or NetworkX. Node and edge types are documented in the ontology, and equipment and instruments carry the closest DEXPI class.

Constraints

• Extraction quality depends on legibility; low-resolution scans can lose small text, and unreadable items are marked rather than guessed.
• Control loops are derived from ISA-5.1 tag numbers and drawn signal lines. Logic that exists only in control narratives or cause-and-effect charts is not captured.
• Flow direction comes from arrows and equipment logic; inferred edges are marked flow_direction: inferred.
• The DEXPI mapping is informative only, not a certified DEXPI export.
• The graph is machine-extracted and must be reviewed by a qualified engineer before use in design, operations, management of change, or safety studies such as HAZOP or LOPA.
• The project is MIT licensed. Development uses pip install -e ".[dev]" and pytest.

HotRepo's take

The repository appeared on HotRepo's new-project list for Python on 2026-11-11, gaining 11 stars and 2 forks in a measured window of about 1.5 hours, with 111 stars and 27 forks overall at that point. That is a short observation window on a young repository, so it shows early attention rather than established adoption; there is no recorded GitHub all-language daily rank. What stands out from the material is the engineering discipline: the symbol-reading step is left to Claude while deterministic scripts handle rendering, graph building and QA, and the output schema ties back to ISA-5.1 tags and DEXPI classes. The README is also explicit about failure modes, including inferring flow direction and flagging it.