Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

feat(content-extraction): add Docling strategy (#1290)

Corentin Thomassetefb830d332d7
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 1ae4d9ff..5101b20d 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
@@ -1,6 +1,7 @@
export const CONTENT_EXTRACTION_STRATEGIES = {
internal: 'internal',
mistralOcr: 'mistral-ocr',
+ docling: 'docling',
} 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 f0a156d7..5daa1f49 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,11 +1,13 @@
import type { ContentExtractionStrategyName } from './content-extraction-strategies.constants';
import type { ContentExtractionStrategyFactory } from './content-extraction-strategies.types';
+import { buildDoclingContentExtractionStrategy } from './docling/docling.content-extraction-strategy';
import { buildLectureContentExtractionStrategy } from './lecture/lecture.content-extraction-strategy';
import { buildMistralOcrContentExtractionStrategy } from './mistral-ocr/mistral-ocr.content-extraction-strategy';
export const strategiesRegistry = {
'internal': buildLectureContentExtractionStrategy,
'mistral-ocr': buildMistralOcrContentExtractionStrategy,
+ 'docling': buildDoclingContentExtractionStrategy,
} satisfies Record<ContentExtractionStrategyName, ContentExtractionStrategyFactory>;
export function getContentExtractionStrategy({ strategyName }: { strategyName: string }) {
diff --git a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.config.ts b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.config.ts
new file mode 100644
index 00000000..f7823f88
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.config.ts
@@ -0,0 +1,35 @@
+import * as v from 'valibot';
+import type { AppConfigDefinition } from '../../../../config/config.types';
+import { urlSchema } from '../../../../config/config.schemas';
+
+export const doclingConfig = {
+ baseUrl: {
+ doc: 'The base URL of the Docling service.',
+ env: 'DOCLING_BASE_URL',
+ schema: urlSchema,
+ default: 'http://localhost:5001',
+ },
+ apiKey: {
+ doc: 'The API key for the Docling service, will be set as `X-API-Key` header in requests to the Docling service, can be configured on docling side using the `DOCLING_SERVE_API_KEY` environment variable.',
+ env: 'DOCLING_API_KEY',
+ schema: v.optional(v.string()),
+ default: undefined,
+ },
+ mimeTypesAllowList: {
+ doc: 'The list of mime types that the Docling 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: 'DOCLING_MIME_TYPES_ALLOW_LIST',
+ schema: v.pipe(
+ v.string(),
+ v.transform(
+ (value) =>
+ new Set(
+ value
+ .split(',')
+ .map((s) => s.trim().toLowerCase())
+ .filter(Boolean),
+ ),
+ ),
+ ),
+ default: '*',
+ },
+} as const satisfies AppConfigDefinition;
diff --git a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.models.test.ts b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.models.test.ts
new file mode 100644
index 00000000..e1ade986
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.models.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, test } from 'vitest';
+import { stripDoclingImagePlaceholders } from './docling.content-extraction-strategy.models';
+
+describe('docling.content-extraction-strategy.models', () => {
+ describe('stripDoclingImagePlaceholders', () => {
+ test('docling replaces graphical content with <!-- image -->, this function removes it', () => {
+ expect(
+ stripDoclingImagePlaceholders(
+ 'This is a test <!-- image --> with <!-- image -->some images.',
+ ),
+ ).to.eql('This is a test with some images.');
+ });
+
+ test('it also trims the text', () => {
+ expect(stripDoclingImagePlaceholders(' This is a test with some images. ')).to.eql(
+ 'This is a test with some images.',
+ );
+
+ expect(
+ stripDoclingImagePlaceholders(' This is a test with some images. <!-- image -->'),
+ ).to.eql('This is a test with some images.');
+ });
+ });
+});
diff --git a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.models.ts b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.models.ts
new file mode 100644
index 00000000..89d6f087
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.models.ts
@@ -0,0 +1,3 @@
+export function stripDoclingImagePlaceholders(text: string): string {
+ return text.replaceAll('<!-- image -->', '').trim();
+}
diff --git a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.ts b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.ts
new file mode 100644
index 00000000..7330372b
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.ts
@@ -0,0 +1,31 @@
+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 { extractTextWithDoclingServer } from './docling.content-extraction-strategy.usecases';
+
+export function buildDoclingContentExtractionStrategy({
+ config,
+}: {
+ config: Config;
+}): ContentExtractionStrategy {
+ const { baseUrl, apiKey, mimeTypesAllowList } = config.documentContentExtraction.strategy.docling;
+
+ return {
+ canExtractTextFromDocument: async ({ file }) => {
+ return isMimeTypeAllowed({
+ mimeType: file.type,
+ allowList: mimeTypesAllowList,
+ });
+ },
+
+ extractTextFromDocument: async ({ file }) => {
+ const { text } = await extractTextWithDoclingServer({
+ file,
+ baseUrl,
+ apiKey,
+ });
+
+ return { text };
+ },
+ };
+}
diff --git a/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.usecases.ts b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.usecases.ts
new file mode 100644
index 00000000..2db982fd
--- /dev/null
+++ b/apps/papra-server/src/modules/documents/content-extraction/content-extraction-strategies/docling/docling.content-extraction-strategy.usecases.ts
@@ -0,0 +1,46 @@
+import { ofetch } from 'ofetch';
+import { IN_MS } from '../../../../shared/units';
+import * as v from 'valibot';
+import { stripDoclingImagePlaceholders } from './docling.content-extraction-strategy.models';
+
+export const doclingResponseSchema = v.object({
+ status: v.literal('success'),
+ document: v.object({
+ md_content: v.string(),
+ }),
+});
+
+export async function extractTextWithDoclingServer({
+ file,
+ baseUrl,
+ apiKey,
+}: {
+ file: File;
+ baseUrl: string;
+ apiKey?: string;
+}) {
+ const url = `${baseUrl.replace(/\/$/, '')}/v1/convert/file`;
+
+ const body = new FormData();
+ body.append('files', file);
+ body.append('to_formats', 'md');
+ body.append('image_export_mode', 'placeholder');
+
+ const response = await ofetch<unknown>(url, {
+ method: 'POST',
+ headers: {
+ // 'Content-Type': 'multipart/form-data',
+ ...(apiKey ? { 'X-Api-Key': apiKey } : {}),
+ },
+ timeout: 30 * IN_MS.SECOND,
+ body,
+ });
+
+ const parsedResponse = v.parse(doclingResponseSchema, response);
+
+ const text = stripDoclingImagePlaceholders(parsedResponse.document.md_content);
+
+ return {
+ text,
+ };
+}
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 29744c56..64f92a19 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
@@ -5,6 +5,7 @@ import {
CONTENT_EXTRACTION_STRATEGIES,
CONTENT_EXTRACTION_STRATEGY_NAMES,
} from './content-extraction-strategies/content-extraction-strategies.constants';
+import { doclingConfig } from './content-extraction-strategies/docling/docling.content-extraction-strategy.config';
export const documentContentExtractionConfig = {
extractionStrategies: {
@@ -12,6 +13,7 @@ export const documentContentExtractionConfig = {
`Content extraction strategy, it can be a single strategy name like \`${CONTENT_EXTRACTION_STRATEGIES.internal}\`, or a comma-separated list of strategy names, in order of preference, like \`${[CONTENT_EXTRACTION_STRATEGIES.mistralOcr, CONTENT_EXTRACTION_STRATEGIES.internal].join(',')}\`. The first strategy that can extract text from the document will be used, and if a strategy fails processing a document, the next one will try. Available strategies are:`,
`- \`${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).`,
].join('\n'),
schema: v.pipe(
v.string(),
@@ -25,5 +27,6 @@ export const documentContentExtractionConfig = {
},
strategy: {
mistralOcr: mistralOcrConfig,
+ docling: doclingConfig,
},
} as const satisfies AppConfigDefinition;