Providers

Docgate is not limited to OpenAI, Anthropic, Mistral, or GLM. Those names are examples of integration shapes, not the product boundary. The wider ecosystem includes managed document AI, specialist parsing APIs, hosted vision models, self-hosted runtimes, and local OCR engines. See the provider landscape for the researched compatibility map and native-adapter priorities.

A provider accepts a list of PNG page bytes and returns exactly one string for each image. Providers are supplied by your application; docgate does not read credentials during planning or at import time.

Pass a provider list to read() or execute(). docgate tries it in order for pages that need model extraction. A failure or a quality-gate rejection moves on to the next provider where available.

Mistral OCR

MistralOcrProvider calls Mistral's native OCR endpoint. Its default model is mistral-ocr-latest; base_url defaults to https://api.mistral.ai/v1.

from decimal import Decimal
import docgate

ocr = docgate.MistralOcrProvider(
    api_key="...",
    cost_per_page=Decimal("0.004"),
)
result = docgate.read("scan.pdf", providers=[ocr])

OpenAI-compatible vision

OpenAICompatibleProvider sends a Chat Completions request with the PNG as a data URL. Set base_url to the versioned API root, such as https://host.example/v1; it defaults to OpenAI's versioned root.

vision = docgate.OpenAICompatibleProvider(
    model="your-vision-model",
    api_key="...",
    base_url="https://your-host/v1",
)

The adapter is intentionally protocol-level: compatibility with a particular host or model is a responsibility of the application operating that endpoint. Depending on their current model and API support, this route can cover hosted or self-hosted services such as Together AI, Fireworks AI, Groq, Z.ai, Hugging Face inference routes, NVIDIA NIM, and vLLM without a brand-specific adapter. Run conformance tests before relying on a host in production.

Anthropic vision

AnthropicProvider calls the native Messages API and sends each page as a PNG. max_tokens defaults to 4096.

claude = docgate.AnthropicProvider(
    model="your-claude-vision-model",
    api_key="...",
    max_tokens=4096,
)

Local and custom providers

Use CallableProvider to integrate an existing SDK, a local OCR engine, or a private service. The callback receives list[bytes] PNGs and must return the same number of text strings.

import docgate

def run_local_ocr(images: list[bytes]) -> list[str]:
    return [local_engine.transcribe_png(image) for image in images]

local_ocr = docgate.CallableProvider("local-ocr", run_local_ocr)
result = docgate.read("scan.pdf", providers=[local_ocr])

For a reusable integration, implement the runtime-checkable Provider protocol: name, engine, cache_identity, estimate(pages, pixels), and transcribe(images). cache_identity must change whenever model, prompt, or non-secret endpoint identity changes, so cached output cannot cross configurations.

The current protocol is page-image/text oriented. Whole-document, asynchronous, or structured providers such as Textract, Google Document AI, Azure Document Intelligence, LlamaParse, and Reducto need a capability-aware contract rather than a misleading wrapper. That contract and its conformance kit are scheduled before the public provider API is frozen.

Process-wide configuration

configure() sets the default provider ladder and optional SQLite cache for later execute() and read() calls. Per-call providers and cache take precedence.

docgate.configure(
    providers=[ocr, vision],
    cache="sqlite:///./docgate-cache.db",
    breaker_failures=3,
    breaker_cooldown_s=120,
)

Only sqlite:/// cache URLs are accepted by configure(). You can also pass a SQLiteCache instance directly.