table2rules 0.5.2__tar.gz → 0.6.1__tar.gz

{table2rules-0.5.2/src/table2rules.egg-info → table2rules-0.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: table2rules
-Version: 0.5.2
+Version: 0.6.1
 Summary: Convert HTML tables to flat, LLM-friendly rules using spatial pathfinding.
 Author: PebbleRoad Pte Ltd
 License-Expression: MIT

{table2rules-0.5.2 → table2rules-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "table2rules"
-version = "0.5.2"
+version = "0.6.1"
 description = "Convert HTML tables to flat, LLM-friendly rules using spatial pathfinding."
 readme = "README.md"
 license = "MIT"

{table2rules-0.5.2 → table2rules-0.6.1}/src/table2rules/_core.py

@@ -211,6 +211,11 @@ def _build_rules(grid) -> List[LogicRule]:
     for row_idx in range(len(grid)):
         if row_idx in rows_with_value:
             continue
+        # A label-only row promoted to a row-group ancestor (scope="rowgroup")
+        # is threaded into the value lines beneath it — emitting it here too
+        # would duplicate it as an orphan label.
+        if any(grid[row_idx][c].get("scope") == "rowgroup" for c in range(n_cols)):
+            continue
         # Anchor the rule at the row's data column so it satisfies the quality
         # gate's "rules originate from <td>" invariant. A row with no <td> at
         # all is a true full-width <th colspan> divider — already handled as a
@@ -247,6 +252,220 @@ def _build_rules(grid) -> List[LogicRule]:
     return rules
 
 
+def _mark_rowgroup_bands(grid) -> None:
+    """Promote value-region-wide body dividers to ``<th scope="rowgroup">`` so
+    the maze threads them into each value line's row path as bounded, nested
+    row-group ancestors — the row-side counterpart of the multi-level column
+    header path.
+
+    A candidate is a body cell whose span reaches the last column and covers a
+    majority of the grid (``is_full_width_note`` geometry): a section band
+    (full width) or a group header / description spanning the value region. A
+    candidate is promoted only when its extent contains at least one real data
+    row — so a standalone trailing note (which groups nothing) is left as a
+    note and still emitted, never stranded as an empty-extent rowgroup. Nested
+    candidates are bounded by colspan: a band's extent ends at the next
+    candidate whose span is equal or wider. Cells already marked
+    ``scope="rowgroup"`` by the source are honored as-is.
+    """
+    if not grid or not grid[0]:
+        return
+    n_cols = len(grid[0])
+    # Column-header texts. A full-width body cell that merely repeats a column
+    # header (a units caption like "(In thousands, except per share data)"
+    # reprinted between sections) is an annotation, not a row-group divider —
+    # promoting it would stamp it onto every row path (where it is already noise
+    # in the column path). Exclude such echoes.
+    header_texts = {
+        (cell.get("text") or "").strip().lower()
+        for row in grid
+        for cell in row
+        if cell and cell.get("is_thead") and (cell.get("text") or "").strip()
+    }
+    candidates = []  # (row, col, colspan)
+    for r in range(len(grid)):
+        for c in range(n_cols):
+            cell = grid[r][c]
+            if not cell or cell.get("is_span_copy"):
+                continue
+            if cell.get("is_thead") or cell.get("is_header_row"):
+                continue
+            text = (cell.get("text") or "").strip()
+            if not text:
+                continue
+            if text.lower() in header_texts:
+                continue
+            if is_full_width_note(c, cell.get("colspan", 1), n_cols):
+                candidates.append((r, c, cell.get("colspan", 1)))
+    candidate_rows = {r for (r, _c, _cs) in candidates}
+
+    def _next_band_below(after_row: int, min_colspan: int) -> int:
+        for rr in range(after_row + 1, len(grid)):
+            if any(r == rr and cs >= min_colspan for (r, _c, cs) in candidates):
+                return rr
+        return len(grid)
+
+    for r, c, cs in candidates:
+        extent_end = _next_band_below(r, cs) - 1
+        has_data_row = False
+        for rr in range(r + 1, extent_end + 1):
+            if rr in candidate_rows:
+                continue
+            if any(
+                grid[rr][cc]["type"] == "td" and (grid[rr][cc].get("text") or "").strip()
+                for cc in range(n_cols)
+            ):
+                has_data_row = True
+                break
+        if not has_data_row:
+            continue
+        for cc in range(c, min(c + cs, n_cols)):
+            grid[r][cc]["type"] = "th"
+            grid[r][cc]["scope"] = "rowgroup"
+
+
+def _mark_label_only_rowgroups(grid) -> None:
+    """Promote *label-only rows* to ``<th scope="rowgroup">`` so the maze threads
+    them into each value line's row path, the row-side counterpart of the
+    full-width band handled by :func:`_mark_rowgroup_bands`.
+
+    A label-only row is a body row whose value (``<td>``) columns are all empty
+    while a leading label column carries text — the ``Label | Value`` form
+    pervasive in financial/insurance schedules (``9. Trip Cancellation | (empty)``
+    above its value rows). Unlike a full-width band the label cell does *not*
+    span the value region; the other columns are simply empty, so
+    ``is_full_width_note`` geometry never sees it. Without this pass the row is
+    emitted as an orphaned ``is_label`` rule and the values beneath it lose their
+    group identity.
+
+    Detection is geometric, not flag-based: a row with no value-bearing ``<td>``
+    but exactly one non-empty body ``<th>`` label source cell. (Row-label
+    columns are already promoted to ``<th scope="row">`` upstream — Signal A/B/C
+    in grid_parser and simple_repair — so "no non-empty ``<td>``" means "no
+    value".)
+
+    The single-label-cell requirement is what separates a group header from a
+    data row whose *designated* value columns merely happen to be empty. A genuine
+    group header carries one title ("9. Trip Cancellation", possibly spanning the
+    first N>1 columns via one ``colspan`` cell). A data row whose value columns
+    are blank ("Average: | 80.2 | 10.7 | 3.3", or a summary row under a header
+    that over-promoted numeric columns to row labels) spreads several distinct
+    values across its label cells — threading those as a group path would invent
+    a breadcrumb and misattribute it to the rows below. Such rows stay on the
+    ``is_label`` preservation path, unchanged.
+
+    Stacking and extent (no content-aware level inference):
+
+    * A maximal run of *consecutive* label-only rows forms one header stack. Its
+      members are threaded as nested ancestors in row order — a title followed by
+      a description (``10. Travel Delay`` then ``If the departure…``) both land in
+      the path, title first.
+    * A stack's extent runs from just below the stack down to the row before the
+      next stack OR the next full-width band, whichever comes first — so a group
+      never leaks into the next line-item or across a section divider.
+    * A stack is promoted only when its extent holds a real value row (parity
+      with the full-width-note guard): a trailing label that groups nothing is
+      left for the ``is_label`` preservation path, never stranded as an
+      empty-extent rowgroup.
+
+    The stored ``rowgroup_extent_end`` is what the maze honors for these bands;
+    full-width bands keep their colspan-bounded extent. The two compose: a
+    section band (wider) and a label-only group (narrower) nest consistently.
+    """
+    if not grid or not grid[0]:
+        return
+    n_rows = len(grid)
+    n_cols = len(grid[0])
+
+    def _is_body_row(r: int) -> bool:
+        return not any(
+            grid[r][c].get("is_thead") or grid[r][c].get("is_header_row") for c in range(n_cols)
+        )
+
+    def _has_value(r: int) -> bool:
+        return any(
+            grid[r][c]["type"] == "td" and (grid[r][c].get("text") or "").strip()
+            for c in range(n_cols)
+        )
+
+    def _label_cols(r: int) -> List[int]:
+        cols: List[int] = []
+        for c in range(n_cols):
+            cell = grid[r][c]
+            if cell.get("is_thead") or cell.get("is_header_row"):
+                continue
+            if cell["type"] != "th":
+                continue
+            if cell.get("is_span_copy"):
+                # A span copy of a label cell originating in this same row is
+                # part of a multi-column label (label spans the first N>1
+                # columns); promote it too. A span copy reaching down from a
+                # row above is not a label of this row.
+                origin = cell.get("origin", (r, c))
+                if origin[0] != r:
+                    continue
+                if not (grid[origin[0]][origin[1]].get("text") or "").strip():
+                    continue
+            elif not (cell.get("text") or "").strip():
+                continue
+            cols.append(c)
+        return cols
+
+    def _single_label_origin(r: int) -> bool:
+        # A group header is exactly one label source cell (a title, possibly
+        # colspan'd). More than one distinct non-empty label cell means a data
+        # row, not a divider — do not thread it.
+        origins = set()
+        for c in _label_cols(r):
+            cell = grid[r][c]
+            origins.add(cell.get("origin", (r, c)) if cell.get("is_span_copy") else (r, c))
+        return len(origins) == 1
+
+    # A row already carrying a rowgroup cell (a full-width band promoted above,
+    # or a source scope="rowgroup") is a boundary, not a label-only candidate.
+    band_rows = {
+        r for r in range(n_rows) for c in range(n_cols) if grid[r][c].get("scope") == "rowgroup"
+    }
+
+    is_label_row = [
+        _is_body_row(r)
+        and r not in band_rows
+        and not _has_value(r)
+        and bool(_label_cols(r))
+        and _single_label_origin(r)
+        for r in range(n_rows)
+    ]
+
+    r = 0
+    while r < n_rows:
+        if not is_label_row[r]:
+            r += 1
+            continue
+        # Gather the maximal consecutive run of label-only rows.
+        s_start = r
+        while r + 1 < n_rows and is_label_row[r + 1]:
+            r += 1
+        s_end = r
+        r += 1  # advance past the stack for the outer loop
+
+        # Extent: down to the row before the next boundary (next label stack or
+        # full-width band). Bounded by a value row's presence.
+        extent_end = n_rows - 1
+        for rr in range(s_end + 1, n_rows):
+            if is_label_row[rr] or rr in band_rows:
+                extent_end = rr - 1
+                break
+        has_data_row = any(_has_value(rr) for rr in range(s_end + 1, extent_end + 1))
+        if not has_data_row:
+            continue
+
+        for rr in range(s_start, s_end + 1):
+            for c in _label_cols(rr):
+                grid[rr][c]["type"] = "th"
+                grid[rr][c]["scope"] = "rowgroup"
+                grid[rr][c]["rowgroup_extent_end"] = extent_end
+
+
 def _process_table_with_gate(table_html: str) -> Tuple[List[LogicRule], GateResult]:
     """Runs the full pipeline and returns rules plus the gate verdict.
 
@@ -264,6 +483,8 @@ def _process_table_with_gate(table_html: str) -> Tuple[List[LogicRule], GateResu
     if not grid:
         return [], GateResult(ok=False, score=0.0, reasons=["empty_grid"])
 
+    _mark_rowgroup_bands(grid)
+    _mark_label_only_rowgroups(grid)
     rules = clean_rules(_build_rules(grid))
     gate = assess_confidence(grid, rules)
     if not gate.ok:

{table2rules-0.5.2 → table2rules-0.6.1}/src/table2rules/grid_parser.py

@@ -465,6 +465,28 @@ def parse_table_to_grid(table: Tag) -> List[List[Dict[str, Any]]]:
                 continue
             promote_cols.add(c)
 
+        # --- Signal C: stub-dimension columns under the leftmost top-level
+        # header group ---
+        # When the leftmost top-level (row 0) header spans more than one column
+        # AND a distinct value-header group exists to its right, that leftmost
+        # group is the row-label dimension (e.g. a "SECTION" header spanning the
+        # rownum and person-class columns, beside a "MAXIMUM LIMIT" value group).
+        # Its descriptor columns are row labels even though they carry thead text
+        # — promoting them threads the row identity (the person-class) into each
+        # value line, not just the leading rownum, mirroring the column path.
+        top0 = grid[0][0] if grid and grid[0] else None
+        if top0 and top0.get("is_thead"):
+            stub_origin = top0.get("origin", (0, 0)) if top0.get("is_span_copy") else (0, 0)
+            stub_cell = grid[stub_origin[0]][stub_origin[1]]
+            stub_width = stub_cell.get("colspan", 1) if stub_cell else 1
+            has_value_group_right = stub_width < max_cols and any(
+                has_thead_text[c] for c in range(stub_width, max_cols)
+            )
+            if stub_width >= 2 and has_value_group_right:
+                for c in range(stub_width):
+                    if _descriptor_like(c):
+                        promote_cols.add(c)
+
         if promote_cols:
             for c in sorted(promote_cols):
                 for r in range(data_start_row_idx, len(grid)):

{table2rules-0.5.2 → table2rules-0.6.1}/src/table2rules/maze_pathfinder.py

@@ -116,51 +116,88 @@ def find_headers_for_cell(
             if scope == "row":
                 continue
 
-            # Locate the origin for scope and rowspan lookup.
+            # scope='rowgroup' bands are handled uniformly in Step 4 (which also
+            # reaches bands spanning the data column when the row-label is
+            # empty), so they can be ordered across columns by nesting level.
+            if scope == "rowgroup":
+                continue
+
+            # Non-scope-rowgroup <th> cells outside thead are only accepted from
+            # the explicit header block (headless tables where header detection
+            # promoted a row).
+            if not cell.get("is_header_row", False):
+                continue
+
+            # Locate the origin for dedup.
             if cell.get("is_span_copy", False):
                 origin = cell.get("origin", (r, header_col))
-                origin_cell = grid[origin[0]][origin[1]]
             else:
                 origin = (r, header_col)
-                origin_cell = cell
-
-            if scope == "rowgroup":
-                # A rowgroup header ancestors rows within its extent:
-                #   rowspan > 1  → extent = [origin_row, origin_row + rowspan - 1]
-                #                  (the rowspan itself bounds the group, as in
-                #                  a <th scope="rowgroup" rowspan="2"> pattern)
-                #   rowspan == 1 → extent = [origin_row, next_rowgroup - 1]
-                #                  (a single-cell divider row like a FinTabNet
-                #                  year label runs until the next such divider
-                #                  in the same column)
-                origin_row, origin_col = origin
-                origin_rowspan = origin_cell.get("rowspan", 1)
-                if origin_rowspan > 1:
-                    extent_end = origin_row + origin_rowspan - 1
-                else:
-                    extent_end = len(grid) - 1
-                    for rr in range(origin_row + 1, len(grid)):
-                        other = grid[rr][origin_col]
-                        if (
-                            other
-                            and not other.get("is_span_copy", False)
-                            and other.get("scope") == "rowgroup"
-                        ):
-                            extent_end = rr - 1
-                            break
-                if row > extent_end:
-                    continue
-            else:
-                # Non-scope-rowgroup <th> cells outside thead are only
-                # accepted from the explicit header block (headless
-                # tables where the header detection promoted a row).
-                is_header_row = cell.get("is_header_row", False)
-                if not is_header_row:
-                    continue
 
             if origin not in seen_origins:
                 seen_origins.add(origin)
                 # Insert at the beginning to maintain hierarchy
                 row_headers.insert(row_header_columns.index(header_col), cell["text"])
 
+    # --- 4. Row-group bands ---
+    # A band / group header ancestors the data rows within its extent. Bands are
+    # collected from the data cell's own column AND every row-label column: the
+    # own column reaches bands that span the value region even when this row's
+    # label cell is empty (which would otherwise drop the band, e.g. an
+    # unlabeled continuation row under a group divider); the row-label columns
+    # reach narrow stub-column dividers (a FinTabNet year label). Extent is
+    # bounded by COLSPAN — a band ends at the next band whose span is equal or
+    # wider — so a narrower inner group header does not close an outer one.
+    # Bands are ordered topmost-first (origin row ascending) and prepended, so
+    # the row path reads outer-band > inner-group > row-labels, mirroring the
+    # multi-level column path.
+    bands: List[Tuple[int, str]] = []  # (origin_row, text)
+    for scan_col in [col, *row_header_columns]:
+        for r in range(row - 1, -1, -1):
+            cell = grid[r][scan_col]
+            if not cell or not cell.get("text", "").strip():
+                continue
+            if cell["type"] != "th" or cell.get("is_thead", False):
+                continue
+            if cell.get("scope") != "rowgroup":
+                continue
+            if cell.get("is_span_copy", False):
+                origin = cell.get("origin", (r, scan_col))
+                origin_cell = grid[origin[0]][origin[1]]
+            else:
+                origin = (r, scan_col)
+                origin_cell = cell
+            if origin in seen_origins:
+                continue
+            origin_row, origin_col = origin
+            my_colspan = origin_cell.get("colspan", 1)
+            origin_rowspan = origin_cell.get("rowspan", 1)
+            stored_extent = origin_cell.get("rowgroup_extent_end")
+            if stored_extent is not None:
+                # Label-only bands carry an explicit extent (the run of value
+                # rows they group, bounded by the next stack or section band),
+                # because their colspan=1 label cannot encode nesting depth the
+                # way a full-width band's width does.
+                extent_end = stored_extent
+            elif origin_rowspan > 1:
+                extent_end = origin_row + origin_rowspan - 1
+            else:
+                extent_end = len(grid) - 1
+                for rr in range(origin_row + 1, len(grid)):
+                    other = grid[rr][origin_col]
+                    if (
+                        other
+                        and not other.get("is_span_copy", False)
+                        and other.get("scope") == "rowgroup"
+                        and other.get("colspan", 1) >= my_colspan
+                    ):
+                        extent_end = rr - 1
+                        break
+            if row > extent_end:
+                continue
+            seen_origins.add(origin)
+            bands.append((origin_row, cell["text"]))
+    bands.sort(key=lambda b: b[0])
+    row_headers[:0] = [text for _row, text in bands]
+
     return row_headers, col_headers

{table2rules-0.5.2 → table2rules-0.6.1/src/table2rules.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: table2rules
-Version: 0.5.2
+Version: 0.6.1
 Summary: Convert HTML tables to flat, LLM-friendly rules using spatial pathfinding.
 Author: PebbleRoad Pte Ltd
 License-Expression: MIT