pdfsmart

Documentation

Overview

Package pdfsmart extracts a PDF's text page by page, sending only the pages that actually need it through docling instead of the whole document - most PDFs are mostly prose, and paying docling's per-page layout-detection pass (see its standard PDF pipeline) for every page of a large document is wasted work when only a handful of pages have an embedded image or an unreadable native text layer.

A page is routed to docling when:

• it has at least one embedded raster image (a PDF XObject with /Subtype /Image, detected via pdfcpu's own resource inspection - a deterministic read of the file's structure, not a heuristic or an ML classification), or
• its native text layer is too sparse (see pdftext.MinCharsPerPage), or looks like broken font-encoding extraction (see textquality.IsGarbledText).

This deliberately does NOT attempt to detect borderless tables or vector-drawn diagrams/charts - those aren't reliably detectable without a trained layout model (this is exactly why docling itself runs layout detection on every page unconditionally, rather than trying to guess which pages need it). A page containing one is only caught here if its native text also happens to be sparse or garbled; otherwise it's extracted natively, and the caller gets prose-quality text for a page that visually contained a table. Callers that can't accept ever missing a table this way (e.g. financial documents, invoices) should keep sending those documents through docling wholesale instead of this package - see Convert's own doc comment for the exact safety contract.

Index

• type PageResult
• type PageSource
• type Result
  • func Convert(ctx context.Context, data []byte, doclingClient *docling.Client) (Result, bool, error)
  • func (r Result) DoclingPageCount() int

Types

type PageResult

type PageResult struct {
	Page   int
	Text   string
	Source PageSource
}

PageResult is one page's contribution to a Result.

type PageSource

type PageSource string

PageSource identifies how a page's text was obtained.

const (
	PageSourceNative  PageSource = "native"
	PageSourceDocling PageSource = "docling"
)

type Result

type Result struct {
	Markdown string
	Pages    []PageResult
}

Result is the outcome of a page-aware PDF-to-markdown conversion.

func Convert

func Convert(ctx context.Context, data []byte, doclingClient *docling.Client) (Result, bool, error)

Convert extracts data's text page by page (see package doc for the native-vs-docling routing rule per page).

ok is true only when EVERY page produced usable text, whether native or via docling - if even one page that needed docling couldn't get it (docling unavailable, or it returned nothing usable for that specific page), ok is false and Result should be discarded. This is a deliberate safety contract, not an oversight: a partial result missing one page's content is exactly the silent, permanent data loss this package exists to avoid on the pages it CAN cheaply skip docling for - it must never produce that same failure mode on a page it couldn't. Callers should fall back to sending the whole document through docling when ok is false, the same as if this package didn't exist.

func (Result) DoclingPageCount

func (r Result) DoclingPageCount() int

DoclingPageCount reports how many pages were actually routed to docling - a direct measure of how much of the document needed the expensive path, useful for logging/tuning.