FormLabelingSettings

Settings for FormLabeling. 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 FormLabelingSettings

Construction

# Per-document override
with Document.open("input.pdf") as doc:
    settings = doc.settings.form_labeling_settings
    settings.some_field = new_value          # mutate fields directly

# SDK-wide default (applies to all documents)
SdkSettings.form_labeling_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.form_labeling_settings = other_settings is rejected.

Properties

candidate_labels

@property
def candidate_labels(self) -> str

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

Optional vocabulary of candidate labels the model should prefer when labeling. Provide labels as a newline- or comma-separated list (for example, “First name, Last name, Date of birth”). The model matches a field to one of these when it fits, and proposes a new label otherwise; each field’s FormFieldNode.LabelSource records whether the label was “matched” or “invented”. Matched labels are normalized to the casing given here. Empty (default) means fully free-form labeling.

Type: str

Default: string.Empty

enable_ai_labeling

@property
def enable_ai_labeling(self) -> bool

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

Opt in to AI semantic labeling of detected form fields. When false (default), form detection runs offline and no vision model is contacted; when true, the flow selected by enrichment_model runs.

Type: bool

Default: false

enable_ai_remove_false_positives

@property
def enable_ai_remove_false_positives(self) -> bool

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

When true, form fields the AI flags as false positives are removed from the document graph so they never reach the exported output. When false (default), flagged fields are kept and annotated (non-destructive). Only takes effect when enable_ai_labeling is true.

Type: bool

Default: false

enrichment_model

@property
def enrichment_model(self) -> FormVlmEnrichmentModel

@enrichment_model.setter
def enrichment_model(self, value: FormVlmEnrichmentModel) -> None

Which model family enriches fields, and therefore which flow runs, when enable_ai_labeling is true. Defaults to Generalist (set-of-marks over the provider configured via provider); set to Specialist to use the dedicated detect+extract model configured via FormVlmConnectionSettings.

Type: FormVlmEnrichmentModel

Default: FormVlmEnrichmentModel.Generalist

fallback_enrichment_model

@property
def fallback_enrichment_model(self) -> Optional[FormVlmEnrichmentModel]

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

Optional fallback flow, retried on the whole document when enrichment_model fails outright — its connection can’t be reached, or, for Specialist, every page failed. null (the default) means no document-level fallback: a primary failure fails the call, and an individual failed Specialist page still just degrades to detector-only output, exactly as when no fallback is configured. When set to Specialist, the fallback connection comes from FormVlmFallbackConnectionSettings — independent of FormVlmConnectionSettings, so primary and fallback can point at two different dedicated endpoints. When set to Generalist, the provider comes from fallback_provider (which must be configured to a real provider) and its matching per-provider settings class.

Type: Optional[FormVlmEnrichmentModel]

Default: null

overlap_threshold

@property
def overlap_threshold(self) -> float

@overlap_threshold.setter
def overlap_threshold(self, value: float) -> None

Specialist only: the geometric overlap bar (IoU for a type-agnostic claim, or IoS for a type-compatible containment claim) the RF-DETR x VLM correlator uses for its hard-match phase and its soft-tier corroboration phase (FormVlmCorrelator.Correlate) — its phase-3 bare-box rescue does not require any overlap at all; it accepts a genuinely disjoint box within the edge-to-edge gap rescue_distance_multiplier configures. Default 0.2 (the benchmarked/scored value, reports/cloud-endpoint-hybrid.json in the training repo) — exposed here mainly for tuning experiments; most callers should leave it at the default.

Type: float

Default: 0.2f

rescue_distance_multiplier

@property
def rescue_distance_multiplier(self) -> float

@rescue_distance_multiplier.setter
def rescue_distance_multiplier(self, value: float) -> None

Specialist only: how the correlator’s phase-3 distance-based rescue decides a bare hard-tier box is close enough to a VLM item to claim it — the edge-to-edge gap on each axis must be less than this value times that box’s own width (x) / height (y) (FormVlmCorrelator.Correlate). Default 2.5 (tuned after field testing). Exposed mainly for tuning experiments.

Type: float

Default: 2.5f