AWS Textract#

Status: docs-only. Implemented from AWS's published API documentation and tested against fixture payloads built from it. It has not yet been run against the live API, so expect wire-format differences. Help verify it: issue #10.

1. Summary#

Textract is not a "parse a document to markdown" product: it returns a flat array of Block objects linked by ids. PuffinParse reassembles those into pages, blocks, markdown tables and extraction results. There is no upload endpoint and no remote-URL input — synchronous calls carry the document inline as base64, asynchronous ones read it from S3.

2. Models exposed by PuffinParse#

Prices are the us-east-1 pay-as-you-go list prices for the first 1M pages/month, taken from the AWS Price List API rather than the marketing page, and used only to fill cost_usd = per_page_usd × usage.pages:

Why textract/layout is priced at the TABLES rate and not TABLES + LAYOUT. AWS bills a combined AnalyzeDocument call at a single combination rate, and there is no Layout…Tables usage type in the price list: "Layout is available for free when used with the Tables feature." So ["LAYOUT","TABLES"] bills exactly like ["TABLES"] — $0.015 / page. A LAYOUT-only call would be $0.004 / page, which you can get with provider_options={"FeatureTypes": ["LAYOUT"]} (the passthrough replaces the array), at the cost of losing markdown tables. Prices are region-dependent and PuffinParse's table is us-east-1 only, so cost_usd is an estimate for any other region.

Async (Start*/Get*) pages cost the same as sync pages; the USE1-Async… usage types carry identical rates.

3. Request flow PuffinParse uses#

Every call is POST {base}/ with these headers, all of them signed:

Content-Type: application/x-amz-json-1.1
X-Amz-Target: Textract.<Operation>
X-Amz-Date: 20260911T123456Z
X-Amz-Content-Sha256: <sha256 hex of the body>
X-Amz-Security-Token: <AWS_SESSION_TOKEN>        # only when set
Authorization: AWS4-HMAC-SHA256 Credential=<id>/<date>/<region>/textract/aws4_request,
               SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date;
                             [x-amz-security-token;]x-amz-target,
               Signature=<hex>

SigV4 is implemented in-file with hmac + sha2 (~60 lines: canonical request → string to sign → four chained HMACs for the signing key). It is re-signed on every retry, because the signature expires with X-Amz-Date. Unit tests assert AWS's own published iam/ListUsers example vectors (signing key c4afb1cc…a4b9, signature 5d672d79…b5d7), so canonicalisation drift is caught without a network call.

3.1 Synchronous (default)#

1. Load bytes. Path and bytes inputs are read locally. A URL input is downloaded by PuffinParse and sent inline — Textract cannot fetch URLs itself.
2. Multi-page guard. If the bytes are a PDF, pdf_page_count() counts /Type /Page objects (falling back to the page tree's /Count). More than one page ⇒ a bad_request error before any billable call (§5).
3. Call. Textract.DetectDocumentText or Textract.AnalyzeDocument with

json { "Document": { "Bytes": "<base64 of the file>" }, "FeatureTypes": ["LAYOUT", "TABLES"], "QueriesConfig": { "Queries": [{ "Text": "What is the total?", "Alias": "total" }] } }

FeatureTypes is omitted for detect-text; QueriesConfig only for textract/queries.

3.2 Asynchronous (multi-page, provider_options.s3_object)#

Textract's async API reads only from S3 — there is no way to hand it bytes. PuffinParse has no S3 client and deliberately does not grow one, so you upload the object yourself and name it:

provider_options={"s3_object": {"bucket": "my-bucket", "name": "invoices/2026-q3.pdf"}}
# optional: "version": "<S3 object version id>"

Then PuffinParse:

1. Textract.StartDocumentTextDetection / Textract.StartDocumentAnalysis with {"DocumentLocation": {"S3Object": {"Bucket": …, "Name": …}}, "FeatureTypes": […]} → {"JobId": …}.
2. Polls Textract.GetDocumentTextDetection / Textract.GetDocumentAnalysis with {"JobId": …, "MaxResults": 1000} starting at 2 s, backing off ×1.5 to 10 s, until JobStatus leaves IN_PROGRESS. SUCCEEDED and PARTIAL_SUCCESS continue; anything else becomes a provider error carrying StatusMessage and the job id.
3. Follows NextToken until it is absent, concatenating every Blocks page (a 3 000-page document is many round trips — budget timeout_secs accordingly).

NotificationChannel / SNS is not used: PuffinParse polls. You can still set it (and OutputConfig, KMSKeyId, JobTag, ClientRequestToken, AdaptersConfig) through provider_options, which is deep-merged into whichever body is actually sent.

Where provider_options are merged: the keys region and s3_object are consumed by PuffinParse; everything else is deep-merged verbatim into the Textract request body, so the remaining keys are top-level Textract request members in PascalCase (FeatureTypes, QueriesConfig, AdaptersConfig, HumanLoopConfig, OutputConfig, KMSKeyId, JobTag, ClientRequestToken, NotificationChannel).

3.3 Page selection#

Textract has no page-range parameter. pages="1-3,7" is therefore applied client-side: blocks whose Page falls outside the selection are dropped after the response arrives. It reduces the output, never the bill. The one exception is textract/queries in async mode, where the ranges are also forwarded as Query.Pages (["1-3", "7"]), which Textract does honour.

language is ignored — Textract auto-detects (English, French, German, Italian, Portuguese, Spanish) and never reports which language it found.

4. Response mapping#

Every operation returns the same envelope: {"Blocks": [...], "DocumentMetadata": {"Pages": n}, "AnalyzeDocumentModelVersion": "1.0"} (plus JobStatus / NextToken / Warnings for Get*).

4.1 ocr mode — LINE / WORD#

LINE blocks become TextPage.lines, WORD blocks become TextPage.words, both with box and confidence; TextPage.text is the lines joined by \n in response order. This is the native path for textract/detect-text, and textract/layout uses it too — AnalyzeDocument returns all lines and words regardless of FeatureTypes, so no second call is needed (and no extra charge).

4.2 parse mode — LAYOUT_* + TABLE#

Textract returns LAYOUT_* blocks in implied reading order (left to right, top to bottom; column by column on multi-column pages). PuffinParse walks them in array order, so Page.markdown is in reading order. A layout block's text is its descendant LINE blocks via Relationships[CHILD].

LAYOUT_LIST points at LAYOUT_TEXT children, and those children also appear at the top level of Blocks; PuffinParse suppresses any layout block that is another layout block's child so list items are not emitted twice.

Tables. A LAYOUT_TABLE is matched to its TABLE block by a direct CHILD reference, or — when it only points at lines — by the highest-overlap unclaimed TABLE on the same page (>10 % of the table's area). The TABLE's CHILD CELL blocks are placed on a RowIndex × ColumnIndex grid (MERGED_CELL blocks are skipped: they repeat content already present in the individual cells) and rendered as markdown. Cell text is the CHILD WORD texts joined by spaces; a SELECTION_ELEMENT child becomes [x] / [ ]; | is escaped. The header row is the lowest RowIndex among cells with EntityTypes: ["COLUMN_HEADER"], else row 1; rows above the header row and TABLE_TITLE / TABLE_FOOTER blocks are emitted as plain lines around the table.

Fallback. If a response carries no LAYOUT_* blocks at all (LAYOUT disabled through provider_options, or nothing detected), PuffinParse emits every TABLE as a markdown table plus one text block per LINE, skipping lines whose words are all inside table cells so table content is not duplicated. output="text" renders every block through markdown_to_text.

Trimmed fixture (crates/puffinparse-core/tests/fixtures/textract_layout.json, most blocks elided):

{
  "DocumentMetadata": { "Pages": 1 },
  "AnalyzeDocumentModelVersion": "1.0",
  "Blocks": [
    { "BlockType": "LAYOUT_TITLE", "Confidence": 98.12, "Id": "lay-title", "Page": 1,
      "Geometry": { "BoundingBox": { "Left": 0.12, "Top": 0.06, "Width": 0.26, "Height": 0.02 } },
      "Relationships": [ { "Type": "CHILD", "Ids": ["ll1"] } ] },
    { "BlockType": "LAYOUT_TABLE", "Confidence": 97.4, "Id": "lay-table", "Page": 1,
      "Relationships": [ { "Type": "CHILD", "Ids": ["tbl-1"] } ] },
    { "BlockType": "TABLE", "Confidence": 99.21, "Id": "tbl-1", "Page": 1,
      "EntityTypes": ["STRUCTURED_TABLE"],
      "Relationships": [ { "Type": "CHILD", "Ids": ["c11","c12","c21","c22","c31","c32"] } ] },
    { "BlockType": "CELL", "RowIndex": 1, "ColumnIndex": 1, "RowSpan": 1, "ColumnSpan": 1,
      "EntityTypes": ["COLUMN_HEADER"], "Id": "c11", "Page": 1,
      "Relationships": [ { "Type": "CHILD", "Ids": ["tw1"] } ] },
    { "BlockType": "LINE", "Confidence": 98.9, "Text": "Quarterly Report", "Id": "ll1", "Page": 1,
      "Relationships": [ { "Type": "CHILD", "Ids": ["lw1","lw2"] } ] },
    { "BlockType": "WORD", "Confidence": 99.0, "Text": "Region", "TextType": "PRINTED", "Id": "tw1", "Page": 1 }
  ]
}

4.3 extract mode — textract/queries#

Each flat property of the request schema becomes one Textract query:

{"Text": <description> ?? <title> ?? <key with _ and - as spaces>, "Alias": <sanitised key>}

The alias keeps [A-Za-z0-9_.:-] (everything else becomes _, duplicates get a numeric suffix) and maps back to the original property name, so "invoice number" in the schema is queried as invoice_number and returned under "invoice number".

Responses are QUERY blocks carrying Query.Alias and a Relationships[{"Type":"ANSWER"}] list of QUERY_RESULT ids. PuffinParse takes the highest-confidence non-empty QUERY_RESULT, coerces its Text to the schema's type (number/integer strip currency and separators; boolean understands yes/no/true/false/selected/[x]), and writes it to data[<key>]. Confidence lands in fields["/<key>"].confidence; with citations=True the answer's page, box and text land in fields["/<key>"].citations. A query with no answer yields data[<key>] = null and no entry in fields — the key is always present, so the shape of data matches the schema.

Only flat string-like fields are supported. Properties typed object or array (or carrying properties / items) cannot be expressed as a Textract query; they are skipped, reported in metadata.textract_unsupported_fields, and set to null. Textract Queries answers one question with one span of text — there is no nesting and no repeated-row extraction. Flatten the schema (line_item_1_total, …) or use a provider with native structured extraction.

instructions on the request is ignored (Textract has no free-text guidance parameter); the fact is recorded in metadata.textract_instructions_ignored.

Textract allows 15 queries per page synchronously and 30 asynchronously. A schema with more flat properties than the applicable limit is rejected with an input error before any call is made.

4.4 extract mode — textract/forms (best effort)#

FORMS returns KEY_VALUE_SET blocks: a block with EntityTypes: ["KEY"] holds the label (its CHILD WORDs) and points at its value block through Relationships[{"Type":"VALUE"}]; the value block's CHILDren are WORDs or a SELECTION_ELEMENT.

PuffinParse matches each schema property to a detected key by case- and punctuation-insensitive comparison (both sides reduced to lowercase alphanumerics), trying the property name and its title, first for an exact match and then for "one name contains the other" (≥3 characters). Each detected key is consumed at most once. Values are coerced by the schema's type exactly as in §4.3, and a selected checkbox becomes true.

This is a heuristic, not schema-driven extraction. Textract decides what the keys are; PuffinParse only tries to line them up with your field names. Properties with no match are set to null and listed in metadata.textract_unmatched_fields; metadata.textract_form_keys_found reports how many key-value pairs Textract actually detected, which is the first thing to look at when fields come back empty. Nested (object/array) properties are never matched. At $0.050/page textract/forms is also the most expensive model here — prefer textract/queries when you know what you want.

5. Errors, status codes, rate limits, timeouts#

Textract reports failures as {"__type": "<Exception>", "message": "…"}, almost always with HTTP 400 — including throttling and server-side failures, so the shared Error::from_http mapping (4xx → bad_request) is wrong for Textract. textract::map_error keys off __type instead (a fully-qualified com.amazonaws.textract#ThrottlingException is accepted too) and prefixes the exception name onto the message:

An async job that ends FAILED becomes a provider error carrying StatusMessage and the job id. PARTIAL_SUCCESS is accepted, logged, and its Warnings surfaced in metadata.

Multi-page PDFs. Synchronous Textract accepts PDF and TIFF at one page only. PuffinParse raises a bad_request before the call:

textract: synchronous operations accept single-page PDF/TIFF only (this document has 2 pages). Multi-page documents require Textract's asynchronous API, which reads the file from S3. Upload the file yourself and pass provider_options={"s3_object": {"bucket": "my-bucket", "name": "path/doc.pdf"}}, or split the PDF into single pages first.

The page count is best effort — it reads uncompressed page objects and the /Count in the page tree, which covers most producers but not PDFs that hide their structure in object streams. When the count cannot be determined, the call goes out and Textract's own 4xx is rewritten into the same message, so the advice is identical either way.

Retries. max_retries (default 2), exponential backoff with full jitter, only on the rate_limit, network and 5xx provider kinds above. Textract returns no Retry-After and no rate-limit headers, so backoff is blind. Default us-east-1 quotas worth knowing (all adjustable in Service Quotas, and lower in most other regions): synchronous AnalyzeDocument 10 TPS, DetectDocumentText 25 TPS; StartDocumentAnalysis 10 TPS, StartDocumentTextDetection 15 TPS; GetDocumentAnalysis 10 TPS, GetDocumentTextDetection 25 TPS; at most 600 asynchronous jobs existing simultaneously per account (exceeding that is LimitExceededException, which PuffinParse retries).

Timeouts. timeout_secs (default 300) is the whole-call deadline — download, signing, the call, job polling and NextToken pagination — and also caps each individual HTTP request, shrinking as the budget is spent.

6. Gotchas#

• The "API key" is a key pair. api_key on a PuffinParse request can only stand in for AWS_ACCESS_KEY_ID; AWS_SECRET_ACCESS_KEY must be in the environment, otherwise the request is refused with an authentication error that says so. Set AWS_SESSION_TOKEN as well for STS / assumed-role credentials — it is signed as x-amz-security-token and included in SignedHeaders. PuffinParse reads only those environment variables: it does not parse ~/.aws/credentials, does not honour AWS_PROFILE, and does not call IMDS or the ECS credential endpoint.
• The region is part of the signature, not just the URL. Signing with the wrong region gives a 400 that talks about the credential scope, not about the host. If you override base_url to a VPC endpoint or a mock, set provider_options={"region": …} to match.
• No fixtures were captured live. The credentials available in this repository's build environment are proxy placeholders; a real DetectDocumentText call against textract.us-east-1.amazonaws.com returned {"__type":"UnrecognizedClientException","message":"The security token included in the request is invalid."}. That round trip does confirm the transport and the signature format (a malformed canonical request yields IncompleteSignature/InvalidSignatureException, not UnrecognizedClientException) and the error mapping (ErrorKind::Authentication), but every textract_*.json fixture is assembled from the shapes in the AWS API reference, with confidences, ids and boxes filled in to be realistic. Re-capture them from a real account before trusting the numbers, and run the #[ignore]d live tests at the bottom of textract.rs.
• Confidence is 0–100, not 0–1. Every Confidence is a percentage; PuffinParse divides by 100. The QUERY_RESULT sample in the AWS docs shows "Confidence": 1.0, which is 1 %, not certainty.
• Boxes are already normalised. Unlike most providers, BoundingBox is 0–1 relative to the page, so no page dimensions are needed — which is just as well, because Textract never reports them and Page.width/height are always None.
• Page is always 1 for JPEG/PNG, even for a scanned image that visually contains several pages. Only PDF and TIFF produce Page > 1, and only through the async API.
• Synchronous PDFs are single-page, full stop (10 MB in memory). Async accepts 500 MB / 3 000 pages but only from S3 — there is no bytes variant of StartDocument*. This is the single biggest limitation of this provider and the reason provider_options.s3_object exists.
• Password-protected PDFs and XFA PDFs are rejected; images must be ≤10 000 px per side.
• AnalyzeDocument always returns every LINE and WORD, whatever FeatureTypes says. That is why textract/layout can serve ocr mode from the same response, and why a FORMS-only call still gives you the full text in raw.
• LAYOUT_LIST children are LAYOUT_TEXT, not LINE — one level of indirection that also means those LAYOUT_TEXT blocks appear twice in Blocks (once nested, once at the top level). Naive iteration duplicates every list item.
• MERGED_CELL duplicates content. A merged cell's CHILD ids are the individual CELLs, which are also children of the TABLE. Rendering both repeats the text; PuffinParse renders only the plain cells, so a row/column span shows its text in the first cell and blanks beside it.
• Queries are English-only and capped at 15 per page synchronously / 30 asynchronously. Answers are capped at 128 characters. A query aimed at a page that does not exist comes back as an INVALID_REQUEST_PARAMETERS entry in Warnings, not as an error.
• Throttling arrives as HTTP 400. Treating Textract's 400s as non-retryable (the usual rule) means giving up on ThrottlingException and ProvisionedThroughputExceededException; the mapping in §5 exists entirely for this.
• Warnings is silent data loss. A PARTIAL_SUCCESS job returns blocks for the pages that worked and lists the failures in Warnings — check metadata.textract_warnings before trusting the page count.
• No provider_job_id for sync calls. Textract returns the request id only in the x-amzn-RequestId response header, which PuffinParse does not surface today.
• Pagination is per 1 000 blocks, not per page. A dense 50-page document can need dozens of Get* round trips; they all come out of timeout_secs.

7. Useful provider_options passthrough#

# 1. Multi-page PDF: upload to S3 yourself, then let PuffinParse drive Start*/Get* + NextToken.
puffinparse.parse("ignored-when-s3.pdf", model="textract/layout",
              provider_options={"s3_object": {"bucket": "my-bucket", "name": "reports/q3.pdf"}},
              timeout=1200)

# 2. Cheapest layout: drop TABLES to bill at the LAYOUT rate ($4 vs $15 per 1k pages).
#    Tables then come back as plain lines instead of markdown grids.
puffinparse.parse("memo.png", model="textract/layout",
              provider_options={"FeatureTypes": ["LAYOUT"]})

# 3. A different region (also changes the signing scope, not just the host).
puffinparse.ocr("scan.png", model="textract/detect-text", provider_options={"region": "eu-west-1"})

# 4. Signatures alongside layout, and the raw Block array for anything PuffinParse does not map.
puffinparse.parse("contract.png", model="textract/layout", include_raw=True,
              provider_options={"FeatureTypes": ["LAYOUT", "TABLES", "SIGNATURES"]})

# 5. A trained Custom Queries adapter (adapters are Queries-only).
puffinparse.extract("claim.png", model="textract/queries", schema=schema,
                provider_options={"AdaptersConfig": {"Adapters": [
                    {"AdapterId": "abc123", "Version": "1"}]}})

# 6. Async with your own output bucket, KMS key and an idempotency token.
puffinparse.parse("big.pdf", model="textract/layout", timeout=1800,
              provider_options={"s3_object": {"bucket": "in", "name": "big.pdf"},
                                "OutputConfig": {"S3Bucket": "out", "S3Prefix": "textract/"},
                                "KMSKeyId": "alias/textract",
                                "ClientRequestToken": "big-pdf-2026-09-11"})

8. Links#

• What is Amazon Textract: https://docs.aws.amazon.com/textract/latest/dg/what-is.html
• AnalyzeDocument: https://docs.aws.amazon.com/textract/latest/dg/API_AnalyzeDocument.html · DetectDocumentText: https://docs.aws.amazon.com/textract/latest/dg/API_DetectDocumentText.html
• StartDocumentAnalysis: https://docs.aws.amazon.com/textract/latest/dg/API_StartDocumentAnalysis.html · GetDocumentAnalysis: https://docs.aws.amazon.com/textract/latest/dg/API_GetDocumentAnalysis.html
• Block reference: https://docs.aws.amazon.com/textract/latest/dg/API_Block.html
• Layout response objects: https://docs.aws.amazon.com/textract/latest/dg/layoutresponse.html
• Tables: https://docs.aws.amazon.com/textract/latest/dg/how-it-works-tables.html · Form data: https://docs.aws.amazon.com/textract/latest/dg/how-it-works-kvp.html · Queries: https://docs.aws.amazon.com/textract/latest/dg/queryresponse.html
• Quotas: https://docs.aws.amazon.com/textract/latest/dg/limits-document.html · https://docs.aws.amazon.com/general/latest/gr/textract.html
• Pricing: https://aws.amazon.com/textract/pricing/ · machine-readable price list: https://pricing.us-east-1.amazonaws.com/offers/v1.0/aws/AmazonTextract/current/index.json
• Signature Version 4: https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv4-signing-examples.html