> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roe-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Insights

> Extracts insights and structured information from PDF documents using AI.

## Document Insights Engine Overview

The Document Insights Engine extracts structured information, insights, and data from PDF documents using AI. It processes documents in batches, supports schema-based extraction, source tracing, and handles multi-page documents efficiently.

## Engine Inputs

The Document Insights Engine Configuration has the following parameters:

* **instructions**: *required.* Instructions for the AI describing what to extract from the PDF. Can also use alias `instruction`.
* **pdf\_files**: *required.* PDF files to extract insights from. Can be file uploads, URLs, or file IDs. Supports multiple files (comma/newline separated). Can also use alias `pdf_file`.
* **batch\_size**: *optional.* Number of PDF pages to process in each batch (default: 10, range: 1-50). Larger batches are faster but may affect quality.
* **model**: *optional.* The AI model to use (default: `gpt-4.1-2025-04-14`).
* **temperature**: *optional.* Controls randomness in output (default: 0.0). Range: 0.0 (deterministic) to 1.0 (most random).
* **use\_source**: *optional.* Trace the sources of extracted data (default: False). Adds cost when enabled.
* **convert\_to\_images**: *optional.* Convert PDF pages to images and send to the model along with text (default: True). Improves extraction for visual documents.
* **output\_schema**: *optional.* JSON schema defining the structure of data to extract. Follows the standard [JSON schema specification](https://json-schema.org/).

See [Template Strings](/agents/input-definition#template-strings) for dynamic parameter configuration.

## Engine Output

The output will be a JSON value matching the structure specified in the **output\_schema** (if defined). Without a schema, returns extracted content in a default format.

## Example Usage

<Steps>
  <Step title="Create an Agent">
    Click on the "Add Agent" button in the top right corner of the Agents page.

    <Frame>
      <img src="https://mintcdn.com/roeai/qeWYCF2quzHQHhsD/images/add-agent.png?fit=max&auto=format&n=qeWYCF2quzHQHhsD&q=85&s=b3e1ec9b816ed1e57cb1ecfa53ff4288" width="1920" height="1045" data-path="images/add-agent.png" />
    </Frame>

    Enter a name and an optional description of your Agent.
  </Step>

  <Step title="Select the Document Insights Engine" />

  <Step title="Configure the engine">
    <Info>\$ starts a template string</Info>

    * **instructions**: \$instructions
    * **pdf\_files**: \$pdf\_files
    * **batch\_size**: 10
    * **model**: gpt-4.1-2025-04-14
    * **temperature**: 0.0
    * **convert\_to\_images**: True
    * **output\_schema**: Copy and paste the JSON schema below:

    ```json theme={null}
    {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "row_name": {
            "type": "string",
            "description": "The name of a row"
          },
          "value_1": {
            "type": "string",
            "description": "The monetary value for the first period"
          },
          "value_2": {
            "type": "string",
            "description": "The monetary value for the second period"
          },
          "type": {
            "type": "string",
            "description": "Asset type classification"
          }
        },
        "description": "A row in the financial statement"
      },
      "description": "All entries from the financial statement table"
    }
    ```

    You can click **Use Widget** to view the JSON schema in the UI.

    <Frame>
      <img src="https://mintcdn.com/roeai/KH5NetBx7zzOcueq/images/use-widget.png?fit=max&auto=format&n=KH5NetBx7zzOcueq&q=85&s=0c487196b29eae93000e0c7e185c2ebd" width="1202" height="448" data-path="images/use-widget.png" />
    </Frame>
  </Step>

  <Step title="Create the Agent">
    Hit the **Create** button.
  </Step>

  <Step title="Run a job">
    Create a new job and provide:

    * **instructions**: "Extract all rows from the ASSETS table in the balance sheet"
    * **pdf\_files**: Upload or provide a URL to a PDF document

    <Frame>
      <img src="https://mintcdn.com/roeai/wyVOyeWPONjXHsrt/images/pdf-extraction/pdf-extraction-agent-inputs.png?fit=max&auto=format&n=wyVOyeWPONjXHsrt&q=85&s=cdee187a4fff63b36086ed34e67978d3" width="1342" height="1362" data-path="images/pdf-extraction/pdf-extraction-agent-inputs.png" />
    </Frame>
  </Step>

  <Step title="View the Results">
    Click **View** on the job to see its status and results.

    <Frame>
      <img src="https://mintcdn.com/roeai/KH5NetBx7zzOcueq/images/text-extraction-view-job.png?fit=max&auto=format&n=KH5NetBx7zzOcueq&q=85&s=ef2a6cf1da74fcf1ddf486373bd5993b" width="2862" height="554" data-path="images/text-extraction-view-job.png" />
    </Frame>

    Scroll down to see the extracted data matching your output schema.

    <Frame>
      <img src="https://mintcdn.com/roeai/wyVOyeWPONjXHsrt/images/pdf-extraction/pdf-extraction-job-outputs.png?fit=max&auto=format&n=wyVOyeWPONjXHsrt&q=85&s=037d62b8994520201d2bfd317b80d1f3" width="1346" height="1126" data-path="images/pdf-extraction/pdf-extraction-job-outputs.png" />
    </Frame>
  </Step>
</Steps>