Textract & Comprehend

Pre-built AI services: no ML required intermediate

Here's a mistake almost everyone makes their first week with LLMs. A ticket lands: "extract the names and email addresses from these 50,000 support messages." You reach for the tool you just learned — you pipe every message through Claude with a clever prompt, and it works beautifully on your ten test cases. Then the bill arrives, the latency is measured in seconds per document, and one message in fifty comes back with a hallucinated email that was never in the text. You've used a Ferrari to deliver pizza. The job — "find the emails" — was a solved problem years before you got there, and Amazon will do it for a fraction of a cent per call, deterministically, in milliseconds.

That is the whole reason this section exists. Textract and Comprehend are what AWS calls pre-built (or "managed") AI services: fully trained models behind a plain API call. You don't train anything, you don't pick a model, you don't manage a GPU — you send text or a document and get back a structured answer. Textract is the OCR specialist (turn pixels into text, forms, and tables); Comprehend is the NLP specialist (pull sentiment, entities, PII, language, and key phrases out of text you already have). Think of them as the microwave in your kitchen: it does exactly one narrow thing, it does it instantly and identically every time, and you'd never dream of buying a full restaurant kitchen just to reheat soup.

Now the precise idea, because the intuition needs a rule behind it. A pre-built service is a fixed-function model: it answers one well-defined question from a closed set of outputs (Comprehend's PII detector only ever returns categories AWS defined; it will never invent a new one). An LLM like Claude is open-ended: it will answer almost anything, in almost any shape, which is exactly its strength and exactly why it is slower, pricier, and occasionally wrong. So the deciding question for every document task is: "Is what I want on the fixed menu?" If yes — sentiment, PII, OCR — use the pre-built service; it is cheaper, faster, and can't hallucinate a category that doesn't exist. If no — arbitrary line items, your custom invoice fields, reasoning across the page — you need the LLM.

• Pre-built service — narrow, deterministic, cheap, fast; output drawn from a fixed set. (Textract, Comprehend.)
• LLM — general, flexible, costs more per call, can hallucinate; output is whatever you prompt for. (Claude on Bedrock.)

The common trap is treating this as a religious "LLM vs. old AI" choice. It isn't either/or. The pattern the rest of this lesson builds toward is the hybrid: let each tool do what it's best at. Textract deterministically turns the PDF into clean text — the one job an LLM is genuinely bad at (reading pixels) — and then Claude does the flexible reasoning the fixed-function API cannot. You get the reliability and price of the specialist for the mechanical part, and the intelligence of the LLM only where you actually need it.

Textract and Comprehend are pay-per-use APIs that solve narrow problems extremely well: OCR and NLP. They are cheaper and more deterministic than an LLM for what they do. The modern pattern is a hybrid: Textract turns a PDF into text, then Claude does the flexible reasoning the fixed-function API cannot.

Textract: OCR, forms, tables intermediate

You have almost certainly hit this wall. Someone hands you a folder of scanned invoices — actual photographs of paper — and asks you to "just pull the totals into a spreadsheet." You open one and realize the computer sees no "total" at all: it sees a grid of coloured dots. The text you can read with your eyes is, to the machine, a picture. Turning that picture back into characters is OCR — optical character recognition — and it is a genuinely hard problem (skewed scans, coffee stains, two-column layouts, handwriting) that took decades of research to get right. Textract is the trained result of that research, rented to you by the call.

But here's the part that makes Textract more than a plain OCR engine, and it's the reason this section matters. Reading the characters is only half the battle; the harder half is understanding structure. On an invoice, "Total" and "$99.00" aren't just two random strings — one is a label and the other is its value, and they belong together even though they might sit inches apart on the page. A row of numbers under "Qty / Item / Price" isn't loose text — it's a table. Textract can reconstruct both. Picture the difference between a human who can only read words aloud and one who can also say "that's a form, and the answer to 'Total' is ninety-nine dollars" — that second understanding is what you're paying for.

You control which understanding you get with one parameter, FeatureTypes, and this is the single most common point of confusion. Call analyze_document with no feature types and you get flat text — the LINE and WORD blocks, useful but dumb. Add FORMS and Textract also links label/value pairs (the key/value structure); add TABLES and it also reconstructs rows and columns as cells. You ask for the analysis you need, because you pay for what you ask for.

One more mental model that saves hours of confusion downstream: Textract does not hand you a tidy nested document. It returns a flat list under Blocks where each block is a typed node — a PAGE, a LINE, a WORD, a KEY_VALUE_SET, a CELL — and the blocks point at each other by ID to describe relationships. In other words the response is a graph, not a tree you can index into. That's why the lab below filters (if b["BlockType"] == "LINE") rather than reaching for resp["lines"] — there is no such key. Expect to iterate and select the block types you care about; that flat-graph shape is deliberate, because it lets one response carry pages, words, forms, and tables all at once without forcing a single rigid structure on documents that come in every shape imaginable.

textract.pyimport boto3
tx = boto3.client("textract", region_name="us-east-1")

# analyze_document with FORMS + TABLES extracts key/value pairs and cells,
# not just raw text. Point it at a document already in S3.
resp = tx.analyze_document(
    Document={"S3Object": {"Bucket": "my-docs", "Name": "invoice.pdf"}},
    FeatureTypes=["FORMS", "TABLES"],
)
# blocks are a graph; pull the raw lines as a quick check
lines = [b["Text"] for b in resp["Blocks"] if b["BlockType"] == "LINE"]
print("\n".join(lines[:5]))

Comprehend: entities, PII, sentiment advanced

Textract gave you the words; now you have to make sense of them. Imagine ten thousand support emails just landed in a bucket. Compliance needs to know which ones contain personal data before they can be archived. Product wants to know which customers are angry. Support wants to know which companies and cities are being complained about. You could read all ten thousand yourself over a very long weekend, or write brittle regexes that catch jane@acme.com but miss jane [at] acme dot com and flag x@y in a URL by mistake. Comprehend is the trained specialist that does these narrow reading-comprehension jobs for you, per call, without you owning a model.

The key thing to internalize — and it's why this sits in its own section rather than blurring into "just use an LLM" — is that Comprehend is not one clever model; it's a family of narrow, single-purpose classifiers, each answering one fixed question and each drawing from a closed, AWS-defined set of answers. detect_sentiment returns one of a fixed handful of moods (POSITIVE, NEGATIVE, NEUTRAL, MIXED). detect_pii_entities returns categories from a predefined list (NAME, EMAIL, ADDRESS, CREDIT_DEBIT_NUMBER, and so on). detect_entities tags real-world things with fixed types (PERSON, LOCATION, ORGANIZATION, DATE). You don't train these and you can't teach them a new category — which sounds like a limitation but is exactly the point. Because the menu is fixed, the output is deterministic and reliable: the same sentence classified today and next month gives the same answer, with a confidence score you can threshold on.

• detect_sentiment — how the text feels: one label from a fixed set, plus per-label confidence scores.
• detect_pii_entities — personal data present (names, emails, cards…), by type and location in the string, so you can redact.
• detect_entities — the real-world things named (people, places, organizations, dates), each tagged with its category.

Because each call is independent and narrow, the honest way to think about Comprehend is as a box of specialized tools rather than a single brain: you compose the ones you need for a task (run sentiment and entities on the same review and merge the results) rather than asking one call to do everything. That composition — several cheap, deterministic classifiers stitched together — is often all a real pipeline needs, and it costs a rounding error compared to sending the same text to an LLM.

Which brings us to the boundary you must keep straight, because it's the single most useful thing in this lesson: Comprehend can only find categories it already knows. Ask it for sentiment or emails and it's perfect. Ask it for "the invoice number and the three line-item totals on this purchase order" and it simply has no such category — there is nothing on its menu to return. That is not a bug to work around; it is the exact seam where you hand off to Claude. Hold that line firmly: known category → Comprehend; arbitrary, document-specific fields → LLM. The next section is that handoff.

comprehend.pyimport boto3
cp = boto3.client("comprehend", region_name="us-east-1")
text = "Contact Jane Doe at jane@acme.com about the Seattle outage. Very frustrated."

print(cp.detect_sentiment(Text=text, LanguageCode="en")["Sentiment"])
print([e["Type"] for e in cp.detect_pii_entities(Text=text, LanguageCode="en")["Entities"]])
print([(e["Text"], e["Type"]) for e in cp.detect_entities(Text=text, LanguageCode="en")["Entities"]])

NEGATIVE
['NAME', 'EMAIL']
[('Jane Doe', 'PERSON'), ('Seattle', 'LOCATION')]

The hybrid: Textract → Claude expert

This is where the two halves of the lesson click together, and it starts with a failure you can feel. Finance hands you invoices from three hundred different vendors and wants vendor, total, and due_date out of each. The naive answer — a template parser that reads "the total is always in the box at bottom-right" — works for exactly the vendors you tested and shatters the first time a supplier moves their total to the top, renames it "Amount Due," or splits it across two lines. Templates are brittle because real documents are infinitely various; you cannot enumerate every layout on Earth. Comprehend can't rescue you either: "invoice total" and "due date on this vendor's form" aren't on its fixed menu. You've walked into the exact gap the pre-built services leave open.

The resolution is to stop asking one tool to do a job it's bad at, and instead chain two tools, each doing what it's best at. Textract is superb at the mechanical, deterministic part an LLM is genuinely weak at — reading pixels reliably into clean text. Claude is superb at the flexible, judgment part a fixed-function API cannot do — looking at that text, regardless of layout, and understanding "this string is the vendor, that number is the total." Neither could do the whole job alone; together they cover it. Think of it as an assembly line: a fast, tireless scanner (Textract) feeds a smart analyst (Claude), and you pay the analyst only for the thinking, not for squinting at scans.

The mechanism that makes the analyst reliable — and this is the piece worth studying — is forced tool use, which you met in W3. Left to prose, an LLM might reply "The vendor appears to be Acme and the total is around $99." That's useless to a program: you'd have to parse English back into fields, and you'd be back to brittle regexes. Instead you hand Claude a tool schema: a JSON shape naming the exact fields and types you want (vendor: string, total: number, which are required), and you set toolChoice to force Claude to answer by calling that tool. Now the model must return schema-valid structured data — a clean dict — instead of a paragraph. The LLM supplies the flexibility (it maps any layout into your fields); the schema supplies the discipline (the output shape never varies). That combination — deterministic OCR, flexible reasoning, rigid output contract — is the pattern that powers real document-intelligence pipelines, and it's the seam every serious system builds on.

Comprehend finds known entity types. When you need arbitrary structured extraction — line items, totals, custom fields — hand the Textract text to Claude with a tool schema (W3). Deterministic OCR + flexible reasoning.

extract.pyimport boto3
brt = boto3.client("bedrock-runtime", region_name="us-east-1")

def extract_invoice(doc_text):
    schema = {"tools": [{"toolSpec": {
        "name": "record_invoice",
        "description": "Record structured invoice fields.",
        "inputSchema": {"json": {"type": "object", "properties": {
            "vendor": {"type": "string"},
            "total": {"type": "number"},
            "due_date": {"type": "string"},
        }, "required": ["vendor", "total"]}},
    }}]}
    resp = brt.converse(
        modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
        messages=[{"role": "user", "content": [{"text": f"Invoice text:\n{doc_text}"}]}],
        toolConfig={**schema, "toolChoice": {"tool": {"name": "record_invoice"}}},
    )
    for b in resp["output"]["message"]["content"]:
        if "toolUse" in b:
            return b["toolUse"]["input"]

import boto3

tx = boto3.client("textract", region_name="us-east-1")
resp = tx.analyze_document(
    Document={"S3Object": {"Bucket": "my-docs", "Name": "invoice.png"}},
    FeatureTypes=["FORMS", "TABLES"],
)
for b in resp["Blocks"]:
    if b["BlockType"] == "LINE":
        print(b["Text"])

import boto3

cp = boto3.client("comprehend", region_name="us-east-1")
text = "Email jane@x.com or call about card 4111111111111111."
resp = cp.detect_pii_entities(Text=text, LanguageCode="en")
for e in resp["Entities"]:
    print(e["Type"])   # e.g. EMAIL, CREDIT_DEBIT_CARD_NUMBER

import boto3

cp = boto3.client("comprehend", region_name="us-east-1")
text = "Loved the Seattle store, but Acme support was slow."
s = cp.detect_sentiment(Text=text, LanguageCode="en")
e = cp.detect_entities(Text=text, LanguageCode="en")
summary = {
    "sentiment": s["Sentiment"],                          # POSITIVE/NEGATIVE/...
    "entities": [(x["Text"], x["Type"]) for x in e["Entities"]],
}
print(summary)

import boto3

brt = boto3.client("bedrock-runtime", region_name="us-east-1")
ocr_text = "Invoice #INV-42  Total: $1,299.00"   # from Textract LINEs
TOOLS = {"tools": [{"toolSpec": {"name": "record_invoice",
  "description": "Extract invoice fields.",
  "inputSchema": {"json": {"type":"object","properties":{
     "invoice_number":{"type":"string"},
     "total":{"type":"number"}},"required":["invoice_number","total"]}}}}],
  "toolChoice": {"tool": {"name": "record_invoice"}}}

r = brt.converse(modelId="anthropic.claude-3-5-sonnet-20241022-v2:0",
    messages=[{"role":"user","content":[{"text": ocr_text}]}],
    toolConfig=TOOLS)
for b in r["output"]["message"]["content"]:
    if "toolUse" in b:
        print(b["toolUse"]["input"])   # {'invoice_number':'INV-42','total':1299.0}

COMPREHEND_TASKS = {"sentiment", "pii", "entities", "language"}

def route(task):
    if task in COMPREHEND_TASKS:
        return "comprehend"      # cheap, deterministic
    if task == "ocr":
        return "textract"
    return "claude-bedrock"      # arbitrary/custom extraction

for t in ("sentiment", "ocr", "custom_line_items"):
    print(t, "->", route(t))

REQUIRED = ["invoice_number", "total"]

def gate(extracted, ocr_confidence, min_conf=0.90):
    missing = [f for f in REQUIRED if not extracted.get(f)]
    if missing or ocr_confidence < min_conf:
        return {"route": "human_review",
                "missing": missing, "confidence": ocr_confidence}
    return {"route": "auto_post", "data": extracted}

good = gate({"invoice_number":"INV-42","total":1299.0}, 0.98)
bad  = gate({"invoice_number":"INV-42"}, 0.97)   # total missing
print(good["route"], "|", bad["route"])   # auto_post | human_review

Knowledge check check yourself