Quickstart

Install

docgate supports Python 3.10 and later.

pip install docgate

Install the optional Office readers when you need DOCX, XLSX, or PPTX input:

pip install "docgate[office]"

Read local text for free

import docgate

result = docgate.read("terms.pdf")

for page in result.pages:
    print(page.page, page.engine.value, page.text[:80])

if not result.receipt.complete:
    print("Unread pages:", result.receipt.unknown)

Usable embedded PDF text is returned with the text_layer engine and costs nothing. Image-only PDF pages require a provider; without one they remain explicitly unknown.

Add a provider for scanned pages

Supply providers per call, or set a process-wide default with configure(). The example uses a nominal page estimate. In a production application, prefer a PricingProfile that records when and where you verified the price.

from decimal import Decimal
import docgate

vision = docgate.OpenAICompatibleProvider(
    model="your-vision-model",
    api_key="...",  # load from your application's secret store
    base_url="https://your-openai-compatible-host/v1",
    cost_per_page=Decimal("0.004"),
)

result = docgate.read("scans.pdf", providers=[vision])
print(result.text)
print(result.receipt.spent)

Check completeness before making a decision

Result.text is a convenience view. Use pages and receipt when page-level provenance matters.

if not result.receipt.complete:
    for unknown in result.receipt.unknown:
        print(f"page {unknown.page}: {unknown.reason.value} — {unknown.detail}")
    # Decide in your application whether to retry, request another file, or stop.

docgate reports facts about extraction. It does not interpret documents or make business decisions from them.