---
title: "AiProcessingSettings"
canonical_url: "https://www.nutrient.io/api/python/settings/vision/advanced/ai-processing-settings/"
md_url: "https://www.nutrient.io/api/python/settings/vision/advanced/ai-processing-settings.md"
last_updated: "2026-08-13T07:38:39.822Z"
description: "Settings for AiProcessing. Values fall back through three levels: document → SDK → built-in default."
---

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`

```python

from nutrient_sdk import AiProcessingSettings

```

## Construction

`AiProcessingSettings` is accessed through a [`Document`](/api/python/document/) instance for per-document overrides, or via [`SdkSettings`](/api/python/settings/document/sdk-settings/) for SDK-wide defaults.

```python

# 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

```python

@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`](/api/python/enums/vlm-provider/)

**Default:** `VlmProvider.Unknown`

---

### api_key

```python

@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

```python

@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

```python

@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`](/api/python/enums/vlm-provider/)

**Default:** `VlmProvider.Unknown`

---

### include_composite_confidence

```python

@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

```python

@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

```python

@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

```python

@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

```python

@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

```python

@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

```python

@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

```python

@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

```python

@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

```python

@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

```python

@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]`

---

---

## Related pages

- [Advanced](/api/python/settings/vision/advanced.md)
- [Per-document override](/api/python/settings/vision/advanced/ai-augmenter-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/claude-api-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/content-extraction-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/custom-vlm-api-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/deskew-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/document-layout-json-export-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/finalizer-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/form-labeling-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/form-recognition-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/google-api-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/handwriting-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/inference-layout-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/ocr-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/open-ai-api-endpoint-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/open-ai-languages-detection-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/open-ai-picture-alt-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/reading-order-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/segmenter-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/table-recognition-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/vision-acceleration-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/vision-descriptor-settings.md)
- [Per-document override](/api/python/settings/vision/advanced/words-detection-settings.md)