This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /api/csharp/settings/vision/advanced/ai-processing-settings.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. 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.

using Nutrient;

The SDK creates this class through factory methods or other SDK objects.

Properties

AiProvider

public VlmProvider AiProvider { get; set; }

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

ApiKey

public string? ApiKey { get; set; }

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

Type: string?

Endpoint

public string? Endpoint { get; set; }

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: string?

FallbackAiProvider

public VlmProvider FallbackAiProvider { get; set; }

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

IncludeCompositeConfidence

public bool IncludeCompositeConfidence { get; set; }

(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

IncludeConfidence

public bool IncludeConfidence { get; set; }

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

IncludeGroundedness

public bool IncludeGroundedness { get; set; }

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

IncludePageImages

public bool IncludePageImages { get; set; }

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

IncludeSourceLocations

public bool IncludeSourceLocations { get; set; }

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

ListWindowTokens

public int ListWindowTokens { get; set; }

Page-content token budget per call for a second, list-filling pass when the extraction schema has an array. Given many pages at once, a model keeps the records it lists whole but stops listing early and leaves nested lists empty, so a document with more page content than this is also extracted in windows of at most this many tokens, and their list items fill in what the whole-document pass left out. Defaults to 16000; 0 turns the second pass off. A per-request listWindowTokens action parameter overrides it.

Type: int

MaxAttempts

public int? MaxAttempts { get; set; }

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: int?

MaxInputTokens

public int MaxInputTokens { get; set; }

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 IncludePageImages) 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

MaxParallelCalls

public int MaxParallelCalls { get; set; }

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

MetadataSchemaVersion

public int MetadataSchemaVersion { get; set; }

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

Model

public string? Model { get; set; }

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

Type: string?

NetworkTimeoutSeconds

public int? NetworkTimeoutSeconds { get; set; }

How long one network call to the AI provider may take, in seconds. null (the default) falls back to the NUTRIENT_AI_NETWORK_TIMEOUT_SECONDS environment variable, and then to a built-in default. Provider-independent — applies regardless of how the connection is configured. On the OpenAI-family providers this bounds one network attempt, 300s by default; a timed-out attempt is retried once, so the practical ceiling for the call is twice this value. In maestrod production traffic every finished attempt took 239s or less, so a slower one is a provider-side stall that the retry recovers. On Anthropic and Google it bounds the whole request, 600s by default, with no retry. Keep it below the caller’s own timeout: a value above the front-end’s read timeout only holds a worker after the client has gone.

Type: int?

Provider

public string? Provider { get; set; }

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

Type: string?

StrictStructuredOutput

public bool StrictStructuredOutput { get; set; }

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

public double? Temperature { get; set; }

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

Type: double?

UnparseableOutputHandling

public UnparseableOutputHandling UnparseableOutputHandling { get; set; }

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

Resource management

public void Dispose()

AiProcessingSettings implements IDisposable. Call Dispose() or use a C# using declaration to release its native handle right away. If you don’t, the handle is released when the object is garbage collected.