fastdocparse 0.1.0__py3-none-any.whl

docextract/pdf_utils.py

@@ -0,0 +1,262 @@
+"""PDF utilities: render pages to images, base64 encoding, box coordinate transforms."""
+
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+import pymupdf  # PyMuPDF
+from PIL import Image
+
+# Rendering constants
+PDF_RENDER_DPI = 150
+
+
+def _safe_open_pdf(pdf_bytes: bytes) -> Optional["pymupdf.Document"]:
+    """pymupdf.open() raises pymupdf.FileDataError/EmptyFileError (both RuntimeError
+    subclasses, not ValueError) on corrupt or non-PDF bytes — a raw file upload gone
+    wrong is an expected, common failure mode here, not a programming error, so it
+    shouldn't propagate as an unhandled crash. Returns None on failure; callers treat
+    that the same as "no text found," which the rest of the pipeline already handles."""
+    try:
+        return pymupdf.open(stream=pdf_bytes, filetype="pdf")
+    except Exception:
+        return None
+
+
+@dataclass
+class PageImage:
+    """A rendered PDF page."""
+    index: int          # 0-based page index
+    png_bytes: bytes    # PNG image bytes
+    width: int          # image width in pixels
+    height: int         # image height in pixels
+
+
+def pdf_to_page_images(pdf_bytes: bytes, max_pages: int = 3, dpi: int = PDF_RENDER_DPI, max_dim: int = 1536) -> List[PageImage]:
+    """Render up to max_pages of a PDF to a PNG image at the given DPI.
+
+    Returns a list of PageImage in page order.
+    """
+    pages: List[PageImage] = []
+    doc = _safe_open_pdf(pdf_bytes)
+    if doc is None:
+        return pages
+    try:
+        zoom = dpi / 72.0  # 72 DPI is the PDF default
+        matrix = pymupdf.Matrix(zoom, zoom)
+        for i in range(min(len(doc), max_pages)):
+            page = doc[i]
+            pix = page.get_pixmap(matrix=matrix, alpha=False)
+
+            # Convert to PIL Image for resizing
+            img = Image.open(io.BytesIO(pix.tobytes("png")))
+
+            # Resize to max_dim for better OCR fidelity
+            if img.width > max_dim or img.height > max_dim:
+                ratio = min(max_dim / img.width, max_dim / img.height)
+                new_size = (int(img.width * ratio), int(img.height * ratio))
+                img = img.resize(new_size, Image.Resampling.LANCZOS)
+            
+            # Convert back to bytes
+            buf = io.BytesIO()
+            img.save(buf, format="PNG")
+            png = buf.getvalue()
+            
+            pages.append(
+                PageImage(index=i, png_bytes=png, width=img.width, height=img.height)
+            )
+    finally:
+        doc.close()
+    return pages
+
+
+def image_bytes_to_page_image(img_bytes: bytes) -> PageImage:
+    """Convert image bytes (PNG/JPG) to a PageImage.
+
+    The image is loaded, resized for faster processing, and re-encoded as PNG.
+    """
+    img = Image.open(io.BytesIO(img_bytes))
+    # Convert to RGB if necessary (for JPEGs with transparency, etc.)
+    if img.mode != "RGB":
+        img = img.convert("RGB")
+    
+    # Resize to max 1536x1536 for better OCR fidelity
+    max_dim = 1536
+    if img.width > max_dim or img.height > max_dim:
+        ratio = min(max_dim / img.width, max_dim / img.height)
+        new_size = (int(img.width * ratio), int(img.height * ratio))
+        img = img.resize(new_size, Image.Resampling.LANCZOS)
+    
+    buf = io.BytesIO()
+    img.save(buf, format="PNG")
+    return PageImage(index=0, png_bytes=buf.getvalue(), width=img.width, height=img.height)
+
+
+def _grid_to_markdown(grid: List[List[str]]) -> str:
+    """Convert a 2D table array into a clean Markdown table string."""
+    if not grid or not grid[0]:
+        return ""
+    header = [str(c or "").strip().replace("\n", " ") for c in grid[0]]
+    if not any(header):
+        return ""
+    lines = ["| " + " | ".join(header) + " |", "| " + " | ".join(["---"] * len(header)) + " |"]
+    for row in grid[1:]:
+        row_cells = [str(c or "").strip().replace("\n", " ") for c in row]
+        if not any(row_cells):
+            continue
+        while len(row_cells) < len(header):
+            row_cells.append("")
+        lines.append("| " + " | ".join(row_cells[:len(header)]) + " |")
+    return "\n".join(lines)
+
+
+def _bbox_overlaps(b1: Tuple[float, float, float, float], b2: Tuple[float, float, float, float], thresh: float = 0.5) -> bool:
+    """Check if block b1 overlaps significantly with table bbox b2."""
+    x0 = max(b1[0], b2[0])
+    y0 = max(b1[1], b2[1])
+    x1 = min(b1[2], b2[2])
+    y1 = min(b1[3], b2[3])
+    if x1 <= x0 or y1 <= y0:
+        return False
+    inter_area = (x1 - x0) * (y1 - y0)
+    b1_area = (b1[2] - b1[0]) * (b1[3] - b1[1])
+    return (inter_area / b1_area) > thresh if b1_area > 0 else False
+
+
+def extract_layout_markdown_from_pdf(pdf_bytes: bytes, max_pages: int = 15, structured_mode: bool = False) -> str:
+    """Phase 1 Engine: Extract digital PDF into layout-preserved Markdown text."""
+    doc = _safe_open_pdf(pdf_bytes)
+    pages_md: List[str] = []
+    if doc is None:
+        return ""
+    try:
+        for i in range(min(len(doc), max_pages)):
+            page = doc[i]
+            
+            # 1. Extract tables
+            table_bboxes: List[Tuple[float, float, float, float]] = []
+            table_markdowns: List[Tuple[float, str]] = []  # (y0, markdown_str)
+            try:
+                tabs = page.find_tables()
+                for tab in tabs.tables:
+                    grid = tab.extract()
+                    md = _grid_to_markdown(grid)
+                    if md:
+                        table_bboxes.append(tab.bbox)
+                        table_markdowns.append((tab.bbox[1], md))
+            except Exception:
+                pass
+
+            # 2. Extract text blocks outside tables
+            blocks = page.get_text("blocks")
+            non_table_blocks: List[Tuple[float, float, str]] = []  # (y0, x0, text)
+            for b in blocks:
+                if len(b) >= 5 and b[4].strip():
+                    bbox = (b[0], b[1], b[2], b[3])
+                    # Check overlap with any extracted table
+                    if not any(_bbox_overlaps(bbox, tb) for tb in table_bboxes):
+                        if structured_mode:
+                            non_table_blocks.append((b[1], b[0], f"[X:{int(b[0])}] {b[4].strip()}"))
+                        else:
+                            non_table_blocks.append((b[1], b[0], b[4].strip()))
+
+            # 3. Merge blocks & tables spatially top-to-bottom
+            all_elements: List[Tuple[float, float, str]] = []
+            for y0, x0, text in non_table_blocks:
+                all_elements.append((y0, x0, text))
+            for y0, md in table_markdowns:
+                all_elements.append((y0, 0.0, f"\n{md}\n"))
+
+            # Sort by Y position (top-to-bottom) then X position
+            all_elements.sort(key=lambda elem: (round(elem[0] / 15), elem[1]))
+
+            page_content = "\n\n".join(text for _, _, text in all_elements)
+            if page_content.strip():
+                pages_md.append(f"--- PAGE {i + 1} ---\n{page_content}")
+    finally:
+        doc.close()
+    return "\n\n".join(pages_md)
+
+
+def extract_text_from_pdf(pdf_bytes: bytes, max_pages: int = 15, structured_mode: bool = False) -> str:
+    """Extract layout-preserved markdown text from a digital PDF."""
+    layout_md = extract_layout_markdown_from_pdf(pdf_bytes, max_pages=max_pages, structured_mode=structured_mode)
+    if layout_md.strip():
+        return layout_md
+    
+    # Fallback to plain text
+    doc = _safe_open_pdf(pdf_bytes)
+    texts: List[str] = []
+    if doc is None:
+        return ""
+    try:
+        for i in range(min(len(doc), max_pages)):
+            page_text = doc[i].get_text("text")
+            if page_text.strip():
+                texts.append(f"--- Page {i + 1} ---\n{page_text}")
+    finally:
+        doc.close()
+    return "\n\n".join(texts)
+
+
+def is_digital_pdf(pdf_bytes: bytes, min_chars: int = 80) -> bool:
+    """Return True if the PDF has a readable text layer (i.e. is not a scan)."""
+    doc = _safe_open_pdf(pdf_bytes)
+    if doc is None:
+        return False
+    total_chars = 0
+    try:
+        for i in range(min(len(doc), 3)):
+            total_chars += len(doc[i].get_text("text").strip())
+            if total_chars >= min_chars:
+                return True
+    finally:
+        doc.close()
+    return False
+
+
+def chunk_document_text(text: str, max_tokens: int = 3000) -> List[str]:
+    """
+    Split document text into chunks based on page delimiters.
+    Approximates tokens via character count (4 chars ~ 1 token).
+    """
+    max_chars = max_tokens * 4
+    pages = text.split("--- PAGE ")
+    # The first element might be empty or preamble before the first page.
+    # We need to re-attach the delimiter for the rest.
+    page_texts = []
+    for i, p in enumerate(pages):
+        if not p.strip():
+            continue
+        prefix = "--- PAGE " if i > 0 else ""
+        page_texts.append(prefix + p)
+
+    chunks = []
+    current_chunk = ""
+
+    for pt in page_texts:
+        if len(current_chunk) + len(pt) > max_chars and current_chunk:
+            chunks.append(current_chunk.strip())
+            current_chunk = pt
+        else:
+            current_chunk += "\n\n" + pt if current_chunk else pt
+
+    if current_chunk:
+        chunks.append(current_chunk.strip())
+
+    # A single page (or a document with no "--- PAGE" delimiters at all) can itself
+    # exceed max_chars — the loop above only splits *between* pages, so that chunk
+    # would otherwise sail past the configured budget by an arbitrary amount. Hard-split
+    # anything still oversized; a mid-sentence cut here is far better than silently
+    # blowing an LLM's context window.
+    final_chunks = []
+    for chunk in chunks:
+        if len(chunk) <= max_chars:
+            final_chunks.append(chunk)
+        else:
+            for start in range(0, len(chunk), max_chars):
+                final_chunks.append(chunk[start:start + max_chars])
+
+    return final_chunks

docextract/prompt_compiler.py

@@ -0,0 +1,86 @@
+"""Prompt compiler for generating dynamic Chain-of-Thought prompts from schemas."""
+
+import json
+from typing import Any, Dict
+from .schema import Schema, Field
+
+def _generate_json_structure(fields: list[Field]) -> Dict[str, Any]:
+    """Generate a sample JSON structure representing the schema."""
+    structure = {}
+    for f in fields:
+        if f.type == "list" and f.sub_fields:
+            structure[f.name] = [_generate_json_structure(f.sub_fields)]
+        else:
+            structure[f.name] = f"<{f.type}> or null"
+    return structure
+
+def compile_prompt(schema: Schema) -> str:
+    """Compile a deterministic CoT prompt from a Pydantic schema."""
+    
+    # Generate reasoning steps
+    reasoning_steps = []
+    for f in schema.fields:
+        if f.type == "list" and f.sub_fields:
+            sub_names = ", ".join([sub.name for sub in f.sub_fields])
+            reasoning_steps.append(f"• What are the items for '{f.name}'? Identify {sub_names}.")
+        else:
+            reasoning_steps.append(f"• What is the '{f.name}'? {f.description}")
+
+    # Generate extraction guide
+    extraction_guide = []
+    idx = 1
+    for f in schema.fields:
+        if f.type == "list" and f.sub_fields:
+            sub_desc = ", ".join([f"{sub.name}: {sub.description}" for sub in f.sub_fields])
+            extraction_guide.append(f"{idx}. {f.name}: List of items containing ({sub_desc}).")
+        else:
+            extraction_guide.append(f"{idx}. {f.name}: {f.description}")
+        idx += 1
+        
+    json_structure = _generate_json_structure(schema.fields)
+    json_str = json.dumps(json_structure, indent=2)
+
+    examples_text = ""
+    json_step_num = 3
+    if schema.examples:
+        examples_text = "\n═══════════════════════════════════════════════\nSTEP 3 — EXAMPLES\n═══════════════════════════════════════════════\n"
+        for i, (doc_snippet, expected_json) in enumerate(schema.examples, 1):
+            examples_text += f"Example {i}:\nDocument Snippet:\n{doc_snippet}\n\nExpected Output:\n```json\n{json.dumps(expected_json, indent=2)}\n```\n\n"
+        json_step_num = 4
+
+
+    prompt = f"""You are an expert document analyst.
+
+Below is text extracted directly from a document (via layout-aware text parsing or OCR).
+Analyze the document step by step and extract the requested fields for schema: {schema.name}.
+
+═══════════════════════════════════════════════
+STEP 1 — DOCUMENT REASONING (think out loud)
+═══════════════════════════════════════════════
+{chr(10).join(reasoning_steps)}
+
+═══════════════════════════════════════════════
+STEP 2 — FIELD EXTRACTION GUIDE
+═══════════════════════════════════════════════
+{chr(10).join(extraction_guide)}
+
+{examples_text}═══════════════════════════════════════════════
+STEP {json_step_num} — JSON OUTPUT
+═══════════════════════════════════════════════
+Output ONLY a valid JSON object in this exact structure:
+
+```json
+{json_str}
+```
+
+RULES:
+- For addresses or multiline text: NEVER leave null if text is visible in the document. Combine all lines into a single string.
+- Numbers only for numeric fields. No symbols/commas.
+- If a field is missing, set to null.
+
+══════════════════════
+DOCUMENT TEXT:
+══════════════════════
+{{document_text}}
+"""
+    return prompt

docextract/result.py

@@ -0,0 +1,42 @@
+"""Typed view of DocumentParser.extract()'s output.
+
+extract() itself keeps returning a plain dict — that's what the CLI needs for
+zero-friction json.dumps(), and changing it would break every existing caller and
+test. This model is an opt-in convenience for callers who want attribute access
+and validation instead of raw dict indexing:
+
+    result = parser.extract(document_bytes, schema)
+    typed = ExtractionResult.from_raw(result)
+    typed.fields["invoice_number"].value
+"""
+
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel
+
+
+class FieldResult(BaseModel):
+    value: Any
+    confidence: str
+    flags: List[str]
+
+
+class ExtractionMeta(BaseModel):
+    truncated: bool
+    truncation_reason: Optional[str] = None
+
+
+class ExtractionResult(BaseModel):
+    meta: ExtractionMeta
+    fields: Dict[str, FieldResult]
+
+    @classmethod
+    def from_raw(cls, raw: Dict[str, Any]) -> "ExtractionResult":
+        """Build a typed result from the dict returned by DocumentParser.extract()."""
+        raw = dict(raw)
+        meta = raw.pop("_meta", None)
+        if meta is None:
+            raise ValueError(
+                "Missing '_meta' key — expected the dict returned by DocumentParser.extract()."
+            )
+        return cls(meta=ExtractionMeta(**meta), fields={k: FieldResult(**v) for k, v in raw.items()})

docextract/schema.py

@@ -0,0 +1,94 @@
+"""Schema definitions for document extraction."""
+
+import json
+from pathlib import Path
+from typing import List, Optional, Tuple, Dict, Any, Union
+from pydantic import BaseModel, field_validator
+
+
+class Field(BaseModel):
+    """Defines a single field to extract from a document."""
+    name: str
+    description: str
+    type: str = "text"  # "text", "number", "date", "currency", "list"
+    required: bool = False
+    pattern: Optional[str] = None  # regex the extracted string value must fully match, e.g. HS/container codes
+    enum: Optional[List[str]] = None  # allowed values, e.g. shipment status, incoterms
+    sub_fields: Optional[List['Field']] = None
+
+    @property
+    def is_numeric(self) -> bool:
+        """True for field types that should be grounded/merged by parsed numeric value
+        rather than exact string match (see grounding.check_substring's numeric= flag)."""
+        return self.type in ("number", "currency")
+
+    @property
+    def is_date(self) -> bool:
+        """True for date fields — grounded by parsed calendar date rather than exact
+        string match (see grounding.check_substring's date= flag), since a normalized
+        "2021-04-22" won't literally appear in a source document that says "22Apr2021"."""
+        return self.type == "date"
+
+
+class Schema(BaseModel):
+    """Defines a complete document schema."""
+    name: str = "DocumentSchema"
+    fields: List[Field]
+    examples: Optional[List[Tuple[str, Dict[str, Any]]]] = None
+
+    @field_validator('fields')
+    @classmethod
+    def validate_field_names(cls, v):
+        if any(f.name == "_meta" for f in v):
+            raise ValueError(
+                "'_meta' is a reserved field name (used for truncation metadata in the "
+                "extraction result) and cannot be used as a schema field name."
+            )
+        return v
+
+    @field_validator('examples')
+    @classmethod
+    def validate_examples(cls, v):
+        if v is not None:
+            for ex in v:
+                if not isinstance(ex, tuple) or len(ex) != 2:
+                    raise ValueError("Each example must be a tuple of (document_snippet, expected_json)")
+                if not isinstance(ex[0], str) or not isinstance(ex[1], dict):
+                    raise ValueError("Each example must be a tuple of (str, dict)")
+        return v
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "Schema":
+        """Build a Schema from a plain dict (as loaded from JSON/YAML) — no Python code needed."""
+        return cls.model_validate(data)
+
+    @classmethod
+    def from_json(cls, path: Union[str, Path]) -> "Schema":
+        """Load a Schema from a .json file."""
+        with open(path, "r") as f:
+            return cls.from_dict(json.load(f))
+
+    @classmethod
+    def from_yaml(cls, path: Union[str, Path]) -> "Schema":
+        """Load a Schema from a .yaml/.yml file."""
+        import yaml  # optional dependency; only needed for this path
+
+        with open(path, "r") as f:
+            return cls.from_dict(yaml.safe_load(f))
+
+    @classmethod
+    def from_file(cls, path: Union[str, Path]) -> "Schema":
+        """Load a Schema from a .json or .yaml/.yml file, dispatching on extension."""
+        path = Path(path)
+        suffix = path.suffix.lower()
+        if suffix in (".yaml", ".yml"):
+            return cls.from_yaml(path)
+        if suffix == ".json":
+            return cls.from_json(path)
+        raise ValueError(f"Unsupported schema file extension {suffix!r} (expected .json, .yaml, or .yml)")
+
+    def get_field(self, name: str) -> Optional[Field]:
+        for f in self.fields:
+            if f.name == name:
+                return f
+        return None

docextract/schema_compiler.py

@@ -0,0 +1,68 @@
+"""Compile a plain-English description of what to extract into a Schema, using the LLM.
+
+Lets a non-technical user describe fields in their own words instead of writing JSON:
+
+    "I want the bill of lading number (starts with BL-), the container number,
+     the shipment status which is one of in_transit, delivered, or customs_hold,
+     and the destination country. Bill of lading and destination are required."
+
+The LLM proposes field names/types/constraints; the caller should review the
+result (or the saved schema file) before relying on it for real extraction —
+a hallucinated schema silently corrupts every later run, so this is meant as
+an authoring aid with a human in the loop, not a fully implicit step.
+"""
+
+from typing import Any, Dict
+
+from .json_repair import parse_json_from_llm
+from .llm_client import LLMClient
+from .schema import Schema
+
+SCHEMA_GEN_PROMPT = """You are a data schema designer. A user described, in plain language, what \
+information they want extracted from a document. Convert their description into a JSON schema.
+
+Output ONLY a valid JSON object with this exact shape:
+{{
+  "name": "<short PascalCase schema name>",
+  "fields": [
+    {{
+      "name": "<snake_case field name>",
+      "description": "<clear description of what to extract, written for a document-extraction assistant to follow>",
+      "type": "text" | "number" | "date" | "currency" | "list",
+      "required": true | false,
+      "pattern": "<regex the value must fully match, or null if the user didn't mention a specific format>",
+      "enum": ["<allowed value>", "..."] or null,
+      "sub_fields": [ {{ "name": "...", "description": "..." }} ]
+    }}
+  ]
+}}
+
+Rules:
+- Use "list" + "sub_fields" only for repeating/tabular data (e.g. line items, containers). Every other field omits "sub_fields" (null).
+- Set "required": true only if the description implies the field is essential/mandatory.
+- Set "pattern" only when the description mentions a specific code/ID format (e.g. "starts with BL-", "6 digits"). Otherwise null.
+- Set "enum" only when the description lists a fixed set of allowed values. Otherwise null.
+- Field names must be snake_case, no spaces, no punctuation.
+- Do not invent fields the user didn't ask for.
+
+User's description:
+\"\"\"
+{description}
+\"\"\"
+
+Output ONLY the JSON object, nothing else."""
+
+
+def compile_schema_from_description(description: str, client: LLMClient) -> Schema:
+    """Turn a natural-language description into a Schema via one LLM call."""
+    prompt = SCHEMA_GEN_PROMPT.format(description=description)
+    raw_response = client.complete(prompt)
+    data: Dict[str, Any] = parse_json_from_llm(raw_response)
+
+    if not data or not data.get("fields"):
+        raise ValueError(
+            "Could not turn that description into a schema. Try listing the specific fields you want, "
+            "e.g. 'invoice number, total price, and a list of line items with product name and quantity'."
+        )
+
+    return Schema.from_dict(data)

docextract/schemas/invoice.json

@@ -0,0 +1,73 @@
+{
+  "name": "Invoice",
+  "fields": [
+    {
+      "name": "invoice_number",
+      "description": "Invoice No / Bill No / Reference number.",
+      "required": true
+    },
+    {
+      "name": "invoice_date",
+      "description": "YYYY-MM-DD format.",
+      "type": "date"
+    },
+    {
+      "name": "exporter_name",
+      "description": "Full name of the seller/exporter/supplier issuing the invoice. Look for company name at the top left, letterhead, or footer signature block."
+    },
+    {
+      "name": "exporter_address",
+      "description": "Complete address of the exporter (combine all address lines with comma separators)."
+    },
+    {
+      "name": "importer_name",
+      "description": "Full name of the buyer/consignee/importer. Look for 'Consignee', 'Bill To', 'Buyer', 'Importer', 'Ship To'."
+    },
+    {
+      "name": "importer_address",
+      "description": "Complete address of the importer/consignee (combine all address lines)."
+    },
+    {
+      "name": "currency",
+      "description": "3-letter ISO code (USD, EUR, GBP, INR, etc.).",
+      "enum": ["USD", "EUR", "GBP", "INR", "JPY", "CNY"]
+    },
+    {
+      "name": "total_price",
+      "description": "Final grand total invoice amount due (numeric only).",
+      "type": "number",
+      "required": true
+    },
+    {
+      "name": "line_items",
+      "description": "Every product row.",
+      "type": "list",
+      "sub_fields": [
+        { "name": "product_name", "description": "Name of the product" },
+        { "name": "product_description", "description": "Description of the product" },
+        { "name": "hs_code", "description": "HSN/HS code" },
+        { "name": "unit_price", "description": "Price per unit" },
+        { "name": "quantity", "description": "Quantity" }
+      ]
+    }
+  ],
+  "examples": [
+    [
+      "GLOBAL EXPORTS INC.\n123 Market St, San Francisco, CA 94105, USA\n\nBILL TO:\nAcme Corp\n456 Industrial Way, Seattle, WA 98101\n\nInvoice: INV-9011\nDate: 04/15/2023\n\nItem\tQty\tPrice\tTotal\nWidget A\t10\t$5.00\t$50.00\nSuper Widget\t2\t$25.00\t$50.00\n\nGrand Total: USD 100.00",
+      {
+        "invoice_number": "INV-9011",
+        "invoice_date": "2023-04-15",
+        "exporter_name": "GLOBAL EXPORTS INC.",
+        "exporter_address": "123 Market St, San Francisco, CA 94105, USA",
+        "importer_name": "Acme Corp",
+        "importer_address": "456 Industrial Way, Seattle, WA 98101",
+        "currency": "USD",
+        "total_price": 100.0,
+        "line_items": [
+          { "product_name": "Widget A", "product_description": "Widget A", "hs_code": null, "unit_price": 5.0, "quantity": 10 },
+          { "product_name": "Super Widget", "product_description": "Super Widget", "hs_code": null, "unit_price": 25.0, "quantity": 2 }
+        ]
+      }
+    ]
+  ]
+}

docextract/schemas/shipment_manifest.json

@@ -0,0 +1,40 @@
+{
+  "name": "ShipmentManifest",
+  "fields": [
+    {
+      "name": "bill_of_lading",
+      "description": "Bill of Lading (B/L) number identifying the shipment.",
+      "required": true,
+      "pattern": "BL-\\d{4,}"
+    },
+    {
+      "name": "container_number",
+      "description": "Shipping container number, ISO 6346 format (4 letters + 7 digits).",
+      "pattern": "[A-Z]{4}\\d{7}"
+    },
+    {
+      "name": "hs_code",
+      "description": "Harmonized System code for the primary goods.",
+      "pattern": "\\d{6,10}"
+    },
+    {
+      "name": "shipment_status",
+      "description": "Current status of the shipment.",
+      "enum": ["in_transit", "delivered", "customs_hold", "delayed"]
+    },
+    {
+      "name": "origin_port",
+      "description": "Port or place of loading."
+    },
+    {
+      "name": "destination_country",
+      "description": "Country of final destination.",
+      "required": true
+    },
+    {
+      "name": "gross_weight_kg",
+      "description": "Total gross weight in kilograms (numeric only).",
+      "type": "number"
+    }
+  ]
+}