Extraction vs. Reasoning

Every document extraction tool does the same thing: you define fields, send a PDF, get JSON back. Vendor name, invoice total, effective date — done.

That works until your agent processes its first real invoice and the line items don't add up to the stated total. Or a contract says "24 months" in the header but "18 months" in the renewal clause. Or a 10-K reports revenue of $92,995M and your pipeline has no idea if that's up or down from last year.

Extraction pulls what's written. It doesn't check if it's correct. And for production agent workflows, that gap is where things break.

Extraction vs. reasoning: a real example

Take a standard invoice PDF and run it through both approaches:

{
  "vendor": "Acme Corp",
  "total": 4850.00,
  "line_items": [
    {"desc": "Consulting", "amount": 3200},
    {"desc": "Travel", "amount": 1550}
  ]
}

{
  "line_items_match_total": {
    "answer": false,
    "reasoning": "Line items sum to $4,750.
      Stated total is $4,850. $100 gap.",
    "confidence": "high"
  }
}

The extraction pipeline returns $4,850 because that's what the document says. The reasoning pipeline catches that $3,200 + $1,550 = $4,750, not $4,850. One pulls data. The other verifies it.

Five questions document extraction can't answer

This isn't an edge case. It's the norm in production:

• Cross-checks: "Do line items sum to the stated total?"
• Computations: "What's the YoY revenue growth rate?"
• Multi-page reasoning: "Does the termination clause on page 12 contradict the renewal terms on page 3?"
• Derived answers: "Is this contract favorable to the buyer?"
• Verification: "Does the tax amount match the subtotal at the stated rate?"

These aren't exotic requirements. Any agent processing invoices at scale needs cross-checks. Any agent reviewing contracts needs to reason across clauses. Any agent analyzing financial documents needs to compute, not just read.

How document reasoning works with the Analyze API

The /analyze endpoint answers questions that require thinking, not just reading. Same schema format as extraction — but instead of pulling literal values, it reasons over the document, computes answers, and cites every source.

schema: {
  "revenue_growth": {
    "type": "number",
    "description": "YoY revenue growth rate"
  },
  "strongest_segment": {
    "type": "string",
    "description": "Fastest growing business segment"
  },
  "debt_to_equity": {
    "type": "number",
    "description": "Debt-to-equity ratio from balance sheet"
  }
}

The response includes computed answers, the reasoning behind each one, and source citations:

{
  "revenue_growth": {
    "answer": -0.0023,
    "reasoning": "Q3 2024: $92,995M vs Q3 2023: $93,210M.
      Computed: (92995-93210)/93210 = -0.23%",
    "sources": ["Revenue was $92,995 million (p.12)",
                "Prior year revenue $93,210 million (p.47)"],
    "confidence": "high"
  }
}

Every number is computed, not generated. The reasoning trace shows exactly which pages were read and what calculations were performed. Your agent can explain how it got the answer — that's what makes it audit-ready.

When to use extraction vs. reasoning

They solve different problems:

The best agent workflows use both. Extract the fields first (fast, cheap). Then run analyze on the ones that need verification or computation. Your agent pulls the invoice total with /extract, then verifies it with /analyze. Try both in the playground.

Your document pipeline is lying to you

Your agent extracted the invoice total. But did the line items actually add up to that total? That's the difference between extraction and reasoning.

Most tools stop at extraction. We built the part that comes after.