---
title: "ExtractSettings"
canonical_url: "https://www.nutrient.io/api/python/settings/vision/extract-settings/"
md_url: "https://www.nutrient.io/api/python/settings/vision/extract-settings.md"
last_updated: "2026-10-26T16:51:00.819Z"
description: "Settings for Extract. Values fall back through three levels: document → SDK → built-in default."
---

Settings for Extract. 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`

```python

from nutrient_sdk import ExtractSettings

```

## Construction

`ExtractSettings` 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.extract_settings
    settings.some_field = new_value          # mutate fields directly

# SDK-wide default (applies to all documents)

SdkSettings.extract_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.extract_settings = other_settings` is rejected.

## Properties

### 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`

---

### enable_complex_field_grounding

```python

@property
def enable_complex_field_grounding(self) -> Optional[bool]

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

```

When true, score leaves whose value sits inside a repeated array/object element through the nutrient-document-decision GGUF model instead of the heuristic hypothesis path, giving it the leaf's real JSON row context. Requires includeGroundedness and metadataSchemaVersion=2. Resolved from the CDN; falls back to the heuristic path on any failure. Defaults to false.

**Type:** `Optional[bool]`

---

### 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`

---

### extraction_schema

```python

@property
def extraction_schema(self) -> str

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

```

Caller-supplied JSON Schema (inline content) describing the extraction output shape. Mutually exclusive with extractionSchemaFile.

**Type:** `str`

---

### extraction_schema_file

```python

@property
def extraction_schema_file(self) -> str

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

```

Path to a file containing the JSON Schema for extraction output. Mutually exclusive with extractionSchema.

**Type:** `str`

---

### include_composite_confidence

```python

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

---

### 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`

---

### include_diagnostics

```python

@property
def include_diagnostics(self) -> Optional[bool]

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

```

When true, emit diagnostics.json as an additional artifact alongside result.json, including silentDrops: parsed table blocks that nothing in the result cites.

**Type:** `Optional[bool]`

---

### include_page_images

```python

@property
def include_page_images(self) -> bool

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

```

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); there is no page cap, as large documents are fit to the model's context window by windowing across multiple calls, not by dropping pages. When false (the default), only the pages whose text holds a chart or a picture (other than a logo, an icon or a bar or QR code) are rendered and sent, because what those pages draw is not in their text. That default applies to OpenAI's own API only: at most 40 pages are imaged, their images are compacted when needed to fit 16 MiB per document, and a request the provider rejects with them is retried text-only. Either way, for a gpt-6 model on OpenAI's own API a strip page (its rendered long side over 4,096 pixels and at least three times its short side), such as a well log or a time-location chart, is sent as overlapping tiles of about 1,024 pixels near its rendered resolution instead of one image the provider would scale down; by default up to 10 such pages are imaged even without a chart or a picture (not in a spreadsheet), besides the 40 pages, and their tiles count against the 16 MiB. The text stays authoritative for source grounding; images add a visual signal. A per-request `includePageImages` action parameter overrides it.

**Type:** `bool`

---

### 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`

---

### instructions

```python

@property
def instructions(self) -> str

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

```

Optional caller hint appended to the extraction prompt.

**Type:** `str`

---

### 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. For gpt-6 on OpenAI's own API, a call that carries image tiles carries at most 16 MiB of images, past which the document is windowed too, and a strip page sent as tiles (see `include_page_images`) whose cost alone exceeds the budget while its text fits still goes in one call, of up to 450,000 tokens, rather than lose its tiles. 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`

---

### 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 `max_input_tokens`); 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`

---

### 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`

---

### output_directory

```python

@property
def output_directory(self) -> str

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

```

Directory to write all emitted artifacts to (optional). Each artifact is written under its artifact name, for example result.json.

**Type:** `str`

---

### output_file_path

```python

@property
def output_file_path(self) -> str

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

```

Path to write the single emitted artifact to a file (optional). Fails if the run emits multiple artifacts.

**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`

---

### reasoning_effort

```python

@property
def reasoning_effort(self) -> str

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

```

Reasoning budget for reasoning models: 'default' (leave the provider's own budget in force), 'none', 'minimal', 'low', 'medium', 'high', or 'xhigh'. Which values a model accepts is decided by the provider. Unset, an OpenAI reasoning model on OpenAI's own API (the o-series, gpt-5 and gpt-6) gets 'high', which lets it work out totals and other computed values; pass 'default' to keep the provider's own budget.

**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

```

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`

---

### 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

- [Vision](/api/python/settings/vision.md)
- [Per-document override](/api/python/settings/vision/document-classification-settings.md)
- [Per-document override](/api/python/settings/vision/document-split-settings.md)
- [Per-document override](/api/python/settings/vision/parse-settings.md)
- [Per-document override](/api/python/settings/vision/schema-generation-settings.md)
- [Per-document override](/api/python/settings/vision/vision-settings.md)