neqsim-technical-document-reading

# Technical Document Reading Skill Extract structured engineering data from technical documents and convert it into formats usable by process simulation, mechanical design, and engineering analysis. Use the public community skill `neqsim-document-intelligence-extraction` before this skill when the task receives files. It owns source inventory, native/OCR/vision routing, provenance, confidence, review gates, and cross-document conflicts. This skill consumes that evidence package and adds document-type schemas, engineering normalization, physical validation, and NeqSim handoffs. Keeping this boundary explicit prevents OCR or multimodal output from being mistaken for verified engineering data. ## Core Principle > **Classify → Extract → Normalize → Validate → Output** > > 1. Classify the document type to select the right extraction strategy > 2. Extract raw data using format-specific tools (PDF, Word, Excel) > 3. Normalize units, component names, and field names to standard conventions > 4. Validate extracted data against physical bounds and completeness checks > 5. Output structured JSON/dict for downstream consumption For P&ID-driven operational studies, also load `neqsim-pid-process-operations`. That skill converts symbols into a process graph, classifies valve functions, maps instrument bubbles to historian tags, and defines steady-state or dynamic NeqSim scenario actions. For water-hammer or liquid-hammer screening, also load `neqsim-water-hammer`. Extract route geometry, wall thickness, roughness/piping class, fittings, valve closure timing, design pressure, and tagreader event references so the output can feed `WaterHammerStudy` or MCP `runWaterHammer`. For trapped-liquid fire rupture studies, also load `neqsim-trapped-liquid-fire-rupture`. Extract segment boundaries, line numbers, pipe geometry, material grade/certificate data, flange/gasket/bolt ratings, fire/PFP basis, relief availability, acceptance criteria, and explicit evidence gaps before handing data to the solver. --- ## 1. Document Type Classification ### Classification Decision Tree When a document is provided, classify it first: | Document Type | Identifying Features | Key Data to Extract | |--------------|---------------------|---------------------| | **Equipment Data Sheet** | API/ASME header, tag numbers, design conditions table | Design T/P, materials, dimensions, nozzle schedule | | **Technical Requirement (TR)** | Numbered clauses, "shall"/"should" language, design factors | Design rules, factors, material constraints, limits | | **Design Basis** | Operating envelope, fluid composition tables, flow scheme description | Compositions, T/P ranges, flow rates, design life | | **Heat & Mass Balance** | Stream table with T, P, flow, composition columns | Stream conditions, equipment duties, compositions | | **Well Test Report** | Choke sizes, flow rates vs time, GOR, water cut | Flow rates, compositions, reservoir P/T, productivity | | **P&ID / PFD Description** | Equipment tags, line numbers, instrument tags, connectivity | Topology, instrumentation, control philosophy | | **Piping Specification** | Material classes, pressure ratings, wall schedules | Pipe sizes, materials, ratings, corrosion allowance | | **Line List / Piping Route Table** | Tabular line numbers, NPS, schedule, from/to nodes, straight length, fittings, valves, elevations | Route segments for `PipingRouteBuilder`: segment id, nodes, internal diameter, wall thickness, length, elevation, K values, source refs | | **Water-Hammer Evidence Pack** | STID/P&ID route, valve data sheet, pump trip log, tagreader pressure/flow/valve-position event window | Route segments, design pressure, event schedule, closure/trip timing, field-data overrides for `runWaterHammer` | | **Trapped Liquid Fire Rupture Evidence Pack** | Combination of P&IDs/STIDs, line lists, piping specs, material certificates, flange/gasket data, fire/PFP documents, and relief basis | Segment id, isolation boundary, trapped volume inputs, material grade, flange class, fire exposure, PFP endurance, relief availability, acceptance criteria, evidence gaps | | **Inspection Report** | Thickness measurements, corrosion rates, anomaly locations | Wall thickness, corrosion rate, remaining life | | **Material Certificate** | Heat numbers, SMYS/SMTS, chemical composition, Charpy values | Mechanical properties, chemical analysis, grade | | **Standards Document** | ISO/API/ASME/DNV/NORSOK header, normative references | Design formulas, factors, limits, test requirements | | **Vendor Quotation** | Equipment specs, pricing, delivery, performance curves | Performance data, dimensions, weight, cost | | **Operating Procedure** | Step-by-step instructions, setpoints, alarm limits | Operating envelope, control setpoints, trip values | | **Engineering Drawing (P&ID)** | Piping & instrumentation diagram — lines, valves, instruments, tags visually laid out | Equipment topology, valve tags, instrument tags, line sizes, piping class, connection types | | **Mechanical Arrangement Drawing** | GA/section/plan views with dimensions, elevations, nozzle locations | Physical dimensions, elevations, nozzle orientations, piping run lengths, standpipe geometry | | **Vendor API Datasheet (image)** | API 610/614/617/692 format data sheets rendered as images in PDFs | Seal type, operating conditions, leakage rates, gas supply requirements, material specs | | **Performance Map / Curve** | Compressor maps, pump curves, phase envelopes, operating windows | Head vs flow, efficiency, surge line, operating point, cricondentherm/bar | | **Process Flow Diagram (image)** | Visual PFD with equipment symbols, stream arrows, T/P/flow annotations | Equipment sequence, stream conditions, control valves, key operating parameters | ### Auto-Detection Heuristics When document type isn't stated, look for these patterns: ```python DOCUMENT_SIGNATURES = { "equipment_data_sheet": [ r"(?i)data\s*sheet", r"(?i)tag\s*no", r"(?i)design\s+press", r"(?i)operating\s+press", r"(?i)nozzle\s+schedule" ], "technical_requirement": [ r"(?i)technical\s+requirement", r"(?i)\bTR[\s-]?\d+", r"(?i)\bshall\b.*\bdesign", r"(?i)design\s+factor" ], "design_basis": [ r"(?i)design\s+basis", r"(?i)basis\s+of\s+design", r"(?i)operating\s+envelope", r"(?i)ambient\s+conditions" ], "heat_mass_balance": [ r"(?i)heat\s+.*mass\s+balance", r"(?i)stream\s+(table|summary)", r"(?i)mol\s*%|mole\s+frac", r"(?i)vapour\s+fraction" ], "well_test": [ r"(?i)well\s+test", r"(?i)choke\s+size", r"(?i)GOR", r"(?i)productivity\s+index", r"(?i)IPR" ], "inspection_report": [ r"(?i)inspection\s+report", r"(?i)wall\s+thickness", r"(?i)corrosion\s+rate", r"(?i)remaining\s+life" ], "material_certificate": [ r"(?i)material\s+cert", r"(?i)heat\s+number", r"(?i)SMYS|SMTS", r"(?i)charpy|impact\s+test" ], "piping_spec": [ r"(?i)piping\s+class", r"(?i)material\s+class", r"(?i)line\s+class", r"(?i)pressure\s+rating" ], "line_list_route_table": [ r"(?i)line\s*list", r"(?i)route\s*table", r"(?i)stress\s*iso(metric)?", r"(?i)from\s+node.*to\s+node", r"(?i)nominal\s+(size|diameter)", r"(?i)straight\s+length" ], "trapped_liquid_fire_rupture": [ r"(?i)trapped\s+liquid", r"(?i)blocked[-\s]?in\s+liquid", r"(?i)thermal\s+expansion", r"(?i)fire\s+exposure", r"(?i)no\s+pressure\s+relief", r"(?i)passive\s+fire\s+protection|PFP", r"(?i)flange\s+(failure|leak|rupture)", r"(?i)pipe\s+rupture" ], "engineering_drawing_pid": [ r"(?i)piping\s+.*instrument.*diagram", r"(?i)P&ID", r"(?i)P\s*&\s*I\s*D", r"(?i)instrument\s+diagram" ], "mechanical_arrangement": [ r"(?i)general\s+arrangement", r"(?i)GA\s+drawing", r"(?i)section\s+view", r"(?i)plan\s+view", r"(?i)mechanical\s+arrangement", r"(?i)elevation\s+view" ], "vendor_api_datasheet_image": [ r"(?i)API\s+6[19][0247]", r"(?i)dry\s+gas\s+seal", r"(?i)seal\s+gas", r"(?i)vendor\s+data\s*sheet", r"(?i)mechanical\s+seal", r"(?i)compressor\s+data\s*sheet" ], "performance_map": [ r"(?i)performance\s+(map|curve)", r"(?i)compressor\s+map", r"(?i)pump\s+curve", r"(?i)phase\s+envelope", r"(?i)head\s+vs\s+flow", r"(?i)surge\s+line", r"(?i)operating\s+point", r"(?i)cricondentherm" ], } ``` ### Trapped-Liquid Fire Rupture Extraction Schema When the downstream task is trapped liquid, blocked-in liquid, fire rupture, PFP demand, or no pressure relief on liquid-filled piping, build this study input block: ```json { "study_type": "trapped_liquid_fire_rupture", "segments": [ { "segment_id": "...", "line_numbers": ["..."], "isolation_boundary": { "upstream": {"tag": "...", "source": "..."}, "downstream": {"tag": "...", "source": "..."}, "vents_drains_relief_paths": [] }, "pipe_geometry": { "internal_diameter_m": {"value": null, "source": "...", "confidence": 0.0}, "wall_thickness_m": {"value": null, "source": "...", "confidence": 0.0}, "exposed_length_m": {"value": null, "source": "...", "confidence": 0.0} }, "material": { "grade": {"value": null, "source": "..."}, "smys_MPa": {"value": null, "source": "..."}, "smts_MPa": {"value": null, "source": "..."} }, "flange_gasket_bolt": { "class": {"value": null, "source": "..."}, "gasket_type": {"value": null, "source": "..."}, "temperature_rating_source": "..." }, "fluid_and_conditions": { "fluid_description": "...", "composition": [], "operating_pressure_bara": {"value": null, "source": "..."}, "operating_temperature_C": {"value": null, "source": "..."} }, "fire_and_pfp": { "fire_type": "api521_pool_fire | fixed_heat_flux | radiative_fire | unknown", "heat_flux_W_m2": {"value": null, "source": "..."}, "pfp_required_endurance_s": {"value": null, "source": "..."} }, "relief_and_acceptance": { "relief_available": {"value": null, "source": "..."}, "relief_set_pressure_bara": {"value": null, "source": "..."}, "acceptance_criteria": [] }, "evidence_gaps": [] } ] } ``` Extraction priority for conflicting values: material certificate > piping spec > line list > P&ID annotation > narrative report > inferred/default. Always report conflicts rather than silently choosing one value. --- ## 2. File Format Handlers