Explainability Settings

explainabilitySettings controls what the /engine/bulk endpoint return alongside the answer. Each flag activates an additional processing stage that trades latency for richer output or higher-quality results.

All parameters live under settings.explainabilitySettings in the request body and default to false.

---

Parameters

Parameter	Type	Default
enabled	boolean	false
assessSourceRelevance	boolean	false
preprocessSources	boolean	false
guided	boolean	false

---

enabled

Activates source grounding for the extraction. When true, the response includes a field_confidences object containing per-field confidence scores and the document regions cited for each value.

Set enabled: true any time you need visibility into where extracted values came from or want to surface confidence data to downstream consumers.

{
  "settings": {
    "explainabilitySettings": {
      "enabled": true
    }
  }
}

field_confidences is only populated when enabled is true and guided is false.

---

assessSourceRelevance

When true, after extraction each field's value is checked against the document passages cited for it. The result is a source-validated confidence score — rather than a raw signal derived from the document scan, the score reflects whether the cited text genuinely supports the extracted value.

When to use: Turn this on when confidence scores drive a decision — for example, routing low-confidence fields to human review, or filtering results below a threshold. Without it, a high score means the model located something in the document; with it, a high score means the cited evidence actually matches the extracted value.

Requires enabled: true.

{
  "settings": {
    "explainabilitySettings": {
      "enabled": true,
      "assessSourceRelevance": true
    }
  }
}

---

preprocessSources

When true, a sourcing pass runs before extraction to identify the document regions most relevant to the schema. The extraction model then works from a focused view of those regions rather than the full document.

When to use: Long or dense documents where the target information is scattered across many pages, or where irrelevant sections might reduce extraction quality. This setting improves extraction accuracy at the cost of an additional LLM call.

Requires enabled: true.

{
  "settings": {
    "explainabilitySettings": {
      "enabled": true,
      "preprocessSources": true
    }
  }
}

---

guided

When true, the request is routed through an orchestrated planning pipeline rather than the standard extraction path.

field_confidences is not populated when guided is true, even if enabled is also true.

---

Response: field_confidences

When enabled: true and guided: false, the response data object includes a field_confidences field. Its shape mirrors answer — each leaf value is replaced with an annotation object.

Top-level annotation

Field	Type	Description
data	any	The extracted value.
confidence_score	number | null	Confidence score for this field (0–1). When assessSourceRelevance is enabled, this reflects source validity in addition to extraction confidence.
sources	array	Document regions cited for this field.

Each item in sources

Field	Type	Description
page_number	integer | null	1-indexed page where the source was found.
confidence_score	number | null	Confidence score for this specific source region (0–1).
bounding_box	object | null	Location of the source region, normalized to [0, 1] relative to page dimensions. Four named corners: upper_left, upper_right, lower_right, lower_left, each {x, y}.

Example

{
  "answer": {
    "policy_number": "DEE00510424BW",
    "broker_name": "Aon"
  },
  "confidence": 0.97,
  "field_confidences": {
    "policy_number": {
      "data": "DEE00510424BW",
      "confidence_score": 0.988,
      "sources": [
        {
          "page_number": 1,
          "confidence_score": 0.988,
          "bounding_box": {
            "upper_left":  {"x": 0.14, "y": 0.07},
            "upper_right": {"x": 0.40, "y": 0.07},
            "lower_right": {"x": 0.40, "y": 0.09},
            "lower_left":  {"x": 0.14, "y": 0.09}
          }
        }
      ]
    },
    "broker_name": {
      "data": "Aon",
      "confidence_score": 0.959,
      "sources": [
        {
          "page_number": 1,
          "confidence_score": 0.959,
          "bounding_box": {
            "upper_left":  {"x": 0.06, "y": 0.19},
            "upper_right": {"x": 0.21, "y": 0.19},
            "lower_right": {"x": 0.21, "y": 0.21},
            "lower_left":  {"x": 0.06, "y": 0.21}
          }
        }
      ]
    }
  }
}

The response settings.explainabilitySettings object echoes back all parameters so you can confirm which pipeline stages were active for a given request.

---

Combining parameters

assessSourceRelevance and preprocessSources are independent and can be combined. Each adds one LLM call to the pipeline, increasing latency and cost proportionally.

Configuration	Effect
enabled: true	field_confidences populated with basic confidence scores.
enabled: true, assessSourceRelevance: true	Confidence scores are source-validated; scores reflect citation quality.
enabled: true, preprocessSources: true	Document pre-filtered to relevant regions before extraction.
enabled: true, assessSourceRelevance: true, preprocessSources: true	Focused context window and source-validated confidence scores.
enabled: true, guided: true	Guided orchestration active; field_confidences is null.

{
  "input": {
    "prompt": "Extract the invoice details.",
    "file": {
      "url": "https://example.com/invoice.pdf"
    }
  },
  "settings": {
    "explainabilitySettings": {
      "enabled": true,
      "assessSourceRelevance": true,
      "preprocessSources": true
    }
  }
}