@tstdl/base 0.93.123 → 0.93.126

package/document-management/service-models/document.service-model.js

@@ -39,7 +39,7 @@ export const deleteDocumentRequestTemplateParametersSchema = assign(pick(Documen
 export const createDocumentRequestParametersSchema = assign(pick(DocumentRequest, ['typeId', 'comment']), object({ collectionIds: array(string()) }), metadataParameterObjectSchema);
 export const updateDocumentRequestParametersSchema = assign(pick(DocumentRequest, ['id']), partial(pick(DocumentRequest, ['typeId', 'comment'])), metadataParameterObjectSchema);
 export const deleteDocumentRequestParametersSchema = assign(pick(DocumentRequest, ['id']), metadataParameterObjectSchema);
-export const loadDataParametersSchema = object({ collectionIds: oneOrMany(string()) });
+export const getDataParametersSchema = object({ collectionIds: oneOrMany(string()) });
 export const createCollectionParametersSchema = assign(pick(DocumentCollection, ['parentId']), metadataParameterObjectSchema);
 export const setDocumentPropertiesParametersSchema = object({
     documentId: string(),

package/document-management/tests/ai-config-hierarchy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/document-management/tests/ai-config-hierarchy.test.js

@@ -0,0 +1,64 @@
+import { afterAll, beforeAll, describe, expect, test, vi } from 'vitest';
+import { injectModel } from '../../ai/genkit/index.js';
+import { runInInjectionContext } from '../../injector/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
+import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
+import { DocumentCategoryTypeService, DocumentManagementAiProviderService, DocumentManagementAncillaryService } from '../server/services/index.js';
+import { TestDocumentManagementAncillaryService } from './helper.js';
+describe('DocumentManagementAiService Hierarchy', () => {
+    let injector;
+    let aiService;
+    let flashModel;
+    const tenantId = crypto.randomUUID();
+    const mockAiProvider = {
+        getGlobalConfiguration: vi.fn(),
+        getClassificationConfiguration: vi.fn(),
+        getDataExtractionConfiguration: vi.fn(),
+        getAssignmentConfiguration: vi.fn(),
+        getValidationConfiguration: vi.fn(),
+        getContentExtractionConfiguration: vi.fn(),
+    };
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({
+            orm: { schema: 'document_management' },
+            modules: { messageBus: true, signals: true, objectStorage: true, documentManagement: true },
+        }));
+        runInInjectionContext(injector, () => {
+            flashModel = injectModel('gemini-2.5-flash');
+        });
+        injector.register(DocumentManagementAiProviderService, { useValue: mockAiProvider });
+        // Ancillary and configuration are already registered by setupIntegrationTest, but we can override if needed
+        injector.register(DocumentManagementAncillaryService, { useToken: TestDocumentManagementAncillaryService });
+        aiService = await injector.resolveAsync(DocumentManagementAiService);
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    test('resolveAiConfiguration should implement Type > Category > Global Step > Global Defaults hierarchy', async () => {
+        const categoryTypeService = await injector.resolveAsync(DocumentCategoryTypeService);
+        const category = await categoryTypeService.createCategory({ tenantId, label: 'Finance', key: 'finance-cat', parentId: null });
+        const type = await categoryTypeService.createType({ tenantId, categoryId: category.id, label: 'Invoice', key: 'invoice-type' });
+        mockAiProvider.getGlobalConfiguration.mockResolvedValue({
+            defaults: { language: 'de', classification: 'Global Default Classify' },
+            steps: {
+                'data-extraction': { language: 'en', extraction: { title: 'Global Step Title' } }
+            },
+            categories: {
+                'finance-cat': { extraction: { title: 'Category Title', subtitle: 'Category Subtitle' } }
+            },
+            documentTypes: {
+                'invoice-type': { extraction: { title: 'Type Title' } }
+            }
+        });
+        mockAiProvider.getDataExtractionConfiguration.mockResolvedValue({
+            extraction: { subtitle: 'Provider Subtitle' }
+        });
+        await runInInjectionContext(injector, async () => {
+            const config = await aiService.resolveAiConfiguration(tenantId, 'data-extraction', { type });
+            expect(config.language).toBe('en'); // Step > Defaults
+            expect(config.classification).toBe('Global Default Classify'); // Fallback to defaults
+            expect(config.extraction.title).toBe('Type Title'); // Type > Category > Step
+            expect(config.extraction.subtitle).toBe('Provider Subtitle'); // Provider > Category
+        });
+    });
+});

package/document-management/tests/ai-config-integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/document-management/tests/ai-config-integration.test.js

@@ -0,0 +1,125 @@
+import { afterAll, beforeAll, describe, expect, test, vi } from 'vitest';
+const mockGenerate = vi.fn();
+vi.mock('genkit', async () => {
+    const original = await vi.importActual('genkit');
+    return {
+        ...original,
+        genkit: () => ({
+            generate: mockGenerate,
+        }),
+    };
+});
+import { injectModel } from '../../ai/genkit/index.js';
+import { runInInjectionContext } from '../../injector/index.js';
+import { ObjectStorage } from '../../object-storage/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
+import { DocumentCategoryTypeService } from '../server/services/document-category-type.service.js';
+import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
+import { DocumentService } from '../server/services/document.service.js';
+import { DocumentManagementAiProviderService, DocumentManagementAncillaryService } from '../server/services/index.js';
+import { TestDocumentManagementAncillaryService } from './helper.js';
+describe('DocumentManagementAiService Integration', () => {
+    let injector;
+    let aiService;
+    let flashModel;
+    const tenantId = crypto.randomUUID();
+    const mockAiProvider = {
+        getGlobalConfiguration: vi.fn(),
+        getClassificationConfiguration: vi.fn(),
+        getDataExtractionConfiguration: vi.fn(),
+        getAssignmentConfiguration: vi.fn(),
+        getValidationConfiguration: vi.fn(),
+        getContentExtractionConfiguration: vi.fn(),
+    };
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({
+            modules: { messageBus: true, signals: true, objectStorage: true, documentManagement: true, taskQueue: true },
+        }));
+        const mockObjectStorage = {
+            store: vi.fn().mockResolvedValue({ mimeType: 'application/pdf', hash: 'hash', size: 100 }),
+            uploadObject: vi.fn(),
+            getDownloadUrl: vi.fn(),
+            getContent: vi.fn().mockResolvedValue(new Uint8Array([1, 2, 3])),
+            getContentStream: vi.fn(),
+            getObject: vi.fn(),
+            exists: vi.fn(),
+        };
+        runInInjectionContext(injector, () => {
+            flashModel = injectModel('gemini-2.5-flash');
+        });
+        injector.register(DocumentManagementAiProviderService, { useValue: mockAiProvider });
+        injector.register(DocumentManagementAncillaryService, { useToken: TestDocumentManagementAncillaryService });
+        injector.register(ObjectStorage, { useValue: mockObjectStorage });
+        aiService = await injector.resolveAsync(DocumentManagementAiService);
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    test('extractData should include granular instructions in prompt', async () => {
+        const categoryTypeService = await injector.resolveAsync(DocumentCategoryTypeService);
+        const documentService = await injector.resolveAsync(DocumentService);
+        const category = await categoryTypeService.createCategory({ tenantId, label: 'Finance', key: 'finance', parentId: null });
+        const type = await categoryTypeService.createType({ tenantId, categoryId: category.id, label: 'Invoice', key: 'invoice' });
+        const document = await documentService.create(tenantId, {
+            typeId: type.id,
+            originalFileName: 'test.pdf',
+            skipWorkflow: true,
+            assignment: { collections: [] }
+        }, new Uint8Array([1, 2, 3]));
+        mockAiProvider.getGlobalConfiguration.mockResolvedValue({
+            documentTypes: {
+                'invoice': {
+                    extraction: {
+                        title: { format: 'INV-{{Date}}' },
+                        summary: { content: 'Focus on items.', strategy: 'append' }
+                    }
+                }
+            }
+        });
+        mockAiProvider.getDataExtractionConfiguration.mockResolvedValue(undefined);
+        // Mock Genkit output
+        mockGenerate.mockResolvedValue({
+            output: {
+                documentTitle: 'INV-2024',
+                documentSubtitle: null,
+                documentSummary: 'Summary',
+                documentTags: [],
+                documentDate: null
+            }
+        });
+        await runInInjectionContext(injector, async () => {
+            await aiService.extractData(tenantId, document.id);
+            const lastCall = mockGenerate.mock.calls[0][0];
+            const systemPrompt = lastCall.system;
+            const systemPromptText = systemPrompt.map((p) => p.text).join('\n');
+            expect(systemPromptText).toContain('Format the title of the document exactly as follows: INV-{{Date}}');
+            expect(systemPromptText).toContain('Focus on items.');
+        });
+    });
+    test('classifyDocumentType should include granular instructions in prompt', async () => {
+        const documentService = await injector.resolveAsync(DocumentService);
+        const document = await documentService.create(tenantId, {
+            originalFileName: 'test.pdf',
+            skipWorkflow: true,
+            assignment: { collections: [] }
+        }, new Uint8Array([1, 2, 3]));
+        mockAiProvider.getGlobalConfiguration.mockResolvedValue({
+            defaults: {
+                classification: { content: 'Prefer Finance types.', strategy: 'append' }
+            }
+        });
+        mockAiProvider.getClassificationConfiguration.mockResolvedValue(undefined);
+        mockGenerate.mockResolvedValue({
+            output: {
+                documentType: 'Category: Finance | Type: Invoice'
+            }
+        });
+        await runInInjectionContext(injector, async () => {
+            await aiService.classifyDocumentType(tenantId, document.id);
+            const lastCall = mockGenerate.mock.calls[1][0];
+            const systemPrompt = lastCall.system;
+            const systemPromptText = systemPrompt.map((p) => p.text).join('\n');
+            expect(systemPromptText).toContain('Prefer Finance types.');
+        });
+    });
+});

package/document-management/tests/ai-config-merge.test.d.ts

@@ -0,0 +1 @@
+export {};

package/document-management/tests/ai-config-merge.test.js

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'vitest';
+import { mergeInstructions } from '../server/services/document-management-ai.service.js';
+describe('AI Instruction Merging', () => {
+    test('should return base when no overrides are provided', () => {
+        const base = 'Default instruction';
+        expect(mergeInstructions(base, [])).toBe(base);
+    });
+    test('should replace with string override', () => {
+        const base = 'Default instruction';
+        const overrides = ['Custom instruction'];
+        expect(mergeInstructions(base, overrides)).toBe('Custom instruction');
+    });
+    test('should append with append strategy', () => {
+        const base = 'Default instruction';
+        const overrides = [{ content: 'Added instruction', strategy: 'append' }];
+        expect(mergeInstructions(base, overrides)).toBe('Default instruction\n\nAdded instruction');
+    });
+    test('should replace with replace strategy', () => {
+        const base = 'Default instruction';
+        const overrides = [{ content: 'New instruction', strategy: 'replace' }];
+        expect(mergeInstructions(base, overrides)).toBe('New instruction');
+    });
+    test('should handle multiple overrides in order', () => {
+        const base = 'Base';
+        const overrides = [
+            { content: 'Global', strategy: 'append' },
+            { content: 'Category', strategy: 'append' },
+            { content: 'Type', strategy: 'replace' }
+        ];
+        expect(mergeInstructions(base, overrides)).toBe('Type');
+    });
+    test('should handle format simple override', () => {
+        const base = 'Create a title.';
+        const overrides = [{ format: '[ID] - [Name]' }];
+        const result = mergeInstructions(base, overrides);
+        expect(result).toContain('[ID] - [Name]');
+    });
+});

package/document-management/tests/document-management-ai-overrides.test.d.ts

@@ -0,0 +1 @@
+export {};

package/document-management/tests/document-management-ai-overrides.test.js

@@ -0,0 +1,64 @@
+import { afterAll, beforeAll, describe, expect, test, vi } from 'vitest';
+import { injectModel } from '../../ai/genkit/index.js';
+import { runInInjectionContext } from '../../injector/index.js';
+import { ObjectStorage } from '../../object-storage/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
+import { DocumentManagementConfiguration } from '../server/module.js';
+import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
+import { DocumentCategoryTypeService, DocumentManagementAiProviderService, DocumentManagementAncillaryService } from '../server/services/index.js';
+import { TestDocumentManagementAncillaryService } from './helper.js';
+describe('DocumentManagementAiService Overrides', () => {
+    let injector;
+    let aiService;
+    let flashModel;
+    let proModel;
+    const tenantId = crypto.randomUUID();
+    const mockAiProvider = {
+        getGlobalConfiguration: vi.fn(),
+        getClassificationConfiguration: vi.fn(),
+        getDataExtractionConfiguration: vi.fn(),
+        getAssignmentConfiguration: vi.fn(),
+        getValidationConfiguration: vi.fn(),
+    };
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({
+            orm: { schema: 'document_management' },
+            modules: { messageBus: true, signals: true, objectStorage: true },
+        }));
+        runInInjectionContext(injector, () => {
+            flashModel = injectModel('gemini-2.5-flash');
+            proModel = injectModel('gemini-2.5-pro');
+        });
+        injector.register(DocumentManagementAiProviderService, { useValue: mockAiProvider });
+        injector.register(DocumentManagementAncillaryService, { useToken: TestDocumentManagementAncillaryService });
+        injector.register(DocumentManagementConfiguration, { useValue: { fileObjectStorageModule: 'docs', fileUploadObjectStorageModule: 'uploads', filePreviewObjectStorageModule: 'previews' } });
+        aiService = await injector.resolveAsync(DocumentManagementAiService);
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    test('resolveAiConfiguration should merge configurations correctly', async () => {
+        const categoryTypeService = await injector.resolveAsync(DocumentCategoryTypeService);
+        const category = await categoryTypeService.createCategory({ tenantId, label: 'Finance', key: 'finance-cat', parentId: null });
+        const type = await categoryTypeService.createType({ tenantId, categoryId: category.id, label: 'Invoice', key: 'invoice-key' });
+        mockAiProvider.getGlobalConfiguration.mockResolvedValue({
+            defaults: {
+                language: 'en',
+                model: flashModel,
+                prompt: { systemAddition: 'Global System' },
+            },
+        });
+        mockAiProvider.getDataExtractionConfiguration.mockResolvedValue({
+            model: proModel,
+            prompt: { systemAddition: 'Extraction System', systemOverride: (base) => `OVERRIDDEN: ${base}` },
+        });
+        await runInInjectionContext(injector, async () => {
+            // Accessing private method for testing purposes
+            const config = await aiService.resolveAiConfiguration(tenantId, 'data-extraction', { type });
+            expect(config.language).toBe('en');
+            expect(config.model).toBe(proModel);
+            expect(config.prompt.systemAddition).toEqual(['Global System', 'Extraction System']);
+            expect(config.prompt.systemOverride('Base')).toBe('OVERRIDDEN: Base');
+        });
+    });
+});

package/document-management/tests/document-management-core.test.js

@@ -1,14 +1,14 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
-import { AiService } from '../../ai/ai.service.js';
-import { AiModuleOptions } from '../../ai/module.js';
+import { GenkitModuleOptions } from '../../ai/genkit/module.js';
 import { runInInjectionContext } from '../../injector/index.js';
 import { ObjectStorage } from '../../object-storage/index.js';
 import { TaskQueue } from '../../task-queue/index.js';
-import { setupIntegrationTest, clearTenantData } from '../../unit-test/index.js';
+import { clearTenantData, setupIntegrationTest } from '../../testing/index.js';
 import { configureDocumentManagement } from '../server/configure.js';
 import { migrateDocumentManagementSchema } from '../server/module.js';
 import { DocumentCategoryTypeService } from '../server/services/document-category-type.service.js';
 import { DocumentCollectionService } from '../server/services/document-collection.service.js';
+import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
 import { DocumentManagementService } from '../server/services/document-management.service.js';
 import { DocumentPropertyService } from '../server/services/document-property.service.js';
 import { DocumentRequestService } from '../server/services/document-request.service.js';
@@ -22,8 +22,8 @@ describe('Document Management Core', () => {
     let collectionService;
     let requestService;
     let managementService;
-    let workflowService;
     let categoryTypeService;
+    let workflowService;
     let propertyService;
     const schema = 'document_management';
     const tenantId = crypto.randomUUID();
@@ -32,8 +32,8 @@ describe('Document Management Core', () => {
             modules: { taskQueue: false, messageBus: true }, // Disabled TaskQueue to avoid background noise
             orm: { schema },
         }));
-        injector.register(AiModuleOptions, { useValue: {} });
-        injector.register(AiService, { useValue: { processFile: vi.fn() } });
+        injector.register(GenkitModuleOptions, { useValue: {} });
+        injector.register(DocumentManagementAiService, { useValue: { extractContent: vi.fn(), classifyDocumentType: vi.fn(), extractData: vi.fn(), findSuitableCollectionsForDocument: vi.fn(), findSuitableRequestForDocument: vi.fn() } });
         injector.register(ObjectStorage, {
             useValue: {
                 uploadObject: vi.fn(),

package/document-management/tests/document-management.api.test.js

@@ -1,15 +1,15 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
-import { AiService } from '../../ai/ai.service.js';
-import { AiModuleOptions } from '../../ai/module.js';
+import { GenkitModuleOptions } from '../../ai/genkit/module.js';
 import { runInInjectionContext } from '../../injector/index.js';
 import { ObjectStorage } from '../../object-storage/index.js';
 import { TaskQueue } from '../../task-queue/index.js';
-import { clearTenantData, setupIntegrationTest } from '../../unit-test/index.js';
+import { clearTenantData, setupIntegrationTest } from '../../testing/index.js';
 import { DocumentManagementAuthorizationService } from '../authorization/document-management-authorization.service.js';
 import { DocumentManagementApiController } from '../server/api/document-management.api.js';
 import { configureDocumentManagement } from '../server/configure.js';
 import { migrateDocumentManagementSchema } from '../server/module.js';
 import { DocumentCollectionService } from '../server/services/document-collection.service.js';
+import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
 import { DocumentService } from '../server/services/document.service.js';
 import { TestDocumentManagementAncillaryService, TestDocumentManagementAuthorizationService } from './helper.js';
 describe('DocumentManagementApi Stats', () => {
@@ -25,8 +25,8 @@ describe('DocumentManagementApi Stats', () => {
             modules: { taskQueue: false, messageBus: true },
             orm: { schema },
         }));
-        injector.register(AiModuleOptions, { useValue: {} });
-        injector.register(AiService, { useValue: { processFile: vi.fn() } });
+        injector.register(GenkitModuleOptions, { useValue: {} });
+        injector.register(DocumentManagementAiService, { useValue: { extractContent: vi.fn(), classifyDocumentType: vi.fn(), extractData: vi.fn(), findSuitableCollectionsForDocument: vi.fn(), findSuitableRequestForDocument: vi.fn() } });
         injector.register(ObjectStorage, {
             useValue: {
                 uploadObject: vi.fn(),

package/document-management/tests/document-statistics.service.test.js

@@ -1,10 +1,9 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
-import { AiService } from '../../ai/ai.service.js';
-import { AiModuleOptions } from '../../ai/module.js';
+import { GenkitModuleOptions } from '../../ai/genkit/module.js';
 import { runInInjectionContext } from '../../injector/index.js';
 import { ObjectStorage } from '../../object-storage/index.js';
 import { getRepository } from '../../orm/server/index.js';
-import { clearTenantData, setupIntegrationTest } from '../../unit-test/index.js';
+import { clearTenantData, setupIntegrationTest } from '../../testing/index.js';
 import { DocumentValidationDefinition } from '../models/document-validation-definition.model.js';
 import { DocumentValidationExecution, DocumentValidationExecutionState, DocumentValidationResultStatus } from '../models/document-validation-execution.model.js';
 import { DocumentWorkflow, DocumentWorkflowState, DocumentWorkflowStep } from '../models/document-workflow.model.js';
@@ -13,6 +12,7 @@ import { configureDocumentManagement } from '../server/configure.js';
 import { migrateDocumentManagementSchema } from '../server/module.js';
 import { DocumentCategoryTypeService } from '../server/services/document-category-type.service.js';
 import { DocumentCollectionService } from '../server/services/document-collection.service.js';
+import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
 import { DocumentStatisticsService } from '../server/services/document-statistics.service.js';
 import { DocumentTagService } from '../server/services/document-tag.service.js';
 import { DocumentService } from '../server/services/document.service.js';
@@ -41,11 +41,15 @@ describe('DocumentStatisticsService', () => {
             exists: vi.fn(),
         };
         const mockAiService = {
-            processFile: vi.fn(),
+            extractContent: vi.fn(),
+            classifyDocumentType: vi.fn(),
+            extractData: vi.fn(),
+            findSuitableCollectionsForDocument: vi.fn(),
+            findSuitableRequestForDocument: vi.fn(),
         };
         injector.register(ObjectStorage, { useFactory: () => mockObjectStorage });
-        injector.register(AiModuleOptions, { useValue: {} });
-        injector.register(AiService, { useValue: mockAiService });
+        injector.register(GenkitModuleOptions, { useValue: {} });
+        injector.register(DocumentManagementAiService, { useValue: mockAiService });
         configureDocumentManagement({
             ancillaryService: TestDocumentManagementAncillaryService,
             authorizationService: TestDocumentManagementAuthorizationService,

package/document-management/tests/document-validation-ai-overrides.test.d.ts

@@ -0,0 +1 @@
+export {};

package/document-management/tests/document-validation-ai-overrides.test.js

@@ -0,0 +1,85 @@
+import { afterAll, beforeAll, describe, expect, test, vi } from 'vitest';
+import { injectModel } from '../../ai/genkit/index.js';
+import { formatInstructions } from '../../ai/prompts/index.js';
+import { runInInjectionContext } from '../../injector/index.js';
+import { object, string } from '../../schema/index.js';
+import { setupIntegrationTest } from '../../testing/index.js';
+import { isString } from '../../utils/type-guards.js';
+import { DocumentManagementConfiguration } from '../server/module.js';
+import { DocumentManagementAiProviderService, DocumentManagementAncillaryService } from '../server/services/index.js';
+import { AiValidationExecutor } from '../server/validators/ai-validation-executor.js';
+import { TestDocumentManagementAncillaryService } from './helper.js';
+class TestAiValidationExecutor extends AiValidationExecutor {
+    identifier = 'test-validation';
+    schema = object({ valid: string() });
+    async getValidationInstructions() { return 'Test Prompt'; }
+    async getResult() { return { status: 'passed' }; }
+    executorConfig = {};
+    getAiConfiguration() { return this.executorConfig; }
+    // Expose protected method for testing
+    async publicExecute(context) {
+        return this.execute(context);
+    }
+}
+describe('AiValidationExecutor Overrides', () => {
+    let injector;
+    let flashModel;
+    let proModel;
+    const tenantId = crypto.randomUUID();
+    const mockAiProvider = {
+        getGlobalConfiguration: vi.fn(),
+        getValidationConfiguration: vi.fn(),
+    };
+    beforeAll(async () => {
+        ({ injector } = await setupIntegrationTest({
+            orm: { schema: 'document_management' },
+            modules: { messageBus: true, signals: true, objectStorage: true },
+        }));
+        runInInjectionContext(injector, () => {
+            flashModel = injectModel('gemini-2.5-flash');
+            proModel = injectModel('gemini-2.5-pro');
+        });
+        injector.register(DocumentManagementAiProviderService, { useValue: mockAiProvider });
+        injector.register(DocumentManagementAncillaryService, { useToken: TestDocumentManagementAncillaryService });
+        injector.register(DocumentManagementConfiguration, { useValue: { fileObjectStorageModule: 'docs', fileUploadObjectStorageModule: 'uploads', filePreviewObjectStorageModule: 'previews' } });
+    });
+    afterAll(async () => {
+        await injector?.dispose();
+    });
+    test('AiValidationExecutor should merge configurations correctly', async () => {
+        mockAiProvider.getGlobalConfiguration.mockResolvedValue({
+            defaults: {
+                language: 'en',
+                model: flashModel,
+                prompt: { systemAddition: 'Global System', userAddition: 'Global User' },
+            },
+        });
+        mockAiProvider.getValidationConfiguration.mockResolvedValue({
+            model: proModel,
+            prompt: { systemAddition: 'Validation System', systemOverride: (base) => `OVERRIDDEN: ${isString(base) ? base : formatInstructions(base)}` },
+        });
+        await runInInjectionContext(injector, async () => {
+            const executor = new TestAiValidationExecutor();
+            executor.executorConfig = {
+                prompt: { systemAddition: 'Executor System', userAddition: 'Executor User' },
+            };
+            const generateSpy = vi.spyOn(executor.genkit, 'generate').mockResolvedValue({ output: { valid: 'yes' } });
+            const context = {
+                execution: { tenantId },
+                definition: { identifier: 'test-validation' },
+            };
+            await executor.publicExecute(context);
+            const call = generateSpy.mock.calls[0][0];
+            const systemText = call.system.map((p) => p.text).join('\n');
+            const userText = call.prompt.map((p) => p.text).join('\n');
+            expect(call.model.name).toBe(proModel.name);
+            expect(systemText).toContain('Global System');
+            expect(systemText).toContain('Executor System');
+            expect(systemText).toContain('Validation System');
+            expect(systemText).toContain('OVERRIDDEN:');
+            expect(userText).toContain('Global User');
+            expect(userText).toContain('Executor User');
+            expect(userText).toContain('IMPORTANT: All generated text content MUST be in en.');
+        });
+    });
+});

package/document-management/tests/document.service.test.js

@@ -1,14 +1,14 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
-import { AiService } from '../../ai/ai.service.js';
-import { AiModuleOptions } from '../../ai/module.js';
+import { GenkitModuleOptions } from '../../ai/genkit/module.js';
 import { runInInjectionContext } from '../../injector/index.js';
 import { ObjectStorage } from '../../object-storage/index.js';
-import { clearTenantData, setupIntegrationTest } from '../../unit-test/index.js';
-import { DocumentWorkflowState } from '../models/document-workflow.model.js';
+import { clearTenantData, setupIntegrationTest } from '../../testing/index.js';
+import { DocumentWorkflowState, DocumentWorkflowStep } from '../models/document-workflow.model.js';
 import { DocumentApproval } from '../models/document.model.js';
 import { configureDocumentManagement } from '../server/configure.js';
 import { DocumentManagementConfiguration, migrateDocumentManagementSchema } from '../server/module.js';
 import { DocumentCollectionService } from '../server/services/document-collection.service.js';
+import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
 import { DocumentWorkflowService } from '../server/services/document-workflow.service.js';
 import { DocumentService } from '../server/services/document.service.js';
 import { TestDocumentManagementAncillaryService, TestDocumentManagementAuthorizationService } from './helper.js';
@@ -34,11 +34,15 @@ describe('DocumentService', () => {
             exists: vi.fn(),
         };
         const mockAiService = {
-            processFile: vi.fn(),
+            extractContent: vi.fn(),
+            classifyDocumentType: vi.fn(),
+            extractData: vi.fn(),
+            findSuitableCollectionsForDocument: vi.fn(),
+            findSuitableRequestForDocument: vi.fn(),
         };
         injector.register(ObjectStorage, { useFactory: () => mockObjectStorage });
-        injector.register(AiModuleOptions, { useValue: {} });
-        injector.register(AiService, { useValue: mockAiService });
+        injector.register(GenkitModuleOptions, { useValue: {} });
+        injector.register(DocumentManagementAiService, { useValue: mockAiService });
         configureDocumentManagement({
             ancillaryService: TestDocumentManagementAncillaryService,
             authorizationService: TestDocumentManagementAuthorizationService,
@@ -99,9 +103,9 @@ describe('DocumentService', () => {
             await workflowService.proceedWorkflow(tenantId, doc.id, crypto.randomUUID(), DocumentWorkflowState.Completed);
             workflows = await workflowService.loadWorkflows(tenantId, doc.id);
             expect(workflows).toHaveLength(2);
-            expect(workflows.find((w) => w.step == 'classification')?.state).toBe('completed');
-            expect(workflows.find((w) => w.step == 'extraction')?.state).toBe('pending');
-            expect(workflows.find((w) => w.step == 'extraction')?.skipAi).toBe(true);
+            expect(workflows.find((w) => w.step == DocumentWorkflowStep.Classification)?.state).toBe('completed');
+            expect(workflows.find((w) => w.step == DocumentWorkflowStep.DataExtraction)?.state).toBe('pending');
+            expect(workflows.find((w) => w.step == DocumentWorkflowStep.DataExtraction)?.skipAi).toBe(true);
         });
     });
     test('proceedWorkflow with skipAi: true should allow progression to Review', async () => {
@@ -112,7 +116,7 @@ describe('DocumentService', () => {
                 assignment: { collections: [collection.id] },
                 skipAi: true,
             }, new Uint8Array([1, 2, 3]));
-            await workflowService.proceedWorkflow(tenantId, doc.id, crypto.randomUUID(), 'review');
+            await workflowService.proceedWorkflow(tenantId, doc.id, crypto.randomUUID(), DocumentWorkflowState.Review);
             const workflows = await workflowService.loadWorkflows(tenantId, doc.id);
             expect(workflows).toHaveLength(1);
             expect(workflows[0].step).toBe('classification');

package/document-management/tests/enum-helpers.test.js

@@ -1,15 +1,15 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test, vi } from 'vitest';
-import { AiService } from '../../ai/ai.service.js';
-import { AiModuleOptions } from '../../ai/module.js';
+import { GenkitModuleOptions } from '../../ai/genkit/module.js';
 import { NotFoundError } from '../../errors/not-found.error.js';
 import { runInInjectionContext } from '../../injector/index.js';
 import { ObjectStorage } from '../../object-storage/index.js';
 import { TaskQueue } from '../../task-queue/index.js';
-import { clearTenantData, setupIntegrationTest } from '../../unit-test/index.js';
+import { clearTenantData, setupIntegrationTest } from '../../testing/index.js';
 import { DocumentPropertyDataType } from '../models/document-property.model.js';
 import { configureDocumentManagement } from '../server/configure.js';
 import { migrateDocumentManagementSchema } from '../server/module.js';
 import { DocumentCategoryTypeService } from '../server/services/document-category-type.service.js';
+import { DocumentManagementAiService } from '../server/services/document-management-ai.service.js';
 import { DocumentManagementService } from '../server/services/document-management.service.js';
 import { DocumentPropertyService } from '../server/services/document-property.service.js';
 import { TestDocumentManagementAncillaryService, TestDocumentManagementAuthorizationService } from './helper.js';
@@ -27,8 +27,8 @@ describe('Document Management Extended Suite', () => {
             modules: { taskQueue: false, messageBus: true },
             orm: { schema },
         }));
-        injector.register(AiModuleOptions, { useValue: {} });
-        injector.register(AiService, { useValue: { processFile: vi.fn() } });
+        injector.register(GenkitModuleOptions, { useValue: {} });
+        injector.register(DocumentManagementAiService, { useValue: { extractContent: vi.fn(), classifyDocumentType: vi.fn(), extractData: vi.fn(), findSuitableCollectionsForDocument: vi.fn(), findSuitableRequestForDocument: vi.fn() } });
         injector.register(ObjectStorage, {
             useValue: {
                 uploadObject: vi.fn(),

package/examples/document-management/ai-provider.d.ts

@@ -0,0 +1,20 @@
+import type { AiConfiguration, DocumentManagementAiConfiguration, DocumentWorkflowStep } from '../../document-management/index.js';
+import { DocumentManagementAiProviderService, type AiConfigurationResolveDataMap } from '../../document-management/server/index.js';
+export declare class ExampleAiProviderService extends DocumentManagementAiProviderService {
+    /**
+     * Providing global defaults for the entire Document Management module.
+     */
+    getGlobalConfiguration(): DocumentManagementAiConfiguration;
+    getContentExtractionConfiguration(): AiConfiguration;
+    /**
+     * Providing specific overrides for the Classification step.
+     */
+    getClassificationConfiguration(): AiConfiguration;
+    /**
+     * Providing specific overrides for the Data Extraction step,
+     * potentially specific to a Document Type Key.
+     */
+    getDataExtractionConfiguration(_tenantId: string, data: AiConfigurationResolveDataMap[typeof DocumentWorkflowStep.DataExtraction]): AiConfiguration;
+    getAssignmentConfiguration(): AiConfiguration;
+    getValidationConfiguration(): AiConfiguration;
+}