field-infrastructure-joins

name	field-infrastructure-joins
description	Build field-level offshore infrastructure data bundles from local BSEE tables for engineering products. Use when users ask for field structures, platforms, pipelines, risers, jumpers, umbilicals, FMP/MCP systems, appurtenances, or product-ready field infrastructure joins.

Field Infrastructure Joins

Use this skill to turn BSEE field, platform, pipeline, FMP, MCP, scanned-document, and decom tables into product-ready engineering data.

Quick Start

From the worldenergydata repo root:

worldenergydata bsee infrastructure-bundle \
  --field "Stones" \
  --output reports/bsee/field_infrastructure/stones

The command defaults to downloaded local data at:

/mnt/ace/worldenergydata/data/modules/bsee/bin

Override the data root when needed:

worldenergydata bsee infrastructure-bundle \
  --field "Julia" \
  --data-root /mnt/ace/worldenergydata/data/modules/bsee/bin \
  --output reports/bsee/field_infrastructure/julia

Generate the engineering-facing product package from a bundle:

worldenergydata bsee field-package \
  --bundle reports/bsee/field_infrastructure/stones \
  --output reports/bsee/field_packages/stones

Retrieve source PDFs from a package queue:

worldenergydata bsee retrieve-documents \
  --queue reports/bsee/field_packages/stones/document_queue.csv \
  --output reports/bsee/field_packages/stones

Index retrieved source PDFs for engineering terms:

worldenergydata bsee index-documents \
  --manifest reports/bsee/field_packages/stones/download_manifest.csv \
  --package-dir reports/bsee/field_packages/stones \
  --max-pages 2

OCR no-text source PDFs when scanned drawings need searchable text:

worldenergydata bsee ocr-documents \
  --index reports/bsee/field_packages/stones/source_document_index.csv \
  --package-dir reports/bsee/field_packages/stones \
  --family pipeline_map \
  --max-pages 1

Import a filled reviewer-ready template after human source-page review:

worldenergydata bsee import-reviewer-inputs \
  --ready-input reports/bsee/field_packages/field_structure_reviewer_ready13_input_template_julia_stones_saint_malo.csv \
  --decision-log reports/bsee/field_packages/field_structure_basis_review_decision_log_top15_julia_stones_saint_malo.csv \
  --output reports/bsee/field_packages/reviewer_import \
  --sqlite-product reports/bsee/field_packages/field_structure_product_julia_stones_saint_malo.sqlite

Output Contract

The command writes:

• field_context.json
• structures.csv
• pipeline_segments.csv
• pipeline_locations.csv
• appurtenances.csv
• documents.csv
• engineering_summary.json

The package command writes:

• index.html
• document_queue.csv with retrieval_url, retrieval_status, and query_url columns for BSEE scanned-document review.
• download_manifest.csv and source_documents/ when retrieve-documents is run against the queue.
• source_document_index.csv when index-documents is run against the retrieval manifest.
• source_document_ocr_index*.csv when ocr-documents is run against no-text indexed PDFs.
• Derived field_document_evidence_*.csv tables when parser and OCR term-hit rows are consolidated for downstream engineering joins.
• Derived field_engineering_join_input_*.csv and field_structure_candidates_*.csv tables when document evidence is joined back to segment, lease, ROW, appurtenance, and structure context.
• Derived field_structure_review_queue_*.csv tables when candidates are ranked for manual source-PDF/drawing review.
• Derived field_structure_review_packet_*.html reports when the top review queue needs local PDF links and product-facing summaries.
• Derived field_structure_review_workbook_*.csv and field_structure_review_evidence_*.csv files when engineering reviewers need decision columns plus per-document evidence snippets.
• Derived field_structure_review_*_geometry*.geojson/.csv/.html files when the review queue needs spatial screening from pipeline route and appurtenance coordinates.
• Derived field_structure_top*_source_contact_sheet/ packets when reviewers need fast visual triage of the source PDFs behind the highest-priority candidates.
• Derived field_structure_top*_targeted_pages/ packets when reviewers need pages scored by candidate segment IDs and structure terms rather than page-1 thumbnails only.
• Derived field_structure_asset_register_top*_draft_*.csv/.html files when top candidates need to be exposed as draft register rows with source-page, geometry, and reviewer-decision traceability.
• Derived field_structure_product_manifest_*.json/.html files when product teams need a stable file catalog, join-key contract, validation status, and promotion gate for a field-structure package.
• Derived field_structure_product_*.sqlite packages when downstream tools need queryable views across the register, evidence, targeted pages, geometry, segments, appurtenances, and source documents.

For column meanings and product usage, read references/product-contract.md.

Join Order

1. Resolve field leases and area/block anchors from deepqual/mv_deep_water_field_leases.bin.
2. Join direct structures from platstruc, permstruc, FMP, and MCP.
3. Join pipeline-map docs and decom pipeline rows by lease or area/block.
4. Use collected segment IDs to pull route/appurtenance rows from pipeloc.
5. Join scanned ROW docs by segment and scanned plan docs by lease.
6. Preserve source_table, join_key, and evidence_confidence in outputs.

Engineering Use

Use this bundle for screening and early engineering workflows:

• tieback and host-infrastructure discovery
• riser/appurtenance inventory from PPL_APURT_TYPE
• flowline and umbilical proxy discovery from decom endpoints/product codes
• FMP/MCP production measurement context
• decommissioning scope discovery
• document retrieval queues for maps, plans, and ROW files
• source-document term triage for flowline, jumper, riser, umbilical, manifold, PLET/FLET, platform, host, well, and subsea references
• OCR triage for image-only pipeline maps and scanned drawings
• field-level evidence filtering with boolean term flags such as has_jumper, has_umbilical, has_riser, has_plet, and has_flowline
• segment-level candidate screening with confidence tiers such as document_text_plus_appurtenance, document_text_plus_segment, and document_text_nonsegment
• prioritized source-PDF review queues for subsea architecture confirmation
• browser review packets for opening BSEE source PDFs and confirming candidate structures
• reviewer workbooks with explicit status, verified class, quantity, notes, and follow-up fields
• spatial screening layers for route/appurtenance context before source drawing confirmation
• source-PDF contact sheets for visual pre-review before filling the verified asset register
• targeted page-hit contact sheets to prioritize the source pages most likely to contain candidate structure evidence
• draft asset-register rows for product and engineering sessions, with proposed structure class, join keys, source links, targeted pages, geometry references, and blank verification fields
• product manifests that let downstream tools ingest the register, evidence, targeted pages, and geometry outputs without rediscovering file paths or join keys
• SQLite product views such as v_asset_product_readiness, v_engineering_review_queue, v_asset_segment_context, v_asset_appurtenance_summary, v_asset_source_documents, and v_asset_geometry_feature_summary
• SQLite-backed review batches that aggregate source documents, targeted pages, segment context, appurtenance summaries, geometry coverage, review focus, risk notes, and blank decision fields
• basis page queues that turn targeted page hits into source-page acceptance worklists for verified document/page decisions
• recommended basis page views and exports that reduce the first-pass review set to one page per candidate while preserving the human acceptance gate

Do not claim jumpers/risers/umbilicals are fully enumerated unless the evidence is present in appurtenances.csv, pipeline_segments.csv, or the scanned document queue/index.