table-stitcher 0.4.2__tar.gz → 0.4.4__tar.gz

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/CHANGELOG.md

@@ -7,6 +7,39 @@ the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html
 
 ## [Unreleased]
 
+## [0.4.4] — 2026-08-13
+
+### Fixed
+
+- **Duplicate header labels crashed the multipage merge** (`merger.py`).
+  Extracted headers that repeat a label — e.g. SEC 13F voting-authority
+  triplets where TableFormer emits `COLUMN 8` three times — made
+  `_build_generic_merged_table` raise `ValueError: Reindexing only valid
+  with uniquely valued Index objects`, because `pd.concat` cannot align
+  fragments on a non-unique column Index. Downstream consumers that
+  fail-soft on the error silently kept a degraded table set for the whole
+  document. Fragments are now merged under positionally deduped labels
+  (collision-safe against pre-existing `X.1`-style names) and the original
+  duplicated labels are restored on the merged output, matching how
+  single-fragment tables pass through untouched.
+
+## [0.4.3] — 2026-06-11
+
+### Fixed
+
+- **Reprinted continuation-page headers appended as data rows on multi-page
+  merge** (`adapters/docling.py`). When a table's column header is reprinted at
+  the top of each page — especially a multi-row (hierarchical) header — the
+  repeated header rows survived the merge as bogus data rows, misaligning the
+  stitched table. Injection now drops a body row when it is *both* flagged
+  `column_header` by Docling *and* a tokenized match (Jaccard ≥ 0.6) for the
+  reconstructed header block. Both signals are required: the flag alone is
+  unreliable (Docling over-flags rowspan/continuation *data* rows as headers),
+  and the tokenized comparison is punctuation-agnostic, so per-cell OCR drift
+  such as `(S$)` vs `($$)` is tolerated without any threshold tuning. The merged
+  DataFrame (`lt.df`) is unchanged; only the injected document is de-duplicated.
+  A `debug` log reports each dropped row.
+
 ## [0.4.2] — 2026-06-08
 
 ### Fixed

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: table-stitcher
-Version: 0.4.2
+Version: 0.4.4
 Summary: Reassemble tables split across page boundaries in PDF extraction
 Project-URL: Homepage, https://github.com/pebbleroad/table-stitcher
 Project-URL: Repository, https://github.com/pebbleroad/table-stitcher
@@ -103,8 +103,8 @@ from table_stitcher import stitch_tables
 
 converter = DocumentConverter()
 doc = converter.convert("report.pdf").document
-doc = stitch_tables(doc)                  # merged tables; ready for
-                                          # export_to_markdown() / HTML / LLM
+doc = stitch_tables(doc)  # merged tables; ready for
+# export_to_markdown() / HTML / LLM
 ```
 
 `stitch_tables()` mutates `doc` in place and returns the same object. If you
@@ -132,10 +132,10 @@ Runnable end-to-end scripts live in [`examples/`](examples/):
 from table_stitcher import stitch_tables, MultiPageConfig
 
 config = MultiPageConfig(
-    max_page_gap=1,              # Only merge tables on consecutive pages
-    max_width_difference=2,      # Column count tolerance
-    header_sim_strict=0.6,       # Threshold for repeated header detection
-    stitch_separator="\n",       # Join character for split content
+    max_page_gap=1,  # Only merge tables on consecutive pages
+    max_width_difference=2,  # Column count tolerance
+    header_sim_strict=0.6,  # Threshold for repeated header detection
+    stitch_separator="\n",  # Join character for split content
 )
 
 doc = stitch_tables(doc, config=config)
@@ -148,6 +148,7 @@ from typing import Any, List
 from table_stitcher import TableStitcher, MultiPageConfig, TableMeta, LogicalTable
 from table_stitcher.adapters.base import TableStitcherAdapter
 
+
 class MyParserAdapter:
     def extract(self, doc, cfg: MultiPageConfig) -> List[TableMeta]:
         """Read tables from your document format into TableMeta objects."""
@@ -157,6 +158,7 @@ class MyParserAdapter:
         """Write merged results back into your document format."""
         ...
 
+
 stitcher = TableStitcher(adapter=MyParserAdapter())
 doc = stitcher.stitch(doc)
 ```
@@ -258,7 +260,13 @@ from typing import Any, List
 import pandas as pd
 from table_stitcher import TableStitcher, MultiPageConfig, TableMeta, LogicalTable
 from table_stitcher.adapters.base import TableStitcherAdapter
-from table_stitcher.merger import tokenize, normalize_col_name, is_numeric_like_colnames, first_row_has_number
+from table_stitcher.merger import (
+    tokenize,
+    normalize_col_name,
+    is_numeric_like_colnames,
+    first_row_has_number,
+)
+
 
 class MyParserAdapter:
     def extract(self, doc: Any, cfg: MultiPageConfig) -> List[TableMeta]:
@@ -281,32 +289,32 @@ class MyParserAdapter:
             # 4. Tokenize first row (fallback similarity signal)
             first_row_tokens = set()
             if df.shape[0] > 0:
-                first_row_tokens = tokenize(
-                    " ".join(str(x) for x in df.iloc[0].tolist())
-                )
+                first_row_tokens = tokenize(" ".join(str(x) for x in df.iloc[0].tolist()))
 
             # 5. Classify: is_headerless, is_header_orphan, is_data_orphan
             raw_columns = [str(c) for c in df.columns]
-            is_headerless = df.attrs.get('is_headerless', False)
-
-            tables_meta.append(TableMeta(
-                idx=idx,
-                df=df,
-                start_page=start_page,
-                pages=pages,
-                width=df.shape[1],
-                header_tokens=header_tokens,
-                first_row_tokens=first_row_tokens,
-                raw_columns=raw_columns,
-                vert_center=None,       # Set if bbox available
-                vert_top=None,          # Normalized 0-1, 0=top of page
-                vert_bottom=None,       # Normalized 0-1, 1=bottom of page
-                is_header_orphan=False, # True if headers-only, no/few data rows
-                is_data_orphan=False,   # True if data-only, no real headers
-                numeric_like_cols=is_numeric_like_colnames(raw_columns),
-                row_count=df.shape[0],
-                is_headerless=is_headerless,
-            ))
+            is_headerless = df.attrs.get("is_headerless", False)
+
+            tables_meta.append(
+                TableMeta(
+                    idx=idx,
+                    df=df,
+                    start_page=start_page,
+                    pages=pages,
+                    width=df.shape[1],
+                    header_tokens=header_tokens,
+                    first_row_tokens=first_row_tokens,
+                    raw_columns=raw_columns,
+                    vert_center=None,  # Set if bbox available
+                    vert_top=None,  # Normalized 0-1, 0=top of page
+                    vert_bottom=None,  # Normalized 0-1, 1=bottom of page
+                    is_header_orphan=False,  # True if headers-only, no/few data rows
+                    is_data_orphan=False,  # True if data-only, no real headers
+                    numeric_like_cols=is_numeric_like_colnames(raw_columns),
+                    row_count=df.shape[0],
+                    is_headerless=is_headerless,
+                )
+            )
         return tables_meta
 
     def inject(self, doc: Any, logical_tables: List[LogicalTable]) -> Any:
@@ -325,6 +333,7 @@ class MyParserAdapter:
 
         return doc
 
+
 # Use it:
 stitcher = TableStitcher(adapter=MyParserAdapter())
 doc = stitcher.stitch(doc)
@@ -374,6 +383,7 @@ except StitchingError as e:
 
 ```python
 import logging
+
 logging.getLogger("table_stitcher").setLevel(logging.INFO)
 ```
 

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/README.md

@@ -65,8 +65,8 @@ from table_stitcher import stitch_tables
 
 converter = DocumentConverter()
 doc = converter.convert("report.pdf").document
-doc = stitch_tables(doc)                  # merged tables; ready for
-                                          # export_to_markdown() / HTML / LLM
+doc = stitch_tables(doc)  # merged tables; ready for
+# export_to_markdown() / HTML / LLM
 ```
 
 `stitch_tables()` mutates `doc` in place and returns the same object. If you
@@ -94,10 +94,10 @@ Runnable end-to-end scripts live in [`examples/`](examples/):
 from table_stitcher import stitch_tables, MultiPageConfig
 
 config = MultiPageConfig(
-    max_page_gap=1,              # Only merge tables on consecutive pages
-    max_width_difference=2,      # Column count tolerance
-    header_sim_strict=0.6,       # Threshold for repeated header detection
-    stitch_separator="\n",       # Join character for split content
+    max_page_gap=1,  # Only merge tables on consecutive pages
+    max_width_difference=2,  # Column count tolerance
+    header_sim_strict=0.6,  # Threshold for repeated header detection
+    stitch_separator="\n",  # Join character for split content
 )
 
 doc = stitch_tables(doc, config=config)
@@ -110,6 +110,7 @@ from typing import Any, List
 from table_stitcher import TableStitcher, MultiPageConfig, TableMeta, LogicalTable
 from table_stitcher.adapters.base import TableStitcherAdapter
 
+
 class MyParserAdapter:
     def extract(self, doc, cfg: MultiPageConfig) -> List[TableMeta]:
         """Read tables from your document format into TableMeta objects."""
@@ -119,6 +120,7 @@ class MyParserAdapter:
         """Write merged results back into your document format."""
         ...
 
+
 stitcher = TableStitcher(adapter=MyParserAdapter())
 doc = stitcher.stitch(doc)
 ```
@@ -220,7 +222,13 @@ from typing import Any, List
 import pandas as pd
 from table_stitcher import TableStitcher, MultiPageConfig, TableMeta, LogicalTable
 from table_stitcher.adapters.base import TableStitcherAdapter
-from table_stitcher.merger import tokenize, normalize_col_name, is_numeric_like_colnames, first_row_has_number
+from table_stitcher.merger import (
+    tokenize,
+    normalize_col_name,
+    is_numeric_like_colnames,
+    first_row_has_number,
+)
+
 
 class MyParserAdapter:
     def extract(self, doc: Any, cfg: MultiPageConfig) -> List[TableMeta]:
@@ -243,32 +251,32 @@ class MyParserAdapter:
             # 4. Tokenize first row (fallback similarity signal)
             first_row_tokens = set()
             if df.shape[0] > 0:
-                first_row_tokens = tokenize(
-                    " ".join(str(x) for x in df.iloc[0].tolist())
-                )
+                first_row_tokens = tokenize(" ".join(str(x) for x in df.iloc[0].tolist()))
 
             # 5. Classify: is_headerless, is_header_orphan, is_data_orphan
             raw_columns = [str(c) for c in df.columns]
-            is_headerless = df.attrs.get('is_headerless', False)
-
-            tables_meta.append(TableMeta(
-                idx=idx,
-                df=df,
-                start_page=start_page,
-                pages=pages,
-                width=df.shape[1],
-                header_tokens=header_tokens,
-                first_row_tokens=first_row_tokens,
-                raw_columns=raw_columns,
-                vert_center=None,       # Set if bbox available
-                vert_top=None,          # Normalized 0-1, 0=top of page
-                vert_bottom=None,       # Normalized 0-1, 1=bottom of page
-                is_header_orphan=False, # True if headers-only, no/few data rows
-                is_data_orphan=False,   # True if data-only, no real headers
-                numeric_like_cols=is_numeric_like_colnames(raw_columns),
-                row_count=df.shape[0],
-                is_headerless=is_headerless,
-            ))
+            is_headerless = df.attrs.get("is_headerless", False)
+
+            tables_meta.append(
+                TableMeta(
+                    idx=idx,
+                    df=df,
+                    start_page=start_page,
+                    pages=pages,
+                    width=df.shape[1],
+                    header_tokens=header_tokens,
+                    first_row_tokens=first_row_tokens,
+                    raw_columns=raw_columns,
+                    vert_center=None,  # Set if bbox available
+                    vert_top=None,  # Normalized 0-1, 0=top of page
+                    vert_bottom=None,  # Normalized 0-1, 1=bottom of page
+                    is_header_orphan=False,  # True if headers-only, no/few data rows
+                    is_data_orphan=False,  # True if data-only, no real headers
+                    numeric_like_cols=is_numeric_like_colnames(raw_columns),
+                    row_count=df.shape[0],
+                    is_headerless=is_headerless,
+                )
+            )
         return tables_meta
 
     def inject(self, doc: Any, logical_tables: List[LogicalTable]) -> Any:
@@ -287,6 +295,7 @@ class MyParserAdapter:
 
         return doc
 
+
 # Use it:
 stitcher = TableStitcher(adapter=MyParserAdapter())
 doc = stitcher.stitch(doc)
@@ -336,6 +345,7 @@ except StitchingError as e:
 
 ```python
 import logging
+
 logging.getLogger("table_stitcher").setLevel(logging.INFO)
 ```
 

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "table-stitcher"
-version = "0.4.2"
+version = "0.4.4"
 description = "Reassemble tables split across page boundaries in PDF extraction"
 readme = "README.md"
 license = "MIT"

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/src/table_stitcher/adapters/README.md

@@ -104,9 +104,9 @@ A few structural constants live at the top of `docling.py` rather than
 in `MultiPageConfig`:
 
 ```python
-_MAX_HEADER_CELL_LEN = 30    # header cells typically short; data cells longer
-_DATA_PATTERNS            # regex list for "this cell is data, not header"
-_AUTO_COLNAME_RE          # "Column_N" / "Unnamed: N" parser placeholders
+_MAX_HEADER_CELL_LEN = 30  # header cells typically short; data cells longer
+_DATA_PATTERNS  # regex list for "this cell is data, not header"
+_AUTO_COLNAME_RE  # "Column_N" / "Unnamed: N" parser placeholders
 ```
 
 These are **adapter-intrinsic** — tuning them changes how the adapter

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/src/table_stitcher/adapters/docling.py

@@ -499,6 +499,42 @@ def _reemit_body_row(
     return grid_row, distinct
 
 
+# Jaccard threshold for recognizing a body row as a reprinted continuation
+# header. Combined with Docling's column_header flag — both must hold — so it
+# stays conservative. Matches the merger's header_sim_strict default; the
+# punctuation-agnostic tokenizer makes it tolerant of per-cell OCR drift such
+# as "(S$)" vs "($$)".
+_REPEATED_HEADER_SIM = 0.6
+
+
+def _row_token_set(cells: list[TableCell]) -> set:
+    """Union of tokenized cell text for a grid row (duplicate span cells fold in)."""
+    toks: set = set()
+    for c in cells:
+        if c:
+            toks |= tokenize(getattr(c, "text", "") or "")
+    return toks
+
+
+def _is_reprinted_header(orig_row: list[TableCell], header_sigs: list[set]) -> bool:
+    """True if ``orig_row`` is a reprinted continuation header to drop from the body.
+
+    Docling reprints the column header at the top of each continuation page; on
+    a multi-row header those rows survive the merge as bogus data rows. They are
+    dropped only when BOTH signals agree: Docling flagged the row
+    ``column_header`` AND it is a tokenized match for one of the reconstructed
+    header-block rows. The flag alone is unreliable — Docling over-flags
+    rowspan/continuation *data* rows as headers — so the content match guards
+    against deleting real data.
+    """
+    if not any(getattr(c, "column_header", False) for c in orig_row if c):
+        return False
+    toks = _row_token_set(orig_row)
+    if not toks:
+        return False
+    return any(jaccard(toks, sig) >= _REPEATED_HEADER_SIM for sig in header_sigs)
+
+
 def _dataframe_to_docling_data(
     df: pd.DataFrame,
     original_data: Optional[TableData] = None,
@@ -587,12 +623,15 @@ def _dataframe_to_docling_data(
 
     # --- Build data rows from merged DataFrame ---
     # Index member fragments' original body rows so spanning cells survive the
-    # round-trip (see _index_member_body_rows).
+    # round-trip (see _index_member_rows).
     body_index = _index_member_rows(member_data) if member_data else {}
+    # Tokenized signatures of the reconstructed header block, for dropping
+    # reprinted continuation headers (see _is_reprinted_header).
+    header_sigs = [s for s in (_row_token_set(h) for h in orig_header_rows) if s]
 
-    for i, (_, row) in enumerate(df.iterrows()):
-        table_row_idx = num_header_rows + i
-
+    emitted = 0
+    for _, row in df.iterrows():
+        table_row_idx = num_header_rows + emitted
         row_vals = ["" if (pd.isna(v) or v is None) else str(v) for v in row]
 
         # Re-emit untouched rows from their original grid cells (preserves
@@ -601,9 +640,15 @@ def _dataframe_to_docling_data(
         bucket = body_index.get(tuple(row_vals))
         if bucket:
             orig_row = bucket.pop(0)
+            if header_sigs and _is_reprinted_header(orig_row, header_sigs):
+                # Reprinted header from a continuation page — already present as
+                # the header block; drop it instead of duplicating into the body.
+                log.debug("Dropped reprinted continuation header row from merged body.")
+                continue
             grid_row, distinct = _reemit_body_row(orig_row, table_row_idx, has_row_headers)
             grid.append(grid_row)
             table_cells.extend(distinct)
+            emitted += 1
             continue
 
         grid_row: list[TableCell] = []
@@ -625,8 +670,9 @@ def _dataframe_to_docling_data(
             table_cells.append(cell)
 
         grid.append(grid_row)
+        emitted += 1
 
-    num_total_rows = num_header_rows + len(df)
+    num_total_rows = num_header_rows + emitted
 
     return TableData(num_rows=num_total_rows, num_cols=num_cols, table_cells=table_cells, grid=grid)
 

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/src/table_stitcher/merger.py

@@ -619,13 +619,34 @@ def _build_orphan_merged_table(
     )
 
 
+def _dedupe_labels(labels: list[str]) -> list[str]:
+    """Make labels unique by suffixing repeats (``B, B`` -> ``B, B.1``)."""
+    used: set[str] = set()
+    counts: dict[str, int] = {}
+    out: list[str] = []
+    for label in labels:
+        candidate = label
+        while candidate in used:
+            counts[label] = counts.get(label, 0) + 1
+            candidate = f"{label}.{counts[label]}"
+        used.add(candidate)
+        out.append(candidate)
+    return out
+
+
 def _build_generic_merged_table(
     members: list[int], meta_by_idx: dict[int, TableMeta], cfg: MultiPageConfig
 ) -> tuple[pd.DataFrame, set[int], list[str]]:
     """Build merged table for the general case."""
     base = meta_by_idx[members[0]]
     merged_df = base.df.copy()
-    canonical_cols = [str(c) for c in base.df.columns]
+    # Duplicate header labels are normal in the wild (rowspan/colspan
+    # parsers, 13F voting-authority triplets), but pd.concat cannot align
+    # frames on a non-unique column Index. Merge under deduped labels and
+    # restore the originals on the way out.
+    original_cols = [str(c) for c in base.df.columns]
+    canonical_cols = _dedupe_labels(original_cols)
+    merged_df.columns = canonical_cols
     merged_pages = set(base.pages)
     warnings: list[str] = []
     prev = base
@@ -648,6 +669,7 @@ def _build_generic_merged_table(
         merged_pages.update(m.pages)
         prev = m
 
+    merged_df.columns = original_cols + [str(c) for c in merged_df.columns[len(original_cols) :]]
     return merged_df, merged_pages, warnings
 
 

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/tests/integration/conftest.py

@@ -333,7 +333,15 @@ def assert_public_stitch_injects_docling_doc(
         ctx = f"public stitch for members={members}, pages={exp['pages']}"
 
         assert getattr(anchor.data, "num_rows", 0) > 0, f"{ctx}: anchor has no data"
-        if "shape" in exp:
+        if "injected_rows" in exp:
+            # Exact injected row count. Used when injection legitimately differs
+            # from the parser-neutral shape — e.g. reprinted continuation-page
+            # headers are dropped from the body (they remain in the merged
+            # DataFrame but are not duplicated into the stitched document).
+            assert anchor.data.num_rows == exp["injected_rows"], (
+                f"{ctx}: injected rows {anchor.data.num_rows} != expected {exp['injected_rows']}"
+            )
+        elif "shape" in exp:
             # +1 or more for header rows; this guards that merged data was injected.
             assert anchor.data.num_rows >= exp["shape"][0] + 1, (
                 f"{ctx}: anchor rows {anchor.data.num_rows} do not contain merged body"

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/tests/integration/fixtures/headerless-continuation/15-page-druglist.corp.expected.yaml

@@ -37,6 +37,9 @@ logical_tables:
   shape:
   - 500
   - 3
+  # Injection drops the reprinted header block (title + column names) that the
+  # merged DataFrame still carries as its first two rows: 500 - 2 = header(2) + body(498).
+  injected_rows: 500
   columns:
   - Column_0
   - Column_1

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/tests/integration/fixtures/inconsistent-header-detection/covid-misc-labs-4pg.pt2.expected.yaml

@@ -73,6 +73,9 @@ logical_tables:
   shape:
   - 46
   - 6
+  # Injection drops the reprinted column header from the continuation page:
+  # 46 - 1 = header(1) + body(45).
+  injected_rows: 46
   columns:
   - Column_0
   - Column_1

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/tests/integration/fixtures/inconsistent-header-detection/retirement-portfolio.corp.expected.yaml

@@ -23,6 +23,9 @@ logical_tables:
   shape:
   - 145
   - 3
+  # Injection drops the reprinted column header from the continuation pages:
+  # 145 - 1 = header(1) + body(144).
+  injected_rows: 145
   columns:
   - Contribution Type
   - Investment Name

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/tests/test_docling_adapter.py

@@ -388,6 +388,77 @@ class TestBodySpanPreservation:
         assert all(cell.col_span == 1 for cell in td.grid[1])
 
 
+class TestReprintedHeaderDedup:
+    """Reprinted continuation-page headers are dropped from the injected body,
+    but column_header-flagged rows that don't match the header (Docling
+    over-flagging rowspan/continuation data) are kept.
+    """
+
+    @staticmethod
+    def _cell(text, r, c, *, header):
+        return TableCell(
+            text=text,
+            row_span=1,
+            col_span=1,
+            column_header=header,
+            row_header=False,
+            start_row_offset_idx=r,
+            end_row_offset_idx=r + 1,
+            start_col_offset_idx=c,
+            end_col_offset_idx=c + 1,
+        )
+
+    def _table(self, rows: list) -> TableData:
+        grid = []
+        flat = []
+        for r, (cells_text, is_header) in enumerate(rows):
+            grid_row = [self._cell(t, r, c, header=is_header) for c, t in enumerate(cells_text)]
+            grid.append(grid_row)
+            flat.extend(grid_row)
+        return TableData(num_rows=len(rows), num_cols=len(rows[0][0]), table_cells=flat, grid=grid)
+
+    def test_drops_reprinted_header_keeps_misflagged_data(self):
+        # Anchor: 1-row header "(S$)" + one data row.
+        anchor = self._table([(["SECTION", "LIMIT (S$)"], True), (["Death", "100"], False)])
+        # Continuation: header reprinted with OCR drift "($$)", a data row, and
+        # a row Docling wrongly flagged column_header (real data, distinct text).
+        satellite = self._table(
+            [
+                (["SECTION", "LIMIT ($$)"], True),
+                (["Injury", "50"], False),
+                (["Sub-limit per accident", "999"], True),
+            ]
+        )
+        # Merged DataFrame: the merger concatenates everything, including the
+        # reprinted header and the mis-flagged row.
+        merged_df = pd.DataFrame(
+            [
+                ["Death", "100"],
+                ["SECTION", "LIMIT ($$)"],
+                ["Injury", "50"],
+                ["Sub-limit per accident", "999"],
+            ],
+            columns=["Column_0", "Column_1"],
+        )
+
+        td = _dataframe_to_docling_data(
+            merged_df, original_data=anchor, member_data=[anchor, satellite]
+        )
+
+        body = [r for r in td.grid if not any(getattr(c, "column_header", False) for c in r if c)]
+        body_text = " ".join(str(c.text) for r in body for c in r if c)
+
+        # Reprinted header (drifted) dropped from the body...
+        assert "($$)" not in body_text
+        # ...but the header block still carries the anchor's "(S$)".
+        assert any("(S$)" in (c.text or "") for r in td.grid for c in r if c)
+        # Real data preserved, including the column_header-mis-flagged row.
+        assert "Death" in body_text and "Injury" in body_text
+        assert "Sub-limit per accident" in body_text and "999" in body_text
+        # 1 header row + 3 body rows (one reprinted header removed from 4).
+        assert td.num_rows == 4
+
+
 class TestAdapterProtocol:
     """Verify DoclingAdapter satisfies the protocol."""
 

{table_stitcher-0.4.2 → table_stitcher-0.4.4}/tests/test_merger.py

@@ -228,6 +228,50 @@ class TestWidthOverflowPolicy:
             align_dataframe_to_header(df, ["A"], meta, cfg)
 
 
+class TestDuplicateHeaderLabels:
+    def test_merge_survives_duplicate_header_labels(self):
+        """
+        Extracted headers repeating a label (e.g. 13F voting-authority
+        triplets emitting 'COLUMN 8' x3) must not crash the multipage
+        merge: pd.concat cannot align frames on a non-unique column Index.
+        """
+        cols = ["A", "B", "B"]
+        df1 = pd.DataFrame([["1", "2", "3"]], columns=cols)
+        df2 = pd.DataFrame([["4", "5", "6"]], columns=cols)
+        metas = [
+            _make_meta(idx=0, df=df1, start_page=1),
+            _make_meta(idx=1, df=df2, start_page=2),
+        ]
+        results = merge_multipage_tables(metas, MultiPageConfig())
+        assert len(results) == 1
+        assert results[0].df.shape == (2, 3)
+        assert results[0].df.iloc[1].tolist() == ["4", "5", "6"]
+        # Original (duplicated) labels are preserved in the output, matching
+        # how single-fragment tables pass through untouched.
+        assert list(results[0].df.columns) == cols
+
+    def test_duplicate_labels_with_wider_continuation(self):
+        cols = ["A", "B", "B"]
+        df1 = pd.DataFrame([["1", "2", "3"]], columns=cols)
+        df2 = pd.DataFrame([["4", "5", "6", "7"]], columns=cols + ["C"])
+        metas = [
+            _make_meta(idx=0, df=df1, start_page=1),
+            _make_meta(idx=1, df=df2, start_page=2),
+        ]
+        results = merge_multipage_tables(metas, MultiPageConfig())
+        assert len(results) == 1
+        assert results[0].df.shape == (2, 4)
+        assert results[0].df.iloc[1, 3] == "7"
+        assert list(results[0].df.columns)[:3] == cols
+
+    def test_dedupe_labels_avoids_existing_suffix_collision(self):
+        from table_stitcher.merger import _dedupe_labels
+
+        out = _dedupe_labels(["X", "X", "X.1"])
+        assert len(set(out)) == 3
+        assert out[0] == "X"
+
+
 class TestMergeTrace:
     def test_logical_table_explains_merge_reason_and_signals(self):
         df = pd.DataFrame({"Name": ["Alice"], "Age": ["30"]})