Document Intelligence Extraction

Use this skill as the intake layer for documents and images supplied to NeqSim tasks. It makes extraction automatic where tools are available without treating OCR or model output as verified engineering data.

When to Use

• A task receives PDF, DOCX, XLSX, CSV, HTML, XML, presentation, image, scan, drawing, chart, or photograph inputs.
• A PDF may contain both embedded text and visual engineering content.
• Multiple sources must be reconciled without silently choosing one value.
• Extracted values will feed simulation, design, safety, operations, or reporting workflows.

Inputs

• source_path: source file path; retain the original file unchanged.
• embedded_text_chars: optional PDF text-layer yield used to trigger OCR.
• contains_visuals: optional Office-document visual-content hint.
• Adapter-produced facts with original text, page or locator, extraction method, confidence, and optional normalized value/unit.

Outputs

• ExtractionPlan: source kind plus ordered native-text, table, OCR, rendering, and vision operations.
• ExtractionResult: schema-versioned evidence package with facts, quality score, warnings, gaps, and review status.
• Conflict records for fields whose normalized values differ across sources.

Engineering Method

The skill uses a staged, loss-minimizing method: preserve native structure, add OCR only when the text layer is absent or weak, use vision when spatial meaning matters, and reconcile all methods into evidence rather than free-form prose. Its Python package implements deterministic classification, routing, provenance validation, review gates, quality scoring, and conflict detection. Runtime adapters perform format parsing, OCR, and multimodal inference. This is an engineering-data governance workflow, not a validated physical model or a substitute for document control.

Extraction Workflow

1. Inventory files recursively and preserve original names, hashes, and relative paths.
2. Classify by actual format where possible, not filename alone. Reject encrypted, corrupt, unexpectedly executable, or unsupported content for manual triage.
3. Prefer structured/native extraction first:
   • PDF text layer and table geometry;
   • DOCX paragraphs, tables, headers, footnotes, and embedded media;
   • XLSX sheet names, cells, formulas, merged ranges, hidden rows/columns, and units;
   • CSV/JSON/XML structure without flattening it to prose.
4. For low-yield/scanned PDFs, render pages and run OCR with word coordinates. Keep OCR text separate from native text.
5. Use multimodal vision for drawings, P&IDs, charts, photographs, symbols, topology, annotations, and spatial relationships. OCR alone cannot establish these semantics.
6. Reconcile native text, OCR, tables, and vision. Do not overwrite disagreements; emit a conflict requiring review.
7. Normalize values and units while preserving the exact original value, text, and unit.
8. Gate every safety-critical, ambiguous, or confidence-below-0.85 fact as needs_review.
9. Hand the evidence package to a document-type skill for engineering interpretation, then to the relevant NeqSim model.

Token-Efficient Reading (markdown_normalize)

Engineering sources are long, and feeding raw parser output to a model wastes context. The optional markdown_normalize step produces a compact Markdown rendition of a source so the model can read, orient, and locate the relevant sections cheaply. A converter such as MarkItDown (pip install 'markitdown[docx,pptx,xlsx,pdf]') is a suitable adapter.

It is a reading aid, not an extraction method. Construct it as follows:

• Use it to decide which pages, sheets, or sections matter; then run the provenance-preserving step on that region only.
• markdown_normalize is rejected as an EvidenceFact.method. The local PDF converter joins pages into one string, so page boundaries are lost and a page citation taken from it would be fabricated. Cite pages from native_text, native_tables, or ocr.
• Do not use it for spreadsheets that carry engineering meaning in formulas, merged ranges, hidden rows, or unit headers. Markdown flattening discards all four; use structured_tables.
• It is not an OCR engine. A scanned PDF still yields near-empty Markdown, and image handling is metadata plus optional model-vision captioning. OCR stays with neqsim-pdf-ocr.
• Cloud layout backends (Azure Document Intelligence, Content Understanding) do emit page markers, but they send the document off the machine. Treat that as an enterprise-governed route, not a community default.

Where it pays off most: Word and PowerPoint documents, HTML, CSV/JSON/XML, EPUB, and text-heavy PDFs such as standards, reports, and specifications that must be read in full before the fields worth extracting are known.

Python Usage Pattern

from document_intelligence_extraction import DocumentIntelligenceExtractor, EvidenceFact

extractor = DocumentIntelligenceExtractor()
plan = extractor.plan("equipment_datasheet.pdf", embedded_text_chars=420)

fact = EvidenceFact(
    field="design_pressure",
    value=150.0,
    unit="bara",
    original_text="Design pressure: 150 bar(a)",
    page=2,
    locator="table:Design Conditions,row:Pressure",
    method="native_tables",
    confidence=0.98,
    safety_critical=True,
)
result = extractor.package(plan, "equipment_datasheet", [fact])
payload = result.to_dict()

The package does not embed one OCR or AI vendor. A harness executes each planned operation using available parsers, OCR engines, and multimodal tools, then creates EvidenceFact objects.

Evidence Contract

Every fact must include:

• semantic field name and extracted value;
• original text and original unit;
• page number or stable locator such as sheet/cell, table/row, bounding box, or XML path;
• extraction method and confidence from 0 to 1;
• normalized value/unit when conversion is performed;
• ambiguity and safety-critical flags;
• review status assigned by the contract.

File-level metadata should additionally preserve content hash, document title/number, revision, date, language, page/sheet count, and extraction-tool versions.

Validation Checklist

• Originals remain unchanged and a content hash is recorded by the harness.
• Native extraction was attempted before OCR.
• Every visual page was rendered and assessed when layout carries meaning.
• Tables retain row/column provenance and multi-page continuations are checked.
• Every fact has original text plus page or locator.
• Values and units are normalized without discarding originals.
• Conflicting sources are reported rather than resolved silently.
• Safety-critical and low-confidence facts require human review.
• Missing expected fields are listed as gaps, never fabricated.
• Downstream NeqSim input validation runs after extraction review.

Common Mistakes

Limitations

• This skill routes and governs extraction; parser, OCR, and multimodal quality depend on the runtime adapters and source quality.
• Handwriting, faint scans, dense drawings, unusual fonts, password protection, and proprietary formats may require specialist tools or manual transcription.
• Confidence is a triage signal, not proof of correctness.
• It does not infer missing engineering values or replace document control and qualified review.

Cooperation and Handoffs

• Chain to neqsim-technical-document-reading for document-type schemas, engineering normalization, and physical validation.
• Chain to neqsim-pdf-ocr when PDF text yield is low or pages are scanned.
• Chain to P&ID, standards, compressor-chart, fluid, process-extraction, or other domain skills only after the evidence package is built.
• Enterprise retrieval, identifiers, controlled-document status, and internal governance remain in enterprise skills; they should emit the same evidence contract. Enterprise document/attachment retrieval skills and task-solver agents (which download action/tag register/maintenance attachments and drawings) use this skill as their intake/extraction layer — every downloaded document, drawing, chart, or photograph is planned and packaged here (native text, OCR, and vision) before interpretation, so all information (including figures, photos, and P&IDs) reaches the model as governed evidence facts.
• Downstream calculations should use NeqSim input validation and retain links back to evidence facts.

Related NeqSim Functionality

The skill supplies governed inputs to NeqSim workflows such as ProcessSystem.fromJsonAndRun, SimulationValidator.validate, process equipment sizing, PVT simulations, and MCP tools including runProcess, runPVT, runPipeline, and validateInput. It performs no thermodynamic calculation itself.

References

• NeqSim repository: https://github.com/equinor/neqsim
• NeqSim Skills Guide: https://github.com/equinor/neqsim/blob/master/docs/integration/skills_guide.md
• W3C Web Content Accessibility Guidelines for text alternatives and document accessibility concepts