Amazon Textract Response Parser

The library provides structured ways to navigate the document hierarchy instead of exposing raw arrays directly. This helps avoid accidental mutations and provides cleaner access patterns:

• .n*** properties: Count items (e.g., doc.nPages).
• .list***(): Returns a copy of the underlying array (e.g., doc.listPages()).
• .iter***(): Returns an iterator for collections (e.g., page.iterLines()).
• .***At***(): Fetches a specific item by index (e.g., table.cellAt(2, 4)).

// Navigate the document hierarchy:
console.log(`Opened doc with ${doc.nPages} pages`);
console.log(
  `The first word of the first line is ${doc.pageNumber(1).lineAtIndex(0).wordAtIndex(0).text}`
);

// Iterate through content:
for (const page of doc.iterPages()) {
  for (const line of page.iterLines()) {
    for (const word of line.iterWords()) {
      console.log(word.text);
    }
  }
}

// Get snapshot arrays instead of iterators:
const linesArrsByPage = doc.listPages().map((p) => p.listLines());

The library allows you to augment or edit Textract JSON objects using its classes (e.g., TextractDocument, Page, Word). When using mutation operations provided by the library, keep the following behaviors in mind:

• In-place modification: Mutation operations provided by library classes modify the source API JSON object in-place and attempt to ensure self-consistency.
• Accessing raw JSON: You can access the underlying API JSON object for any class via the .dict property (e.g., word.dict, table.dict). If you modify the JSON directly via .dict, you are responsible for updating any required references in other objects to maintain consistency.
• Dynamic reflection: Individual block-level changes made to the underlying API JSON (like overriding word text or coordinates) are dynamically reflected in the parsed TRP objects. However, changes affecting inter-block relationships may cause staleness issues.
• Array properties: To prevent unsupported arbitrary mutations (like table.rows.pop()), the library generally exposes getters and iterators rather than direct access to lists. Use methods like table.nRows, table.iterRows(), table.listRows(), or table.cellsAt() instead of attempting to manipulate arrays directly.

The synchronous request/response APIs used in many basic examples are limited to images or single-page documents. For multi-page documents or large batches, you must use the Asynchronous Textract APIs.

Workflow for Asynchronous Processing:

1. Upload: Upload the source document to an Amazon S3 bucket.
2. Start Analysis: Call StartDocumentAnalysis (or similar async commands) which returns a job ID.
3. Retrieve Results: Use the job ID with GetDocumentAnalysis to retrieve the results once the job is complete.

Best Practices for Scale:

• Avoid Polling: Instead of repeatedly calling GetDocumentAnalysis, use Amazon SNS notifications to trigger your application when the analysis is ready. This is more quota-efficient.
• Manage Quotas: Be aware of Amazon Textract quota limits. For spiky workloads, implement a queuing mechanism to manage request rates.
• Infrastructure: A production-ready solution typically involves AWS Lambda and Amazon SNS topics.

The Textract-Augmented AI (A2I) response parser library allows you to parse the JSON returned by an A2I human review workflow. It provides language-specific constructs to navigate document elements like forms and fields.

To use the parser, you must first obtain the human review results from S3 (which are published after the human review is complete) and extract the specific Textract response segment from the A2I JSON structure. Once extracted, you can initialize a Document object to iterate through pages and fields.

# 1. Extract the Textract response from the A2I JSON
# The path in the JSON is typically: a2i_json["humanAnswers"][0]["answerContent"]["AWS/Textract/AnalyzeDocument/Forms/V1"]
a2i_response = a2i_json["humanAnswers"][0]["answerContent"]["AWS/Textract/AnalyzeDocument/Forms/V1"]

# 2. Initialize the Document object
doc = Document(a2i_response)

# 3. Iterate over elements
for page in doc.pages:
    for field in page.form.fields:
        k = field.key.text if field.key else ""
        v = field.value.text if field.value else ""
        print(f"Field: Key: {k}, Value: {v}")