$worker

pdf

Name: pdf
Author: iii

v0.1.0

Read PDFs locally — classify text-based vs scanned, convert to markdown, extract positioned text and tables, and report which pages still need OCR.

Experimental

Published as experimental by its release pipeline. It installs and resolves like any other worker, but its interface may change without notice.

iiiverified

4 installs1 in 7d0 today

install

$iii worker add pdf@0.1.0

binarypdf document markdown text-extraction ocr-routing tables

macOS: arm64 · x64
Linux: arm64 · armv7 · x64
Windows: arm64 · x64 · x86

7functions 0triggers 1skills 1deps v0.1.0version

repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

pdf::classify

function

Classify a PDF as text-based, scanned, image-based or mixed, and report which pages need OCR and why. Samples content streams rather than extracting text, so it answers in tens of milliseconds. Call this before any other pdf function.

request

bytes_base64string
Base64-encoded PDF bytes, for a document with no path. Mutually exclusive with `path`.
fs_scopeany of
The filesystem jail this call runs under. Stamped by the harness on an agent's call; absent on an operator or console call, which is already user-initiated and not subject to the agent's scope.
any of (2)
variant 1
grantsstring[]
Additional directories or files explicitly granted to this session.
rootstringrequired
The session's working directory.
variant 2
valuenull
passwordstring
Password for an encrypted document. Never logged or echoed back.
pathstring
Filesystem path to the PDF. Mutually exclusive with `bytes_base64`.
sample_pagesinteger· uintmin 0
Pages sampled for the verdict, overriding the configured default. `0` scans every page, which is slower but settles a borderline mixed document.

response

confidencenumber· floatrequired
How much to trust the verdict, from 0.0 to 1.0.
document_typeall ofrequired
The document-level verdict.
all of (1)
variant 1
one of (4)
variant 1
valuestringenum: text_based
variant 2
valuestringenum: scanned
variant 3
valuestringenum: image_based
variant 4
valuestringenum: mixed
elapsed_msinteger· uint64requiredmin 0
Wall-clock time for the classification.
has_encoding_issuesboolean
`true` when font encodings decoded badly. Only known on the encrypted path, which extracts far enough to notice; absent otherwise, where `suspected_garbled_text` in `ocr_reasons` carries the same signal.
ocr_reasonsobject[]required
Per-page explanation for `pages_needing_ocr`.
- pageinteger· uint32requiredmin 0
  1-indexed page number.
- reasonsstring[]required
  Machine-readable reasons: `scanned` (a raster page), `no_text` (nothing extractable and nothing to OCR), `vector_text` (characters drawn as outlines rather than text) or `suspected_garbled_text` (a text layer that decodes to nonsense).
ocr_recommendedboolean
`true` when the images carry meaning the text layer does not, so OCR adds something even on a text-based document. Absent for an encrypted document, for the same reason as `pages_sampled`.
page_countinteger· uint32requiredmin 0
Pages in the document.
pages_needing_ocrinteger[]· uint32requiredmin 0
1-indexed pages that cannot be read without OCR. Empty for a clean text-based document.
pages_sampledinteger· uint32min 0
Pages actually inspected. Lower than `page_count` when sampling, so a verdict from a sample can be told apart from one that read everything. Absent for an encrypted document, which takes a decryption path that does not report the counters.
pages_with_textinteger· uint32min 0
Inspected pages that carry text operators. Absent for an encrypted document, for the same reason as `pages_sampled`.
sourcestringrequired
Source label: the file name, or `<inline>` for an in-memory document.
titlestring
Document title from the PDF metadata, when it has one.

pdf::extract-items

function

Extract positioned text items: the box, font, size and styling of every run of characters on a page. Coordinates are PDF points with a bottom-left origin. Use this for layout-aware reading; use pdf::to-markdown to just read the document.

request

bytes_base64string
Base64-encoded PDF bytes, for a document with no path. Mutually exclusive with `path`.
fs_scopeany of
The filesystem jail this call runs under. Stamped by the harness on an agent's call; absent on an operator or console call, which is already user-initiated and not subject to the agent's scope.
any of (2)
variant 1
grantsstring[]
Additional directories or files explicitly granted to this session.
rootstringrequired
The session's working directory.
variant 2
valuenull
max_itemsinteger· uintmin 0
Items to return before truncating. Omit for the configured default; `0` returns every item, which on a dense document is a very large response.
pagesinteger[]· uint32min 0
1-indexed pages to read. Omit for the whole document.
pathstring
Filesystem path to the PDF. Mutually exclusive with `bytes_base64`.

response

coordinate_originstringrequired
Origin convention for `x` and `y`, always `pdf-points, bottom-left`. Stated on every response because a caller that assumed the other convention reads the wrong end of the page with no error. Note `pdf::extract-regions` takes boxes with a top-left origin instead.
countinteger· uintrequiredmin 0
Items returned.
elapsed_msinteger· uint64requiredmin 0
Wall-clock time for the extraction.
itemsobject[]required
The items, in document order, capped per `max_items`.
- boldbooleanrequired
- fontstringrequired
  Font name as the document names it.
- font_sizenumber· floatrequired
  Font size in points.
- heightnumber· floatrequired
  Height in PDF points, approximated from the font size.
- italicbooleanrequired
- kindone ofrequired
  What one item is.
  one of (4)
  variant 1
  valuestringenum: text
  variant 2
  valuestringenum: image
  variant 3
  valuestringenum: link
  variant 4
  valuestringenum: form_field
- linkstring
  Link target, for a `link` item.
- mcidinteger· int64
  Marked-content id tying this item to the document's tagged structure tree, when the document has one.
- pageinteger· uint32requiredmin 0
  1-indexed page number.
- strikeoutbooleanrequired
  Recovered from vector lines through the text, not from a flag.
- textstringrequired
  The characters.
- underlinebooleanrequired
  Recovered from vector lines near the baseline, not from a flag.
- widthnumber· floatrequired
  Width in PDF points.
- xnumber· floatrequired
  Left edge, PDF points from the left of the page.
- ynumber· floatrequired
  Baseline, PDF points from the **bottom** of the page.
sourcestringrequired
Source label: the file name, or `<inline>` for an in-memory document.
total_countinteger· uintrequiredmin 0
Items the document holds for the requested pages. Equal to `count` when nothing was dropped.
truncatedbooleanrequired
`true` when `items` stops short. Narrow `pages`, or pass `max_items: 0`.

pdf::extract-regions

function

Extract the real text, or a markdown table, from inside bounding boxes on given pages. Built for the hybrid path where a vision model locates a region and the exact characters come from the document rather than from a transcription. Coordinates are PDF points with a top-left origin.

request

bytes_base64string
Base64-encoded PDF bytes, for a document with no path. Mutually exclusive with `path`.
fs_scopeany of
The filesystem jail this call runs under. Stamped by the harness on an agent's call; absent on an operator or console call, which is already user-initiated and not subject to the agent's scope.
any of (2)
variant 1
grantsstring[]
Additional directories or files explicitly granted to this session.
rootstringrequired
The session's working directory.
variant 2
valuenull
modeall of
Flat text, or a markdown table.
all of (1)
variant 1
one of (2)
variant 1
valuestringenum: text
variant 2
valuestringenum: table
pathstring
Filesystem path to the PDF. Mutually exclusive with `bytes_base64`.
regionsobject[]required
One entry per page, each carrying the boxes to read on it.
- boxesnumber[][]required4…4 items
  Boxes as `[x1, y1, x2, y2]` in PDF points, origin at the top left.
- pageinteger· uint32requiredmin 0
  1-indexed page number.

response

coordinate_originstringrequired
Origin convention the requested boxes were read under, always `pdf-points, top-left`. Stated on every response because a caller that assumed the other convention gets text from the wrong end of the page with no error. Note `pdf::extract-items` reports bottom-left instead.
elapsed_msinteger· uint64requiredmin 0
Wall-clock time for the extraction.
pagesobject[]required
One entry per requested page, in the order they were given.
- pageinteger· uint32requiredmin 0
  1-indexed page number.
- regionsobject[]required
  One result per requested box, in the order they were given.
  needs_ocrbooleanrequired
  `true` when the extraction is not trustworthy: an empty box, a font the parser cannot decode, or text that decodes to nonsense. In `table` mode it also means no table structure was found.
  ocr_reasonstring
  Machine-readable reason, when the cause is known.
  textstringrequired
  The text, or the markdown table in `table` mode.
region_countinteger· uintrequiredmin 0
Boxes read across every page.
regions_needing_ocrinteger· uintrequiredmin 0
Boxes whose result should not be trusted.
sourcestringrequired
Source label: the file name, or `<inline>` for an in-memory document.

pdf::extract-text

function

Extract a PDF as plain text, with no structure recovery. Cheaper than pdf::to-markdown and the right call when the text will be searched or embedded rather than read.

request

bytes_base64string
Base64-encoded PDF bytes, for a document with no path. Mutually exclusive with `path`.
fs_scopeany of
The filesystem jail this call runs under. Stamped by the harness on an agent's call; absent on an operator or console call, which is already user-initiated and not subject to the agent's scope.
any of (2)
variant 1
grantsstring[]
Additional directories or files explicitly granted to this session.
rootstringrequired
The session's working directory.
variant 2
valuenull
max_charsinteger· uintmin 0
Characters to return before truncating. Omit for the configured default; `0` returns the whole document.
pathstring
Filesystem path to the PDF. Mutually exclusive with `bytes_base64`.

response

bodyall ofrequired
The text, capped per `max_chars`.
all of (1)
variant 1
charsinteger· uintrequiredmin 0
Characters returned in `text`.
previewstring
Leading characters of the content. Present only when the body was truncated, so a caller can see the shape of what it did not get without re-reading the start of `text`.
textstringrequired
The content, shortened to the effective character cap.
total_charsinteger· uintrequiredmin 0
Characters the document actually holds. Equal to `chars` when nothing was dropped.
truncatedbooleanrequired
`true` when `text` stops short of the document. Ask again with `max_chars: 0` to take everything, or on the functions that accept one, narrow with a `pages` filter.
elapsed_msinteger· uint64requiredmin 0
Wall-clock time for the extraction.
sourcestringrequired
Source label: the file name, or `<inline>` for an in-memory document.

pdf::on-config-change

function

Internal: hot-reload the pdf worker from the authoritative configuration when it changes, swapping the per-call snapshot.

request

idstring
Configuration id that changed (advisory; the handler re-fetches).

response

okbooleanrequired

pdf::to-markdown

function

Convert a text-based PDF to markdown, preserving headings, lists, links and tables. Returns nothing for a scanned document — call pdf::classify first. Responses are capped; pass max_chars 0 to take the whole document, or pages to take a slice of it.

request

bytes_base64string
Base64-encoded PDF bytes, for a document with no path. Mutually exclusive with `path`.
fs_scopeany of
The filesystem jail this call runs under. Stamped by the harness on an agent's call; absent on an operator or console call, which is already user-initiated and not subject to the agent's scope.
any of (2)
variant 1
grantsstring[]
Additional directories or files explicitly granted to this session.
rootstringrequired
The session's working directory.
variant 2
valuenull
include_imagesboolean
Include `[Image: …]` placeholders. Off by default: nothing here decodes pixels, so a placeholder adds noise without adding information.
max_charsinteger· uintmin 0
Characters to return before truncating. Omit for the configured default; `0` returns the whole document.
pagesinteger[]· uint32min 0
1-indexed pages to convert. Omit for the whole document. A page filter is the cheap way to read a long report: take the pages you need rather than the whole thing truncated.
passwordstring
Password for an encrypted document. Never logged or echoed back.
pathstring
Filesystem path to the PDF. Mutually exclusive with `bytes_base64`.
per_pageboolean
Return markdown per page as well as the joined document. Useful when a caller wants to route some pages to OCR and keep the rest.
profileall of
Source fidelity versus token efficiency.
all of (1)
variant 1
one of (2)
variant 1
valuestringenum: fidelity
variant 2
valuestringenum: compact
strip_headers_footersboolean
Strip repeated running headers and footers.

response

bodyall ofrequired
The markdown, capped per `max_chars`.
all of (1)
variant 1
charsinteger· uintrequiredmin 0
Characters returned in `text`.
previewstring
Leading characters of the content. Present only when the body was truncated, so a caller can see the shape of what it did not get without re-reading the start of `text`.
textstringrequired
The content, shortened to the effective character cap.
total_charsinteger· uintrequiredmin 0
Characters the document actually holds. Equal to `chars` when nothing was dropped.
truncatedbooleanrequired
`true` when `text` stops short of the document. Ask again with `max_chars: 0` to take everything, or on the functions that accept one, narrow with a `pages` filter.
document_typeall ofrequired
The document-level verdict, so a caller that skipped `pdf::classify` still learns it got nothing because the document is a scan.
all of (1)
variant 1
one of (4)
variant 1
valuestringenum: text_based
variant 2
valuestringenum: scanned
variant 3
valuestringenum: image_based
variant 4
valuestringenum: mixed
elapsed_msinteger· uint64requiredmin 0
Wall-clock time for the conversion.
has_encoding_issuesbooleanrequired
`true` when font encodings decoded badly. The markdown, if any, is not to be trusted.
ocr_reasonsobject[]required
Per-page explanation for `pages_needing_ocr`.
- pageinteger· uint32requiredmin 0
  1-indexed page number.
- reasonsstring[]required
  Machine-readable reasons: `scanned` (a raster page), `no_text` (nothing extractable and nothing to OCR), `vector_text` (characters drawn as outlines rather than text) or `suspected_garbled_text` (a text layer that decodes to nonsense).
page_countinteger· uint32requiredmin 0
Pages in the document.
pagesobject[]
Per-page markdown, when `per_page` was requested.
- markdownstringrequired
  Markdown for this page.
- needs_ocrbooleanrequired
  `true` when this page's text is not trustworthy and OCR would do better.
- ocr_reasonstring
  Machine-readable reason, when the cause is known.
- pageinteger· uint32requiredmin 0
  1-indexed page number.
pages_convertedinteger· uint32requiredmin 0
Pages actually converted. Equal to `page_count` unless `pages` was set.
pages_needing_ocrinteger[]· uint32requiredmin 0
1-indexed pages that need OCR.
pages_with_columnsinteger[]· uint32requiredmin 0
1-indexed pages laid out in multiple columns.
pages_with_tablesinteger[]· uint32requiredmin 0
1-indexed pages holding a detected table.
sourcestringrequired
Source label: the file name, or `<inline>` for an in-memory document.

pdf::ui-content

function

Serve the pdf worker's injected console UI assets (content function for its console:script / console:style triggers).

request

pathstringrequired
The asset path from the trigger config (e.g. `state/page.js`).

response

contentstringrequired
The asset source, verbatim.
content_typestringrequired
MIME type the console should serve the asset with.

triggers

no triggers registered