docgate

Spend the minimum on document AI, and know exactly what you didn't check.

Most document pipelines extract every page and return an empty string when a page could not be read. docgate is deliberately different: it extracts the free text layer first, bounds raster output before allocating memory, and always returns a receipt that distinguishes blank, skipped, and unknown pages.

Formats

Install Office readers when needed:

pip install "docgate[office]"

For a non-PDF byte stream, pass a file path today; stream adapters are an intentional extension point for future formats.

import docgate

result = docgate.read("bundle.pdf")
print(result.text)
print(result.receipt.complete)
print(result.receipt.unknown)

Install

pip install docgate

What it can do

• Extract usable embedded PDF text for free, before calling any model.
• Output-bounded page rasterisation. A pathological declared page size cannot allocate an unbounded image.
• A Clamp is reported whenever requested output is reduced.
• A Receipt accompanies every result. Pages that were not read are explicit Unknown records, never silently omitted.
• Send only pages without a usable text layer to your OCR/vision provider.
• Fall back across providers and record every failed attempt as a Degradation.

Bring any OCR or vision model

docgate is provider-neutral. It ships lightweight adapters for Claude and any OpenAI-compatible vision endpoint (including compatible GLM deployments). For every other model — local Tesseract, a private endpoint, Azure, Gemini, or an SDK you already use — pass a small CallableProvider or implement Provider.

from decimal import Decimal
import docgate

vision = docgate.OpenAICompatibleProvider(
    model="your-vision-model",
    api_key="...",
    base_url="https://your-openai-compatible-host/v1",
    cost_per_page=Decimal("0.004"),
)

result = docgate.read("bundle.pdf", providers=[vision])

Claude uses its native Messages API:

claude = docgate.AnthropicProvider(model="your-claude-vision-model", api_key="...")
result = docgate.read("bundle.pdf", providers=[claude])

For a local or custom engine:

local_ocr = docgate.CallableProvider("my-ocr", lambda png_pages: [run_ocr(p) for p in png_pages])
result = docgate.read("bundle.pdf", providers=[local_ocr])

Control spend and retain private cache hits

Pass a hard budget to stop before an extra paid page. The partial result stays useful and every page not attempted is listed as BUDGET_EXHAUSTED.

result = docgate.read("bundle.pdf", providers=[vision], budget=Decimal("0.10"))
assert result.receipt.spent <= Decimal("0.10")

Use SQLiteCache for durable local cache hits across runs. Cache entries use a SHA-256 digest of the rendered PNG bytes plus provider identity — never a path or filename. Failed and empty responses are never stored.

cache = docgate.SQLiteCache(".docgate-cache.db")
result = docgate.read("bundle.pdf", providers=[vision], cache=cache)

Stay available when providers fail

Provider fallbacks are tried in order. Repeated failures open a circuit breaker, so a dead key does not consume a full timeout for every page. After its cooldown, docgate automatically allows one recovery probe; a successful call closes the breaker. Every skipped or failed provider is recorded in receipt.degraded.

docgate.configure(
    providers=[primary_vision, backup_vision],
    breaker_failures=3,
    breaker_cooldown_s=120,
)

read() is a convenience wrapper around plan() then execute(). Planning is local-only and does not invoke any provider.

plan = docgate.plan("bundle.pdf", need="degree certificate")
print(plan.estimated_cost)       # Decimal('0') in v0.1
print(plan.candidate_pages)      # ranked from local text-layer signals
result = docgate.execute(plan)

Select before you spend

Pass selection="candidates" to read only pages with local keyword evidence, or selection="top_k" with max_paid_pages to cap work at the highest-ranked pages. Every excluded page is present in receipt.unknown as SKIPPED_BY_PLAN; partial output is always visible.

result = docgate.read(
    "bundle.pdf",
    need="degree certificate",
    selection="top_k",
    max_paid_pages=1,
    providers=[vision],
)

What docgate does not do

• It is not an OCR engine or hosted model service.
• It is not RAG, a vector store, or an agent framework.
• It does not interpret, score, verify, or make decisions about documents.
• It has no telemetry or phone-home behaviour.

Status

v0.1 provides the safe local foundation, provider-neutral OCR/vision adapters, hard budgets, and durable content-addressed caching. Self-closing circuit breakers and hybrid image-region OCR are next.

License

Apache-2.0.

Releases

Releases are published from GitHub Actions using PyPI Trusted Publishing—no long-lived PyPI token is stored in this project. See the release guide.