$worker

document

Name: document
Author: iii

v0.1.10

Convert Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV and PDF documents to markdown on this machine, detect the format from the bytes, pull out the images embedded in them, and transcribe a scan by rendering its pages and reading them with a vision model.

iiiverified

4 installs0 in 7d0 today

install

$iii trigger compose::add worker=document@0.1.10

binarylicense: Apache-2.0attachments csv document docx epub markdown ocr pptx text-extraction xlsx

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

5functions 0triggers 1skills 1deps v0.1.10version

repoiii-hq/workers

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

functions

document::detect

function

Identify a document's file format from its bytes. Reports the family it belongs to and whether this worker can convert it, falling back to the file name for CSV, which carries no signature. Microseconds, and no conversion.

request

bytes_base64string
Base64-encoded document bytes, for a document with no path — an attachment held in memory. Mutually exclusive with `path`.
file_namestring
Original file name for `bytes_base64`, used only to recognise a format the content cannot name (`.csv`). Ignored when `path` is set.
fs_scopeany of
Filesystem jail for this call. Stamped by the harness on an agent's call; absent on an operator or console call.
any of (2)
variant 1
grantsstring[]
Additional directories or files explicitly granted to this session.
rootstringrequired
The session's working directory.
variant 2
valuenull
pathstring
Filesystem path to the document. Mutually exclusive with `bytes_base64`.

response

convertiblebooleanrequired
`true` when `document::to-markdown` can convert this file.
detected_fromany of
How the format was arrived at. `extension` is the weaker claim: the content matched nothing known, and only the file name suggested this.
any of (2)
variant 1
one of (3)
variant 1
valuestringenum: requested
variant 2
valuestringenum: content
variant 3
valuestringenum: extension
variant 2
valuenull
elapsed_msinteger· uint64requiredmin 0
Wall-clock time for the detection.
familyany of
What the document is: prose, a spreadsheet, a presentation, a book, a PDF. Absent when the format is unknown.
any of (2)
variant 1
one of (5)
variant 1
valuestringenum: prose
variant 2
valuestringenum: spreadsheet
variant 3
valuestringenum: presentation
variant 4
valuestringenum: book
variant 5
valuestringenum: pdf
variant 2
valuenull
formatany of
The format, or `null` when nothing recognised it. A null means the file is not one of the formats this worker reads — an image, an archive, a plain text file — not that it is broken.
any of (2)
variant 1
one of (12)
variant 1
valuestringenum: doc
variant 2
valuestringenum: docx
variant 3
valuestringenum: odt
variant 4
valuestringenum: rtf
variant 5
valuestringenum: ppt
variant 6
valuestringenum: pptx
variant 7
valuestringenum: odp
variant 8
valuestringenum: excel
variant 9
valuestringenum: ods
variant 10
valuestringenum: csv
variant 11
valuestringenum: epub
variant 12
valuestringenum: pdf
variant 2
valuenull
has_assetsbooleanrequired
`true` when the format can carry embedded assets for `document::extract-assets` to pull out. False for a PDF, which converts straight to markdown without a document model, and for a CSV, which is rows of text with nowhere to put a picture. A caller routing on this should not spend a call to be told a spreadsheet has no images.
size_bytesinteger· uint64requiredmin 0
Size of the document in bytes.
sourcestringrequired
Source label: the file name, or `<inline>` for an in-memory document that arrived without one.

document::extract-assets

function

Extract the images and embedded objects from a document as base64, for a deck or report whose content is pictures rather than text. Capped per response and per asset; anything left out is listed with its type and size. Not available for PDFs — use pdf::extract-regions.

request

bytes_base64string
Base64-encoded document bytes, for a document with no path — an attachment held in memory. Mutually exclusive with `path`.
file_namestring
Original file name for `bytes_base64`, used only to recognise a format the content cannot name (`.csv`). Ignored when `path` is set.
formatany of
Force a format instead of detecting one.
any of (2)
variant 1
one of (12)
variant 1
valuestringenum: doc
variant 2
valuestringenum: docx
variant 3
valuestringenum: odt
variant 4
valuestringenum: rtf
variant 5
valuestringenum: ppt
variant 6
valuestringenum: pptx
variant 7
valuestringenum: odp
variant 8
valuestringenum: excel
variant 9
valuestringenum: ods
variant 10
valuestringenum: csv
variant 11
valuestringenum: epub
variant 12
valuestringenum: pdf
variant 2
valuenull
fs_scopeany of
Filesystem jail for this call. Stamped by the harness on an agent's call; absent on an operator or console call.
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_bytesboolean
Include the base64 payload. Set `false` to inventory a document — what it holds and how big — without moving the bytes.
max_assetsinteger· uintmin 0
Assets to return in this response. Narrows the configured ceiling; it cannot raise it.
media_type_prefixstring
Return only assets whose media type starts with this, e.g. `image/`. Omit for every asset.
pathstring
Filesystem path to the document. Mutually exclusive with `bytes_base64`.

response

assetsobject[]required
The assets, in document order, up to the effective ceiling.
- bytes_base64string
  The payload, base64-encoded.
- indexinteger· uintrequiredmin 0
  Position in the document's asset list, stable for a given document.
- media_typestringrequired
  MIME type, e.g. `image/png`.
- omittedstring
  Why the payload is absent, when it is: `not_requested`, `too_large` (this asset alone is over the per-asset ceiling), or `budget_spent` (the response's total byte budget went on earlier assets — ask for this one on its own).
- origin_partstringrequired
  The package part or stream it came from, for provenance.
- size_bytesinteger· uint64requiredmin 0
  Size of the payload in bytes, whether or not the payload is included.
elapsed_msinteger· uint64requiredmin 0
Wall-clock time for the extraction.
formatall ofrequired
The format that was parsed.
all of (1)
variant 1
one of (12)
variant 1
valuestringenum: doc
variant 2
valuestringenum: docx
variant 3
valuestringenum: odt
variant 4
valuestringenum: rtf
variant 5
valuestringenum: ppt
variant 6
valuestringenum: pptx
variant 7
valuestringenum: odp
variant 8
valuestringenum: excel
variant 9
valuestringenum: ods
variant 10
valuestringenum: csv
variant 11
valuestringenum: epub
variant 12
valuestringenum: pdf
sourcestringrequired
Source label: the file name, or `<inline>` for an in-memory document.
total_countinteger· uintrequiredmin 0
Assets the document holds after `media_type_prefix` is applied. Larger than `assets.len()` when the ceiling cut the response short.
truncatedbooleanrequired
`true` when the ceiling cut the response short.

document::ocr

function

Transcribe a scanned document with no readable text: a scanned PDF, a photographed page, a picture-only deck. Renders the pages and reads them with a vision model. Costs money per page: pass `pages` (pdf::classify) to narrow it.

request

bytes_base64string
Base64-encoded document bytes, for a document with no path — an attachment held in memory. Mutually exclusive with `path`.
file_namestring
Original file name for `bytes_base64`, used only to recognise a format the content cannot name (`.csv`). Ignored when `path` is set.
fs_scopeany of
Filesystem jail for this call. Stamped by the harness on an agent's call; absent on an operator or console call.
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 everything transcribed.
modelstring
Vision model to read with. Omit for the configured default. The model is checked for vision support before anything is rendered.
pagesinteger[]· uint32min 0
1-indexed PDF pages to transcribe; omit for every page up to the configured ceiling. Pass the scan pages `pdf::classify` reports.
pathstring
Filesystem path to the document. Mutually exclusive with `bytes_base64`.

response

bodyall ofrequired
The joined transcription, 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 markdown, 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.
elapsed_msinteger· uint64requiredmin 0
Wall-clock time, rendering included.
modelstringrequired
The model that read them.
pagesobject[]required
Per-page transcriptions, in order.
- cachedbooleanrequired
  `true` when this page came from the cache rather than the model.
- charsinteger· uintrequiredmin 0
- pageinteger· uint32requiredmin 0
  1-indexed page number, or the asset's index for an office document.
- textstringrequired
  The transcription. Empty when the page held no legible text.
pages_cachedinteger· uintrequiredmin 0
Pages served from the cache, costing nothing.
pages_transcribedinteger· uintrequiredmin 0
Pages actually read by the model this call. Excludes cache hits, so this is what was paid for.
sourcestringrequired
Source label: the file name, or `<inline>` for an in-memory document.
viastringrequired
How the pixels were obtained: `image`, `pdf-render` or `document-assets`.

document::on-config-change

function

Internal: hot-reload the document 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

document::to-markdown

function

Convert a Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV or PDF document to markdown, preserving headings, lists, links and tables. Responses are capped; pass max_chars 0 for the whole document. For a PDF run pdf::classify first to find pages needing OCR.

request

bytes_base64string
Base64-encoded document bytes, for a document with no path — an attachment held in memory. Mutually exclusive with `path`.
file_namestring
Original file name for `bytes_base64`, used only to recognise a format the content cannot name (`.csv`). Ignored when `path` is set.
formatany of
Force a format instead of detecting one. Only needed when the content carries no signature and the file name is absent or wrong.
any of (2)
variant 1
one of (12)
variant 1
valuestringenum: doc
variant 2
valuestringenum: docx
variant 3
valuestringenum: odt
variant 4
valuestringenum: rtf
variant 5
valuestringenum: ppt
variant 6
valuestringenum: pptx
variant 7
valuestringenum: odp
variant 8
valuestringenum: excel
variant 9
valuestringenum: ods
variant 10
valuestringenum: csv
variant 11
valuestringenum: epub
variant 12
valuestringenum: pdf
variant 2
valuenull
fs_scopeany of
Filesystem jail for this call. Stamped by the harness on an agent's call; absent on an operator or console call.
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 document. Mutually exclusive with `bytes_base64`.

response

asset_countinteger· uintrequiredmin 0
Embedded images and objects the document carries. Their bytes are not here — call `document::extract-assets` for those — but the count says whether a deck's content is pictures rather than text, which markdown alone would not reveal.
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 markdown, 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.
detected_fromall ofrequired
How the format was arrived at.
all of (1)
variant 1
one of (3)
variant 1
valuestringenum: requested
variant 2
valuestringenum: content
variant 3
valuestringenum: extension
elapsed_msinteger· uint64requiredmin 0
Wall-clock time for the conversion.
familyall ofrequired
What the document is: prose, a spreadsheet, a presentation, a book, a PDF.
all of (1)
variant 1
one of (5)
variant 1
valuestringenum: prose
variant 2
valuestringenum: spreadsheet
variant 3
valuestringenum: presentation
variant 4
valuestringenum: book
variant 5
valuestringenum: pdf
formatall ofrequired
The format that was converted.
all of (1)
variant 1
one of (12)
variant 1
valuestringenum: doc
variant 2
valuestringenum: docx
variant 3
valuestringenum: odt
variant 4
valuestringenum: rtf
variant 5
valuestringenum: ppt
variant 6
valuestringenum: pptx
variant 7
valuestringenum: odp
variant 8
valuestringenum: excel
variant 9
valuestringenum: ods
variant 10
valuestringenum: csv
variant 11
valuestringenum: epub
variant 12
valuestringenum: pdf
sourcestringrequired
Source label: the file name, or `<inline>` for an in-memory document.

triggers

no triggers registered