Provider governance

Document selection controls which pages are read. A provider policy controls where those pages are allowed to go. The checks happen before cache lookup or provider invocation and every denial is recorded as a Degradation.

Keep sensitive pages local

Built-in HTTP providers identify their trust zone as external. CallableProvider defaults to custom, because docgate cannot determine whether the wrapped function calls a local binary, an internal service, or a public API. Assign it explicitly when enforcing a boundary.

import docgate

local_ocr = docgate.CallableProvider(
    "company-tesseract",
    run_local_ocr,
    trust_zone="local",
)
external_vision = docgate.OpenAICompatibleProvider(
    model="your-vision-model",
    api_key="...",
)

result = docgate.read(
    "confidential-bundle.pdf",
    providers=[local_ocr, external_vision],
    provider_policy=docgate.TrustZonePolicy(("local",)),
)

In this example, external vision is never invoked. If local OCR fails, the page becomes Unknown rather than crossing the policy boundary. The receipt records the external provider as policy_denied:trust_zone_not_allowed:external.

Application-specific policy

Implement ProviderPolicy when a fixed allowlist is not enough. The policy receives only ProviderContext: page number, provider name, engine, trust zone, pixel count, and estimated cost. It does not receive the source, path, image, transcription, filename, or credentials.

class CostAndBoundaryPolicy:
    def evaluate(self, context):
        if context.trust_zone not in {"local", "company-vpc"}:
            return docgate.PolicyDecision(False, "outside_company_boundary")
        if context.estimated_cost > Decimal("0.01"):
            return docgate.PolicyDecision(False, "page_quote_too_high")
        return docgate.PolicyDecision(True, "approved")

A policy exception or invalid return value fails closed for that provider and is visible as policy_denied:policy_error:.... Policy is routing governance, not domain interpretation: the application decides which policy applies to a document or workflow.