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 / ClaudeApiSettings / 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

Daemon-level default for whether the single rolled-up composite confidence number is attached to result.json metadata leaves (the individual signals are surfaced whenever IncludeConfidence is on; this controls only the composite). Defaults to false (off); 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_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

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

Opt-in (default false): when 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). Note that under strict mode the model must emit every schema property — absence can’t be expressed by omission unless the schema allows null. A per-request strictStructuredOutput action parameter overrides it.

Type: bool

Default: false

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]