Accepts PDF bytes over HTTP POST or WebSocket. Downstream selects oneof t[String, Image, Document, Document.Page]: text or structured document per upload, raster or structured page per selected page. out_1 pairs every out_0 item with its session ID.
Typical backends
PDF text to model to JSON.
Caveats
- I/O contractHandled PDF/page/raster/encoding errors log and return HTTP 422 or WebSocket 1011; listener continues. Image/Page may emit pages before failure; String/Document emit nothing for that upload. Listener/output stream/type errors end the worker. Image/Page stream; String/Document buffer.
- Parameter interactionDefaults:
transport http; drop_frames true; max_pdf_bytes 33554432 bytes (range 1..2147483647). Only drop_frames updates live, sampled at HTTP request/WebSocket message start. False blocks on backpressure; true can lose paired items/IDs despite success, including single pages. Empty Image/Page windows emit no IDs. Dropping the first PNG's page strands later digest-only figures. - I/O contractPort 9100: POST /pdf or /; WS /ws or /; GET /health gives 200, ok plus newline. transport: http/websocket/both. Unknown routes/disabled WS give 404; POST /pdf or / checks size (413) before disabled HTTP (404). Send raw PDF bytes; multipart is not parsed and Content-Type is unchecked. HTTP: empty 400, above max_pdf_bytes 413, handled extraction failure 422 with error text, success 200 with JSON {"session_id":"<id>"}. WebSocket success sends the same JSON in one text message. Each upload gets a new ID matching out_1, not a receipt acknowledgement. Parsing copies bodies; input limits do not cap memory.
- I/O contract
document_context adds Contents of upload <id>.pdf : plus newline to String. Document source_uri is <id>.pdf; client filenames are ignored. Non-binary/empty WebSocket messages fail with 1011; oversized messages can close with framework code 1009 before extraction. 1011 reasons cap at 123 UTF-8 bytes; full handled errors are logged. One listener thread extracts synchronously: extraction/backpressure delays clients/health. Aborting before the final HTTP body chunk emits nothing; later disconnects cannot retract emitted items. No explicit listener-stop hook ends the loop before thread joining. - Parameter interactionDefaults:
dpi 200; first_page 1; last_page Nothing (); document_context true; max_document_raster_bytes 1073741824 bytes. Downstream fixes out_0 at startup; no mode switch. - Hard constraintDocument limits summed page PNG data-URL bytes, including data:image/png;base64, prefixes. Before rendering it rejects ceil(width*dpi/72)*ceil(height*dpi/72)*4 above
max_document_raster_bytes. Encoded pages remain in memory; temporary rasters and non-page-image data need extra memory. Other arms ignore this budget. - Parameter interactionPage windows are inclusive, 1-based and clamped; Nothing ends at the final page. Reversed windows or starts beyond the end select nothing: no Image/Page items, empty Document pages, or String with two final newlines plus any header. Text/structured arms still validate global tags; Document still reads metadata/attachments/history.
- FallbackNo OCR: image-only ink needs downstream OCR on page rasters. Without a text layer String can still carry forms/annotations; without block wording it has a newline per selected page and two final newlines, plus any header. has_text_layer records a text-drawing callback: true need not mean usable text; false covers scans and blank pages.
- I/O contractParagraphs use sizes, line-box pitch, edges, column bands and list markers, without face-name comparisons. Bounds cover the lines; line/run wording and boxes remain. Only paragraph joins repair inferred ASCII line-break hyphens: joined text drops the hyphen, its run retains it with hyphen_break. Intended compound hyphens can be lost. Cell/item/caption text joins lines with spaces without this repair or alignment/leading. Form text has no lines. Lines carry boxes/runs. Runs carry optional size (points), face and sampled RGB ink; bold/italic, rotation, space_after and hyphen_break. Run rotation passes Poppler's text-box value unchanged. Size is Nothing without positive font metrics; face is Nothing without font info or a nonempty name. A six-uppercase-letter prefix plus '+' is removed when a face follows. Bold names contain bold/black/heavy/semib; italic names contain italic/oblique (case-insensitive), not descriptor flags. No name means false. Ink is Nothing without raster or with reversed clipped edges; otherwise a brightness-ranked box pixel, not PDF fill colour. Background/overlapping ink can affect it. Paragraph leading is the upper median positive line-centre step (points); align is left/right/center/justify. Both are inferred, absent for one line and possibly unknown.
- I/O contractWording (adjoining boxes, annotations, forms, outlines, info, alt) is NFC. URIs/XMP keep their spelling. Graphemes belong to their first run; mark-only runs keep boxes/formatting but no text. NFC preserves compatibility ligatures, relational signs, superscripts and fractions; sequences without a precomposed character remain multiple codepoints. Text/structured map U+F020–F0FF through Adobe Symbol only if the face contains 'symbol' case-insensitively; ASCII/decoded Unicode survive. Layout can convert smaller raised/lowered runs to Unicode scripts if every character maps: digits, + - = ( ), plus n/i for superscripts. ASCII can change in any font. Empty runs, unmapped private-use characters, invalid UTF-8, replacement characters or controls below U+0020 except tab/CR/LF omit the entire source run from both projections with original-byte hex warnings. Structured pages expose omission boxes; String does not. Raster ink and other symbolic fonts' valid Unicode remain.
- I/O contractDecoded embedded colour images carry stored byte length, intrinsic pixel dimensions and SHA-256 of BGR8 layout/dimensions/pixels. Placements resolve colour space/decode before deduplication, including inline images. Equal digests share one emitted PNG across selected pages; the cache resets per PDF. Drawn figures/stencils have no pixel digest/PNG. Drawn byte length/dimensions are zero; stencils retain stored length/dimensions. Each Figure-role MCID without overlapping embedded images yields a drawn figure; untagged paths remain rules. Embedded PNGs contain base BGR8 pixels without hard/soft masks, colour-key transparency or interpolation; page rasters show composited appearance. Keep PNGs by digest for empty URLs. The first encountered painting carries the PNG but can sort after a digest-only block. Captions/alt associate by Figure-region overlap, which can be ambiguous; captions must be nested in the figure. Named child roles clear inherited alt.
- I/O contractStructured pages carry displayed crop width/height (points), raster size (pixels), requested DPI, original zero-based page index and rotation (0/90/180/270 degrees). Boxes use top-left origin, normalize to 0..1 and clip to the crop; off-page bounds can collapse to a boundary. Rules expose path-fill/stroke bounds/paint/kind/width (points; fills zero), not paths or a complete display list. Path bounds include control points without stroke expansion or clipping-path intersection. Rule kinds are point-based classifications: a corner-only triangle can be fill, a zero-signed-area path line.
- I/O contractString/structured share block wording/order, NFC, Symbol conversion and paragraph hyphen joins. String joins nonempty block wording with newlines: table captions/cells, list labels/items, figure captions, forms and annotation contents; no alt. Figure captions/form appearances can remain ordinary text too, duplicating wording. String skips rendering/PNG/pixel decoding but reads stored image streams. Image is BGR8 without alpha: no text, omissions, page index or document metadata. Document.Page has no document metadata.
- LimitationLayout is inferred. Narrowest overlapping role wins. H1–H9 keep levels; H/inferred headings use 1. Untagged headings need >=1.35 times median size and <=12 runs; nonheading roles override size. Spaces use geometry, not space_after. Headers/footers/artifacts are not filtered. Runs containing U+0590–08FF, FB1D–FDFF or FE70–FEFF count as right-to-left; their lines skip column splitting. Blocks use ascending MCIDs only if all have tag order; tables/lists/forms/annotations lack it and force unturned top-to-bottom, left-to-right order. Ties keep insertion order; run/block confidence is fixed at 1, not estimated probability. Tables/lists require supported tags, not drawings. Table row/column indices are zero-based; cells emit in that order. Fills are Nothing; TH header status is absent. ordered is true only for Decimal/UpperRoman/LowerRoman/UpperAlpha/LowerAlpha; marker is the first nonempty label's run text; items include labels. Full numbering style is absent. Cell/item/caption word assignment uses box midpoints: overlaps can duplicate/exclude wording.
- Hard constraintText/structured validate Table-owner RowSpan/ColSpan throughout /K, including unselected pages/referenced ClassMap. Absent/null means 1; positive Int64 spans survive. Nonpositive/noninteger spans fail before output with attribute/value/type, not omission boxes. Int64 grid overflow fails when extracting a selected page; empty windows skip grid arithmetic. Image skips span validation.
dpi accepts 1..9007199254740992 (2^53), Poppler double's continuous exact integer range; the next integer rounds to the same value. String validates it without rendering. Raster arms use it for pixels/ink, not wording/point geometry. Each raster dimension is capped at 536870911 before rendering; smaller rasters can still fail Poppler/encoding/allocation. Text/structured reject /K cycles or over 256 nested dictionaries/arrays, even outside selected pages. References add no depth; completed references are visited once. The iterative validator reports cycle/limit. Image skips tags. Invalid structure roots, role-name types, attribute containers, class-name types, non-name List-owner numbering, /K child types or negative/noninteger tag-tree MCIDs fail. Page-paint MCIDs are checked only on selected pages. Elements may omit Type but need name S; marked-content references use Type MCR with integer MCID. - LimitationAbsent strings/collections stay empty; optional measurements stay Nothing. Wrong-typed info/annotation strings, language, alt, metadata streams and dates warn/remain unknown. Bad form-value types become empty; bad label types warn/use an available qualified name. String conversion can fail. Dates accept optional D:, four-digit year, successive optional two-digit parts; absent month/day default 1, time midnight, zone UTC. Invalid dates warn with field/all original bytes in hex (empty, truncated, bad calendar/offset, trailing garbage). Valid dates emit UTC ISO 8601; non-date annotation modification strings retain NFC text with warnings. UTC years outside 0000–9999 use signed six-digit form. XMP is verbatim/unchecked/unrepaired; language is not inferred.
Recoverable defects warn: undefined classes leave unknown attributes/defaults; unknown ListNumbering acts as None. Oversized signed MCIDs have no semantic assignment; duplicate semantic MCIDs keep first. Missing tag pages, object references, misplaced rows/cells/items or unpainted tags yield no regions. Unassociated/unpainted figure captions and tables/lists without supported cells/items remain text. Empty paths, untagged content and other-page tags create no regions here. Attribute streams warn/use absent defaults in Poppler. Values validate by owner; other-owner keys warn, but Poppler loses owners and may interpret recognized spans/numbering. Uninterpretable spans default 1; cell spans are not inherited. Unbalanced marked-content ends warn. Only the innermost active MCID gains bounds; nested unnumbered content can leave outer regions incomplete.
Widgetless forms yield no entries; each selected-page widget can yield one, omitted only if label AND value are empty. Labels prefer nonempty alternate UI name, then qualified name. Editable choices keep custom text; other selections join comma-space in option order. Button names use PDFDocEncoding then NFC. Signature/undefined values warn/become empty; widgets stay rasterized. Link/Popup annotations have no blocks. Unsupported subtypes warn/keep generic fields and slashless reversible PDF names; non-ASCII/whitespace/delimiter/hash bytes use uppercase #XX. Names are bytes. Only markup annotations read author/creation/reply; replies resolve among retained same-page names, warning if absent/unnamed. Transparent colour is Nothing; quads become bounds; CMYK uses simple RGB conversion.
- Hard constraintStructured extraction fails on bad embedded-image dimensions/reset/rows/PNG. The decoder needs positive components, 1..16 bits/component and row bits <=2147483640. Missing image streams or stored-stream reset failure also fail String. Missing parsed form fields/widgets/annotations/structure elements, invalid annotation subtype names and non-finite/nonpositive page or non-finite content geometry can fail text/structured; bad attachments/outline Unicode can fail Document. Parser/filter repairs can yield partial content with diagnostics; this is not a PDF conformance validator.
- I/O contractOnly Document reads metadata: full-input digest and total page_count, irrespective of selection. tagged/has_form mean parsed containers, not completeness/filled values. Outlines are preorder, levels start at 0, closed descendants included; targets are 1-based or 0 if unresolved/nonlocal/actionless (unresolved local targets warn). Attachments carry actual decoded size, byte digest and plain base64. Revisions open prefixes ending just after each literal %%EOF; cross-reference history is unverified. Unreadable candidates warn/are omitted; indices start at 0 consecutively; readable candidates can be stream markers.
- LimitationAll arms buffer the full PDF. Tags/forms repeat per selected page; many revisions/tags/outlines/fields cost time. Image/Page lack a raster-memory cap. Images/attachments/XMP/streams/text/traversals lack separate size/time caps beyond /K nesting. High DPI/large sheets/pathological PDFs can stall or exhaust memory/stack. Allocation failures can escape input-error handling/end the worker.