AI Extract Field Options

Defines options controlling how AI Extract and AI Table Reader work for a Data Field.

Remarks

The 'AI Extract Field Options' class provides advanced configuration for how Grooper's AI Extract method interacts with a specific Data Field. These options allow you to fine-tune the instructions and alignment strategies used by the LLM (Large Language Model) when extracting data, ensuring that field values are accurately located, labeled, and mapped back to the document.

Role in Grooper

• Used to customize the extraction and alignment behavior for individual fields when using AI Extract or AI Table Reader.
• Supports both single-value fields and columns within tables, adapting to a wide range of document layouts and data types.
• Enables integration of field-specific instructions, value lists, and header detection into the LLM prompt, improving extraction accuracy and reliability.

How It Works

• Each Data Field can be extended with an 'AI Extract Field Options' object, allowing you to override default extraction behavior.
• Options such as alignment mode, inclusion of value lists, and header detection are used to generate more precise LLM prompts and to interpret the LLM's output in a way that best matches the document's structure.
• These settings are especially important for fields with complex value types, choice lists, or when extracting from tables with dynamic headers.

Configuration and Usage

• Configure the alignment mode to control how extracted values are mapped back to the document (e.g., by value, by quote, by label).
• Enable or disable inclusion of value lists to guide the LLM toward valid field values.
• For table columns, enable header detection to allow the LLM to identify and use the correct column header during extraction.

Example Scenario

Suppose you have a field with a fixed set of valid values (a choice list) and want the LLM to only return those values. By enabling 'Include List Values', the LLM prompt will include the list, increasing the likelihood of valid results. For a table column with dynamic headers, enabling 'Detect Header Cell' ensures the LLM can correctly identify the column in the document.

These options provide granular control over AI-driven extraction, supporting robust, accurate, and context-aware data capture in Grooper.

Properties

Name	Type		Description
Field Alignment	FieldAlignMode	►	Specifies the mode to be used for aligning values captured by the AI back to locations in the document. DefaultNatural Can be one of the following values: Name Value Description None 0 No attempt is made to align the extracted value to a location in the document. Only the value is requested from the LLM in the JSON schema. The value is used as-is, with no attempt to match or highlight it in the document. No navigation or highlighting will be available in the Data Grid or Data Viewer. Use this mode when provenance is not important, or when alignment is not possible (e.g., for computed or synthetic fields). This mode provides the simplest and fastest extraction, but no review context. ► Natural 1 Aligns the value by searching for an exact match in the document content. Only the value is requested from the LLM in the JSON schema. Grooper attempts to locate the value in the document text using normalization and type-specific matching (e.g., for numbers and dates, multiple formats are considered). If a unique match is found, the value is highlighted and navigable in the Data Grid and Data Viewer. If the value is ambiguous or appears multiple times, additional context may be needed. Use this mode for fields with unique, well-formed values such as IDs, numbers, or dates. Fast and reliable for simple fields, but may not work for repeated or ambiguous values. ► Quoted 2 Aligns the value using a quoted passage from the document content. The JSON schema requests both the value and an originalValue property from the LLM, where originalValue is the exact text as it appears in the document. Grooper uses the quoted text to locate the value in the OCR text, even if the value itself is ambiguous or appears multiple times. This is especially useful for long text fields, descriptions, or values embedded in larger passages. If the LLM returns an inaccurate or incomplete quote, alignment may fail. Use this mode when the value may be ambiguous, or when you want to ensure the exact document text is captured and reviewable. ► Labeled 3 Aligns the value by matching it to the closest label or field name in the document. The JSON schema requests both the value and a label property from the LLM, where label is the field name or header as it appears in the document. Grooper locates the label in the document and associates the value with the nearest occurrence. This is effective for forms, tables, or documents with clear field labels or headers. If the label is not unique or is missing, alignment may be ambiguous. Use this mode when values may be repeated but are always associated with a unique label in the document. ► LabeledAndQuoted 4 Aligns the value using both a label and a quoted passage from the document. The JSON schema requests the value, a label, and an originalValue property from the LLM. Grooper first finds the label, then uses the quote to pinpoint the value's location. This provides the highest accuracy for complex documents, multi-line fields, or when both label and context are needed to disambiguate the value. Use this mode for fields where neither label nor quote alone is sufficient, or where maximum review accuracy is required. If either the label or quote is missing or inaccurate, alignment may fall back to the available information. ► Geometric 5 Uses explicit page and location information provided by the LLM to align the value. This mode must be used in conjunction with the Layout Objects quoting method, which provides the location of each text segment. The JSON schema requests the value, __pageNo, and __bounds properties from the LLM. The LLM is asked to return the page number and bounding box coordinates (left, top, width, height) for the value. Grooper uses this information to directly extract and highlight the value from the document geometry. This is most useful when the LLM or extraction process can provide precise location data, such as in table extraction or when working with structured layouts. Use for advanced scenarios where spatial accuracy is critical, or when reviewing values in visually complex documents. If the LLM returns invalid or missing coordinates, alignment will fail. ► The 'Field Alignment' property determines how Grooper attempts to map values extracted by the LLM back to their original locations in the document. This affects how confidence, provenance, and review information are assigned to extracted values. Impact The chosen mode affects how Grooper validates, reviews, and presents extracted values, and can improve accuracy in complex or ambiguous extraction scenarios.
Include List Values	Boolean	►	If true, the LLM instructions will include the list of values for this field. DefaultTrue The 'Include List Values' property controls whether the list of valid values (choice list) for this field is included in the LLM prompt. This helps guide the LLM to return only valid or expected values, improving extraction accuracy for fields with a defined set of options. Configuration Guidance Enable for fields with a fixed set of valid values (e.g., status, type, category). Disable for free-form fields or when the list is too large to be practical. Example If a field has valid values ["Approved", "Pending", "Rejected"], enabling this property will instruct the LLM to only return one of these values. Impact Including the value list can significantly improve the reliability of AI extraction for choice fields, but may increase prompt length for large lists.
Detect Header Cell	Boolean	►	If true, specifies that the LLM should detect the header label used for this column. DefaultTrue The 'Detect Header Cell' property instructs the LLM to identify the header label for this column when extracting data from a table. This is especially important for tables with dynamic, variable, or multi-row headers. Configuration Guidance Enable for Data Columns in tables where header text may change or is not fixed. Only relevant when the parent table has 'Detect Header' enabled in AI Extract Table Options. Example In a table where the column header may be "Amount", "Total", or "Sum" depending on the document, enabling this property allows the LLM to adapt and correctly identify the column. Impact Improves extraction accuracy for tables with non-standard or variable headers, ensuring the correct column is targeted by the LLM.