ExtractSettings

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

from nutrient_sdk import ExtractSettings

Construction

# 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

@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

@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

@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

@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

@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

@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

@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

@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

@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

@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

@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

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

@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

@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

@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

@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

@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

@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

@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

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