parse-bench 1.0.0__py3-none-any.whl

parse_bench/evaluation/metrics/parse/structural_consistency_metric.py

@@ -0,0 +1,251 @@
+"""Structural consistency metric for HTML table comparison.
+
+A binary metric that flags when a predicted table has an inconsistent
+internal structure — specifically, when rows or columns have an
+inconsistent number of cells (after resolving colspan/rowspan).
+
+This is a *self-consistency* check on the predicted table alone (not a
+comparison against ground truth). A structurally consistent table has
+every row spanning the same total number of columns and every column
+spanning the same total number of rows.
+
+Returns 1.0 (consistent) or 0.0 (inconsistent) per table, averaged
+across all tables in the document.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from bs4 import BeautifulSoup
+
+from parse_bench.evaluation.metrics.base import Metric
+from parse_bench.evaluation.metrics.parse.table_extraction import extract_html_tables
+from parse_bench.schemas.evaluation import MetricValue
+
+
+def _mode_value(counts: list[int]) -> int:
+    """Return the modal (most common) value from *counts*.
+
+    Ties are broken by first occurrence, matching the platform logic.
+    """
+    if not counts:
+        return 0
+    freq: dict[int, int] = {}
+    first_seen: dict[int, int] = {}
+    for i, c in enumerate(counts):
+        freq[c] = freq.get(c, 0) + 1
+        if c not in first_seen:
+            first_seen[c] = i
+
+    best_count = 0
+    best_val = counts[0]
+    for val, f in freq.items():
+        if f > best_count or (f == best_count and first_seen[val] < first_seen[best_val]):
+            best_count = f
+            best_val = val
+    return best_val
+
+
+def _check_table_consistency(table_html: str) -> dict[str, Any]:
+    """Check structural consistency of a single HTML table.
+
+    Returns a dict with:
+        - consistent: bool
+        - num_rows: int
+        - num_cols: int (max column span across all rows)
+        - row_cell_counts: list[int] — effective column count per row
+        - col_cell_counts: list[int] — effective row count per column
+        - row_inconsistency: bool — True if rows have different widths
+        - col_inconsistency: bool — True if columns have different heights
+        - row_inconsistency_details: list[str] — per-row mismatch descriptions
+        - col_inconsistency_details: list[str] — per-column mismatch descriptions
+    """
+    soup = BeautifulSoup(table_html, "lxml")
+    table = soup.find("table")
+    if not table:
+        return {"consistent": True, "num_rows": 0, "num_cols": 0}
+
+    rows = table.find_all("tr")
+    if not rows:
+        return {"consistent": True, "num_rows": 0, "num_cols": 0}
+
+    num_rows = len(rows)
+
+    # Build an occupancy grid by resolving rowspan/colspan
+    occupied: dict[tuple[int, int], bool] = {}
+
+    for row_idx, row in enumerate(rows):
+        col_idx = 0
+        for cell in row.find_all(["td", "th"]):
+            while (row_idx, col_idx) in occupied:
+                col_idx += 1
+
+            rowspan = int(str(cell.get("rowspan", "1")))
+            colspan = int(str(cell.get("colspan", "1")))
+
+            for r in range(row_idx, row_idx + rowspan):
+                for c in range(col_idx, col_idx + colspan):
+                    occupied[(r, c)] = True
+
+            col_idx += colspan
+
+    if not occupied:
+        return {"consistent": True, "num_rows": num_rows, "num_cols": 0}
+
+    max_row = max(r for r, c in occupied) + 1
+    max_col = max(c for r, c in occupied) + 1
+
+    # Count how many columns each row spans
+    row_cell_counts = []
+    for r in range(max_row):
+        count = sum(1 for c in range(max_col) if (r, c) in occupied)
+        row_cell_counts.append(count)
+
+    # Count how many rows each column spans
+    col_cell_counts = []
+    for c in range(max_col):
+        count = sum(1 for r in range(max_row) if (r, c) in occupied)
+        col_cell_counts.append(count)
+
+    # Check consistency: all rows should have the same width,
+    # all columns should have the same height
+    row_inconsistent = len(set(row_cell_counts)) > 1
+    col_inconsistent = len(set(col_cell_counts)) > 1
+
+    consistent = not row_inconsistent and not col_inconsistent
+
+    # Build per-row/col inconsistency details using the modal expected value
+    row_inconsistency_details: list[str] = []
+    col_inconsistency_details: list[str] = []
+
+    if row_inconsistent:
+        expected_cols = _mode_value(row_cell_counts)
+        for i, count in enumerate(row_cell_counts):
+            if count != expected_cols:
+                row_inconsistency_details.append(f"row {i + 1} has {count} cols, expected {expected_cols}")
+
+    if col_inconsistent:
+        expected_rows = _mode_value(col_cell_counts)
+        for i, count in enumerate(col_cell_counts):
+            if count != expected_rows:
+                col_inconsistency_details.append(f"col {i + 1} has {count} rows, expected {expected_rows}")
+
+    return {
+        "consistent": consistent,
+        "num_rows": max_row,
+        "num_cols": max_col,
+        "row_cell_counts": row_cell_counts,
+        "col_cell_counts": col_cell_counts,
+        "row_inconsistency": row_inconsistent,
+        "col_inconsistency": col_inconsistent,
+        "row_inconsistency_details": row_inconsistency_details,
+        "col_inconsistency_details": col_inconsistency_details,
+    }
+
+
+class StructuralConsistencyMetric(Metric):
+    """Binary structural consistency metric for predicted HTML tables.
+
+    Checks that each predicted table is internally consistent: every row
+    spans the same number of columns and every column spans the same
+    number of rows (after resolving colspan/rowspan).
+
+    Only evaluates the *actual* (predicted) tables. Ground truth is used
+    only for table matching (so we report per-table diagnostics aligned
+    with the GT table order).
+
+    Returns a single MetricValue with value 1.0 (all tables consistent)
+    or 0.0 (at least one inconsistent), with per-table details in metadata.
+    """
+
+    @property
+    def name(self) -> str:
+        return "structural_consistency"
+
+    def compute(  # type: ignore[override]
+        self,
+        expected: str,
+        actual: str,
+        **kwargs: Any,
+    ) -> list[MetricValue]:
+        actual_tables = extract_html_tables(actual)
+
+        if not actual_tables:
+            return [
+                MetricValue(
+                    metric_name="structural_consistency",
+                    value=1.0,
+                    metadata={"tables_found_actual": 0, "note": "No tables to check"},
+                )
+            ]
+
+        per_table: list[dict[str, Any]] = []
+        scores: list[float] = []
+        details: list[str] = []
+
+        for idx, table_html in enumerate(actual_tables):
+            result = _check_table_consistency(table_html)
+            score = 1.0 if result["consistent"] else 0.0
+            scores.append(score)
+            per_table.append(
+                {
+                    "table_index": idx,
+                    "consistent": result["consistent"],
+                    "num_rows": result["num_rows"],
+                    "num_cols": result["num_cols"],
+                    "row_inconsistency": result.get("row_inconsistency", False),
+                    "col_inconsistency": result.get("col_inconsistency", False),
+                }
+            )
+
+            nr = result["num_rows"]
+            nc = result["num_cols"]
+
+            if idx > 0:
+                details.append("=" * 40)
+
+            if result["consistent"]:
+                details.append(f"Table {idx + 1}: 1.0 — consistent ({nr}×{nc})")
+            else:
+                row_details: list[str] = result.get("row_inconsistency_details", [])
+                col_details: list[str] = result.get("col_inconsistency_details", [])
+                issues = row_details + col_details
+                row_counts = result.get("row_cell_counts", [])
+                col_counts = result.get("col_cell_counts", [])
+                n_bad_rows = len(row_details)
+                n_bad_cols = len(col_details)
+                summary = f"Table {idx + 1}: 0.0 — inconsistent ({nr}×{nc})"
+                if n_bad_rows:
+                    summary += f" {n_bad_rows}/{nr} rows"
+                if n_bad_cols:
+                    summary += f" {n_bad_cols}/{nc} cols"
+                details.append(summary)
+                if row_counts:
+                    details.append(f"  row widths:  {row_counts}")
+                if col_counts:
+                    details.append(f"  col heights: {col_counts}")
+                for issue in issues:
+                    details.append(f"  {issue}")
+
+        avg_score = sum(scores) / len(scores)
+        n_ok = sum(1 for s in scores if s == 1.0)
+        n_bad = sum(1 for s in scores if s == 0.0)
+        details.insert(
+            0,
+            f"{avg_score:.3f} — {len(actual_tables)} table(s) checked, {n_ok} consistent, {n_bad} inconsistent",
+        )
+
+        return [
+            MetricValue(
+                metric_name="structural_consistency",
+                value=avg_score,
+                metadata={
+                    "tables_found_actual": len(actual_tables),
+                    "tables_consistent": n_ok,
+                    "tables_inconsistent": n_bad,
+                    "per_table_details": per_table,
+                },
+                details=details,
+            )
+        ]

parse_bench/evaluation/metrics/parse/table_extraction.py

@@ -0,0 +1,152 @@
+"""Shared table identification + parsing stage.
+
+Run once per (expected_md, actual_md) so all table metrics consume the
+same set of tables, paired the same way. Normalization stays inside each
+metric — GriTS and TRM apply their own per-cell normalization downstream.
+
+GT parse failures raise loudly (dataset bug). Pred parse failures are
+dropped silently (model bug — dropped tables count as unmatched_expected
+for any GT they would have paired with, so the model still pays the score).
+"""
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from parse_bench.evaluation.metrics.parse.table_parsing import TableData, parse_html_tables
+
+if TYPE_CHECKING:
+    from parse_bench.evaluation.metrics.parse.table_title_stripping import HeaderHints
+
+_TABLE_OPEN_RE = re.compile(r"<table(?=[>\s])", re.IGNORECASE)
+_TABLE_CLOSE_RE = re.compile(r"</table\s*>", re.IGNORECASE)
+
+
+def extract_html_tables(content: str) -> list[str]:
+    """Extract all top-level HTML table strings from markdown/HTML content.
+
+    Uses depth-aware string scanning to correctly handle nested tables.
+    Nested tables (inside <td> cells) are included as part of the outer
+    table's HTML string, not extracted as separate entries.
+    """
+    if not content:
+        return []
+
+    tables: list[str] = []
+    search_start = 0
+    while True:
+        open_match = _TABLE_OPEN_RE.search(content, search_start)
+        if open_match is None:
+            break
+        start = open_match.start()
+
+        # Track nesting depth to find the matching </table>
+        depth = 0
+        pos = open_match.end()
+        end = -1
+        while pos < len(content):
+            next_open = _TABLE_OPEN_RE.search(content, pos)
+            next_close = _TABLE_CLOSE_RE.search(content, pos)
+            if next_close is None:
+                break
+            if next_open is not None and next_open.start() < next_close.start():
+                depth += 1
+                pos = next_open.end()
+            else:
+                if depth == 0:
+                    end = next_close.end()
+                    break
+                depth -= 1
+                pos = next_close.end()
+        if end == -1:
+            tables.append(content[start:])
+            break
+        tables.append(content[start:end])
+        search_start = end
+
+    return tables
+
+
+class GroundTruthTableParseError(RuntimeError):
+    """Raised when a ground-truth table cannot be parsed. Dataset bug."""
+
+
+@dataclass(frozen=True)
+class ExtractedTable:
+    """One table, identified once. Cell content is NOT normalized.
+
+    - GriTS reads ``raw_html`` and runs it through its own ``html_to_cells`` +
+      ``normalize_cell_text`` path (P2). In P5 it switches to reading
+      ``table_data`` directly with upgraded normalization.
+    - TRM reads ``table_data`` and runs it through its own ``normalize_table``
+      (P3 onward).
+    """
+
+    raw_html: str
+    table_data: TableData  # raw parse_html_tables output, NOT normalized
+    header_hints: "HeaderHints | None" = None  # populated by strip_title_rows
+
+
+@dataclass(frozen=True)
+class TableExtractionCounts:
+    """Per-doc table counts surfaced as MetricValues."""
+
+    expected: int
+    actual: int
+    unparseable_pred: int  # dropped pred tables (gt is always 0 — they raise)
+
+
+def extract_normalized_tables(
+    md: str,
+    *,
+    side: str,  # "expected" or "actual"
+    doc_id: str | None = None,
+) -> tuple[list[ExtractedTable], int]:
+    """Extract and parse all tables on one side of a doc.
+
+    Returns ``(tables, n_unparseable)``. ``n_unparseable`` is always 0 for the
+    expected side because GT parse failures raise.
+
+    Note: despite the name, this stage does **not** normalize cell content —
+    each metric applies its own normalization downstream. The name is kept
+    for backward compatibility with the plan.
+    """
+    raw_slices = extract_html_tables(md)
+    if not raw_slices:
+        return [], 0
+
+    # Parse each slice independently rather than calling parse_html_tables
+    # on the whole doc and zipping by index. The two parsers (depth-aware
+    # string scanner in extract_html_tables vs. lxml/bs4 in parse_html_tables)
+    # can disagree on what counts as a top-level table for malformed HTML,
+    # which would silently mis-pair raw_html with table_data. Parsing each
+    # slice individually makes the (raw_html, table_data) pairing correct
+    # by construction.
+    tables: list[ExtractedTable] = []
+    unparseable = 0
+    for i, raw in enumerate(raw_slices):
+        parsed_one = parse_html_tables(raw)
+        if not parsed_one:
+            if side == "expected":
+                raise GroundTruthTableParseError(f"Failed to parse expected table {i} in doc {doc_id!r}")
+            unparseable += 1
+            continue
+        tables.append(ExtractedTable(raw_html=raw, table_data=parsed_one[0]))
+    return tables, unparseable
+
+
+def extract_table_pairs(
+    expected_md: str,
+    actual_md: str,
+    *,
+    doc_id: str | None = None,
+) -> tuple[list[ExtractedTable], list[ExtractedTable], TableExtractionCounts]:
+    """Extract both sides for one doc."""
+    expected, _ = extract_normalized_tables(expected_md, side="expected", doc_id=doc_id)
+    actual, n_unparseable_pred = extract_normalized_tables(actual_md, side="actual", doc_id=doc_id)
+    counts = TableExtractionCounts(
+        expected=len(expected),
+        actual=len(actual),
+        unparseable_pred=n_unparseable_pred,
+    )
+    return expected, actual, counts

parse_bench/evaluation/metrics/parse/table_merging.py

@@ -0,0 +1,195 @@
+"""Table-merging (junction merge) metric — parse.
+
+Scores whether a parser joins table fragments that belong to one logical table —
+both within a page (section-break continuations) and across a page break — and
+keeps genuinely distinct tables apart. Reads ``metadata["table_merging"]``:
+
+    atoms          : ordered split GT tables  (reading order = sorted by page,idx)
+    logical_tables : the merged grouping; ``fragments`` lists the atom keys it joins
+
+Each consecutive atom pair ``(aᵢ, aᵢ₊₁)`` is a *junction*. Ground-truth says
+"merge" iff both atoms belong to the same logical table; the parser says "merge"
+iff both atoms land in the same predicted table (assignment = global argmax of
+GriTS containment-recall, **no page blocking, no threshold**). Each junction is a
+merge/separate decision scored over all four confusion quadrants — correct
+*non*-merges (TN) count too, so over-, under-, and appropriate-merging all
+register.
+
+Metrics (rates 0..1, higher better):
+  - table_merge_accuracy   : HEADLINE — (TP+TN)/N over all junctions (page-agnostic)
+  - table_merge_precision  : over-merge sensitivity   (TP / (TP+FP))
+  - table_merge_recall     : under-merge sensitivity  (TP / (TP+FN))
+  - table_merge_specificity: TN / (TN+FP)
+  - table_merge_f1
+  - table_merge_accuracy_within_page / _cross_page : per-kind slices
+  - table_merge_tp/fp/fn/tn: confusion-matrix counts (metadata["count"] ⇒ the
+    runner SUMS them at corpus level → total_table_merge_{tp,fp,fn,tn})
+  - table_merge_grits_con  : secondary content signal (merged logical-table GriTS)
+
+Pure over ``(parse_output, gt)``; no I/O.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from bs4 import BeautifulSoup
+from lxml import etree
+from lxml import html as lxml_html
+
+from parse_bench.evaluation.metrics.parse._vendor_grits_reference import grits_from_html
+from parse_bench.schemas.evaluation import MetricValue
+
+
+def _all_predicted_tables(parse_output: Any) -> list[str]:
+    """Flat, reading-ordered list of predicted ``<table>`` HTML across all pages.
+
+    Page-agnostic by design: a cross-page merge surfaces as one predicted table
+    (on the first page), and index identity is what "same predicted table" means.
+    """
+    out: list[str] = []
+    for page in getattr(parse_output, "pages", []) or []:
+        md = getattr(page, "markdown", "") or ""
+        for t in BeautifulSoup(md, "lxml").find_all("table"):
+            out.append(str(t))
+    return out
+
+
+def _xml_safe(table_html: str) -> str | None:
+    """Normalize a table fragment to well-formed XML the vendor GriTS can parse.
+
+    ``_vendor_grits_reference.html_to_cells`` uses ``xml.etree.ElementTree``
+    (strict XML — raises on unclosed tags / bare ``&``), unlike the lenient lxml
+    used elsewhere in the bench. Re-serialize through lxml (which repairs and
+    escapes) and return just the ``<table>``. ``None`` if there is no table.
+    """
+    if not table_html or not table_html.strip():
+        return None
+    try:
+        node = lxml_html.fromstring(table_html)
+    except Exception:
+        return None
+    table = node if node.tag == "table" else node.find(".//table")
+    if table is None:
+        return None
+    return str(etree.tostring(table, encoding="unicode", method="xml"))
+
+
+def _grits(true_html: str, pred_html: str, key: str) -> float:
+    """One GriTS sub-score between two table fragments; 0.0 on any parse failure."""
+    t = _xml_safe(true_html)
+    p = _xml_safe(pred_html)
+    if t is None or p is None:
+        return 0.0
+    try:
+        return float(grits_from_html(t, p).get(key, 0.0) or 0.0)
+    except Exception:
+        return 0.0
+
+
+def _prf(tp: int, fp: int, fn: int) -> tuple[float, float, float]:
+    """Precision / recall / F1; a 0-denominator component is vacuously 1.0."""
+    prec = tp / (tp + fp) if (tp + fp) else 1.0
+    rec = tp / (tp + fn) if (tp + fn) else 1.0
+    f1 = 2 * prec * rec / (prec + rec) if (prec + rec) else 0.0
+    return prec, rec, f1
+
+
+def _slice_accuracy(slice_name: str, b: dict[str, int]) -> list[MetricValue]:
+    """Per-kind accuracy slice; omitted entirely when that kind has no junctions."""
+    n = b["tp"] + b["fp"] + b["fn"] + b["tn"]
+    if n == 0:
+        return []
+    acc = (b["tp"] + b["tn"]) / n
+    return [
+        MetricValue(
+            metric_name=f"table_merge_accuracy_{slice_name}",
+            value=acc,
+            metadata={**b, "n_junctions": n},
+        )
+    ]
+
+
+def _logical_table_grits_con(logical: list[dict[str, Any]], pred: list[str]) -> float:
+    """Secondary content signal: mean GriTS-Con of each merged logical table vs its
+    best-matching predicted table. 1.0 vacuously when there are no logical tables."""
+    if not logical:
+        return 1.0
+    if not pred:
+        return 0.0
+    scores = [max((_grits(lt.get("html", ""), p, "grits_con") for p in pred), default=0.0) for lt in logical]
+    return sum(scores) / len(scores)
+
+
+def compute_table_merging_metrics(parse_output: Any, gt: dict[str, Any]) -> list[MetricValue]:
+    atoms: list[dict[str, Any]] = gt.get("atoms") or []
+    logical: list[dict[str, Any]] = gt.get("logical_tables") or []
+    frag_logical = {f: lt["id"] for lt in logical for f in lt.get("fragments", [])}
+
+    pred = _all_predicted_tables(parse_output)
+
+    # Assign each atom to the predicted table that best CONTAINS it (recall-oriented,
+    # global argmax, no page blocking, no threshold). None when the parser produced
+    # no tables OR no predicted table contains the atom at all (dropped fragment).
+    assign: dict[str, int | None] = {}
+    for a in atoms:
+        if not pred:
+            assign[a["key"]] = None
+            continue
+        scores = [_grits(a["html"], p, "grits_recall_con") for p in pred]
+        best = max(range(len(pred)), key=lambda j: scores[j])
+        assign[a["key"]] = best if scores[best] > 0.0 else None
+
+    if len(atoms) < 2:
+        return []  # junction-free doc — emit nothing, don't pollute corpus averages
+
+    tp = fp = fn = tn = 0
+    within = {"tp": 0, "fp": 0, "fn": 0, "tn": 0}
+    cross = {"tp": 0, "fp": 0, "fn": 0, "tn": 0}
+    for a, b in zip(atoms, atoms[1:], strict=False):
+        la, lb = frag_logical.get(a["key"]), frag_logical.get(b["key"])
+        gt_merge = la is not None and la == lb
+        ja, jb = assign[a["key"]], assign[b["key"]]
+        pred_merge = ja is not None and ja == jb
+        bucket = within if a["page"] == b["page"] else cross
+        if gt_merge and pred_merge:
+            tp += 1
+            bucket["tp"] += 1
+        elif gt_merge and not pred_merge:
+            fn += 1
+            bucket["fn"] += 1
+        elif not gt_merge and pred_merge:
+            fp += 1
+            bucket["fp"] += 1
+        else:
+            tn += 1
+            bucket["tn"] += 1
+
+    n = tp + fp + fn + tn  # == len(atoms) - 1
+    acc = (tp + tn) / n
+    prec, rec, f1 = _prf(tp, fp, fn)
+    spec = tn / (tn + fp) if (tn + fp) else 1.0
+    grits_con = _logical_table_grits_con(logical, pred)
+
+    cm = f"TP={tp} FP={fp} FN={fn} TN={tn}"
+    md = {"tp": tp, "fp": fp, "fn": fn, "tn": tn, "n_atoms": len(atoms), "n_logical": len(logical)}
+
+    results = [
+        # HEADLINE (doc-averaged at corpus level via avg_table_merge_accuracy) + inline CM.
+        MetricValue(metric_name="table_merge_accuracy", value=acc, metadata=md, details=[cm]),
+        MetricValue(metric_name="table_merge_precision", value=prec, metadata=md),
+        MetricValue(metric_name="table_merge_recall", value=rec, metadata=md),
+        MetricValue(metric_name="table_merge_specificity", value=spec, metadata=md),
+        MetricValue(metric_name="table_merge_f1", value=f1, metadata=md),
+        # Confusion counts as first-class metrics. metadata["count"] makes the runner
+        # SUM them at corpus level (total_table_merge_{tp,fp,fn,tn}) rather than average,
+        # so over-/under-/appropriate-merging stay visible beside the headline.
+        MetricValue(metric_name="table_merge_tp", value=float(tp), metadata={"count": tp, "n_atoms": len(atoms)}),
+        MetricValue(metric_name="table_merge_fp", value=float(fp), metadata={"count": fp, "n_atoms": len(atoms)}),
+        MetricValue(metric_name="table_merge_fn", value=float(fn), metadata={"count": fn, "n_atoms": len(atoms)}),
+        MetricValue(metric_name="table_merge_tn", value=float(tn), metadata={"count": tn, "n_atoms": len(atoms)}),
+        MetricValue(metric_name="table_merge_grits_con", value=grits_con, metadata=md),
+    ]
+    results += _slice_accuracy("within_page", within)
+    results += _slice_accuracy("cross_page", cross)
+    return results

parse_bench/evaluation/metrics/parse/table_pairing.py

@@ -0,0 +1,87 @@
+"""Shared GT->pred table assignment for the table-similarity metrics.
+
+GriTS and TEDS both build an ``n_expected x n_actual`` cost matrix and solve a
+single document-global Hungarian assignment over it. On multi-page documents
+that recur near-identical tables across pages, the global assignment mis-pairs a
+GT table on one page with a prediction on another. When per-table page labels
+are available, ``assign_tables`` instead solves the assignment **per page** so a
+GT table only ever pairs with a prediction on the same page.
+
+The return shape mirrors ``scipy.optimize.linear_sum_assignment`` — a
+``(row_ind, col_ind)`` pair of equal-length index lists — so callers consume it
+exactly as before.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+
+import numpy as np
+from scipy.optimize import linear_sum_assignment
+
+
+def page_blocking_active(
+    expected_pages: list[int] | None,
+    actual_pages: list[int] | None,
+    n_expected: int,
+    n_actual: int,
+) -> bool:
+    """Return True when page-constrained matching can and should be applied.
+
+    Requires both page-label lists to be present and length-consistent with the
+    table counts. Any mismatch (missing labels, wrong length) falls back to the
+    document-global assignment, so the feature is self-disabling.
+    """
+    return (
+        expected_pages is not None
+        and actual_pages is not None
+        and len(expected_pages) == n_expected
+        and len(actual_pages) == n_actual
+    )
+
+
+def assign_tables(
+    cost_matrix: np.ndarray,
+    expected_pages: list[int] | None = None,
+    actual_pages: list[int] | None = None,
+) -> tuple[list[int], list[int]]:
+    """Solve the GT->pred table assignment minimizing total cost.
+
+    When ``expected_pages`` / ``actual_pages`` are provided and consistent with
+    ``cost_matrix.shape`` (see :func:`page_blocking_active`), the assignment is
+    solved independently per page: a GT table on page P can only pair with a
+    prediction on page P. GT tables whose page has no predictions are left
+    unmatched (they appear in neither returned list, so the caller scores them
+    as unmatched-expected). Otherwise a single global assignment is solved.
+
+    Returns ``(row_ind, col_ind)`` as index lists, mirroring
+    ``scipy.optimize.linear_sum_assignment``.
+    """
+    n_expected, n_actual = cost_matrix.shape
+
+    if not page_blocking_active(expected_pages, actual_pages, n_expected, n_actual):
+        row_ind, col_ind = linear_sum_assignment(cost_matrix)
+        return row_ind.tolist(), col_ind.tolist()
+
+    assert expected_pages is not None and actual_pages is not None  # narrowed by the guard above
+
+    pred_by_page: dict[int, list[int]] = defaultdict(list)
+    for j, page in enumerate(actual_pages):
+        pred_by_page[page].append(j)
+
+    gt_by_page: dict[int, list[int]] = defaultdict(list)
+    for i, page in enumerate(expected_pages):
+        gt_by_page[page].append(i)
+
+    row_out: list[int] = []
+    col_out: list[int] = []
+    for page, gt_idxs in gt_by_page.items():
+        pred_idxs = pred_by_page.get(page)
+        if not pred_idxs:
+            continue
+        sub = cost_matrix[np.ix_(gt_idxs, pred_idxs)]
+        sub_rows, sub_cols = linear_sum_assignment(sub)
+        for sr, sc in zip(sub_rows.tolist(), sub_cols.tolist(), strict=True):
+            row_out.append(gt_idxs[sr])
+            col_out.append(pred_idxs[sc])
+    return row_out, col_out