ScottDuncanAI/pid-to-kg

P&ID에서 지식 그래프로

작업은 결정론적 스크립트와 사용자(에이전트)로 나뉩니다:

• 스크립트는 페이지를 분류(벡터 vs 스캔)하고, 읽을 수 있는 타일로 렌더링하며, OCR/텍스트 힌트를 수집한 후 그래프를 구축, 검사, 저장, 쿼리합니다.
• **사용자(에이전트)**는 도면을 읽고 시트별로 하나의 구조화된 추출 파일을 작성합니다. 기호 인식 및 선 추적은 시각적 추론 작업으로, 스크립트가 잘 수행하지 못하는 부분입니다.

모든 스크립트는 이 파일과 같은 디렉토리의 scripts/에 있습니다. 전체 경로로 호출하고(아래 명령어는 scripts/로 축약), 작업 디렉토리는 사용자의 현재 폴더(예: work/<plant>)에 유지하세요.

설정. 많은 사용자가 프로그래머가 아닌 엔지니어이므로, 설정은 에이전트가 직접 처리하세요. 스크립트는 Python 3.10+가 필요합니다. 첫 실행 전에 pip install -r <skill dir>/scripts/requirements.txt로 의존성을 설치하세요(사용자의 Python이 다른 작업과 공유되는 경우 가상 환경 사용). Python이 없으면 python.org에서 설치하도록 안내하고 중단하세요.

기본 규칙

• P&ID 페이지만. 도면은 종종 긴 허가서나 설계 보고서 안에 포함됩니다. 사용자가 페이지를 지정하면 --pages로 전달하세요. 그렇지 않고 PDF에 페이지가 여러 장인 경우 탐색하여 페이지 개요를 보거나 사용자에게 물은 후, --pages로 프로브를 다시 실행하여 이후 단계에서 보고서, 범례, 비P&ID 도면을 건너뛰도록 하세요.
• 하나의 플랜트, 하나의 작업 디렉토리, 하나의 그래프. 서로 다른 플랜트의 시트를 같은 작업 디렉토리에 절대 넣지 마세요. 태그가 관련 없는 플랜트 간에 병합됩니다. 사용자가 여러 플랜트를 제공하면 각각에 대해 전체 워크플로우를 별도로 실행하세요.
• 그래프당 하나의 설정. PDF에 같은 도면의 두 개정판(동일한 제목 또는 영역, 중복 태그, 예: 준공도와 이전 초안)이 포함된 경우 병합하지 마세요. 사용자에게 어떤 개정판을 사용할지 묻고, 해당 개정판만 추출한 후 제외된 페이지와 그 이유를 보고서에 기록하세요. QA는 중복 가능성을 possible_duplicate_revision으로 플래그 지정합니다. 각 시트의 issue_status를 타이틀 블록 또는 스탬프에서 기록하세요.
• 그려진 것만 기록. 그래프를 완전하게 만들기 위해 태그, 연결 또는 루프를 절대 임의로 만들지 마세요. 불명확한 것은 낮은 confidence로 기록하거나 unreadable에 넣으세요.
• QA 루프는 필수. 오류가 없을 때까지 재구축하고, 모든 경고를 도면에서 다시 확인하세요.

워크플로우

다음 체크리스트를 노트에 복사하고 완료 시 체크하세요:

- [ ] 1. 프로브:    python scripts/probe_pdf.py <pdf> --work <work> --plant-name "<name>" [--pages 47-60]
- [ ] 2. 렌더링:   python scripts/render_pages.py <work>
- [ ] 3. 방향 확인: 각 pages/page_NN/overview_grid.png를 열고; 텍스트가 똑바르지 않으면 회전 수정
- [ ] 4. 힌트:    python scripts/make_hints.py <work>
- [ ] 5. 추출:     각 시트에 대해 <work>/extract/page_NN.json 작성 (참조: references/extraction_procedure.md)
- [ ] 6. 구축:    python scripts/build_kg.py <work>
- [ ] 7. QA 루프:  모든 오류 수정, 모든 경고 재확인, 재구축 (반복)
- [ ] 8. 보고:    결과 요약 및 미해결 이슈를 사용자에게 제시

1. 프로브

probe_pdf.py는 각 페이지에 클래스와 추출 경로를 할당하고 <work>/manifest.json을 작성합니다. --pages를 사용하면 이후 단계에서 해당 페이지만 렌더링하고 읽습니다.

클래스	의미	경로
vector_text	텍스트 레이어가 있는 벡터 도면	벡터에서 렌더링; 텍스트 레이어에서 정확한 텍스트를 힌트로 사용
vector_outlined	벡터 도면, 텍스트가 외곽선으로 그려짐 (텍스트 레이어 없음)	고해상도 벡터 렌더링; OCR 힌트
raster	스캔 이미지	네이티브 해상도 렌더링, 업스케일 및 대비 향상; OCR 힌트
raster_with_text	OCR 텍스트 레이어가 있는 스캔	raster와 동일; 텍스트 레이어를 (신뢰할 수 없는) 힌트로 사용
hybrid	벡터와 큰 이미지 혼합	두 경로 모두 사용

프로브 결과를 사용자에게 한 줄로 보고하세요. 예: "텍스트가 외곽선 처리된 벡터 시트 14장."

낮은 스캔 해상도는 노트에 플래그 지정됩니다. 해당 시트에서 unreadable 항목이 더 많이 기록될 것으로 예상하세요.

2–3. 렌더링 및 방향 확인

render_pages.py는 각 페이지에 대해 다음을 작성합니다:

• overview.png
• overview_grid.png (타일 이름 표시)
• tiles/의 중첩 타일
• tiles.json (빈 타일 기록)

방향은 OCR이 설치된 경우 OCR로 감지됩니다. 항상 overview_grid.png에서 확인하세요. 주요 도면 텍스트가 똑바르지 않으면 해당 페이지를 명시적 회전으로 다시 렌더링하세요(시계 방향): render_pages.py <work> --pages N --rotation 90.

타이틀 블록은 도면과 다르게 회전된 경우가 있습니다. 타이틀 블록이 아닌 도면 레이블을 기준으로 방향을 맞추세요.

4. 힌트

make_hints.py는 hints/page_NN.json을 작성합니다. 각 파일은 텍스트 레이어 또는 OCR에서 가져온 페이지 위치가 포함된 후보 태그를 보관합니다. 이는 힌트일 뿐입니다. OCR은 오독하거나 놓칠 수 있습니다. 추출 중에 힌트 파일을 읽을 필요는 없습니다. QA는 이를 사용하여 놓친 태그를 플래그 지정합니다. OCR이 설치되지 않은 경우 이 단계는 건너뛰며, 최종 보고서에 이를 명시하세요.

5. 각 시트 추출

이것이 작업의 핵심입니다. references/extraction_procedure.md 를 정확히 따르세요. 다음을 다룹니다:

• 읽기 순서: 개요, 그 다음 모든 비어 있지 않은 타일, 그 다음 확대/축소된 영역
• 배관 런, 티, 탭, 신호 및 페이지 외부 커넥터 모델링 방법
• 신뢰도 보정
• 저장 전 실행할 자체 점검 목록

필요할 때 읽을 참고 자료:

• references/isa_5_1.md: 계측기 문자 코드, 버블 기호, 신호선 유형
• references/symbol_guide.md: 장비 및 밸브 기호가 kind 값에 매핑되는 방법
• references/ontology.md: 그래프의 노드 및 엣지 유형과 파생 방법
• references/schema/extraction.schema.json: 페이지 파일의 정확한 JSON 스키마

extract/page_NN.json을 작성하고 다음 시트를 시작하기 전에 저장하세요. 긴 작업이 한 번에 한 시트 이상의 컨텍스트를 보유하지 않도록 합니다. 시트가 많고 환경이 서브 에이전트를 지원하는 경우 시트를 병렬로 추출할 수 있습니다. 각 서브 에이전트에 절차 파일과 자체 페이지 디렉토리를 제공하세요.

6–7. 구축 및 QA 루프

build_kg.py는 모든 페이지 파일의 유효성을 검사하고 스키마 오류 시 정확한 메시지와 함께 중단됩니다. 그런 다음 <work>/kg/에 다음 파일을 작성합니다:

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

qa_report.md를 통해 작업하세요:

• 오류(예: unresolved_reference)는 페이지 파일의 실수입니다. 수정하고 재구축하세요.
• 경고는 재확인할 타일을 명명합니다. 해당 타일을 다시 보거나 crop.py를 사용하여 확대/축소된 보기로 확인한 후, 도면에 다른 내용이 표시되면 추출을 수정하세요. 일반적인 경고:
  • instrument_not_located: measures가 없는 센서
  • equipment_not_connected
  • unmatched_off_page
  • possible_missed_tags: 추출에 없는 OCR 태그
  • tiles_not_reviewed
• 도면에서 올바른 것으로 판명된 경고는 남겨도 괜찮습니다. 예: 다른 도면이 제공되지 않은 페이지 외부 커넥터, 또는 OCR 오독. 이러한 항목을 보고서에 나열하세요.

오류가 없고 모든 경고가 확인되었을 때 중단하세요.

python scripts/crop.py <work> --page 5 --bbox 0.40 0.20 0.55 0.35   # 영역의 확대 보기

8. 보고

사용자에게 다음을 알리세요:

• 출력물 위치
• 주요 수치 (장비, 계측기, 루프 수)
• summary.md에서 가져온 두세 개의 예제 흐름 경로 및 루프
• 불확실한 사항

자세한 내용은 qa_report.md를 참조하세요. 그래프는 기계 추출된 것이며 설계, 운영 또는 안전에 사용하기 전에 엔지니어 검토가 필요하다는 점을 명확히 밝히세요.

그래프 사용

• summary.md는 LLM에 대한 간결하고 토큰 효율적인 컨텍스트입니다: 장비 수준 흐름, 위치 정보가 포함된 계측기 테이블, 루프 테이블.
• graph.json은 정식 그래프로, 모든 도구가 읽을 수 있습니다.
• graph.duckdb는 SQL용입니다. 뷰는 equipment, equipment_flow, instruments, loops, signals이며, 테이블 매크로는 upstream(id) 및 downstream(id)입니다.

kg_query.py를 사용하여 질문에 답변하세요. 다른 도구가 출력을 사용하는 경우 --json을 추가하세요:

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"

시트의 추출 품질을 측정하려면 수동으로 작은 골드 파일(scripts/eval_kg.py 형식)을 만들어 python scripts/eval_kg.py <work>/kg gold.json을 실행하세요. 태그, 흐름 및 루프 정밀도/재현율과 계측기 배치를 보고합니다.

그래프를 다른 도구로 이동하려면: python scripts/export.py <work>/kg graphml은 yEd, Gephi 또는 NetworkX용 파일을 생성하고, python scripts/export.py <work>/kg neo4j는 CSV와 Cypher 임포트 스크립트를 생성합니다.