Skip to content

armgit / papra

Public Imported from GitHub
0

The minimalistic document archiving platform.

refactor(auto-tagging): renammed to enrichment (#1576)

Corentin Thomasset96f900955959
diff --git a/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.test.ts b/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.test.ts
index a5d12ab0..78dd674b 100644
--- a/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.test.ts
+++ b/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.test.ts
@@ -4,39 +4,14 @@ import { createInMemoryDatabase } from '../app/database/database.test-utils';
import { createTestEventServices } from '../app/events/events.test-utils';
import type { AiServices } from '../ai/ai.services';
import { overrideConfig } from '../config/config.test-utils';
-import { createDocumentNotFoundError } from '../documents/documents.errors';
-import { createDocumentsRepository } from '../documents/documents.repository';
-import type { ResolveOrganizationSettingsUsecase } from '../organizations/organization-settings/organization-settings.usecases';
import { createTestLogger } from '../shared/logger/logger.test-utils';
import { createTagsRepository } from '../tags/tags.repository';
import { documentsTagsTable, tagsTable } from '../tags/tags.table';
import { applyTagsToDocuments, createTag } from '../tags/tags.usecases';
-import {
- buildApplyAutoTaggingActions,
- buildAutoTagDocument,
- buildPromptForAutoTagging,
-} from './auto-tagging.usecases';
+import { buildApplyAutoTaggingActions, buildPromptForAutoTagging } from './auto-tagging.usecases';
import type { AutoTaggingResponse } from './auto-tagging.models';
import { buildAutoTaggingSystemPrompt, buildAutoTaggingUserPrompt } from './auto-tagging.models';
-function createTestResolveOrganizationSettings(
- autoTagging: Partial<{ isEnabled: boolean; canCreateNewTags: boolean; maxTags: number }> = {},
-): ResolveOrganizationSettingsUsecase {
- return async () => ({
- organizationSettings: {
- ai: {
- autoTagging: {
- isEnabled: true,
- canCreateNewTags: false,
- maxTags: 5,
- modelId: 'gpt-4',
- ...autoTagging,
- },
- },
- },
- });
-}
-
function createTestAiServices({ response }: { response: AutoTaggingResponse }) {
const generateStructuredData = vi
.fn<AiServices['generateStructuredData']>()
@@ -59,7 +34,6 @@ async function createTestDeps(
return {
db,
- documentsRepository: createDocumentsRepository({ db }),
tagsRepository,
eventServices,
logger,
@@ -146,163 +120,6 @@ describe('auto-tagging usecases', () => {
});
});
- describe('buildAutoTagDocument', () => {
- test('when auto-tagging is disabled in the organization settings, the document is not tagged and the AI is not called', async () => {
- const deps = await createTestDeps(seed);
- const { aiServices, generateStructuredData } = createTestAiServices({
- response: { existingTags: ['Finance'] },
- });
- const autoTagDocument = buildAutoTagDocument({
- ...deps,
- promptForAutoTagging: buildPromptForAutoTagging({ aiServices }),
- resolveOrganizationSettings: createTestResolveOrganizationSettings({ isEnabled: false }),
- });
-
- await autoTagDocument(documentIds);
-
- expect(generateStructuredData).not.toHaveBeenCalled();
- expect(await deps.db.select().from(documentsTagsTable)).toEqual([]);
- });
-
- test('when the organization has no existing tags and cannot create new ones, the document is not tagged and the AI is not called', async () => {
- const deps = await createTestDeps({
- organizations: seed.organizations,
- documents: seed.documents,
- });
- const { aiServices, generateStructuredData } = createTestAiServices({
- response: { existingTags: [] },
- });
- const autoTagDocument = buildAutoTagDocument({
- ...deps,
- promptForAutoTagging: buildPromptForAutoTagging({ aiServices }),
- resolveOrganizationSettings: createTestResolveOrganizationSettings({
- isEnabled: true,
- canCreateNewTags: false,
- }),
- });
-
- await autoTagDocument(documentIds);
-
- expect(generateStructuredData).not.toHaveBeenCalled();
- expect(await deps.db.select().from(documentsTagsTable)).toEqual([]);
- });
-
- test('when the AI selects existing tags, they are applied to the document', async () => {
- const deps = await createTestDeps(seed);
- const { aiServices } = createTestAiServices({ response: { existingTags: ['Finance'] } });
- const autoTagDocument = buildAutoTagDocument({
- ...deps,
- promptForAutoTagging: buildPromptForAutoTagging({ aiServices }),
- resolveOrganizationSettings: createTestResolveOrganizationSettings(),
- });
-
- await autoTagDocument(documentIds);
-
- expect(await deps.db.select().from(documentsTagsTable)).toEqual([
- { documentId: 'doc_1', tagId: 'tag_1' },
- ]);
- });
-
- test('when the AI proposes new tags, they are created and applied to the document', async () => {
- const deps = await createTestDeps({
- organizations: seed.organizations,
- documents: seed.documents,
- });
- const { aiServices } = createTestAiServices({
- response: { newTags: [{ name: 'Invoice', description: 'Invoices and receipts' }] },
- });
- const autoTagDocument = buildAutoTagDocument({
- ...deps,
- promptForAutoTagging: buildPromptForAutoTagging({ aiServices }),
- resolveOrganizationSettings: createTestResolveOrganizationSettings({
- canCreateNewTags: true,
- }),
- });
-
- await autoTagDocument(documentIds);
-
- const createdTags = await deps.db.select().from(tagsTable);
- expect(createdTags.length).toEqual(1);
- expect(createdTags[0]).toMatchObject({
- name: 'Invoice',
- description: 'Invoices and receipts',
- color: '#CCCCCC',
- organizationId: 'org_1',
- });
- expect(await deps.db.select().from(documentsTagsTable)).toEqual([
- { documentId: 'doc_1', tagId: createdTags[0]!.id },
- ]);
- });
-
- test('the organization model and tag settings are passed to analysis and its actions are passed to application', async () => {
- const deps = await createTestDeps(seed);
- const actions = { tagIdsToAdd: ['tag_1'], tagsToCreate: [{ name: 'Invoice' }] };
- const promptForAutoTagging = vi
- .fn<ReturnType<typeof buildPromptForAutoTagging>>()
- .mockResolvedValue(actions);
- const applyAutoTaggingActions = vi
- .fn<ReturnType<typeof buildApplyAutoTaggingActions>>()
- .mockResolvedValue();
- const autoTagDocument = buildAutoTagDocument({
- ...deps,
- promptForAutoTagging,
- applyAutoTaggingActions,
- resolveOrganizationSettings: createTestResolveOrganizationSettings({
- maxTags: 2,
- canCreateNewTags: true,
- }),
- });
-
- await autoTagDocument(documentIds);
-
- expect(promptForAutoTagging).toHaveBeenCalledTimes(1);
- const [request] = promptForAutoTagging.mock.calls[0]!;
- expect(request).toMatchObject({
- document: baseDocument,
- canCreateNewTags: true,
- maxTags: 2,
- modelId: 'gpt-4',
- });
- expect(request.existingTags.toSorted((a, b) => a.id.localeCompare(b.id))).toMatchObject(
- seed.tags,
- );
- expect(applyAutoTaggingActions).toHaveBeenCalledExactlyOnceWith({
- ...documentIds,
- ...actions,
- });
- });
-
- test('a missing document fails before analysis', async () => {
- const deps = await createTestDeps({ organizations: seed.organizations, tags: seed.tags });
- const promptForAutoTagging = vi.fn<ReturnType<typeof buildPromptForAutoTagging>>();
- const autoTagDocument = buildAutoTagDocument({
- ...deps,
- promptForAutoTagging,
- resolveOrganizationSettings: createTestResolveOrganizationSettings(),
- });
-
- await expect(autoTagDocument(documentIds)).rejects.toEqual(createDocumentNotFoundError());
- expect(promptForAutoTagging).not.toHaveBeenCalled();
- });
-
- test('an inference failure is propagated without applying tags', async () => {
- const deps = await createTestDeps(seed);
- const error = new Error('Inference failed');
- const { aiServices, generateStructuredData } = createTestAiServices({ response: {} });
- generateStructuredData.mockRejectedValue(error);
- const applyAutoTaggingActions = vi.fn<ReturnType<typeof buildApplyAutoTaggingActions>>();
- const autoTagDocument = buildAutoTagDocument({
- ...deps,
- promptForAutoTagging: buildPromptForAutoTagging({ aiServices }),
- applyAutoTaggingActions,
- resolveOrganizationSettings: createTestResolveOrganizationSettings(),
- });
-
- await expect(autoTagDocument(documentIds)).rejects.toEqual(error);
- expect(applyAutoTaggingActions).not.toHaveBeenCalled();
- });
- });
-
describe('buildApplyAutoTaggingActions', () => {
test('existing and successfully created tags are applied despite a creation failure, preserving current tags and emitting the domain event', async () => {
const deps = await createTestDeps(seed);
diff --git a/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.ts b/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.ts
index a7472dcd..e33e6992 100644
--- a/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.ts
+++ b/apps/papra-server/src/modules/auto-tagging/auto-tagging.usecases.ts
@@ -1,11 +1,5 @@
import type { AiServices } from '../ai/ai.services';
-import type { TagsRepository } from '../tags/tags.repository';
import type { Tag } from '../tags/tags.types';
-import type { ResolveOrganizationSettingsUsecase } from '../organizations/organization-settings/organization-settings.usecases';
-import type { DocumentsRepository } from '../documents/documents.repository';
-import { createDocumentNotFoundError } from '../documents/documents.errors';
-import type { Logger } from '@crowlog/logger';
-import { createLogger } from '../shared/logger/logger';
import type {
applyTagsToDocuments as applyTagsToDocumentsUsecase,
createTag as createTagUsecase,
@@ -18,7 +12,6 @@ import {
buildAutoTaggingUserPrompt,
getTagsActions,
} from './auto-tagging.models';
-import { ensureModelId } from '../ai/ai.models';
export function buildPromptForAutoTagging({ aiServices }: { aiServices: AiServices }) {
return async ({
@@ -105,67 +98,3 @@ export function buildApplyAutoTaggingActions({
});
};
}
-
-export function buildAutoTagDocument({
- promptForAutoTagging,
- applyAutoTaggingActions,
- documentsRepository,
- tagsRepository,
- resolveOrganizationSettings,
- logger = createLogger({ namespace: 'autoTagDocument' }),
-}: {
- promptForAutoTagging: ReturnType<typeof buildPromptForAutoTagging>;
- applyAutoTaggingActions: ReturnType<typeof buildApplyAutoTaggingActions>;
- documentsRepository: Pick<DocumentsRepository, 'getDocumentById'>;
- tagsRepository: Pick<TagsRepository, 'getOrganizationTags'>;
- resolveOrganizationSettings: ResolveOrganizationSettingsUsecase;
- logger?: Logger;
-}) {
- return async ({ documentId, organizationId }: { documentId: string; organizationId: string }) => {
- const [{ document }, { tags: existingTags }, { organizationSettings }] = await Promise.all([
- documentsRepository.getDocumentById({ documentId, organizationId }),
- tagsRepository.getOrganizationTags({ organizationId }),
- resolveOrganizationSettings({ organizationId }),
- ]);
-
- const orgHasNoExistingTags = existingTags.length === 0;
- const {
- canCreateNewTags,
- maxTags,
- isEnabled: isAutoTaggingEnabled,
- } = organizationSettings.ai.autoTagging;
-
- if (orgHasNoExistingTags && !canCreateNewTags) {
- logger.info(
- { documentId, organizationId },
- 'No tags available and cannot create new tags. Skipping auto-tagging.',
- );
- return;
- }
-
- if (!isAutoTaggingEnabled) {
- logger.info(
- { documentId, organizationId },
- 'Auto-tagging is disabled in organization settings. Skipping auto-tagging.',
- );
- return;
- }
-
- if (!document) {
- throw createDocumentNotFoundError();
- }
-
- const startedAt = Date.now();
- const actions = await promptForAutoTagging({
- document,
- existingTags,
- canCreateNewTags,
- maxTags,
- modelId: ensureModelId(organizationSettings.ai.autoTagging.modelId),
- });
- const durationMs = Date.now() - startedAt;
- logger.info({ documentId, organizationId, durationMs }, 'Auto-tagging completed');
-
- await applyAutoTaggingActions({ documentId, organizationId, ...actions });
- };
-}
diff --git a/apps/papra-server/src/modules/document-enrichment/document-enrichment.usecases.test.ts b/apps/papra-server/src/modules/document-enrichment/document-enrichment.usecases.test.ts
new file mode 100644
index 00000000..acce28f0
--- /dev/null
+++ b/apps/papra-server/src/modules/document-enrichment/document-enrichment.usecases.test.ts
@@ -0,0 +1,258 @@
+import { describe, expect, test, vi } from 'vitest';
+import type { AiServices } from '../ai/ai.services';
+import { createInMemoryDatabase } from '../app/database/database.test-utils';
+import { createTestEventServices } from '../app/events/events.test-utils';
+import type { AutoTaggingResponse } from '../auto-tagging/auto-tagging.models';
+import {
+ buildApplyAutoTaggingActions,
+ buildPromptForAutoTagging,
+} from '../auto-tagging/auto-tagging.usecases';
+import { overrideConfig } from '../config/config.test-utils';
+import { createDocumentNotFoundError } from '../documents/documents.errors';
+import { createDocumentsRepository } from '../documents/documents.repository';
+import type { ResolveOrganizationSettingsUsecase } from '../organizations/organization-settings/organization-settings.usecases';
+import { createTestLogger } from '../shared/logger/logger.test-utils';
+import { createTagsRepository } from '../tags/tags.repository';
+import { documentsTagsTable, tagsTable } from '../tags/tags.table';
+import { applyTagsToDocuments, createTag } from '../tags/tags.usecases';
+import { buildEnrichDocument } from './document-enrichment.usecases';
+
+function createTestResolveOrganizationSettings(
+ autoTagging: Partial<{ isEnabled: boolean; canCreateNewTags: boolean; maxTags: number }> = {},
+): ResolveOrganizationSettingsUsecase {
+ return async () => ({
+ organizationSettings: {
+ ai: {
+ autoTagging: {
+ isEnabled: true,
+ canCreateNewTags: false,
+ maxTags: 5,
+ modelId: 'gpt-4',
+ ...autoTagging,
+ },
+ },
+ },
+ });
+}
+
+function createTestAiServices({ response }: { response: AutoTaggingResponse }) {
+ const generateStructuredData = vi
+ .fn<AiServices['generateStructuredData']>()
+ .mockResolvedValue(response);
+
+ return {
+ aiServices: { generateStructuredData } as AiServices,
+ generateStructuredData,
+ };
+}
+
+async function createTestDeps(seedOptions: Parameters<typeof createInMemoryDatabase>[0]) {
+ const { db } = await createInMemoryDatabase(seedOptions);
+ const config = overrideConfig();
+ const tagsRepository = createTagsRepository({ db });
+ const eventServices = createTestEventServices();
+ const { logger } = createTestLogger();
+
+ return {
+ db,
+ documentsRepository: createDocumentsRepository({ db }),
+ tagsRepository,
+ logger,
+ applyAutoTaggingActions: buildApplyAutoTaggingActions({
+ createTag: async (args) => createTag({ ...args, config, tagsRepository }),
+ applyTagsToDocuments: async (args) =>
+ applyTagsToDocuments({ ...args, tagsRepository, eventServices, logger }),
+ }),
+ };
+}
+
+const baseDocument = {
+ id: 'doc_1',
+ organizationId: 'org_1',
+ name: 'Doc 1',
+ originalName: 'Doc 1',
+ originalStorageKey: 'doc_1',
+ originalSha256Hash: 'doc_1',
+ mimeType: 'text/plain',
+ content: 'Some document content',
+};
+
+const documentIds = { documentId: 'doc_1', organizationId: 'org_1' };
+
+const seed = {
+ organizations: [{ id: 'org_1', name: 'Org 1' }],
+ documents: [baseDocument],
+ tags: [
+ {
+ id: 'tag_1',
+ name: 'Finance',
+ normalizedName: 'finance',
+ color: '#000000',
+ organizationId: 'org_1',
+ },
+ {
+ id: 'tag_2',
+ name: 'Household',
+ normalizedName: 'household',
+ color: '#000000',
+ organizationId: 'org_1',
+ },
+ ],
+};
+
+describe('document enrichment', () => {
+ test('when auto-tagging is disabled in the organization settings, the document is not tagged and the AI is not called', async () => {
+ const deps = await createTestDeps(seed);
+ const { aiServices, generateStructuredData } = createTestAiServices({
+ response: { existingTags: ['Finance'] },
+ });
+ const enrichDocument = buildEnrichDocument({
+ ...deps,
+ promptForAutoTagging: buildPromptForAutoTagging({ aiServices }),
+ resolveOrganizationSettings: createTestResolveOrganizationSettings({ isEnabled: false }),
+ });
+
+ await enrichDocument(documentIds);
+
+ expect(generateStructuredData).not.toHaveBeenCalled();
+ expect(await deps.db.select().from(documentsTagsTable)).toEqual([]);
+ });
+
+ test('when the organization has no existing tags and cannot create new ones, the document is not tagged and the AI is not called', async () => {
+ const deps = await createTestDeps({
+ organizations: seed.organizations,
+ documents: seed.documents,
+ });
+ const { aiServices, generateStructuredData } = createTestAiServices({
+ response: { existingTags: [] },
+ });
+ const enrichDocument = buildEnrichDocument({
+ ...deps,
+ promptForAutoTagging: buildPromptForAutoTagging({ aiServices }),
+ resolveOrganizationSettings: createTestResolveOrganizationSettings({
+ isEnabled: true,
+ canCreateNewTags: false,
+ }),
+ });
+
+ await enrichDocument(documentIds);
+
+ expect(generateStructuredData).not.toHaveBeenCalled();
+ expect(await deps.db.select().from(documentsTagsTable)).toEqual([]);
+ });
+
+ test('when the AI selects existing tags, they are applied to the document', async () => {
+ const deps = await createTestDeps(seed);
+ const { aiServices } = createTestAiServices({ response: { existingTags: ['Finance'] } });
+ const enrichDocument = buildEnrichDocument({
+ ...deps,
+ promptForAutoTagging: buildPromptForAutoTagging({ aiServices }),
+ resolveOrganizationSettings: createTestResolveOrganizationSettings(),
+ });
+
+ await enrichDocument(documentIds);
+
+ expect(await deps.db.select().from(documentsTagsTable)).toEqual([
+ { documentId: 'doc_1', tagId: 'tag_1' },
+ ]);
+ });
+
+ test('when the AI proposes new tags, they are created and applied to the document', async () => {
+ const deps = await createTestDeps({
+ organizations: seed.organizations,
+ documents: seed.documents,
+ });
+ const { aiServices } = createTestAiServices({
+ response: { newTags: [{ name: 'Invoice', description: 'Invoices and receipts' }] },
+ });
+ const enrichDocument = buildEnrichDocument({
+ ...deps,
+ promptForAutoTagging: buildPromptForAutoTagging({ aiServices }),
+ resolveOrganizationSettings: createTestResolveOrganizationSettings({
+ canCreateNewTags: true,
+ }),
+ });
+
+ await enrichDocument(documentIds);
+
+ const createdTags = await deps.db.select().from(tagsTable);
+ expect(createdTags.length).toEqual(1);
+ expect(createdTags[0]).toMatchObject({
+ name: 'Invoice',
+ description: 'Invoices and receipts',
+ color: '#CCCCCC',
+ organizationId: 'org_1',
+ });
+ expect(await deps.db.select().from(documentsTagsTable)).toEqual([
+ { documentId: 'doc_1', tagId: createdTags[0]!.id },
+ ]);
+ });
+
+ test('the organization model and tag settings are passed to analysis and its actions are passed to application', async () => {
+ const deps = await createTestDeps(seed);
+ const actions = { tagIdsToAdd: ['tag_1'], tagsToCreate: [{ name: 'Invoice' }] };
+ const promptForAutoTagging = vi
+ .fn<ReturnType<typeof buildPromptForAutoTagging>>()
+ .mockResolvedValue(actions);
+ const applyAutoTaggingActions = vi
+ .fn<ReturnType<typeof buildApplyAutoTaggingActions>>()
+ .mockResolvedValue();
+ const enrichDocument = buildEnrichDocument({
+ ...deps,
+ promptForAutoTagging,
+ applyAutoTaggingActions,
+ resolveOrganizationSettings: createTestResolveOrganizationSettings({
+ maxTags: 2,
+ canCreateNewTags: true,
+ }),
+ });
+
+ await enrichDocument(documentIds);
+
+ expect(promptForAutoTagging).toHaveBeenCalledTimes(1);
+ const [request] = promptForAutoTagging.mock.calls[0]!;
+ expect(request).toMatchObject({
+ document: baseDocument,
+ canCreateNewTags: true,
+ maxTags: 2,
+ modelId: 'gpt-4',
+ });
+ expect(request.existingTags.toSorted((a, b) => a.id.localeCompare(b.id))).toMatchObject(
+ seed.tags,
+ );
+ expect(applyAutoTaggingActions).toHaveBeenCalledExactlyOnceWith({
+ ...documentIds,
+ ...actions,
+ });
+ });
+
+ test('a missing document fails before analysis', async () => {
+ const deps = await createTestDeps({ organizations: seed.organizations, tags: seed.tags });
+ const promptForAutoTagging = vi.fn<ReturnType<typeof buildPromptForAutoTagging>>();
+ const enrichDocument = buildEnrichDocument({
+ ...deps,
+ promptForAutoTagging,
+ resolveOrganizationSettings: createTestResolveOrganizationSettings(),
+ });
+
+ await expect(enrichDocument(documentIds)).rejects.toEqual(createDocumentNotFoundError());
+ expect(promptForAutoTagging).not.toHaveBeenCalled();
+ });
+
+ test('an inference failure is propagated without applying tags', async () => {
+ const deps = await createTestDeps(seed);
+ const error = new Error('Inference failed');
+ const { aiServices, generateStructuredData } = createTestAiServices({ response: {} });
+ generateStructuredData.mockRejectedValue(error);
+ const applyAutoTaggingActions = vi.fn<ReturnType<typeof buildApplyAutoTaggingActions>>();
+ const enrichDocument = buildEnrichDocument({
+ ...deps,
+ promptForAutoTagging: buildPromptForAutoTagging({ aiServices }),
+ applyAutoTaggingActions,
+ resolveOrganizationSettings: createTestResolveOrganizationSettings(),
+ });
+
+ await expect(enrichDocument(documentIds)).rejects.toEqual(error);
+ expect(applyAutoTaggingActions).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/papra-server/src/modules/document-enrichment/document-enrichment.usecases.ts b/apps/papra-server/src/modules/document-enrichment/document-enrichment.usecases.ts
new file mode 100644
index 00000000..e4e4e102
--- /dev/null
+++ b/apps/papra-server/src/modules/document-enrichment/document-enrichment.usecases.ts
@@ -0,0 +1,75 @@
+import type { Logger } from '@crowlog/logger';
+import { ensureModelId } from '../ai/ai.models';
+import type {
+ buildApplyAutoTaggingActions,
+ buildPromptForAutoTagging,
+} from '../auto-tagging/auto-tagging.usecases';
+import { createDocumentNotFoundError } from '../documents/documents.errors';
+import type { DocumentsRepository } from '../documents/documents.repository';
+import type { ResolveOrganizationSettingsUsecase } from '../organizations/organization-settings/organization-settings.usecases';
+import { createLogger } from '../shared/logger/logger';
+import type { TagsRepository } from '../tags/tags.repository';
+
+export function buildEnrichDocument({
+ promptForAutoTagging,
+ applyAutoTaggingActions,
+ documentsRepository,
+ tagsRepository,
+ resolveOrganizationSettings,
+ logger = createLogger({ namespace: 'documentEnrichment' }),
+}: {
+ promptForAutoTagging: ReturnType<typeof buildPromptForAutoTagging>;
+ applyAutoTaggingActions: ReturnType<typeof buildApplyAutoTaggingActions>;
+ documentsRepository: Pick<DocumentsRepository, 'getDocumentById'>;
+ tagsRepository: Pick<TagsRepository, 'getOrganizationTags'>;
+ resolveOrganizationSettings: ResolveOrganizationSettingsUsecase;
+ logger?: Logger;
+}) {
+ return async ({ documentId, organizationId }: { documentId: string; organizationId: string }) => {
+ const [{ document }, { tags: existingTags }, { organizationSettings }] = await Promise.all([
+ documentsRepository.getDocumentById({ documentId, organizationId }),
+ tagsRepository.getOrganizationTags({ organizationId }),
+ resolveOrganizationSettings({ organizationId }),
+ ]);
+
+ const orgHasNoExistingTags = existingTags.length === 0;
+ const {
+ canCreateNewTags,
+ maxTags,
+ isEnabled: isAutoTaggingEnabled,
+ } = organizationSettings.ai.autoTagging;
+
+ if (orgHasNoExistingTags && !canCreateNewTags) {
+ logger.info(
+ { documentId, organizationId },
+ 'No tags available and cannot create new tags. Skipping auto-tagging.',
+ );
+ return;
+ }
+
+ if (!isAutoTaggingEnabled) {
+ logger.info(
+ { documentId, organizationId },
+ 'Auto-tagging is disabled in organization settings. Skipping auto-tagging.',
+ );
+ return;
+ }
+
+ if (!document) {
+ throw createDocumentNotFoundError();
+ }
+
+ const startedAt = Date.now();
+ const actions = await promptForAutoTagging({
+ document,
+ existingTags,
+ canCreateNewTags,
+ maxTags,
+ modelId: ensureModelId(organizationSettings.ai.autoTagging.modelId),
+ });
+ const durationMs = Date.now() - startedAt;
+ logger.info({ documentId, organizationId, durationMs }, 'Auto-tagging completed');
+
+ await applyAutoTaggingActions({ documentId, organizationId, ...actions });
+ };
+}
diff --git a/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.test.ts b/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.test.ts
new file mode 100644
index 00000000..a799119d
--- /dev/null
+++ b/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.test.ts
@@ -0,0 +1,179 @@
+import { describe, expect, test, vi } from 'vitest';
+import type { AiServices } from '../../ai/ai.services';
+import { createInMemoryDatabase } from '../../app/database/database.test-utils';
+import { createTestEventServices } from '../../app/events/events.test-utils';
+import { overrideConfig } from '../../config/config.test-utils';
+import { createDocumentNotFoundError } from '../../documents/documents.errors';
+import { createDocumentsRepository } from '../../documents/documents.repository';
+import { registerExtractDocumentFileContentTask } from '../../documents/tasks/extract-document-file-content.task';
+import { createOrganizationSettingsRepository } from '../../organizations/organization-settings/organization-settings.repository';
+import { createReadableStream } from '../../shared/streams/readable-stream';
+import { createInMemoryStorageService } from '../../storage/storage.test-utils';
+import { documentsTagsTable } from '../../tags/tags.table';
+import { createInMemoryTaskServices } from '../../tasks/tasks.test-utils';
+import { registerEnrichDocumentTask } from './enrich-document.task';
+
+const documentIds = { documentId: 'doc_1', organizationId: 'org_1' };
+const context = { workerId: 'test' };
+
+async function createTestDeps({ aiEnabled = true, autoTaggingEnabled = true } = {}) {
+ const { db } = await createInMemoryDatabase({
+ organizations: [{ id: 'org_1', name: 'Org 1' }],
+ documents: [
+ {
+ id: 'doc_1',
+ organizationId: 'org_1',
+ name: 'invoice.txt',
+ originalName: 'invoice.txt',
+ originalStorageKey: 'doc_1',
+ originalSha256Hash: 'doc_1',
+ mimeType: 'text/plain',
+ },
+ ],
+ tags: [
+ {
+ id: 'tag_1',
+ organizationId: 'org_1',
+ name: 'Finance',
+ normalizedName: 'finance',
+ color: '#000000',
+ },
+ ],
+ });
+ const config = overrideConfig({
+ ai: { isEnabled: aiEnabled },
+ autoTagging: { isEnabled: autoTaggingEnabled, modelId: 'openai://test-model' },
+ documentContentExtraction: { extractionStrategies: ['internal'] },
+ });
+ const taskServices = createInMemoryTaskServices();
+ const documentsStorageService = createInMemoryStorageService();
+ const eventServices = createTestEventServices();
+ const generateStructuredData = vi
+ .fn<AiServices['generateStructuredData']>()
+ .mockResolvedValue({ existingTags: ['Finance'] });
+ const aiServices = { generateStructuredData } as AiServices;
+
+ await documentsStorageService.saveFile({
+ storageKey: 'doc_1',
+ fileStream: createReadableStream({ content: 'Invoice for office supplies' }),
+ fileName: 'invoice.txt',
+ mimeType: 'text/plain',
+ });
+
+ await registerEnrichDocumentTask({ db, config, taskServices, eventServices, aiServices });
+ await registerExtractDocumentFileContentTask({
+ db,
+ config,
+ taskServices,
+ eventServices,
+ documentsStorageService,
+ });
+
+ const taskRegistry = taskServices.getTaskRegistry();
+ const { taskDefinition: extractTask } = taskRegistry.getTaskOrThrow({
+ taskName: 'extract-document-file-content',
+ });
+
+ return {
+ db,
+ taskServices,
+ taskRegistry,
+ generateStructuredData,
+ documentsRepository: createDocumentsRepository({ db }),
+ organizationSettingsRepository: createOrganizationSettingsRepository({ db }),
+ extractDocumentContent: async () =>
+ extractTask.handler({ data: { ...documentIds, ocrLanguages: ['eng'] }, context }),
+ };
+}
+
+describe('document enrichment task', () => {
+ test('text extraction schedules enrichment, which tags the document using its extracted content and existing settings', async () => {
+ const deps = await createTestDeps();
+ await deps.organizationSettingsRepository.createOrUpdateOrganizationSettings({
+ organizationId: 'org_1',
+ settings: { aiAutoTaggingEnabled: true },
+ });
+
+ await deps.extractDocumentContent();
+
+ expect(await deps.taskServices.getJobCount()).toEqual({ count: 1 });
+ expect(deps.generateStructuredData).not.toHaveBeenCalled();
+ const { job } = await deps.taskServices.getDriver().getNextJobAndMarkAsProcessing({
+ abortSignal: AbortSignal.timeout(1_000),
+ });
+ expect(job).toMatchObject({ taskName: 'enrich-document', data: documentIds });
+ expect(deps.taskRegistry.getTask({ taskName: 'auto-tag-document' }).taskDefinition).toEqual(
+ undefined,
+ );
+
+ const { taskDefinition } = deps.taskRegistry.getTaskOrThrow({ taskName: job.taskName });
+ await taskDefinition.handler({ data: job.data, context });
+
+ expect(deps.generateStructuredData).toHaveBeenCalledTimes(1);
+ const [request] = deps.generateStructuredData.mock.calls[0]!;
+ expect(request).toMatchObject({
+ organizationId: 'org_1',
+ modelId: 'openai://test-model',
+ source: 'auto-tagging',
+ });
+ expect(request.userPrompt).toContain('Invoice for office supplies');
+ expect(await deps.db.select().from(documentsTagsTable)).toEqual([
+ { documentId: 'doc_1', tagId: 'tag_1' },
+ ]);
+ });
+
+ test('enrichment keeps automatic tagging disabled for organizations without settings', async () => {
+ const deps = await createTestDeps();
+ const { taskDefinition } = deps.taskRegistry.getTaskOrThrow({ taskName: 'enrich-document' });
+
+ await taskDefinition.handler({ data: documentIds, context });
+
+ expect(deps.generateStructuredData).not.toHaveBeenCalled();
+ expect(await deps.db.select().from(documentsTagsTable)).toEqual([]);
+ });
+
+ test('disabling AI prevents enrichment registration and scheduling without preventing text extraction', async () => {
+ const deps = await createTestDeps({ aiEnabled: false });
+
+ await deps.extractDocumentContent();
+
+ expect(deps.taskRegistry.getTask({ taskName: 'enrich-document' }).taskDefinition).toEqual(
+ undefined,
+ );
+ expect(await deps.taskServices.getJobCount()).toEqual({ count: 0 });
+ expect(await deps.documentsRepository.getDocumentById(documentIds)).toMatchObject({
+ document: { content: 'Invoice for office supplies' },
+ });
+ });
+
+ test('disabling global auto-tagging prevents enrichment registration and scheduling without preventing text extraction', async () => {
+ const deps = await createTestDeps({ autoTaggingEnabled: false });
+
+ await deps.extractDocumentContent();
+
+ expect(deps.taskRegistry.getTask({ taskName: 'enrich-document' }).taskDefinition).toEqual(
+ undefined,
+ );
+ expect(await deps.taskServices.getJobCount()).toEqual({ count: 0 });
+ expect(await deps.documentsRepository.getDocumentById(documentIds)).toMatchObject({
+ document: { content: 'Invoice for office supplies' },
+ });
+ });
+
+ test('a failed extraction does not schedule enrichment', async () => {
+ const deps = await createTestDeps();
+ const { taskDefinition } = deps.taskRegistry.getTaskOrThrow({
+ taskName: 'extract-document-file-content',
+ });
+
+ await expect(
+ taskDefinition.handler({
+ data: { ...documentIds, documentId: 'missing', ocrLanguages: ['eng'] },
+ context,
+ }),
+ ).rejects.toEqual(createDocumentNotFoundError());
+
+ expect(await deps.taskServices.getJobCount()).toEqual({ count: 0 });
+ expect(deps.generateStructuredData).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/papra-server/src/modules/auto-tagging/tasks/auto-tag-document.task.ts b/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.ts
similarity index 87%
rename from apps/papra-server/src/modules/auto-tagging/tasks/auto-tag-document.task.ts
rename to apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.ts
index a201bb7e..7ca4f2b7 100644
--- a/apps/papra-server/src/modules/auto-tagging/tasks/auto-tag-document.task.ts
+++ b/apps/papra-server/src/modules/document-enrichment/tasks/enrich-document.task.ts
@@ -3,7 +3,6 @@ import type { TaskServices } from '../../tasks/tasks.services';
import { createTagsRepository } from '../../tags/tags.repository';
import {
buildApplyAutoTaggingActions,
- buildAutoTagDocument,
buildPromptForAutoTagging,
} from '../../auto-tagging/auto-tagging.usecases';
import { applyTagsToDocuments, createTag } from '../../tags/tags.usecases';
@@ -14,8 +13,9 @@ import type { Config } from '../../config/config.types';
import { createDocumentsRepository } from '../../documents/documents.repository';
import type { EventServices } from '../../app/events/events.services';
import type { AiServices } from '../../ai/ai.services';
+import { buildEnrichDocument } from '../document-enrichment.usecases';
-export async function registerAutoTagDocumentTask({
+export async function registerEnrichDocumentTask({
taskServices,
aiServices,
db,
@@ -32,7 +32,7 @@ export async function registerAutoTagDocumentTask({
return;
}
- const taskName = 'auto-tag-document';
+ const taskName = 'enrich-document';
taskServices.registerTask({
taskName,
@@ -47,8 +47,8 @@ export async function registerAutoTagDocumentTask({
organizationId: string;
};
- const logger = createLogger({ namespace: 'autoTagDocument' });
- const autoTagDocument = buildAutoTagDocument({
+ const logger = createLogger({ namespace: 'documentEnrichment' });
+ const enrichDocument = buildEnrichDocument({
documentsRepository,
tagsRepository,
logger,
@@ -64,7 +64,7 @@ export async function registerAutoTagDocumentTask({
}),
});
- await autoTagDocument({ documentId, organizationId });
+ await enrichDocument({ documentId, organizationId });
},
});
}
diff --git a/apps/papra-server/src/modules/documents/tasks/extract-document-file-content.task.ts b/apps/papra-server/src/modules/documents/tasks/extract-document-file-content.task.ts
index 63a5db25..1edd79f6 100644
--- a/apps/papra-server/src/modules/documents/tasks/extract-document-file-content.task.ts
+++ b/apps/papra-server/src/modules/documents/tasks/extract-document-file-content.task.ts
@@ -59,7 +59,7 @@ export async function registerExtractDocumentFileContentTask({
}
await taskServices.scheduleJob({
- taskName: 'auto-tag-document',
+ taskName: 'enrich-document',
data: { documentId, organizationId },
});
},
diff --git a/apps/papra-server/src/modules/tasks/tasks.definitions.ts b/apps/papra-server/src/modules/tasks/tasks.definitions.ts
index ce9daee0..f69f634e 100644
--- a/apps/papra-server/src/modules/tasks/tasks.definitions.ts
+++ b/apps/papra-server/src/modules/tasks/tasks.definitions.ts
@@ -1,4 +1,4 @@
-import { registerAutoTagDocumentTask } from '../auto-tagging/tasks/auto-tag-document.task';
+import { registerEnrichDocumentTask } from '../document-enrichment/tasks/enrich-document.task';
import type { GlobalDependencies } from '../app/server.types';
import { registerExtractDocumentFileContentTask } from '../documents/tasks/extract-document-file-content.task';
import { registerHardDeleteExpiredDocumentsTask } from '../documents/tasks/hard-delete-expired-documents.task';
@@ -15,6 +15,6 @@ export async function registerTaskDefinitions(deps: GlobalDependencies) {
await registerExtractDocumentFileContentTask(deps);
await registerApplyTaggingRuleToDocumentsTask(deps);
await registerPurgeExpiredKvEntriesTask(deps);
- await registerAutoTagDocumentTask(deps);
+ await registerEnrichDocumentTask(deps);
await registerReverifyPlanEntitlementsTask(deps);
}