Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

feat(content-extraction): add Azure Document Intelligence strategy (#1291)

Corentin Thomassetbc4c6a203ef2
diff --git a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/azure-di/azure-di.content-extraction-strategy.config.ts b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/azure-di/azure-di.content-extraction-strategy.config.ts
new file mode 100644
index 00000000..9536d9c0
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/azure-di/azure-di.content-extraction-strategy.config.ts
@@ -0,0 +1,48 @@
+import * as v from 'valibot';
+import type { AppConfigDefinition } from '../../../../config/config.types';
+import { urlSchema } from '../../../../config/config.schemas';
+import { coercedStrictlyPositiveIntegerSchema } from '../../../../shared/schemas/number.schemas';
+
+export const azureDiConfig = {
+ endpoint: {
+ doc: 'The endpoint of the Azure Document Intelligence service.',
+ env: 'AZURE_DI_ENDPOINT',
+ schema: v.optional(urlSchema),
+ default: undefined,
+ },
+ apiKey: {
+ doc: 'The API key for the Azure Document Intelligence service, will be set as `Ocp-Apim-Subscription-Key` header in requests to the Azure Document Intelligence service.',
+ env: 'AZURE_DI_API_KEY',
+ schema: v.string(),
+ default: '',
+ },
+ mimeTypesAllowList: {
+ doc: 'The list of mime types that the Azure Document Inteligence strategy will be used for. If the document mime type is not in this list, the strategy will be skipped. Comma separated list. Supports wildcards, e.g. "image/*" matches all image mime types, and "*" matches all formats. Prefix an entry with "!" to negate it, e.g. "*,!image/png" allows everything except PNG. Negations always take precedence over allows, even more specific ones (e.g. "image/png,!image/*" rejects PNG).',
+ env: 'AZURE_DI_MIME_TYPES_ALLOW_LIST',
+ schema: v.pipe(
+ v.string(),
+ v.transform(
+ (value) =>
+ new Set(
+ value
+ .split(',')
+ .map((s) => s.trim().toLowerCase())
+ .filter(Boolean),
+ ),
+ ),
+ ),
+ default: '*',
+ },
+ pollingAttempts: {
+ doc: 'The number of attempts to poll the Azure Document Intelligence service for the result of a document processing job.',
+ env: 'AZURE_DI_POLLING_ATTEMPTS',
+ schema: coercedStrictlyPositiveIntegerSchema,
+ default: 10,
+ },
+ pollingDelayMs: {
+ doc: 'The delay in milliseconds between polling attempts to the Azure Document Intelligence service for the result of a document processing job.',
+ env: 'AZURE_DI_POLLING_DELAY_MS',
+ schema: coercedStrictlyPositiveIntegerSchema,
+ default: 2000,
+ },
+} as const satisfies AppConfigDefinition;
diff --git a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/azure-di/azure-di.content-extraction-strategy.ts b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/azure-di/azure-di.content-extraction-strategy.ts
new file mode 100644
index 00000000..32d2b974
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/azure-di/azure-di.content-extraction-strategy.ts
@@ -0,0 +1,43 @@
+import type { Config } from '../../../../config/config.types';
+import type { ContentExtractionStrategy } from '../content-extraction-strategies.types';
+import { isMimeTypeAllowed } from '../../../../shared/mime-types/mime-types.models';
+import { extractTextWithAzureDi } from './azure-di.content-extraction-strategy.usecases';
+import { isNilOrEmptyString } from '../../../../shared/utils';
+
+export function buildAzureDiContentExtractionStrategy({
+ config,
+}: {
+ config: Config;
+}): ContentExtractionStrategy {
+ const { endpoint, apiKey, mimeTypesAllowList, pollingAttempts, pollingDelayMs } =
+ config.documentContentExtraction.strategy.azureDi;
+
+ return {
+ canExtractTextFromDocument: async ({ file }) => {
+ return (
+ !isNilOrEmptyString(endpoint) &&
+ !isNilOrEmptyString(apiKey) &&
+ isMimeTypeAllowed({
+ mimeType: file.type,
+ allowList: mimeTypesAllowList,
+ })
+ );
+ },
+
+ extractTextFromDocument: async ({ file }) => {
+ if (isNilOrEmptyString(endpoint)) {
+ throw new Error('Azure DI endpoint is not configured');
+ }
+
+ const { text } = await extractTextWithAzureDi({
+ file,
+ endpoint,
+ apiKey,
+ pollingAttempts,
+ pollingDelayMs,
+ });
+
+ return { text };
+ },
+ };
+}
diff --git a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/azure-di/azure-di.content-extraction-strategy.usecases.ts b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/azure-di/azure-di.content-extraction-strategy.usecases.ts
new file mode 100644
index 00000000..7397fc84
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/azure-di/azure-di.content-extraction-strategy.usecases.ts
@@ -0,0 +1,123 @@
+import { ofetch } from 'ofetch';
+import { IN_MS } from '../../../../shared/units';
+import * as v from 'valibot';
+import { buildUrl } from '@corentinth/chisels';
+import { sleep } from '@papra/std';
+import type { Logger } from '../../../../shared/logger/logger';
+import { createLogger } from '../../../../shared/logger/logger';
+
+const API_VERSION = '2024-11-30';
+
+export const jobResultResponseSchema = v.variant('status', [
+ v.object({
+ status: v.picklist(['notStarted', 'running', 'failed']),
+ }),
+ v.object({
+ status: v.literal('succeeded'),
+ analyzeResult: v.object({
+ content: v.string(),
+ }),
+ }),
+]);
+
+export async function extractTextWithAzureDi({
+ file,
+ endpoint,
+ apiKey,
+ pollingAttempts,
+ pollingDelayMs,
+ logger = createLogger({ namespace: 'azure-di.content-extraction-strategy.usecases' }),
+}: {
+ file: File;
+ endpoint: string;
+ apiKey: string;
+ pollingAttempts: number;
+ pollingDelayMs: number;
+ logger?: Logger;
+}) {
+ const url = buildUrl({
+ baseUrl: endpoint,
+ path: '/documentintelligence/documentModels/prebuilt-layout:analyze',
+ queryParams: {
+ 'api-version': API_VERSION,
+ 'outputContentFormat': 'markdown',
+ },
+ });
+
+ const response = await ofetch.raw<unknown>(url, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/octet-stream',
+ 'Ocp-Apim-Subscription-Key': apiKey,
+ },
+ timeout: 10 * IN_MS.SECOND,
+ body: file,
+ });
+
+ const operationLocation = response.headers.get('operation-location');
+
+ if (!operationLocation) {
+ throw new Error('Azure DI job creation failed: operation-location header missing');
+ }
+
+ logger.debug('Azure DI job created');
+
+ const { text, attempts } = await pollJobResult({
+ operationLocation,
+ apiKey,
+ pollingAttempts,
+ pollingDelayMs,
+ logger,
+ });
+
+ return { text, attempts };
+}
+
+export async function pollJobResult({
+ operationLocation,
+ apiKey,
+ pollingAttempts,
+ pollingDelayMs,
+ logger,
+}: {
+ operationLocation: string;
+ apiKey: string;
+ pollingAttempts: number;
+ pollingDelayMs: number;
+ logger: Logger;
+}) {
+ for (let attempt = 0; attempt < pollingAttempts; attempt++) {
+ const response = await ofetch<unknown>(operationLocation, {
+ method: 'GET',
+ headers: {
+ 'Ocp-Apim-Subscription-Key': apiKey,
+ },
+ timeout: 10 * IN_MS.SECOND,
+ });
+
+ const result = v.parse(jobResultResponseSchema, response);
+
+ logger.debug(
+ {
+ attempt,
+ status: result.status,
+ },
+ 'Azure DI job result polled',
+ );
+
+ if (result.status === 'succeeded') {
+ return {
+ text: result.analyzeResult.content,
+ attempts: attempt + 1,
+ };
+ } else if (result.status === 'failed') {
+ throw new Error('Azure DI job failed');
+ }
+
+ if (attempt < pollingAttempts - 1) {
+ await sleep(pollingDelayMs);
+ }
+ }
+
+ throw new Error('Azure DI job did not complete in time');
+}
diff --git a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/content-extraction-strategies.constants.ts b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/content-extraction-strategies.constants.ts
index 5101b20d..c3e1c436 100644
--- a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/content-extraction-strategies.constants.ts
+++ b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/content-extraction-strategies.constants.ts
@@ -2,6 +2,7 @@ export const CONTENT_EXTRACTION_STRATEGIES = {
internal: 'internal',
mistralOcr: 'mistral-ocr',
docling: 'docling',
+ azureDi: 'azure-di',
} as const;
export const CONTENT_EXTRACTION_STRATEGY_NAMES = Object.values(CONTENT_EXTRACTION_STRATEGIES);
diff --git a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/content-extraction.strategies.ts b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/content-extraction.strategies.ts
index 5daa1f49..ef026257 100644
--- a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/content-extraction.strategies.ts
+++ b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/content-extraction.strategies.ts
@@ -1,3 +1,4 @@
+import { buildAzureDiContentExtractionStrategy } from './azure-di/azure-di.content-extraction-strategy';
import type { ContentExtractionStrategyName } from './content-extraction-strategies.constants';
import type { ContentExtractionStrategyFactory } from './content-extraction-strategies.types';
import { buildDoclingContentExtractionStrategy } from './docling/docling.content-extraction-strategy';
@@ -8,6 +9,7 @@ export const strategiesRegistry = {
'internal': buildLectureContentExtractionStrategy,
'mistral-ocr': buildMistralOcrContentExtractionStrategy,
'docling': buildDoclingContentExtractionStrategy,
+ 'azure-di': buildAzureDiContentExtractionStrategy,
} satisfies Record<ContentExtractionStrategyName, ContentExtractionStrategyFactory>;
export function getContentExtractionStrategy({ strategyName }: { strategyName: string }) {
diff --git a/apps/papra-server/src/modules/documents/content-extraction/content-extraction.config.ts b/apps/papra-server/src/modules/documents/content-extraction/content-extraction.config.ts
index 64f92a19..378e0137 100644
--- a/apps/papra-server/src/modules/documents/content-extraction/content-extraction.config.ts
+++ b/apps/papra-server/src/modules/documents/content-extraction/content-extraction.config.ts
@@ -6,6 +6,7 @@ import {
CONTENT_EXTRACTION_STRATEGY_NAMES,
} from './content-extraction-strategies/content-extraction-strategies.constants';
import { doclingConfig } from './content-extraction-strategies/docling/docling.content-extraction-strategy.config';
+import { azureDiConfig } from './content-extraction-strategies/azure-di/azure-di.content-extraction-strategy.config';
export const documentContentExtractionConfig = {
extractionStrategies: {
@@ -14,6 +15,7 @@ export const documentContentExtractionConfig = {
`- \`${CONTENT_EXTRACTION_STRATEGIES.internal}\`: Uses the internal \`lecture\` library to extract text from documents, which support all common document formats and uses Tesseract for OCR. This strategy is always available, great to use as a fallback when other strategies fail.`,
`- \`${CONTENT_EXTRACTION_STRATEGIES.mistralOcr}\`: Uses the Mistral OCR API to extract text from documents. This strategy requires a valid Mistral API key.`,
`- \`${CONTENT_EXTRACTION_STRATEGIES.docling}\`: Uses a Docling server to extract text from documents. This strategy requires a running [Docling server](https://github.com/docling-project/docling-serve).`,
+ `- \`${CONTENT_EXTRACTION_STRATEGIES.azureDi}\`: Uses the Azure Document Intelligence service to extract text from documents. This strategy requires a valid Azure Document Intelligence endpoint and API key.`,
].join('\n'),
schema: v.pipe(
v.string(),
@@ -28,5 +30,6 @@ export const documentContentExtractionConfig = {
strategy: {
mistralOcr: mistralOcrConfig,
docling: doclingConfig,
+ azureDi: azureDiConfig,
},
} as const satisfies AppConfigDefinition;
diff --git a/packages/std/src/index.ts b/packages/std/src/index.ts
index 63e90f90..e543eec7 100644
--- a/packages/std/src/index.ts
+++ b/packages/std/src/index.ts
@@ -1,2 +1,3 @@
export * from './string/string';
export * from './object/object';
+export * from './timing/timing';
diff --git a/packages/std/src/timing/timing.ts b/packages/std/src/timing/timing.ts
new file mode 100644
index 00000000..421bda08
--- /dev/null
+++ b/packages/std/src/timing/timing.ts
@@ -0,0 +1,3 @@
+export function sleep(ms: number): Promise<void> {
+ return new Promise((resolve) => setTimeout(resolve, ms));
+}