detect_tables: catch narrow-column undercount via text-cluster topology (#93)

text_cluster_column_undercount previously fired only on tables with
6+ markdown columns. That missed a common production failure shape:
4-column page geometry where the heuristic detector's x-position
clustering collapses 2 narrow numeric columns (dates, IDs, amounts)
into adjacent wider columns, producing 2-column markdown.

The original 6-column floor existed because raw x-cluster count is
noisy on small tables — wrapped continuations, bullet indents, and
within-cell text variation produce many small x-clusters that don't
correspond to real columns. Examples:

  - Pcmso-style 2-column key/value layout with multi-line values
    shows 10 raw x-clusters but only 1 has more than a single item.
  - Yale-style archival catalog with 3 columns shows 6 raw
    x-clusters but most clusters are single-item continuations.

Replace the raw cluster count with a "significant cluster" count:
clusters whose item count is at least 1/4 of the dominant cluster
(and ≥2 items). That filters the within-cell-variation noise while
preserving signal from real columns, which consistently have one
item per row.

With significant-cluster counting:
  - Narrow-undercount fires when significant_clusters >= 3 AND
    significant_clusters >= table_cols * 2 (catches 4-col-collapsed-
    to-2 cases without misfiring on pcmso 10-clusters or yale 6
    where the significant subset matches markdown).
  - Legacy wide-undercount path (table_cols >= 6) keeps the same
    +2 / 1.2x thresholds, now applied to significant clusters
    instead of raw clusters.

Verified against representative regression and must-not-regress
cases from prior PR cycles: narrow-undercount catches genuine
column-drop cases (significant=4, markdown=2 → routes to OCR);
must-not-regress fixtures (italian-gov 6520 chars, pcmso 1733
chars, yale 1754 chars, doc200/182/189 still routing to OCR via
PR #91 guards) unchanged.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Abimael Martell
2026-05-18 17:26:35 -07:00
committed by GitHub
co-authored by Claude Opus 4.7
parent 647ea5c7cd
commit 73cffed1da
2 changed files with 153 additions and 9 deletions
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@firecrawl/pdf-inspector",
"version": "1.8.14",
"version": "1.8.15",
"description": "Fast PDF classification and text extraction. Detect text-based vs scanned PDFs, extract text by region with quality checks. Native Rust performance via napi-rs.",
"main": "index.js",
"types": "index.d.ts",