super-document-processor 0.1.3__py3-none-any.whl

super_document_processor/utils/pdf_table_utils.py

@@ -0,0 +1,627 @@
+import re
+
+try:
+    import pymupdf as fitz
+except ImportError:
+    import fitz
+
+
+def join_multiline_cell(lines: list[str]) -> str:
+    """Combine multiple lines within a single cell using <br>, resolving footnote/superscript artifacts and line wraps."""
+    lines = [l.strip() for l in lines if l.strip()]
+    if not lines:
+        return ""
+    if len(lines) == 1:
+        return lines[0]
+
+    # Resolve footnote superscripts on numeric values:
+    # e.g. ['1', '46'] or ['6', '46'] where one element is a 1-digit footnote marker and the other is the metric value
+    cleaned_nums = [
+        re.sub(r"[\s\$,%\(\)\+\-–—]", "", l)
+        for l in lines
+    ]
+    if all(cn.replace(".", "", 1).isdigit() for cn in cleaned_nums if cn):
+        if len(lines) == 2:
+            # If one is a 1-character footnote marker and the other is a full number (>= 2 chars or decimal)
+            if len(cleaned_nums[0]) == 1 and len(cleaned_nums[1]) >= 2:
+                return lines[1]
+            elif len(cleaned_nums[1]) == 1 and len(cleaned_nums[0]) >= 2:
+                return lines[0]
+
+    # Smart line joining: fold mid-sentence wrap continuations, separate bullets/distinct items with <br>
+    bullet_starters = ("-", "•", "➢", "*", "+", "–", "—")
+    combined_items = []
+
+    for line in lines:
+        if not combined_items:
+            combined_items.append(line)
+        else:
+            prev = combined_items[-1]
+            is_bullet = line.startswith(bullet_starters) or bool(re.match(r"^\d+[\.\)]\s+", line))
+            prev_is_bullet = prev.startswith(bullet_starters)
+            prev_ended_clause = prev.endswith((".", ";", ":", "]", ")", "-", "–", "—"))
+
+            # If it's a new bullet point, a header/section tag, or after punctuation, separate with <br>
+            if is_bullet or prev_ended_clause:
+                combined_items.append(line)
+            # If previous line was short (e.g. title/date item like '12th Jun –'), keep as separate item with <br>
+            elif len(prev) < 20 and not prev_is_bullet:
+                combined_items.append(line)
+            else:
+                # Wrap continuation of existing sentence/paragraph
+                combined_items[-1] = f"{prev} {line}"
+
+    return "<br>".join(combined_items)
+
+
+def normalize_cell_value(val: str) -> str:
+    """Clean PDF extraction artifacts from cell text such as broken numbers, spaced decimals, commas, and parens."""
+    if not val:
+        return ""
+
+    v = str(val).replace("\n", " ").replace("|", "¦").strip()
+
+    # Fix spaced commas in numbers: '3 ,092' -> '3,092'
+    v = re.sub(r"(\d+)\s*,\s*(\d+)", r"\1,\2", v)
+
+    # Fix spaced decimals in numbers: '0 .4' -> '0.4'
+    v = re.sub(r"(\d+)\s*\.\s*(\d+)", r"\1.\2", v)
+
+    # Fix spaced parentheses: '( 0.0)' -> '(0.0)'
+    v = re.sub(r"\(\s*([-\d.,%]+)\s*\)", r"(\1)", v)
+
+    # Fix spaced percent signs: '29 %' -> '29%'
+    v = re.sub(r"([-\d.,]+)\s*%", r"\1%", v)
+
+    # Fix space-split numbers including decimals (e.g. '1 03' -> '103', '1 0.7' -> '10.7', '1 2.7' -> '12.7', '2 61' -> '261')
+    if re.match(r"^-?\(?\s*[\d.]+(?:\s+[\d.]+)+\s*\)?%?$", v):
+        v = re.sub(r"(?<=\d)\s+(?=[\d.])", "", v)
+        v = re.sub(r"(?<=\.)\s+(?=\d)", "", v)
+
+    return v.strip()
+
+
+def is_complementary_entangled_pair(cell_lines_A: list[list[str]], cell_lines_B: list[list[str]]) -> bool:
+    """Strictly verify if row A and row B form a complementary pair of entangled rows.
+    Condition:
+    1. Both rows have non-empty Col 0 labels.
+    2. In the columns where Row A has 2+ lines, Row B is completely empty.
+    3. In the columns where Row B has data, Row A has only 1 line (or is empty).
+    4. At least one multi-line column exists in Row A and at least one filled column exists in Row B.
+    """
+    if not cell_lines_A or not cell_lines_B:
+        return False
+    if not (cell_lines_A[0] and cell_lines_B[0]):
+        return False
+
+    num_cols = max(len(cell_lines_A), len(cell_lines_B))
+    has_split_in_A = False
+    has_data_in_B = False
+
+    for c in range(1, num_cols):
+        cl_A = cell_lines_A[c] if c < len(cell_lines_A) else []
+        cl_B = cell_lines_B[c] if c < len(cell_lines_B) else []
+
+        cl_A_filled = [x for x in cl_A if x.strip()]
+        cl_B_filled = [x for x in cl_B if x.strip()]
+
+        if len(cl_A_filled) >= 2:
+            has_split_in_A = True
+            # Row B must NOT have data in this column (conflict guard)
+            if cl_B_filled:
+                return False
+        elif cl_B_filled:
+            has_data_in_B = True
+            # Row A must have at most 1 line in this column
+            if len(cl_A_filled) > 1:
+                return False
+
+    return has_split_in_A and has_data_in_B
+
+
+def unpack_table_spanning_cells(table: fitz.table.Table, page: fitz.Page) -> list[list]:
+    """Unpack multi-column spanning cells that contain collapsed multi-line records
+    using physical PDF word coordinates and column boundaries.
+    """
+    raw_rows = table.extract()
+    if not raw_rows:
+        return []
+
+    has_multiline_spans = any(
+        any(c is None for c in r) and any(c is not None and "\n" in str(c) for c in r)
+        for r in raw_rows
+    )
+    if not has_multiline_spans:
+        return raw_rows
+
+    x_cuts = sorted(list({round(c[0], 2) for c in table.cells} | {round(c[2], 2) for c in table.cells}))
+    num_cols = len(x_cuts) - 1
+    if num_cols != len(raw_rows[0]):
+        return raw_rows
+
+    words = page.get_text("words", clip=fitz.Rect(table.bbox))
+
+    expanded_rows = []
+    for r_idx, r in enumerate(raw_rows):
+        spans = []
+        c = 0
+        while c < len(r):
+            val = r[c]
+            span = 1
+            while c + span < len(r) and r[c + span] is None:
+                span += 1
+            spans.append((c, span, val))
+            c += span
+
+        if not any(span > 1 and val and "\n" in str(val) for c, span, val in spans):
+            expanded_rows.append(r)
+            continue
+
+        r_y0 = table.rows[r_idx].bbox[1] if (hasattr(table, "rows") and r_idx < len(table.rows)) else table.bbox[1]
+        r_y1 = table.rows[r_idx].bbox[3] if (hasattr(table, "rows") and r_idx < len(table.rows)) else table.bbox[3]
+
+        unfolded_spans = []
+        for c_start, span, val in spans:
+            if val is None:
+                unfolded_spans.append([])
+                continue
+            lines_text = [l.strip() for l in str(val).split("\n") if l.strip()]
+            if span == 1 or len(lines_text) <= 1:
+                unfolded_spans.append([[l] for l in lines_text])
+                continue
+
+            x0 = x_cuts[c_start] - 1.0
+            x1 = x_cuts[c_start + span] + 1.0
+
+            # Filter words physically residing within this cell's bounding box
+            cell_words = [
+                w for w in words
+                if x0 <= (w[0] + w[2]) / 2 <= x1 and r_y0 - 1.0 <= (w[1] + w[3]) / 2 <= r_y1 + 1.0
+            ]
+            cell_words.sort(key=lambda w: (w[1], w[0]))
+
+            # Group words by visual line height
+            line_groups = []
+            for w in cell_words:
+                mid_y = (w[1] + w[3]) / 2
+                placed = False
+                for lg in line_groups:
+                    if abs(mid_y - lg["y_mid"]) < 4.0:
+                        lg["words"].append(w)
+                        lg["y_mid"] = sum((word[1] + word[3]) / 2 for word in lg["words"]) / len(lg["words"])
+                        placed = True
+                        break
+                if not placed:
+                    line_groups.append({"y_mid": mid_y, "words": [w]})
+            line_groups.sort(key=lambda lg: lg["y_mid"])
+
+            cell_rows = []
+            for l_idx, lg in enumerate(line_groups):
+                l_words = sorted(lg["words"], key=lambda w: w[0])
+                if l_idx == 0:
+                    # Top-level banner across the entire spanning span
+                    slot_row = [""] * span
+                    slot_row[0] = " ".join(w[4] for w in l_words)
+                    cell_rows.append(slot_row)
+                else:
+                    # Assign each word to its exact column slot based purely on its physical x-center
+                    slot_row = [""] * span
+                    for w in l_words:
+                        w_mid = (w[0] + w[2]) / 2
+                        slot = min(
+                            range(span),
+                            key=lambda s: 0 if (x_cuts[c_start + s] - 1.0 <= w_mid <= x_cuts[c_start + s + 1] + 1.0)
+                            else abs(w_mid - (x_cuts[c_start + s] + x_cuts[c_start + s + 1]) / 2)
+                        )
+                        if slot_row[slot]:
+                            slot_row[slot] += " " + w[4]
+                        else:
+                            slot_row[slot] = w[4]
+                    cell_rows.append(slot_row)
+            unfolded_spans.append(cell_rows)
+
+        max_lines = max(len(us) for us in unfolded_spans)
+        for line_idx in range(max_lines):
+            curr_row = [""] * len(r)
+            for s_idx, (c_start, span, val) in enumerate(spans):
+                us = unfolded_spans[s_idx]
+                if not us:
+                    continue
+                # Col 0 alignment: if Col 0 has 1 fewer line (missing subheader row)
+                if c_start == 0 and len(us) == max_lines - 1:
+                    if line_idx == 0:
+                        curr_row[0] = us[0][0] if us[0] else ""
+                    elif line_idx == 1:
+                        curr_row[0] = ""
+                    else:
+                        curr_row[0] = us[line_idx - 1][0] if line_idx - 1 < len(us) and us[line_idx - 1] else ""
+                    continue
+
+                if line_idx < len(us):
+                    for k in range(min(span, len(us[line_idx]))):
+                        curr_row[c_start + k] = us[line_idx][k]
+            expanded_rows.append(curr_row)
+
+    return expanded_rows
+
+
+def unflatten_multiline_data_rows(rows: list[list]) -> list[list]:
+    """If a table row contains multiple parallel rows of data collapsed into a single
+    vector cell block (due to missing horizontal vector lines in the PDF), unflatten them into
+    distinct individual rows based strictly on structural geometry.
+    """
+    if not rows:
+        return []
+
+    result = []
+    idx = 0
+    num_rows = len(rows)
+
+    while idx < num_rows:
+        row = rows[idx]
+        cell_lines = []
+        for cell in row:
+            if cell is None:
+                cell_lines.append([])
+            else:
+                lines = [l.strip() for l in str(cell).split("\n") if l.strip()]
+                cell_lines.append(lines)
+
+        max_lines = max(len(cl) for cl in cell_lines[1:]) if len(cell_lines) > 1 else (len(cell_lines[0]) if cell_lines else 1)
+
+        if max_lines <= 1:
+            result.append(row)
+            idx += 1
+            continue
+
+        # Case 1: Col 0 contains all row labels for the multiple rows
+        if cell_lines and len(cell_lines[0]) >= max_lines:
+            for line_idx in range(max_lines):
+                sub_row = []
+                for cl in cell_lines:
+                    val = cl[line_idx] if line_idx < len(cl) else ""
+                    sub_row.append(val)
+                result.append(sub_row)
+            idx += 1
+            continue
+
+        # Case 2: Strictly verify if row idx and row idx + 1 are a complementary entangled pair
+        if idx + 1 < num_rows:
+            next_row = rows[idx + 1]
+            next_cell_lines = []
+            for cell in next_row:
+                if cell is None:
+                    next_cell_lines.append([])
+                else:
+                    next_cell_lines.append([l.strip() for l in str(cell).split("\n") if l.strip()])
+
+            if is_complementary_entangled_pair(cell_lines, next_cell_lines):
+                num_cols = max(len(cell_lines), len(next_cell_lines))
+                row_A = []
+                row_B = []
+
+                for c in range(num_cols):
+                    cl_A = cell_lines[c] if c < len(cell_lines) else []
+                    cl_B = next_cell_lines[c] if c < len(next_cell_lines) else []
+
+                    if c == 0:
+                        row_A.append(cl_A[0] if cl_A else "")
+                        row_B.append(cl_B[0] if cl_B else "")
+                    else:
+                        if len(cl_A) >= 2:
+                            row_A.append(cl_A[0])
+                            row_B.append(cl_A[1])
+                        elif len(cl_A) == 1:
+                            row_A.append(cl_A[0])
+                            row_B.append(cl_B[0] if cl_B else "")
+                        else:
+                            row_A.append("")
+                            row_B.append(cl_B[0] if cl_B else "")
+
+                result.append(row_A)
+                result.append(row_B)
+                idx += 2
+                continue
+
+        # Otherwise, keep as 1 row so join_multiline_cell handles wrapped paragraphs/bullets
+        result.append(row)
+        idx += 1
+
+    return result
+
+
+def merge_super_headers(rows: list[list[str]]) -> list[list[str]]:
+    """Detect leading 2-tier super headers (where category banners span across columns in Row 0)
+    and fuse them with sub-column headers.
+    """
+    if len(rows) < 2:
+        return rows
+
+    num_cols = max(len(r) for r in rows)
+    norm_rows = [r + [""] * (num_cols - len(r)) for r in rows]
+
+    r0_filled = [c for c in norm_rows[0] if c.strip() != ""]
+
+    # Super-headers require at least 2 distinct banners in Row 0 spanning subsets of columns
+    if len(r0_filled) < 2 or len(r0_filled) >= num_cols * 0.7:
+        return norm_rows
+
+    header_rows = norm_rows[:2]
+    data_rows = norm_rows[2:]
+
+    # Forward-fill category banners across columns
+    filled_header_rows = []
+    for h_row in header_rows:
+        filled_r = []
+        curr = ""
+        non_empty = [c for c in h_row if c.strip()]
+        is_sparse_banner = (1 <= len(non_empty) < num_cols * 0.7)
+        for c in h_row:
+            if c.strip():
+                curr = c
+            filled_r.append(curr if is_sparse_banner else c)
+        filled_header_rows.append(filled_r)
+
+    # Build unified headers column by column
+    merged_headers = []
+    for col_idx in range(num_cols):
+        top_val = filled_header_rows[0][col_idx].strip()
+        bot_val = filled_header_rows[1][col_idx].strip()
+
+        if col_idx == 0:
+            # For Col 0, use top_val or bot_val (e.g. 'Particulars (Rs Mn)' or 'Category')
+            raw_top = header_rows[0][0].strip()
+            raw_bot = header_rows[1][0].strip()
+            if raw_top and raw_bot and raw_top != raw_bot:
+                if raw_bot.startswith("(") and raw_bot.endswith(")"):
+                    merged_headers.append(f"{raw_top} {raw_bot}")
+                else:
+                    merged_headers.append(f"{raw_top} ({raw_bot})")
+            else:
+                merged_headers.append(raw_top or raw_bot)
+        else:
+            if top_val and bot_val and top_val != bot_val:
+                if bot_val.startswith("(") and bot_val.endswith(")"):
+                    merged_headers.append(f"{top_val} {bot_val}")
+                else:
+                    merged_headers.append(f"{top_val} ({bot_val})")
+            else:
+                merged_headers.append(top_val or bot_val)
+
+    return [merged_headers] + data_rows
+
+
+def clean_table(rows: list[list]) -> list[list[str]]:
+    """Clean extracted table cells, unflatten collapsed rows, join multiline cells, and drop empty columns."""
+    if not rows:
+        return []
+
+    rows = unflatten_multiline_data_rows(rows)
+
+    cleaned_rows = []
+    for idx_r, r in enumerate(rows):
+        cleaned_row = []
+        for cell in r:
+            if cell is None:
+                val = ""
+            else:
+                lines = [line.strip() for line in str(cell).split("\n") if line.strip()]
+                val = join_multiline_cell(lines)
+
+            val = normalize_cell_value(val)
+            cleaned_row.append(val)
+
+        # Keep row if it has content or is an empty separator row between data sections
+        has_content = any(c.strip() != "" for c in cleaned_row)
+        if has_content:
+            cleaned_rows.append(cleaned_row)
+        elif cleaned_rows and idx_r < len(rows) - 1:
+            has_future_content = any(any(str(c or "").strip() != "" for c in next_r) for next_r in rows[idx_r + 1:])
+            if has_future_content:
+                cleaned_rows.append(cleaned_row)
+
+    # Fix parenthesis spillover between adjacent columns (e.g., Col0: "(CoM", Col1: ") 7")
+    for r in cleaned_rows:
+        for idx in range(len(r) - 1):
+            if r[idx].endswith("(") or (r[idx].count("(") > r[idx].count(")")):
+                if r[idx + 1].startswith(")"):
+                    r[idx] = (r[idx] + ")").strip()
+                    r[idx + 1] = r[idx + 1][1:].strip()
+
+    if not cleaned_rows:
+        return []
+
+    num_cols = max(len(r) for r in cleaned_rows)
+    matrix = [r + [""] * (num_cols - len(r)) for r in cleaned_rows]
+
+    # Filter out completely empty columns
+    valid_col_indices = [c for c in range(num_cols) if any(matrix[r][c] != "" for r in range(len(matrix)))]
+
+    if not valid_col_indices:
+        return []
+
+    matrix = [[row[c] for c in valid_col_indices] for row in matrix]
+    return merge_super_headers(matrix)
+
+
+def format_table_with_pipes(rows: list[list[str]]) -> str:
+    """Format cleaned 2D matrix into a markdown pipe-delimited table string with outer border pipes."""
+    if not rows:
+        return ""
+
+    num_cols = len(rows[0])
+    headers = rows[0]
+    data_rows = rows[1:]
+
+    col_widths = []
+    for col_idx in range(num_cols):
+        max_w = max(len(rows[r_idx][col_idx]) if col_idx < len(rows[r_idx]) else 0 for r_idx in range(len(rows)))
+        col_widths.append(max(max_w, 3))
+
+    header_line = "| " + " | ".join(headers[c].ljust(col_widths[c]) for c in range(num_cols)) + " |"
+    separator_line = "| " + " | ".join("-" * max(col_widths[c], 3) for c in range(num_cols)) + " |"
+
+    lines = [header_line, separator_line]
+    for row in data_rows:
+        row_line = "| " + " | ".join((row[c] if c < len(row) else "").ljust(col_widths[c]) for c in range(num_cols)) + " |"
+        lines.append(row_line)
+
+    return "\n".join(lines)
+
+
+def split_parallel_tables(rows: list[list[str]]) -> list[list[list[str]]]:
+    """Detect if two independent tables placed side-by-side on the page were erroneously
+    merged into a single wide matrix, and separate them into distinct tables.
+    Guarded against false positives from section headers, footnotes, and stepped matrices.
+    """
+    if not rows or len(rows) < 3:
+        return [rows]
+
+    num_cols = max(len(r) for r in rows)
+    if num_cols < 4:
+        return [rows]
+
+    matrix = [r + [""] * (num_cols - len(r)) for r in rows]
+
+    # Guard 1: If Row 0 is an intact, continuous single header across almost all columns (>= 75%),
+    # then it is a single unified table, not two distinct side-by-side tables.
+    r0_filled = sum(1 for c in matrix[0] if str(c or "").strip() != "")
+    if r0_filled >= num_cols * 0.75:
+        return [rows]
+
+    best_split_col = None
+    max_disjoint_score = 0
+
+    for k in range(2, num_cols - 1):
+        left_only_rows = 0
+        right_only_rows = 0
+        shared_rows = 0
+
+        for r in matrix:
+            has_left = any(str(c or "").strip() != "" for c in r[:k])
+            has_right = any(str(c or "").strip() != "" for c in r[k:])
+            if has_left and not has_right:
+                left_only_rows += 1
+            elif has_right and not has_left:
+                right_only_rows += 1
+            elif has_left and has_right:
+                shared_rows += 1
+
+        total_active_rows = left_only_rows + right_only_rows + shared_rows
+        if total_active_rows == 0:
+            continue
+
+        if left_only_rows >= 2 and right_only_rows >= 2:
+            disjoint_score = (left_only_rows + right_only_rows) / total_active_rows
+            if disjoint_score > max_disjoint_score and disjoint_score >= 0.35:
+                # Guard 2: Multi-Column Density Guard
+                # Ensure both left and right sides contain genuine multi-column records
+                # (at least 2 rows with >= 2 filled cells on each side, filtering out 1-cell footnotes)
+                left_dense = sum(1 for r in matrix if sum(1 for c in r[:k] if str(c or "").strip() != "") >= 2)
+                right_dense = sum(1 for r in matrix if sum(1 for c in r[k:] if str(c or "").strip() != "") >= 2)
+
+                if left_dense >= 2 and right_dense >= 2:
+                    max_disjoint_score = disjoint_score
+                    best_split_col = k
+
+    if best_split_col is None:
+        return [rows]
+
+    k = best_split_col
+    left_raw = [[cell for cell in r[:k]] for r in matrix if any(str(c or "").strip() != "" for c in r[:k])]
+    right_raw = [[cell for cell in r[k:]] for r in matrix if any(str(c or "").strip() != "" for c in r[k:])]
+
+    result = []
+    if left_raw and len(left_raw) >= 2:
+        result.append(left_raw)
+    if right_raw and len(right_raw) >= 2:
+        result.append(right_raw)
+
+    return result if result else [rows]
+
+
+def get_all_page_tables(page: fitz.Page) -> list:
+    """Find all tables on the page, prioritizing strict vector-line bordered tables over loose heuristic tables,
+    while selecting heuristic tables only when vector lines suffered row/header collapse.
+    """
+    strict_tables = list(page.find_tables(strategy="lines_strict").tables)
+    def_tables = list(page.find_tables().tables)
+
+    chosen_tables = []
+    handled_def_indices = set()
+
+    for s_tab in strict_tables:
+        s_rect = fitz.Rect(s_tab.bbox)
+        overlapping_def_idx = None
+        for d_idx, d_tab in enumerate(def_tables):
+            if d_idx in handled_def_indices:
+                continue
+            d_rect = fitz.Rect(d_tab.bbox)
+            intersection = s_rect & d_rect
+            if intersection.is_valid and intersection.get_area() > 0.3 * min(s_rect.get_area(), d_rect.get_area()):
+                overlapping_def_idx = d_idx
+                break
+
+        if overlapping_def_idx is not None:
+            handled_def_indices.add(overlapping_def_idx)
+            d_tab = def_tables[overlapping_def_idx]
+            # Only prefer heuristic detection if strict lines completely failed to segment columns
+            if s_tab.col_count <= 1 < d_tab.col_count:
+                chosen_tables.append(d_tab)
+            else:
+                chosen_tables.append(s_tab)
+        else:
+            chosen_tables.append(s_tab)
+
+    for d_idx, d_tab in enumerate(def_tables):
+        if d_idx not in handled_def_indices:
+            chosen_tables.append(d_tab)
+
+    chosen_tables.sort(key=lambda t: (t.bbox[1], t.bbox[0]))
+    return chosen_tables
+
+
+def is_genuine_table(cleaned_rows: list[list[str]], raw_table) -> bool:
+    """Validate that the extracted matrix represents a genuine structured table and not a false-positive
+    callout box, decorative border, or single paragraph container.
+    """
+    if not cleaned_rows or len(cleaned_rows) < 2:
+        return False
+    if len(cleaned_rows[0]) < 2:
+        return False
+
+    raw = (raw_table.extract() if hasattr(raw_table, "extract") else None) or []
+    if len(raw) <= 2:
+        non_empty_per_row = [sum(1 for c in r if c and str(c).strip()) for r in raw]
+        if min(non_empty_per_row, default=0) <= 1 and max(non_empty_per_row, default=0) <= 2:
+            total_chars = sum(len(str(c or "")) for r in raw for c in r)
+            total_cells = sum(non_empty_per_row)
+            if total_cells <= 3 and total_chars > 200:
+                return False
+
+    return True
+
+
+def extract_tables_from_pdf_page(tables: list, page: fitz.Page, page_num: int) -> list:
+    """Extract and format tables from a PDF page using PyMuPDF native table extraction."""
+    found_tables = get_all_page_tables(page)
+    for table in found_tables:
+        raw_rows = unpack_table_spanning_cells(table, page)
+        if not raw_rows:
+            continue
+
+        sub_tables_raw = split_parallel_tables(raw_rows)
+        for sub_raw in sub_tables_raw:
+            cleaned_rows = clean_table(sub_raw)
+            if not is_genuine_table(cleaned_rows, table):
+                continue
+            table_text = format_table_with_pipes(cleaned_rows)
+            if not table_text:
+                continue
+            table_bbox = fitz.Rect(table.bbox)
+            tables.append({
+                "bbox": table_bbox,
+                "text": table_text,
+                "page": page_num,
+            })
+    return tables