API overview¶

The package's public entry points are available directly from docgate.

Workflow¶

API	Purpose
`plan(source, ...)`	Create a local-only `DocPlan`.
`execute(plan, ...)`	Run a plan with providers, budget, cache, and reliability controls.
`read(source, ...)`	Convenience wrapper for `plan()` followed by `execute()`.
`configure(...)`	Set process-wide default providers, cache, and circuit-breaker settings.
`audit(source, ...)`	Inspect extraction/rendering risks locally without provider calls.
`read_many(sources, ...)`	Process many documents with bounded concurrency and aggregate receipts.

Source accepts a pathlib.Path, str, or PDF bytes. Use format= to override extension-based detection.

Providers and controls¶

API	Purpose
`Provider`	Runtime-checkable protocol for OCR or vision backends.
`MistralOcrProvider`	Native Mistral OCR adapter.
`OpenAICompatibleProvider`	Chat Completions vision adapter.
`AnthropicProvider`	Native Anthropic Messages vision adapter.
`CallableProvider`	Adapter around a local function or existing SDK.
`TextQualityGate`	Offline minimum-evidence check before accepting provider text.
`ExecutionPolicy`	Timeout, retry, and backoff settings per provider/page call.
`CircuitBreakers`	Provider circuit-breaker registry.
`PricingProfile`	Caller-owned per-page estimate with verification metadata.
`SQLiteCache`	Durable local cache for successful OCR/vision output.
`ProviderPolicy`	Content-free hook for allowing or denying provider routing.
`TrustZonePolicy`	Built-in allowlist for local, external, or custom trust zones.

Results and evidence¶

API	Purpose
`Result`	Completed `PageText` records plus a `Receipt`; `text` joins completed pages.
`Receipt`	Spend, cache use, completed/unknown work, degradations, clamps, and quotes.
`Unknown` / `UnknownReason`	Explicit record of a page that was not read.
`Degradation`	A provider failure, breaker skip, or quality-gate rejection.
`Clamp` / `ClampReason`	A render output reduction and its reason.
`CostQuote`	Estimate and optional pricing provenance for one provider invocation.
`Engine`	Provenance label: text layer, hybrid, OCR, vision, or cached.
`ProgressEvent`	Content-free execution callback event.
`AuditReport`	Stable local preflight summary with page-level findings.
`BatchResult` / `BatchReceipt`	Ordered per-document outcomes and aggregate operational totals.

DocPlan.to_dict(), Receipt.to_dict(), and Result.to_dict() return versioned JSON-safe dictionaries. Result text is excluded unless include_text=True is passed explicitly.

Rendering¶

render_page(source, page, max_pixels=...) renders a 1-indexed PDF page and returns RenderResult with PNG bytes, actual pixel count, and an optional clamp. It is normally used internally; it is public for applications that need the same bounded rasterization behavior.

All records exposed by the result model are frozen dataclasses. See the guide pages for behavioral details and examples rather than depending on internal implementation details.