AiProcessingSettings

Settings for AiProcessing. Values fall back through three levels: document → SDK → built-in default. Writes target the document only when set on a document’s settings, otherwise the SDK globally when set on SdkSettings.

Tags: Vision, Advanced

from nutrient_sdk import AiProcessingSettings

Construction

# Per-document override
with Document.open("input.pdf") as doc:
    settings = doc.settings.ai_processing_settings
    settings.some_field = new_value          # mutate fields directly

# SDK-wide default (applies to all documents)
SdkSettings.ai_processing_settings.some_field = new_value

Settings are configured by writing to fields on the returned object. The settings property itself cannot be reassigned — doc.settings.ai_processing_settings = other_settings is rejected.

Properties

ai_provider

@property
def ai_provider(self) -> VlmProvider

@ai_provider.setter
def ai_provider(self, value: VlmProvider) -> None

The primary AI provider for extraction/classification. Uses the same VlmProvider vocabulary as the vision pipeline, so its connection (endpoint, key, model) is read from the matching per-provider settings class (OpenAIApiEndpointSettings / GoogleApiSettings / AnthropicApiSettings / CustomVlmApiSettings) — the single place a provider is configured for every AI module.

Type: VlmProvider

Default: VlmProvider.Unknown

api_key

@property
def api_key(self) -> str

@api_key.setter
def api_key(self, value: str) -> None

API key for the configured provider. Legacy flat connection (see Provider).

Type: str

endpoint

@property
def endpoint(self) -> str

@endpoint.setter
def endpoint(self, value: str) -> None

Endpoint URL. Required for the local provider. Optional for openai — supply it to route through an OpenAI-compatible proxy/gateway; the public OpenAI endpoint is used when unset. Optional for anthropic (defaults to the public Anthropic base when unset). When set, must be a valid absolute URL. Legacy flat connection (see Provider).

Type: str

fallback_ai_provider

@property
def fallback_ai_provider(self) -> VlmProvider

@fallback_ai_provider.setter
def fallback_ai_provider(self, value: VlmProvider) -> None

Optional secondary AI provider used to transparently retry a request when the primary AiProvider returns no content (content filtering) or is temporarily unavailable. Its connection is read from the matching per-provider settings class. Only consulted when AiProvider is set; a value of Unknown (the default), or one equal to AiProvider, disables fallback.

Type: VlmProvider

Default: VlmProvider.Unknown

include_composite_confidence

@property
def include_composite_confidence(self) -> bool

@include_composite_confidence.setter
def include_composite_confidence(self, value: bool) -> None

(Schema v1 only.) Daemon-level default for whether the legacy rolled-up composite number is attached to result.json metadata leaves as confidence. No effect under schema v2 (the composite is internal-only there). Defaults to false; a per-request includeCompositeConfidence action parameter overrides it.

Type: bool

Default: false

include_confidence

@property
def include_confidence(self) -> bool

@include_confidence.setter
def include_confidence(self, value: bool) -> None

Daemon-level default for whether AI processing capacities emit confidence output - the confidence.json sidecar and the per-field confidence signals on result.json metadata. Defaults to false (off); a per-request includeConfidence action parameter overrides it.

Type: bool

Default: false

include_groundedness

@property
def include_groundedness(self) -> bool

@include_groundedness.setter
def include_groundedness(self, value: bool) -> None

Daemon-level default for whether the NLI groundedness score is computed and surfaced as the primary confidence.groundedness (schema v2 only). It runs one ONNX forward pass per cited field, so it defaults to false to keep latency predictable; turn it on per request via includeGroundedness. Has no effect under schema v1 or when IncludeConfidence is off.

Type: bool

Default: false

include_page_images

@property
def include_page_images(self) -> bool

@include_page_images.setter
def include_page_images(self, value: bool) -> None

Opt-in (default false): when true, every page of the source document is rendered to an image and sent to the model alongside the IR-lite text (multimodal extraction). The text stays authoritative for source grounding; images add a visual signal. There is no page cap — large documents are fit to the model’s context window by windowing across multiple calls, not by dropping pages. A per-request includePageImages action parameter overrides it.

Type: bool

Default: false

include_source_locations

@property
def include_source_locations(self) -> bool

@include_source_locations.setter
def include_source_locations(self, value: bool) -> None

Whether extraction grounds each extracted field back to its source location in the document — the metadata node of result.json with per-field match labels and source bounding boxes. Defaults to true. Turn off to cut model token usage when only the extracted values matter: grounding mirrors the schema in the structured-output request so the model also returns per-field source ids. A per-request includeSourceLocations action parameter overrides it.

Type: bool

Default: true

max_attempts

@property
def max_attempts(self) -> Optional[int]

@max_attempts.setter
def max_attempts(self, value: Optional[int]) -> None

Maximum retry attempts on structured-output failure. null uses the capacity default of 1. Provider-independent — applies regardless of how the connection is configured.

Type: Optional[int]

max_input_tokens

@property
def max_input_tokens(self) -> int

@max_input_tokens.setter
def max_input_tokens(self, value: int) -> None

Input-token budget per model call. When the estimated input (schema + IR-lite text + page images) exceeds this, the document is split into page-level windows that each fit, extracted independently, and merged — so a large document never hard-fails on the provider’s context limit. Defaults to 100000, a conservative value that fits common model context windows while leaving room for output; raise it for large-context models. A per-request maxInputTokens action parameter overrides it.

Type: int

Default: 100_000

max_parallel_calls

@property
def max_parallel_calls(self) -> int

@max_parallel_calls.setter
def max_parallel_calls(self, value: int) -> None

Maximum number of windowed extraction calls to run concurrently. Only applies when a large document is split into page-level windows (see MaxInputTokens); each window is an independent VLM call, so running several at once is a large wall-clock win. Defaults to 4 — a balance between throughput and provider rate limits; raise it for large-context keys, lower it (or set 1 for fully sequential) if you hit rate limits. A per-request maxParallelCalls action parameter overrides it.

Type: int

Default: 4

metadata_schema_version

@property
def metadata_schema_version(self) -> int

@metadata_schema_version.setter
def metadata_schema_version(self, value: int) -> None

Daemon-level default for the result.json metadata schema version: 1 = the legacy flat shape (per-field match / confidenceComponents / opt-in composite confidence); 2 = the simplified citation + confidence shape (primary groundedness, ocr, boolean schemaValid). Defaults to 1 for backward compatibility; a per-request metadataSchemaVersion overrides it.

Type: int

Default: 1

model

@property
def model(self) -> str

@model.setter
def model(self, value: str) -> None

Model identifier (e.g. "gpt-4o" or a local model id). Legacy flat connection (see Provider).

Type: str

provider

@property
def provider(self) -> str

@provider.setter
def provider(self, value: str) -> None

Provider discriminator. One of "openai", "local" (custom OpenAI-compatible endpoint), or "anthropic" (alias "claude", native Anthropic Messages API).

Type: str

strict_structured_output

@property
def strict_structured_output(self) -> bool

@strict_structured_output.setter
def strict_structured_output(self, value: bool) -> None

Default true: structured output runs in the provider’s strict mode — the response is grammar-constrained to the schema, which is normalized automatically (additionalProperties: false, all properties required, unsupported keywords moved into descriptions). On by default because the schema is otherwise only advisory: without strict, the provider compiles no decoding grammar and nothing stops the model returning a payload that doesn’t match, which is what produced “AI processing failed to produce valid JSON” failures in production. Note that under strict mode the model must emit every schema property — absence stays expressible because optional properties are made nullable before the schema reaches the provider. Set to false, or pass the per-request strictStructuredOutput action parameter, to opt back out.

Type: bool

Default: true

temperature

@property
def temperature(self) -> Optional[float]

@temperature.setter
def temperature(self, value: Optional[float]) -> None

Sampling temperature passed to the model. null uses the provider default. Legacy flat connection (see Provider).

Type: Optional[float]

unparseable_output_handling

@property
def unparseable_output_handling(self) -> UnparseableOutputHandling

@unparseable_output_handling.setter
def unparseable_output_handling(self, value: UnparseableOutputHandling) -> None

How extraction responds when the model’s output never parses against the requested schema. Default keeps each API surface’s own behavior (the SDK’s structured-extraction API fails with a descriptive error; server pipelines return an empty result with warnings). Set Fail or ReturnEmpty to force one behavior everywhere. A per-request onFailureReturnEmptyJson action parameter overrides it.

Type: UnparseableOutputHandling

Default: UnparseableOutputHandling.Default