Document Intelligence

Azure Document Intelligence (formerly Form Recognizer) converts PDF documents into Markdown. Reaktors use it to extract text from uploaded or linked PDFs so that AI models can process the content.

You configure Document Intelligence as a Connection of type document-intelligence under Connections in the sidebar.

---

Connection Modes

Document Intelligence supports two connection modes. You can configure one or both.

Direct Azure Connection

Connect directly to your own Azure Document Intelligence resource. You need:

Field	Description
API Key	Found in the Azure Portal under Keys and Endpoint for your Document Intelligence resource.
Endpoint URL	The resource endpoint, e.g. https://your-resource.cognitiveservices.azure.com/

Main Server Proxy

Routes PDF conversion through a central Operaide instance. The main server maintains its own conversion cache, so documents that have already been converted there are returned immediately without an additional Azure API call. This significantly reduces Azure usage when multiple instances or Reaktors process the same documents.

Field	Description
Proxy Server URL	URL of the Operaide instance acting as proxy.
Proxy Server API Key	API key for authenticating with the proxy.

tip

When both modes are configured, the proxy is used first. If it fails and Enable Azure Fallback is on, the service retries directly against Azure.

---

Caching

Every PDF is hashed before conversion. If the same document has been converted before, the cached result is returned immediately — no Azure API call is made. Caching happens in two layers:

1. MongoDB — primary cache, checked first.
2. File Cache — gzipped JSON files on disk, used as fallback when the database cache misses.

Cache Key Prefix

The optional Cache Key Prefix lets you scope the cache. The prefix is prepended to the document hash, so documents cached under different prefixes are treated as separate entries.

Use cases:

• Set a prefix per organisation or Reaktor to isolate caches.
• Change the prefix (e.g. from v1 to v2) to force re-conversion of all documents without deleting old cache entries.
• Leave it empty to use the default (unprefixed) cache shared by all consumers.

When a proxy server is configured, the prefix is forwarded so that both the local instance and the proxy use the same scoped cache key.

File Cache

Field	Description
File Cache Directory	Local directory for storing converted documents as gzipped files.
Enable File Cache	When enabled, the file cache is checked as a fallback if the database cache misses. Enabled by default.

---

Timeout and Fallback

Field	Default	Description
Conversion Timeout	3 min	Maximum wait time for a single PDF conversion. Range: 10 000–600 000 ms.
Enable Azure Fallback	On	When enabled and the proxy fails, retries the conversion directly against Azure. Only applies when both modes are configured.

---

Usage in Reaktors

Reference the connection by name in your Reaktor code. The @operaide/document package provides two aktors:

Aktor	Purpose
aktorConvertPDFToMarkdown	Convert a single PDF (URL or base64) to Markdown
aktorConvertMultiplePDFsToMarkdown	Convert multiple PDFs to an array of Markdown strings

Example:

import { aktorConvertPDFToMarkdown } from '@operaide/document';
import { aktorSetting } from '@operaide/aktor';
import { z } from 'zod';

const connectionName = aktorSetting(
    z.string(),
    'default',
    'Document Intelligence Connection'
);

const markdown = aktorConvertPDFToMarkdown({
    pdf: pdfUrlOrBase64,
    connectionName,
});

tip

Use default as the connection name for standard setups. Using aktorSetting lets operators swap the connection at deployment time without code changes.