Skip to content

Give a page its printed number as the unit's label - #825

Merged
kentare merged 2 commits into
mainfrom
feat/633-give-page-printed-number-as
Nov 19, 2026
Merged

kentare merged 2 commits into
mainfrom
feat/633-give-page-printed-number-as

Conversation

@kentare

@kentare kentare commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

What and why

Parts

  • New pageLabels(units) in packages/ingest/src/page-labels.ts, run by doclingParts
  • A page's candidate: its first furniture part, in seq order, that reads as a page number (12, s. 12, side 3 av 9, page 3 of 9, 3/9)
  • Kept only when the nearest labelled page before or after, within 2 pages, has the same offset
  • Only the nearest labelled page on each side is compared, as in the Python rule
  • The label is the number as a string, leading zeros dropped; otherwise null
  • Lone page numbers at a page's edge count: Derive conversion parts from a Docling document #630 made them furniture
  • docling-parts stays version 1; no storage code changes

Docs

  • ADR 0055: status line, Consequences (labels built before parts are stored), the share of labels dropped, and the Measured row
  • docs/adr/README.md: "built with page labels"
More background
  • The issue's acceptance number (70.5 % ± 1) comes from labels_footers.py, which reads only Docling's own furniture
  • Derive conversion parts from a Docling document #630 later made a bare number in the top or bottom 10 % of a page furniture too, so those are candidates here, as ADR 0055 says ("a number in a furniture part of the page")
  • The same script measures that wider rule as rule_plus_body_band_coverage_pct: 73.74 % on seed 7. This PR: 73.70 %
  • Against the Python rule the edge numbers add 424 labelled pages and remove 47: on 18 an edge number comes before the footer and disagrees, on 29 it becomes the nearest neighbour and disagrees
  • Without the edge numbers this code keeps 22 pages fewer than the Python (70.33 %). On 20 of them Docling puts the page header or footer inside a full-page picture, and the walk folds text inside a picture into the picture part
  • Footers written - 12 - are not read: 38 pages (0.34 %) in 2 files of seed 7
  • Leaving the edge numbers out would give about 70.3 %, but needs a flag on the part saying why it is furniture; decided against in the grilling
  • The issue asks for the pattern on whitespace-collapsed text. A part's text is already collapsed and trimmed by the walk (textOf), so pageLabels matches it as it is
  • Roman numerals are not read (ADR 0055, Left)

Closes #633

Risk

Low. Nothing that runs calls doclingParts yet; the units it returns now carry labels.

Undo

Revert is enough.

How it was tested

  • npm run check locally: 7 tests outside the diff timed out at a load average of 57 (Test timed out in 15000ms, no assertion). CI runs the full suite and passes
  • New tests in packages/ingest/src/page-labels.test.ts: "a printed label is kept only when a neighbouring page agrees", "only the nearest labelled page on each side is compared", "a label with no labelled page within 2 pages is dropped", "a chapter number in a page header is not a page label", "side 3 av 9 gives the label 3", "a number in the body is never a label", "a lone page number at the page's edge is a label", "a label drops its leading zeros", "the pattern is linear on a long adversarial string"
  • Each rule switched off once goes red on its test: body parts as candidates, a reach of 3, the last match on a page winning, no neighbour check, any agreeing page within 2 instead of the nearest, zeros kept. A backtracking pattern hangs the linear-time test
  • Run by hand over the 200 files of seed 7 of the local Docling export (the sampling of benchmarks/ingestion/blocks/parts/labels_footers.py):
Measure This PR labels_footers.py
Pages 11,175 11,175
Pages with a kept label 73.70 % 73.74 % (with body edge numbers)
Same, Docling's furniture only - 70.49 %
Kept labels that differ from the physical page 47.5 % -
  • Labels checked against the PDFs: 139 KUDOS PDFs kept locally have Docling output, with 4,765 kept labels (2,544 from footers, 2,126 from headers, 95 lone edge numbers). For 4,660 the number is in the PDF's own text layer in the top or bottom 12 % of the page, read with PDFKit. The 27 + 105 without one (outlined numbers, scans) were spot-checked on rendered pages and are right. Wrong: 2, in one file, where numbered boxes near the top (8, 9) are Docling page headers on two pages in a row. A two-page spread printed 8 and 9 gets the label 9. All 95 edge-number labels are right

  • npm run check passes

Checklist

  • Every new rule has a test whose name states it
  • User-facing text is in the i18n catalogues, in bokmål and English, with no em-dashes
  • Vendor SDKs stay in packages/providers-*
  • ADRs, docs and docs/architecture/modules are updated if a contract, boundary or module changed
  • No secrets, personal data or local paths

doclingParts fills each page unit's label from the first furniture part on
the page that reads as a page number, kept only when the nearest labelled
page within 2 pages before or after has the same offset. Lone page numbers
at a page's edge count, since docling-parts makes them furniture: on seed 7
of the Docling export 73.70 % of pages keep a label, against 73.74 % for
labels_footers.py with body edge numbers.
Pin the nearest-neighbour rule with a test, say in ADR 0055 that labels
are built and how many the wider rule drops, and keep comments to one line.
@kentare

kentare commented Nov 19, 2026

Copy link
Copy Markdown
Contributor Author

Ready for review. Blind review, a claim-checking review and a check of the fixes are done and CI passes. Open: lone page numbers at a page's edge count as labels, so seed 7 keeps 73.70 % against the issue's 70.5 % (the target moved to 73.74 %, see the comment on #633). #824 edits the same ADR 0055 lines and says parts are stored without labels: merging this one first keeps docling-parts at version 1.

@kentare
kentare marked this pull request as ready for review November 19, 2026 13:46
@kentare
kentare added this pull request to the merge queue Nov 19, 2026

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 findings, 0 Important. The summary comment has the overview.

| Pages with a character outside the BMP | 0.05 and 0.16 % | same |
| Tables with merged cells | 26 % | same |
| Pages with a printed label kept by the rule | 70.5 and 66.2 % | same |
| Pages with a printed label kept by the rule | 70.5 and 66.2 %; 73.7 % in the first with lone edge numbers, as `docling-parts` reads | same |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: New ADR label figures not backed by benchmark scripts or results

The Measurements section says its numbers come from the scripts and results in benchmarks/ingestion/blocks/parts/. The new figures (73.7 % of pages labelled, and 2.5 % of labels not kept at line 161) appear in neither. The committed script also does not count lone page numbers at a page's edge as furniture, so nobody can reproduce them.

Rule: Docs and ADRs that claim more than the code does

Evidence and fix

Evidence: Line 116 of the ADR says the scripts and results are in benchmarks/ingestion/blocks/parts/. results.md:63 records only 70.5 % and 66.2 %. git grep -n "73\.7" -- benchmarks docs finds no match under benchmarks/ingestion/blocks/parts. labels_footers.py and stats.py only treat text as a label source when it is furniture or a page_header, page_footer or page_number label, and have no edge-number rule.

Fix: Add the run that produced 73.7 % and 2.5 % to benchmarks/ingestion/blocks/parts/results.md, and extend labels_footers.py with the lone-edge-number rule. If that is not possible, remove the two new figures from lines 131 and 161.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Holds: no script in the repository gave 73.7 % or 2.5 %. #825 merged before the fix, so it is in #831: results.md gets the coverage labels_footers.py already prints with lone edge numbers counted (73.7 % and 69.1 %), the ADR cites those, and the 2.5 % is dropped.

@github-actions

Copy link
Copy Markdown
Contributor

Model review

1 finding: 1 open, 0 fixed, 0 dismissed.

Walkthrough

The pull request makes doclingParts give each page unit a printed page label. A new pageLabels function takes the first furniture part on a page that reads as a page number (12, s. 12, side 3 av 9) and keeps it only when the nearest labelled page within 2 pages on either side has the same offset from the physical page. ADR 0055 and the ADR index now say that labels are built, and give new coverage figures.

Area What changes
packages/ingest Adds pageLabels in page-labels.ts with its tests, and doclingParts now sets each unit's label from it instead of always returning null.
docs/adr ADR 0055's status, measurements, rationale and consequences, and the ADR index row, now say that printed page labels are built, with new figures for lone page numbers at a page's edge.

Findings

Where Finding Status
Nit docs/adr/0055-conversion-parts.md:131 New ADR label figures not backed by benchmark scripts or results
Docs and ADRs that claim more than the code does
Open
Fix the open findings with your coding agent
Fix these review findings on digdir/genki#825. Read each thread first; if a finding is wrong, reply in the thread instead of changing code. Add or update a test for each fix, then run npm run check.

1. docs/adr/0055-conversion-parts.md:131: New ADR label figures not backed by benchmark scripts or results
   Fix: Add the run that produced 73.7 % and 2.5 % to `benchmarks/ingestion/blocks/parts/results.md`, and extend `labels_footers.py` with the lone-edge-number rule. If that is not possible, remove the two new figures from lines 131 and 161.

Reviewed at 426a461 with claude-opus-5-5 in 1.2 min. Pushes are checked against open findings, and fixed ones are resolved. Add the label review again to review new commits.

Merged via the queue into main with commit f90faa6 Nov 19, 2026
22 checks passed
@kentare
kentare deleted the feat/633-give-page-printed-number-as branch November 19, 2026 13:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Give a page its printed number as the unit's label

1 participant