Adding text extractors

Extracting semantic key-value pairs (KVP) from documents

You can configure a text extractor to extract semantic key value pairs (KVP) from documents. Semantic KVP extraction can adapt to document variations such as format and layouts by focusing on the key-value pairings for extracting data.

To extract the key-value pairs from documents:

1. Select the text extractor node in the agentic workflow.

2. Set the Extract key-value pairs switch to on.

3. Click Add schema.

4. Specify the fields and tables that you want to extract from the documents by using a valid JSON schema. Here is an example JSON.

   [
       {
           "document_type": "Invoice",
           "document_description": "An invoice is a standard document issued by a seller to a buyer, outlining products or services provided, quantities, prices, and payment terms.",
           "fields": {
               "invoice_number": {
                   "description": "A unique identifier assigned by the vendor for this invoice.",
                   "example": "2023-AUS-987654"
               },
               "document_date": {
                   "description": "Date of the document.",
                   "example": "2025-07-05"
               },
               "vendor_name": {
                   "description": "Legal or trade name of the company issuing the invoice. Usually located in the header or footer, near the logo, or billing details.",
                   "example": "ABC Supply Company Ltd"
               },
               "vendor_number": {
                   "description": "Internal identifier used by the buyer's system to refer to the vendor.",
                   "example": "VEND-1023"
               }
           }
       }
   ]
   }

5. Select a model to use for the text extractor.

   From the Models list, select a model or click View all foundation models to open the model selection dialog, which lists all available models. You can search for a model or choose one from the list. After you select a model, click Save. Any notices associated with the selected model, such as deprecation notices or third‑party license requirements, are displayed.

   Certain models include a status tag in the dialog to indicate states such as Recommended or Third party. A warning icon indicates that a model might be withdrawn or deprecated in a subsequent release.

6. Enter the KVP Force Schema Name.

To edit an existing schema, select the text extractor node in the agentic workflow, and click Edit schema.

Variance in kvp_model_name values for semantic KVP extraction

On-premises

When a flow tool uses a default kvp_model_name or the API caller specifies one at run time, it is important to understand the subtle differences between the passed kvp_model_name values to ensure the expected results.

Semantic key-value pair extraction: When to use and limitations

When you enable semantic key-value pair (KVP) extraction in the text extractor, the system uses a layout-aware, multimodal model to identify relationships between keys and values within the document. This is the same functionality that is used in the structured document extractor.

When to use semantic KVP extraction

Use semantic KVP extraction when your documents meet the following criteria:

• Have a structured or fixed layout
• Contain clearly defined key-value pairs (for example, labels and values)
• Include tables or form-like sections
• Are typically short (1–3 pages), such as invoices, purchase orders, or tax forms

When not to use semantic KVP extraction

Semantic KVP extraction might not perform well in the following scenarios:

• Large documents
• Documents where the desired values appear in free-flowing paragraphs

Limitations

This capability does not support extracting multiple values for the same field, either within a single page or across multiple pages. For example, it cannot be used to extract all person names in a document, all clauses of a certain type in an agreement, or all potential PII occurrences. For these use cases, consider using full text extraction combined with downstream processing such as generative prompts, or other specialized approaches.

Mapping data to inputs

By default, auto-mapping is enabled. However, you can map values to the inputs.

To map values to inputs, complete the following steps:

1. Select the text extractor node and then click Edit data mapping.

2. Specify the input values for data mapping. For more information about data mapping, see Mapping data.

Text extractor limits and restrictions

Text extractors have the following limits and restrictions.