parse-bench 1.0.0__py3-none-any.whl

parse_bench/test_cases/parse_rule_schemas.py

@@ -0,0 +1,1071 @@
+"""Pydantic schemas for parse rule payloads.
+
+The parse rule pipeline uses loosely typed dictionaries today. These models add
+structured validation while keeping compatibility with legacy payloads via
+`extra="allow"`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+from parse_bench.evaluation.metrics.parse.test_types import TestType
+
+
+class DictCompatPydanticModel(BaseModel):
+    """Base model with a light dict-like `get` interface."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    def get(self, key: str, default: Any = None) -> Any:
+        # O(1) lookup: check field names, extra fields, then aliases
+        cls_fields = type(self).model_fields
+        if key in cls_fields or (self.model_extra and key in self.model_extra):
+            return getattr(self, key)
+        # Check aliases (e.g. "_csv_path" → csv_path)
+        for field_name, field_info in cls_fields.items():
+            if field_info.alias == key:
+                return getattr(self, field_name)
+        return default
+
+
+class ParseRuleBase(DictCompatPydanticModel):
+    """Base schema shared by all typed parse rules.
+
+    `id` is intentionally optional so existing datasets without rule ids keep
+    loading cleanly while new ids can be added incrementally.
+    """
+
+    type: str
+    id: str | None = Field(
+        default=None,
+        description="Optional stable identifier for the rule",
+    )
+    page: int | None = Field(default=None)
+    max_diffs: int | float = Field(default=0, description="Allowed Levenshtein distance")
+    tags: list[str] = Field(default_factory=list)
+    layout_id: str | None = Field(
+        default=None,
+        description="Primary linked layout element id for visual grounding.",
+    )
+    layout_ids: list[str] = Field(
+        default_factory=list,
+        description="All linked layout element ids for visual grounding.",
+    )
+    layout_bindings: dict[str, str | list[str]] = Field(
+        default_factory=dict,
+        description="Optional role-based grounding map (e.g. before/after for order rules).",
+    )
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+
+    @model_validator(mode="after")
+    def normalize_layout_grounding(self) -> ParseRuleBase:
+        """Normalize grounding fields into a consistent, deduped representation."""
+
+        ordered_ids: list[str] = []
+        if self.layout_id:
+            ordered_ids.append(self.layout_id)
+
+        if self.layout_ids:
+            ordered_ids.extend(layout_id for layout_id in self.layout_ids if isinstance(layout_id, str))
+
+        if self.layout_bindings:
+            for value in self.layout_bindings.values():
+                if isinstance(value, str):
+                    ordered_ids.append(value)
+                elif isinstance(value, list):
+                    ordered_ids.extend(v for v in value if isinstance(v, str))
+
+        deduped_ids: list[str] = []
+        seen: set[str] = set()
+        for layout_id in ordered_ids:
+            if layout_id and layout_id not in seen:
+                seen.add(layout_id)
+                deduped_ids.append(layout_id)
+
+        self.layout_ids = deduped_ids
+        if self.layout_id is None and self.layout_ids:
+            self.layout_id = self.layout_ids[0]
+        return self
+
+
+class _HasAnchorCells(BaseModel):
+    """Shared table anchor cells field."""
+
+    table_anchor_cells: list[Any] | None = Field(default_factory=list)
+    model_config = ConfigDict(extra="allow")
+
+    @field_validator("table_anchor_cells", mode="before")
+    @classmethod
+    def _coerce_null_to_list(cls, v: Any) -> list[Any]:
+        return v if v is not None else []
+
+
+class ParsePresenceRule(ParseRuleBase):
+    """Schema for `present` and `absent` rules."""
+
+    type: Literal[TestType.PRESENT.value, TestType.ABSENT.value]
+    text: str = ""
+    keep_formatting_text_normalisation: bool = False
+    case_sensitive: bool = True
+    first_n: int | None = None
+    last_n: int | None = None
+    count: int | None = None
+
+
+class _SentenceBagRule(ParseRuleBase):
+    bag_of_sentence: dict[str, int] = Field(default_factory=dict)
+
+
+class ParseUnexpectedSentenceRule(_SentenceBagRule):
+    type: Literal[TestType.UNEXPECTED_SENTENCE.value]
+
+
+class ParseUnexpectedSentencePercentRule(_SentenceBagRule):
+    type: Literal[TestType.UNEXPECTED_SENTENCE_PERCENT.value]
+    original_md: str | None = Field(
+        default=None,
+        description=(
+            "Original ground-truth markdown; when provided, sentences found in this text are not counted as unexpected."
+        ),
+    )
+
+
+class ParseTooManySentenceOccurrenceRule(_SentenceBagRule):
+    type: Literal[TestType.TOO_MANY_SENTENCE_OCCURENCE.value]
+
+
+class ParseTooManySentenceOccurrencePercentRule(_SentenceBagRule):
+    type: Literal[TestType.TOO_MANY_SENTENCE_OCCURENCE_PERCENT.value]
+
+
+class ParseMissingSentenceRule(_SentenceBagRule):
+    type: Literal[TestType.MISSING_SENTENCE.value]
+
+
+class ParseMissingSentencePercentRule(_SentenceBagRule):
+    type: Literal[TestType.MISSING_SENTENCE_PERCENT.value]
+
+
+class ParseMissingSpecificSentenceRule(ParseRuleBase):
+    """Check that a specific sentence is present (fail if missing)."""
+
+    type: Literal[TestType.MISSING_SPECIFIC_SENTENCE.value]
+    sentence: str = Field(description="The specific sentence to look for.")
+
+
+class _WordBagRule(ParseRuleBase):
+    bag_of_word: dict[str, int] = Field(default_factory=dict)
+
+
+class ParseUnexpectedWordRule(_WordBagRule):
+    type: Literal[TestType.UNEXPECTED_WORD.value]
+
+
+class ParseUnexpectedWordPercentRule(_WordBagRule):
+    type: Literal[TestType.UNEXPECTED_WORD_PERCENT.value]
+
+
+class ParseTooManyWordOccurrenceRule(_WordBagRule):
+    type: Literal[TestType.TOO_MANY_WORD_OCCURENCE.value]
+
+
+class ParseTooManyWordOccurrencePercentRule(_WordBagRule):
+    type: Literal[TestType.TOO_MANY_WORD_OCCURENCE_PERCENT.value]
+
+
+class ParseMissingWordRule(_WordBagRule):
+    type: Literal[TestType.MISSING_WORD.value]
+
+
+class ParseMissingWordPercentRule(_WordBagRule):
+    type: Literal[TestType.MISSING_WORD_PERCENT.value]
+
+
+class ParseMissingSpecificWordRule(ParseRuleBase):
+    """Check that a specific word is present (fail if missing)."""
+
+    type: Literal[TestType.MISSING_SPECIFIC_WORD.value]
+    word: str = Field(description="The specific word to look for.")
+
+
+class ParseExtraContentRule(_SentenceBagRule):
+    type: Literal[TestType.EXTRA_CONTENT.value]
+
+
+class ParseBaselineRule(ParseRuleBase):
+    type: Literal[TestType.BASELINE.value]
+    max_length: int | None = None
+    max_length_skips_image_alt_tags: bool = False
+    max_repeats: int = 30
+    check_disallowed_characters: bool = True
+
+
+class ParseOrderRule(ParseRuleBase):
+    type: Literal[TestType.ORDER.value]
+    before: str = ""
+    after: str = ""
+    keep_formatting_text_normalisation: bool = False
+
+    @model_validator(mode="after")
+    def validate_layout_bindings(self) -> ParseOrderRule:
+        """Validate role-based layout grounding for order rules."""
+
+        if not self.layout_bindings:
+            return self
+
+        allowed_roles = {"before", "after"}
+        invalid_roles = sorted(role for role in self.layout_bindings if role not in allowed_roles)
+        if invalid_roles:
+            invalid = ", ".join(invalid_roles)
+            raise ValueError(f"Order rule layout_bindings only supports roles 'before' and 'after'; got: {invalid}")
+
+        for role, value in self.layout_bindings.items():
+            if isinstance(value, list):
+                raise ValueError(f"Order rule layout_bindings.{role} must be a single layout id string")
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f"Order rule layout_bindings.{role} must be a non-empty layout id string")
+
+        before_layout = self.layout_bindings.get("before")
+        if isinstance(before_layout, str):
+            # Some legacy datasets contain stale `layout_id` values on order rules.
+            # Canonicalize to the role-specific binding instead of failing load.
+            if self.layout_id != before_layout:
+                self.layout_id = before_layout
+
+            if before_layout in self.layout_ids:
+                ordered_ids = [layout_id for layout_id in self.layout_ids if layout_id != before_layout]
+                self.layout_ids = [before_layout, *ordered_ids]
+            else:
+                self.layout_ids = [before_layout, *self.layout_ids]
+        return self
+
+
+class ParseTableRule(ParseRuleBase):
+    type: Literal[TestType.TABLE.value]
+    cell: str = ""
+    up: str | None = None
+    down: str | None = None
+    left: str | None = None
+    right: str | None = None
+    top_heading: str | None = None
+    left_heading: str | None = None
+    ignore_markdown_tables: bool = False
+
+
+class ParseTablesValuesRule(ParseRuleBase):
+    type: Literal[TestType.TABLES_VALUES.value]
+    table_variations: list[Any] | None = None
+    json_path: str | None = None
+    table_match_threshold: float = 0.8
+    table_values_match_threshold: float = 0.9
+    add_check_num_rows_test: bool = True
+    add_check_num_cols_test: bool = True
+
+
+class ParseTablesNumRowsRule(ParseRuleBase):
+    type: Literal[TestType.TABLES_NUM_ROWS.value]
+    expected_num_rows: int = 0
+    actual_num_rows: int | None = None
+
+
+class ParseTablesNumColsRule(ParseRuleBase):
+    type: Literal[TestType.TABLES_NUM_COLS.value]
+    expected_num_cols: int = 0
+    actual_num_cols: int | None = None
+
+
+class ParseTableMarkerCellsRule(ParseRuleBase):
+    """Require icon-like values to survive as cells in one parsed table."""
+
+    type: Literal[TestType.TABLE_MARKER_CELLS.value]
+    min_count: int = Field(default=2, ge=1)
+    min_distinct_rows: int = Field(default=2, ge=1)
+    min_distinct_columns: int = Field(default=1, ge=1)
+    marker_aliases: list[str] = Field(default_factory=list)
+    allow_repeated_ocr_glyphs: bool = True
+
+
+class ParseTableColspanRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_COLSPAN.value]
+    cell: str = ""
+    expected_colspan: int = 1
+
+
+class ParseTableRowspanRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_ROWSPAN.value]
+    cell: str = ""
+    expected_rowspan: int = 1
+
+
+class ParseTableSameRowRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_SAME_ROW.value]
+    cell_a: str = ""
+    cell_b: str = ""
+
+
+class ParseTableSameColumnRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_SAME_COLUMN.value]
+    cell_a: str = ""
+    cell_b: str = ""
+
+
+class ParseTableHeaderChainRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_HEADER_CHAIN.value]
+    data_cell: str = ""
+    column_headers: list[Any] = Field(default_factory=list)
+    row_headers: list[Any] = Field(default_factory=list)
+
+
+class ParseTableAdjacentUpRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_ADJACENT_UP.value]
+    anchor_cell: str = ""
+    expected_neighbor: str = ""
+
+
+class ParseTableAdjacentDownRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_ADJACENT_DOWN.value]
+    anchor_cell: str = ""
+    expected_neighbor: str = ""
+
+
+class ParseTableAdjacentLeftRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_ADJACENT_LEFT.value]
+    anchor_cell: str = ""
+    expected_neighbor: str = ""
+
+
+class ParseTableAdjacentRightRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_ADJACENT_RIGHT.value]
+    anchor_cell: str = ""
+    expected_neighbor: str = ""
+
+
+class ParseTableTopHeaderRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_TOP_HEADER.value]
+    data_cell: str = ""
+    expected_header: str = ""
+
+
+class ParseTableLeftHeaderRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_LEFT_HEADER.value]
+    data_cell: str = ""
+    expected_header: str = ""
+
+
+class ParseTableNoLeftRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_NO_LEFT.value]
+    cell: str = ""
+
+
+class ParseTableNoRightRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_NO_RIGHT.value]
+    cell: str = ""
+
+
+class ParseTableNoAboveRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_NO_ABOVE.value]
+    cell: str = ""
+
+
+class ParseTableNoBelowRule(ParseRuleBase, _HasAnchorCells):
+    type: Literal[TestType.TABLE_NO_BELOW.value]
+    cell: str = ""
+
+
+class ParseChartDataPointRule(ParseRuleBase):
+    type: Literal[TestType.CHART_DATA_POINT.value]
+    value: str | int | float | None = None
+    labels: list[str] = Field(default_factory=list)
+    normalize_numbers: bool = True
+    relative_tolerance: float = 0.01
+
+
+class ParseChartDataArrayLabelsRule(ParseRuleBase):
+    type: Literal[TestType.CHART_DATA_ARRAY_LABELS.value]
+    data: list[Any] = Field(default_factory=list)
+    x_axis_shuffle: bool = False
+    transposed: bool = False
+    csv_path: str | None = Field(default=None, alias="_csv_path")
+
+
+class ParseChartDataArrayDataRule(ParseRuleBase):
+    type: Literal[TestType.CHART_DATA_ARRAY_DATA.value]
+    data: list[Any] = Field(default_factory=list)
+    x_axis_shuffle: bool = False
+    y_axis_shuffle: bool = False
+    normalize_numbers: bool = True
+    transposed: bool = False
+    csv_path: str | None = Field(default=None, alias="_csv_path")
+
+
+class ParseFormFieldRule(ParseRuleBase):
+    """Schema for `form_field` rules.
+
+    Locates a labeled field in the parsed markdown/HTML and checks its value.
+    Used for benchmarking form (key-value, checkbox, signature) extraction.
+
+    `label` may be a list of strings for table-like form cells where one
+    value is identified by multiple visible keys (for example a row label
+    plus a column label). Label-list order is not significant.
+
+    For repeated yes/no checkbox groups, use a label list containing the
+    question and option text, e.g. `["Multistage cement?", "No"]`, with
+    `value_type: "checkbox"` and `value: true` or `false`.
+
+    For repeated row fields such as open-hole intervals, use the existing
+    row-index form, e.g. `"FROM (row 1)"` and `"TO (row 1)"`. This works for
+    markdown tables and flattened parser output such as `FROM none TO RRC`.
+
+    `label_max_diffs` may be a number or a list aligned with `label` to allow
+    limited OCR/handwriting variation in key text after normalization.
+    `value_max_diffs` is the equivalent tolerance for the extracted value.
+
+    `value` may be a list of strings to declare acceptable alternatives for
+    genuinely ambiguous fields (e.g. illegible handwriting). The evaluator
+    passes if the parsed value matches *any* alternative. Use sparingly —
+    most rules should be a single string. List form is only for value_type
+    "text" and "signature".
+    """
+
+    type: Literal[TestType.FORM_FIELD.value]
+    label: str | list[str] = ""
+    label_max_diffs: int | float | list[int | float] = 0
+    value_max_diffs: int | float = 0
+    value: str | bool | list[str] = ""
+    value_type: Literal["text", "checkbox", "signature"] = "text"
+
+
+class ParseFormattingRule(ParseRuleBase):
+    type: Literal[
+        TestType.IS_UNDERLINE.value,
+        TestType.IS_NOT_UNDERLINE.value,
+        TestType.IS_BOLD.value,
+        TestType.IS_NOT_BOLD.value,
+        TestType.IS_STRIKEOUT.value,
+        TestType.IS_NOT_STRIKEOUT.value,
+        TestType.IS_ITALIC.value,
+        TestType.IS_NOT_ITALIC.value,
+        TestType.IS_MARK.value,
+        TestType.IS_NOT_MARK.value,
+        TestType.IS_SUP.value,
+        TestType.IS_NOT_SUP.value,
+        TestType.IS_SUB.value,
+        TestType.IS_NOT_SUB.value,
+    ]
+    text: str = ""
+
+
+class ParseMarkColorRule(ParseRuleBase):
+    """Schema for `mark_color` rules.
+
+    Validates that text is wrapped in a ``<mark>`` tag AND that the tag
+    contains the expected color string in one of its attributes
+    (e.g. ``style="background-color: yellow"``, ``background="yellow"``,
+    ``backgroundColor="yellow"``).
+    """
+
+    type: Literal[TestType.MARK_COLOR.value]
+    text: str = ""
+    color: str = ""
+
+
+class ParseAbsentUnlessStrikeoutRule(ParseRuleBase):
+    """Schema for `absent_unless_strikeout` rules.
+
+    For text deleted in a revision (struck through in the source document):
+    the parse should either omit the text entirely, or keep it explicitly
+    marked as struck (``~~text~~``, ``<s>``, ``<del>``, ``<strike>`` or a
+    ``text-decoration: line-through`` style). The rule FAILS when the text
+    appears as regular, unmarked content — the failure mode where deleted
+    contract language becomes indistinguishable from current language.
+    """
+
+    type: Literal[TestType.ABSENT_UNLESS_STRIKEOUT.value]
+    text: str = ""
+
+
+class ParsePresentAsStrikeoutRule(ParseRuleBase):
+    """Schema for `present_as_strikeout` rules.
+
+    Stricter counterpart of `absent_unless_strikeout`: deleted (struck)
+    source text must be RETAINED in the output AND sit inside explicit
+    strikeout markup. Fails both when the text is dropped entirely and when
+    it appears only as plain content. Region-based like
+    `absent_unless_strikeout`, so wider-than-GT struck spans pass.
+    """
+
+    type: Literal[TestType.PRESENT_AS_STRIKEOUT.value]
+    text: str = ""
+
+
+class ParseTextColorRule(ParseRuleBase):
+    """Schema for `text_color` rules.
+
+    Validates that text appears inside an HTML tag whose attributes carry a
+    text color matching the expected color family (e.g. ``red``, ``blue``,
+    ``green``, ``orange``). Attribute colors may be named colors, hex codes
+    (``#c69200``) or ``rgb()`` values; matching is done by hue family, not
+    exact value, so ``#ffa6a6`` satisfies ``red``.
+
+    Primary use: colored revision text in legal redlines, where color encodes
+    revision semantics (e.g. red struck = deleted, blue underlined = inserted).
+    """
+
+    type: Literal[TestType.TEXT_COLOR.value]
+    text: str = ""
+    color: str = ""
+
+
+class ParseTitleRule(ParseRuleBase):
+    type: Literal[TestType.IS_TITLE.value]
+    text: str = ""
+    level: int | None = None
+
+
+class ParseListLevelRule(ParseRuleBase):
+    """Schema for `list_level` rules.
+
+    Validates that `text` appears as a list item at nesting level `level`
+    (1 = top level). Levels are computed from the output with CommonMark
+    list-item semantics (https://spec.commonmark.org/0.31.2/#list-items): a
+    nested item's marker must sit at or beyond the column of the first content
+    character of the item it nests under - there is no fixed space count.
+    HTML `<ul>/<ol>/<li>` nesting is accepted as equivalent. Deliberately not
+    evaluated for indentation inside table cells.
+    """
+
+    type: Literal[TestType.LIST_LEVEL.value]
+    text: str = ""
+    level: int | None = None
+
+
+class ParseLatexRule(ParseRuleBase):
+    type: Literal[TestType.IS_LATEX.value]
+    formula: str
+
+
+class ParseNotLatexRule(ParseRuleBase):
+    """Formula-like text that must remain ordinary Markdown."""
+
+    type: Literal[TestType.IS_NOT_LATEX.value]
+    text: str
+
+
+class ParseCodeBlockRule(ParseRuleBase):
+    type: Literal[TestType.IS_CODE_BLOCK.value]
+    language: str = ""
+    code: str = ""
+
+
+class ParseTitleHierarchyPercentRule(ParseRuleBase):
+    type: Literal[TestType.TITLE_HIERARCHY_PERCENT.value]
+    title_hierarchy: dict[str, Any] = Field(default_factory=dict)
+
+
+class HeadingExpectation(DictCompatPydanticModel):
+    """One visible page heading in reading order."""
+
+    text: str = Field(min_length=1)
+    level: int = Field(ge=1, le=6)
+
+
+class ParseHeadingStructureRule(ParseRuleBase):
+    """Complete ordered heading inventory for one transcribed page."""
+
+    type: Literal[TestType.HEADING_STRUCTURE.value]
+    # Empty is a meaningful negative annotation, so callers must state it
+    # explicitly instead of silently getting a no-headings rule after a typo.
+    headings: list[HeadingExpectation]
+
+
+class ParsePageSectionRule(ParseRuleBase):
+    type: Literal[TestType.IS_HEADER.value, TestType.IS_FOOTER.value]
+    text: str = ""
+
+
+class ParseBagOfDigitPercentRule(ParseRuleBase):
+    """Schema for `bag_of_digit_percent` rule.
+
+    Compares digit frequency (0-9) between expected markdown and actual output.
+    Digits inside HTML tag attributes (e.g. colspan="2") are excluded.
+    """
+
+    type: Literal[TestType.BAG_OF_DIGIT_PERCENT.value]
+    bag_of_digit: dict[str, int] = Field(default_factory=dict)
+
+
+class ParseRotateCheckRule(ParseRuleBase):
+    type: Literal[TestType.ROTATE_CHECK.value]
+    value: int | float | str | None = None
+
+
+class ParseWatermarkRemovalRule(ParseRuleBase):
+    """Score watermark suppression without rewarding destroyed body text."""
+
+    type: Literal[TestType.WATERMARK_REMOVAL.value]
+    page: int = Field(ge=1)
+    watermark_texts: list[str] = Field(min_length=1)
+    allowed_occurrences: list[int] | None = Field(
+        default=None,
+        description=(
+            "Maximum output occurrences allowed for each watermark phrase. Use this when the same phrase "
+            "also occurs legitimately in the page body; defaults to zero for every phrase."
+        ),
+    )
+    preserve_texts: list[str] = Field(min_length=1)
+    watermark_match_threshold: float = Field(default=0.80, ge=0.0, le=1.0)
+    preserve_match_threshold: float = Field(default=0.85, ge=0.0, le=1.0)
+    removal_pass_threshold: float = Field(default=1.0, ge=0.0, le=1.0)
+    preservation_pass_threshold: float = Field(default=0.80, ge=0.0, le=1.0)
+
+    @model_validator(mode="after")
+    def validate_allowed_occurrences(self) -> ParseWatermarkRemovalRule:
+        if self.allowed_occurrences is None:
+            return self
+        if len(self.allowed_occurrences) != len(self.watermark_texts):
+            raise ValueError("allowed_occurrences must have one value per watermark_texts entry")
+        if any(value < 0 for value in self.allowed_occurrences):
+            raise ValueError("allowed_occurrences values must be non-negative")
+        return self
+
+
+class ParseDiagramGraphRule(ParseRuleBase):
+    """One diagram the parser must render as a mermaid block whose *graph* matches ``graph``.
+
+    Mermaid source is never compared: both sides are parsed into labelled nodes and edges,
+    nodes are aligned by fuzzy label similarity (Hungarian assignment) and edges are scored on
+    the aligned node ids. ``graph`` is ``{"nodes": [{"id","label"}], "edges": [{"from","to",
+    "label"?, "directed"?}], "groups"?: [{"id","label","members"}]}``. ``bbox`` is normalized
+    COCO ``[x, y, w, h]`` in page fractions, as for inline images.
+    """
+
+    type: Literal[TestType.DIAGRAM_GRAPH.value]
+    graph: dict[str, Any] = Field(default_factory=dict, description="Ground-truth graph: nodes, edges, optional groups")
+    diagram_class: str = Field(default="flowchart", description="Annotated kind (flowchart, org_chart, process, ...)")
+    accepted_types: list[str] = Field(
+        default_factory=lambda: ["flowchart"],
+        description="Mermaid diagram types that may represent this figure (flowchart, state, sequence, mindmap, ...)",
+    )
+    bbox: list[float] = Field(default_factory=list, description="Normalized [x, y, w, h] of the diagram on the page")
+    caption: str | None = Field(default=None, description="Verbatim caption printed next to the diagram, if any")
+    reference_image: str | None = Field(default=None, description="Crop PNG next to the test case, for the report")
+    text_before: list[str] = Field(default_factory=list, description="Text lines just above the diagram, reading order")
+    text_after: list[str] = Field(default_factory=list, description="Text lines just below the diagram, reading order")
+    annotator_confidence: float | None = Field(default=None, description="Annotator confidence in the graph")
+    node_match_threshold: int = Field(
+        default=80, description="rapidfuzz token_set_ratio at or above which two labels align"
+    )
+    node_recall_threshold: float = Field(default=0.80, description="Minimum share of expected nodes found")
+    node_precision_threshold: float = Field(
+        default=0.70, description="Minimum share of predicted nodes that are expected"
+    )
+    edge_f1_threshold: float = Field(default=0.60, description="Minimum edge F1 over aligned nodes")
+    edge_label_threshold: int = Field(default=70, description="Fuzzy ratio for edge labels when the reference has one")
+
+    @field_validator("bbox")
+    @classmethod
+    def _validate_bbox(cls, v: list[float]) -> list[float]:
+        if v and (len(v) != 4 or any(not isinstance(x, (int, float)) for x in v)):
+            raise ValueError("bbox must be [x, y, w, h]")
+        return [float(x) for x in v]
+
+    @field_validator("graph")
+    @classmethod
+    def _validate_graph(cls, v: dict[str, Any]) -> dict[str, Any]:
+        nodes = v.get("nodes") or []
+        ids = {str(n.get("id")) for n in nodes if isinstance(n, dict)}
+        if not ids:
+            raise ValueError("graph must declare at least one node")
+        for e in v.get("edges") or []:
+            if str(e.get("from")) not in ids or str(e.get("to")) not in ids:
+                raise ValueError(f"edge {e} references an unknown node id")
+        return v
+
+
+class ParseDiagramEdgeRule(ParseRuleBase):
+    """One relation that must (or must not) hold between two labelled nodes of a mermaid diagram.
+
+    Anchors are the robust complement to the graph rule: they are cheap to annotate, easy to
+    verify by eye, and insensitive to how creatively the rest of the diagram was transcribed.
+    ``relation`` is ``edge`` (a direct link source→target), ``path`` (source reaches target
+    through any directed chain, tolerating inserted intermediate nodes) or ``no_edge``.
+    """
+
+    type: Literal[TestType.DIAGRAM_EDGE.value]
+    source: str = Field(description="Label of the source node")
+    target: str = Field(description="Label of the target node")
+    relation: Literal["edge", "path", "no_edge"] = Field(default="edge")
+    label: str | None = Field(default=None, description="Expected edge text (e.g. Yes / No), fuzzy-matched when set")
+    directed: bool = Field(default=True, description="False accepts the link in either direction")
+    diagram_id: str | None = Field(default=None, description="``id`` of the diagram_graph rule this anchor belongs to")
+    node_match_threshold: int = Field(default=80, description="rapidfuzz token_set_ratio to identify source/target")
+    edge_label_threshold: int = Field(default=70, description="Fuzzy ratio for the edge label when set")
+
+
+class ParseDiagramCountRule(ParseRuleBase):
+    """Page-level decision: the right number of *parseable* mermaid blocks, none where none belong.
+
+    ``expected_count`` is 0 on negative pages (charts, schematics, maps, infographics) where any
+    mermaid block fails the rule. Blocks that do not parse into at least one node count against
+    the page everywhere.
+    """
+
+    type: Literal[TestType.DIAGRAM_COUNT.value]
+    expected_count: int = Field(default=0, description="Number of mermaid blocks the page should carry")
+    strict: bool = Field(default=True, description="Penalise extra parseable blocks beyond expected_count")
+
+
+class ParsePageDecorationRule(ParseRuleBase):
+    """Running header, running footer and printed page number of one page.
+
+    ``None`` for a slot means the page has none and the parser must leave it empty; a string is
+    the verbatim furniture text (header/footer pieces joined by `` | `` in reading order). The
+    rule reads the parser's structured page fields when available, else the markdown tags, and
+    also checks that the furniture text does not remain in the body markdown.
+    """
+
+    type: Literal[TestType.PAGE_DECORATION.value]
+    header: str | None = Field(
+        default=None, description="Running header text, pieces joined by ' | '; None = no header"
+    )
+    footer: str | None = Field(
+        default=None, description="Running footer text, pieces joined by ' | '; None = no footer"
+    )
+    page_number: str | None = Field(default=None, description="Canonical printed page number (3, iv, A-3); None = none")
+    page_number_raw: str | None = Field(default=None, description="Page number as printed (Page 3 of 10), for leakage")
+    text_threshold: int = Field(default=85, description="token_set_ratio at or above which header/footer text matches")
+    leak_min_chars: int = Field(default=4, description="Furniture pieces shorter than this are not checked for leakage")
+    annotator_confidence: float | None = Field(default=None, description="Annotator confidence, informational")
+
+
+type ParseRule = (
+    ParsePresenceRule
+    | ParseUnexpectedSentenceRule
+    | ParseUnexpectedSentencePercentRule
+    | ParseTooManySentenceOccurrenceRule
+    | ParseTooManySentenceOccurrencePercentRule
+    | ParseMissingSentenceRule
+    | ParseMissingSentencePercentRule
+    | ParseMissingSpecificSentenceRule
+    | ParseUnexpectedWordRule
+    | ParseUnexpectedWordPercentRule
+    | ParseTooManyWordOccurrenceRule
+    | ParseTooManyWordOccurrencePercentRule
+    | ParseMissingWordRule
+    | ParseMissingWordPercentRule
+    | ParseMissingSpecificWordRule
+    | ParseExtraContentRule
+    | ParseBaselineRule
+    | ParseOrderRule
+    | ParseTableRule
+    | ParseTablesValuesRule
+    | ParseTablesNumRowsRule
+    | ParseTablesNumColsRule
+    | ParseTableMarkerCellsRule
+    | ParseTableColspanRule
+    | ParseTableRowspanRule
+    | ParseTableSameRowRule
+    | ParseTableSameColumnRule
+    | ParseTableHeaderChainRule
+    | ParseTableAdjacentUpRule
+    | ParseTableAdjacentDownRule
+    | ParseTableAdjacentLeftRule
+    | ParseTableAdjacentRightRule
+    | ParseTableTopHeaderRule
+    | ParseTableLeftHeaderRule
+    | ParseTableNoLeftRule
+    | ParseTableNoRightRule
+    | ParseTableNoAboveRule
+    | ParseTableNoBelowRule
+    | ParseChartDataPointRule
+    | ParseChartDataArrayLabelsRule
+    | ParseChartDataArrayDataRule
+    | ParseFormFieldRule
+    | ParseFormattingRule
+    | ParseMarkColorRule
+    | ParseTextColorRule
+    | ParseAbsentUnlessStrikeoutRule
+    | ParsePresentAsStrikeoutRule
+    | ParseLatexRule
+    | ParseNotLatexRule
+    | ParseCodeBlockRule
+    | ParseTitleRule
+    | ParseTitleHierarchyPercentRule
+    | ParseHeadingStructureRule
+    | ParseListLevelRule
+    | ParsePageSectionRule
+    | ParseBagOfDigitPercentRule
+    | ParseRotateCheckRule
+    | ParseWatermarkRemovalRule
+    | ParseDiagramGraphRule
+    | ParseDiagramEdgeRule
+    | ParseDiagramCountRule
+    | ParsePageDecorationRule
+)
+
+type ParseRuleInput = ParseRule | dict[str, Any]
+
+_RULE_TYPE_TO_MODEL: dict[str, type[ParseRuleBase]] = {
+    TestType.PRESENT.value: ParsePresenceRule,
+    TestType.ABSENT.value: ParsePresenceRule,
+    TestType.UNEXPECTED_SENTENCE.value: ParseUnexpectedSentenceRule,
+    TestType.UNEXPECTED_SENTENCE_PERCENT.value: ParseUnexpectedSentencePercentRule,
+    TestType.TOO_MANY_SENTENCE_OCCURENCE.value: ParseTooManySentenceOccurrenceRule,
+    TestType.TOO_MANY_SENTENCE_OCCURENCE_PERCENT.value: ParseTooManySentenceOccurrencePercentRule,
+    TestType.MISSING_SENTENCE.value: ParseMissingSentenceRule,
+    TestType.MISSING_SENTENCE_PERCENT.value: ParseMissingSentencePercentRule,
+    TestType.MISSING_SPECIFIC_SENTENCE.value: ParseMissingSpecificSentenceRule,
+    TestType.UNEXPECTED_WORD.value: ParseUnexpectedWordRule,
+    TestType.UNEXPECTED_WORD_PERCENT.value: ParseUnexpectedWordPercentRule,
+    TestType.TOO_MANY_WORD_OCCURENCE.value: ParseTooManyWordOccurrenceRule,
+    TestType.TOO_MANY_WORD_OCCURENCE_PERCENT.value: ParseTooManyWordOccurrencePercentRule,
+    TestType.MISSING_WORD.value: ParseMissingWordRule,
+    TestType.MISSING_WORD_PERCENT.value: ParseMissingWordPercentRule,
+    TestType.MISSING_SPECIFIC_WORD.value: ParseMissingSpecificWordRule,
+    TestType.EXTRA_CONTENT.value: ParseExtraContentRule,
+    TestType.BASELINE.value: ParseBaselineRule,
+    TestType.ORDER.value: ParseOrderRule,
+    TestType.TABLE.value: ParseTableRule,
+    TestType.TABLES_VALUES.value: ParseTablesValuesRule,
+    TestType.TABLES_NUM_ROWS.value: ParseTablesNumRowsRule,
+    TestType.TABLES_NUM_COLS.value: ParseTablesNumColsRule,
+    TestType.TABLE_MARKER_CELLS.value: ParseTableMarkerCellsRule,
+    TestType.TABLE_COLSPAN.value: ParseTableColspanRule,
+    TestType.TABLE_ROWSPAN.value: ParseTableRowspanRule,
+    TestType.TABLE_SAME_ROW.value: ParseTableSameRowRule,
+    TestType.TABLE_SAME_COLUMN.value: ParseTableSameColumnRule,
+    TestType.TABLE_HEADER_CHAIN.value: ParseTableHeaderChainRule,
+    TestType.TABLE_ADJACENT_UP.value: ParseTableAdjacentUpRule,
+    TestType.TABLE_ADJACENT_DOWN.value: ParseTableAdjacentDownRule,
+    TestType.TABLE_ADJACENT_LEFT.value: ParseTableAdjacentLeftRule,
+    TestType.TABLE_ADJACENT_RIGHT.value: ParseTableAdjacentRightRule,
+    TestType.TABLE_TOP_HEADER.value: ParseTableTopHeaderRule,
+    TestType.TABLE_LEFT_HEADER.value: ParseTableLeftHeaderRule,
+    TestType.TABLE_NO_LEFT.value: ParseTableNoLeftRule,
+    TestType.TABLE_NO_RIGHT.value: ParseTableNoRightRule,
+    TestType.TABLE_NO_ABOVE.value: ParseTableNoAboveRule,
+    TestType.TABLE_NO_BELOW.value: ParseTableNoBelowRule,
+    TestType.CHART_DATA_POINT.value: ParseChartDataPointRule,
+    TestType.CHART_DATA_ARRAY_LABELS.value: ParseChartDataArrayLabelsRule,
+    TestType.CHART_DATA_ARRAY_DATA.value: ParseChartDataArrayDataRule,
+    TestType.FORM_FIELD.value: ParseFormFieldRule,
+    TestType.IS_UNDERLINE.value: ParseFormattingRule,
+    TestType.IS_NOT_UNDERLINE.value: ParseFormattingRule,
+    TestType.IS_BOLD.value: ParseFormattingRule,
+    TestType.IS_NOT_BOLD.value: ParseFormattingRule,
+    TestType.IS_STRIKEOUT.value: ParseFormattingRule,
+    TestType.IS_NOT_STRIKEOUT.value: ParseFormattingRule,
+    TestType.IS_ITALIC.value: ParseFormattingRule,
+    TestType.IS_NOT_ITALIC.value: ParseFormattingRule,
+    TestType.IS_MARK.value: ParseFormattingRule,
+    TestType.IS_NOT_MARK.value: ParseFormattingRule,
+    TestType.MARK_COLOR.value: ParseMarkColorRule,
+    TestType.TEXT_COLOR.value: ParseTextColorRule,
+    TestType.ABSENT_UNLESS_STRIKEOUT.value: ParseAbsentUnlessStrikeoutRule,
+    TestType.PRESENT_AS_STRIKEOUT.value: ParsePresentAsStrikeoutRule,
+    TestType.IS_SUP.value: ParseFormattingRule,
+    TestType.IS_NOT_SUP.value: ParseFormattingRule,
+    TestType.IS_SUB.value: ParseFormattingRule,
+    TestType.IS_NOT_SUB.value: ParseFormattingRule,
+    TestType.IS_LATEX.value: ParseLatexRule,
+    TestType.IS_NOT_LATEX.value: ParseNotLatexRule,
+    TestType.IS_CODE_BLOCK.value: ParseCodeBlockRule,
+    TestType.IS_TITLE.value: ParseTitleRule,
+    TestType.TITLE_HIERARCHY_PERCENT.value: ParseTitleHierarchyPercentRule,
+    TestType.HEADING_STRUCTURE.value: ParseHeadingStructureRule,
+    TestType.LIST_LEVEL.value: ParseListLevelRule,
+    TestType.IS_HEADER.value: ParsePageSectionRule,
+    TestType.IS_FOOTER.value: ParsePageSectionRule,
+    TestType.BAG_OF_DIGIT_PERCENT.value: ParseBagOfDigitPercentRule,
+    TestType.ROTATE_CHECK.value: ParseRotateCheckRule,
+    TestType.WATERMARK_REMOVAL.value: ParseWatermarkRemovalRule,
+    TestType.DIAGRAM_GRAPH.value: ParseDiagramGraphRule,
+    TestType.DIAGRAM_EDGE.value: ParseDiagramEdgeRule,
+    TestType.DIAGRAM_COUNT.value: ParseDiagramCountRule,
+    TestType.PAGE_DECORATION.value: ParsePageDecorationRule,
+}
+
+_BUILTIN_RULE_TYPES: frozenset[str] = frozenset(_RULE_TYPE_TO_MODEL)
+
+
+def get_rule_type(rule: ParseRuleInput | Any) -> str | None:
+    """Return the `type` field from either a typed schema or raw dict."""
+
+    if isinstance(rule, ParseRuleBase):
+        return rule.type
+    if isinstance(rule, BaseModel):
+        value = getattr(rule, "type", None)
+        return value if isinstance(value, str) else None
+    if isinstance(rule, dict):
+        raw_type = rule.get("type")
+        return raw_type if isinstance(raw_type, str) else None
+    return None
+
+
+def get_rule_id(rule: ParseRuleInput | Any) -> str | None:
+    """Return optional `id` from either typed schema or raw dict."""
+
+    if isinstance(rule, ParseRuleBase):
+        return rule.id
+    if isinstance(rule, BaseModel):
+        value = getattr(rule, "id", None)
+        return value if isinstance(value, str) else None
+    if isinstance(rule, dict):
+        value = rule.get("id")
+        return value if isinstance(value, str) else None
+    return None
+
+
+def get_rule_page(rule: ParseRuleInput | Any) -> int | None:
+    """Return optional `page` from either typed schema or raw dict."""
+
+    if isinstance(rule, ParseRuleBase):
+        return rule.page
+    if isinstance(rule, BaseModel):
+        value = getattr(rule, "page", None)
+        return value if isinstance(value, int) else None
+    if isinstance(rule, dict):
+        value = rule.get("page")
+        return value if isinstance(value, int) else None
+    return None
+
+
+def get_rule_layout_id(rule: ParseRuleInput | Any) -> str | None:
+    """Return primary `layout_id` from either typed schema or raw dict."""
+
+    if isinstance(rule, ParseRuleBase):
+        return rule.layout_id
+    if isinstance(rule, BaseModel):
+        value = getattr(rule, "layout_id", None)
+        if isinstance(value, str):
+            return value
+        layout_ids = get_rule_layout_ids(rule)
+        return layout_ids[0] if layout_ids else None
+    if isinstance(rule, dict):
+        value = rule.get("layout_id")
+        if isinstance(value, str):
+            return value
+        layout_ids = get_rule_layout_ids(rule)
+        return layout_ids[0] if layout_ids else None
+    return None
+
+
+def get_rule_layout_ids(rule: ParseRuleInput | Any) -> list[str]:
+    """Return normalized `layout_ids` from either typed schema or raw dict."""
+
+    if isinstance(rule, ParseRuleBase):
+        return list(rule.layout_ids)
+    if isinstance(rule, BaseModel):
+        value = getattr(rule, "layout_ids", None)
+        if isinstance(value, list):
+            return [v for v in value if isinstance(v, str)]
+        return []
+    if isinstance(rule, dict):
+        value = rule.get("layout_ids")
+        if isinstance(value, list):
+            return [v for v in value if isinstance(v, str)]
+        fallback = rule.get("layout_id")
+        if isinstance(fallback, str):
+            return [fallback]
+    return []
+
+
+def get_rule_layout_bindings(rule: ParseRuleInput | Any) -> dict[str, str | list[str]]:
+    """Return `layout_bindings` from either typed schema or raw dict."""
+
+    if isinstance(rule, ParseRuleBase):
+        return dict(rule.layout_bindings)
+
+    def _is_valid_binding_value(value: Any) -> bool:
+        return isinstance(value, str) or (isinstance(value, list) and all(isinstance(item, str) for item in value))
+
+    if isinstance(rule, BaseModel):
+        value = getattr(rule, "layout_bindings", None)
+        if isinstance(value, dict):
+            return {str(k): v for k, v in value.items() if _is_valid_binding_value(v)}
+        return {}
+    if isinstance(rule, dict):
+        value = rule.get("layout_bindings")
+        if isinstance(value, dict):
+            return {str(k): v for k, v in value.items() if _is_valid_binding_value(v)}
+    return {}
+
+
+def rule_to_dict(rule: ParseRuleInput | Any) -> dict[str, Any]:
+    """Serialize a typed or raw rule to a mutable dict for reporting/evals."""
+
+    if isinstance(rule, BaseModel):
+        return rule.model_dump(by_alias=True)
+    if isinstance(rule, dict):
+        return dict(rule)
+    raise TypeError(f"Expected ParseRule or dict, got {type(rule)!r}")
+
+
+def register_parse_rule_model(rule_type: str, model: type[ParseRuleBase]) -> None:
+    """Register the pydantic schema for an additional rule ``type``.
+
+    Extensions pair this with ``rules_base.register_rule_class`` (or call
+    ``parse_bench.extensions.register_rule_type`` which does both). Built-in
+    rule types cannot be replaced.
+    """
+    if not isinstance(rule_type, str) or not rule_type:
+        raise ValueError("rule_type must be a non-empty string")
+    if not (isinstance(model, type) and issubclass(model, ParseRuleBase)):
+        raise TypeError("model must subclass ParseRuleBase")
+    existing = _RULE_TYPE_TO_MODEL.get(rule_type)
+    if existing is not None and existing is not model and rule_type in _BUILTIN_RULE_TYPES:
+        raise ValueError(f"{rule_type!r} is a built-in rule type and cannot be replaced")
+    _RULE_TYPE_TO_MODEL[rule_type] = model
+
+
+def registered_parse_rule_types() -> list[str]:
+    """Every rule ``type`` with a registered schema (built-ins and extensions)."""
+    return list(_RULE_TYPE_TO_MODEL)
+
+
+def coerce_parse_rule(rule_data: ParseRuleInput | Any) -> ParseRuleBase:
+    """Coerce raw rule payloads into the typed parse rule model.
+
+    Idempotent: already-typed rules are returned as-is.
+    """
+
+    if isinstance(rule_data, ParseRuleBase):
+        return rule_data  # type: ignore[return-value]
+
+    if isinstance(rule_data, dict):
+        rule_dict = rule_data
+    else:
+        raise TypeError(f"Expected rule payload as dict or ParseRule, got {type(rule_data)!r}")
+
+    rule_type = rule_dict.get("type")
+    if not isinstance(rule_type, str):
+        raise ValueError("Rule payload must contain a string 'type' field")
+
+    model_cls = _RULE_TYPE_TO_MODEL.get(rule_type)
+    if model_cls is None:
+        raise ValueError(f"Unknown parse rule type: {rule_type}")
+
+    return model_cls.model_validate(rule_dict)
+
+
+def coerce_parse_rule_list(rules: list[dict[str, Any]] | list[ParseRule]) -> list[ParseRuleBase]:
+    """Validate a list of parse rule payloads and return typed objects."""
+
+    parsed: list[ParseRule] = []
+    for rule in rules:
+        parsed.append(coerce_parse_rule(rule))
+    return parsed
+
+
+def coerce_parse_rule_list_or_none(
+    rules: list[dict[str, Any]] | list[ParseRule] | None,
+) -> list[ParseRuleBase] | None:
+    """Coerce rule lists while preserving explicit None for optional fields."""
+
+    if rules is None:
+        return None
+    return coerce_parse_rule_list(rules)