Merge pull request #61 from bcgov/AI-1042

Add document image normalization docs

Author: kmandryk

apps/backend-services/package.json

@@ -60,10 +60,12 @@
 		"openid-client": "^6.8.2",
 		"passport": "^0.7.0",
 		"passport-jwt": "^4.0.1",
+		"pdf-lib": "^1.17.1",
 		"pg": "^8.16.3",
 		"prisma": "7.2.0",
 		"prom-client": "^15.1.3",
 		"rxjs": "^7.8.2",
+		"sharp": "^0.34.5",
 		"uuid": "13.0.0"
 	},
 	"devDependencies": {

apps/backend-services/src/benchmark/ground-truth-generation.service.spec.ts

@@ -76,6 +76,7 @@ import {
   BlobStorageInterface,
 } from "@/blob-storage/blob-storage.interface";
 import { DocumentService } from "@/document/document.service";
+import { PdfNormalizationService } from "@/document/pdf-normalization.service";
 import { OcrService } from "@/ocr/ocr.service";
 import { GroundTruthGenerationService } from "./ground-truth-generation.service";
 import { GroundTruthJobDbService } from "./ground-truth-job-db.service";
@@ -102,6 +103,13 @@ const mockHitlDatasetService = {
   buildGroundTruth: jest.fn(),
 };
 
+const mockPdfNormalizationService = {
+  validateForUpload: jest.fn().mockResolvedValue(undefined),
+  normalizeToPdf: jest
+    .fn()
+    .mockImplementation((buf: Buffer) => Promise.resolve(Buffer.from(buf))),
+};
+
 const sampleManifest = {
   schemaVersion: "1.0",
   samples: [
@@ -148,6 +156,10 @@ describe("GroundTruthGenerationService", () => {
           provide: HitlDatasetService,
           useValue: mockHitlDatasetService,
         },
+        {
+          provide: PdfNormalizationService,
+          useValue: mockPdfNormalizationService,
+        },
         {
           provide: BLOB_STORAGE,
           useValue: mockBlobStorage,

apps/backend-services/src/benchmark/ground-truth-generation.service.ts

@@ -17,6 +17,11 @@ import {
   BlobStorageInterface,
 } from "@/blob-storage/blob-storage.interface";
 import { DocumentService } from "@/document/document.service";
+import { extensionForOriginalBlob } from "@/document/original-blob-key.util";
+import {
+  PdfNormalizationError,
+  PdfNormalizationService,
+} from "@/document/pdf-normalization.service";
 import { ExtractedFields } from "@/ocr/azure-types";
 import { OcrService } from "@/ocr/ocr.service";
 import {
@@ -54,6 +59,7 @@ export class GroundTruthGenerationService {
     private readonly documentService: DocumentService,
     private readonly ocrService: OcrService,
     private readonly hitlDatasetService: HitlDatasetService,
+    private readonly pdfNormalization: PdfNormalizationService,
     @Inject(BLOB_STORAGE) private readonly blobStorage: BlobStorageInterface,
   ) {}
 
@@ -233,7 +239,10 @@ export class GroundTruthGenerationService {
         ? "image"
         : "pdf";
       const originalFilename = path.basename(inputFile.path);
-      const ext = path.extname(originalFilename);
+      const originalExtension = extensionForOriginalBlob(
+        originalFilename,
+        fileType,
+      );
 
       // Read modelId from workflow config ctx defaults
       const workflow = await this.groundTruthJobDbService.findWorkflowConfig(
@@ -246,19 +255,74 @@ export class GroundTruthGenerationService {
         (workflowConfig?.ctx?.modelId?.defaultValue as string) ||
         "prebuilt-layout";
 
-      // Create document record
       const documentId = crypto.randomUUID();
-      const docBlobKey = `documents/${documentId}/original${ext}`;
+      const docBlobKey = `documents/${documentId}/original.${originalExtension}`;
+
+      await this.pdfNormalization.validateForUpload(fileBuffer, fileType);
 
-      // Write file to document storage
       await this.blobStorage.write(docBlobKey, fileBuffer);
 
+      const normalizedKey = `documents/${documentId}/normalized.pdf`;
+      try {
+        const pdfBuffer = await this.pdfNormalization.normalizeToPdf(
+          fileBuffer,
+          fileType,
+        );
+        await this.blobStorage.write(normalizedKey, pdfBuffer);
+      } catch (e) {
+        if (e instanceof BadRequestException) {
+          throw e;
+        }
+        if (!(e instanceof PdfNormalizationError)) {
+          this.logger.warn(
+            `Ground truth job ${jobId}: unexpected normalization error: ${
+              e instanceof Error ? e.message : String(e)
+            }`,
+          );
+        }
+        const errorMessage =
+          e instanceof PdfNormalizationError
+            ? e.message
+            : "Document could not be converted to PDF.";
+        const failedDoc = {
+          id: documentId,
+          title: job.sampleId,
+          original_filename: originalFilename,
+          file_path: docBlobKey,
+          normalized_file_path: null as string | null,
+          file_type: fileType,
+          file_size: fileBuffer.length,
+          metadata: {
+            source: "ground-truth-generation",
+            datasetId,
+            datasetVersionId: versionId,
+            sampleId: job.sampleId,
+          } as Prisma.JsonValue,
+          source: "ground-truth-generation",
+          status: DocumentStatus.conversion_failed,
+          apim_request_id: null,
+          workflow_id: null,
+          workflow_config_id: job.workflowConfigId,
+          workflow_execution_id: null,
+          model_id: modelId,
+          group_id: groupId,
+        };
+        await this.documentService.createDocument(failedDoc);
+        await this.groundTruthJobDbService.updateJob(jobId, {
+          documentId,
+          status: GroundTruthJobStatus.failed,
+          error: errorMessage,
+        });
+        return;
+      }
+
       // Create document in DB
       const documentData = {
         id: documentId,
         title: job.sampleId,
         original_filename: originalFilename,
         file_path: docBlobKey,
+        normalized_file_path: normalizedKey,
         file_type: fileType,
         file_size: fileBuffer.length,
         metadata: {

apps/backend-services/src/benchmark/hitl-dataset.service.spec.ts

@@ -83,6 +83,7 @@ describe("HitlDatasetService", () => {
       id: "doc-1",
       original_filename: "invoice-001.pdf",
       file_path: "documents/doc-1/original.pdf",
+      normalized_file_path: "documents/doc-1/normalized.pdf",
       file_type: "pdf",
       status: "completed_ocr",
       ocr_result: { keyValuePairs: mockOcrFields },
@@ -92,6 +93,7 @@ describe("HitlDatasetService", () => {
       id: "doc-2",
       original_filename: "invoice-002.pdf",
       file_path: "documents/doc-2/original.pdf",
+      normalized_file_path: "documents/doc-2/normalized.pdf",
       file_type: "pdf",
       status: "completed_ocr",
       ocr_result: { keyValuePairs: mockOcrFields },

apps/backend-services/src/benchmark/hitl-dataset.service.ts

@@ -33,6 +33,7 @@ interface DocumentWithReview {
   id: string;
   original_filename: string;
   file_path: string;
+  normalized_file_path: string | null;
   file_type: string;
   ocr_result: {
     keyValuePairs: unknown;
@@ -345,13 +346,20 @@ export class HitlDatasetService {
     }
     usedSampleIds.add(sampleId);
 
-    // Copy the original document file
-    const inputFilename = `${sampleId}${ext}`;
+    if (!doc.normalized_file_path) {
+      throw new Error(
+        "Document has no normalized PDF; cannot export to dataset",
+      );
+    }
+
+    const inputFilename = `${sampleId}.pdf`;
     const inputRelativePath = `inputs/${inputFilename}`;
     const inputBlobKey = `${storagePrefix}/${inputRelativePath}`;
 
-    const originalFileBuffer = await this.blobStorage.read(doc.file_path);
-    await this.blobStorage.write(inputBlobKey, originalFileBuffer);
+    const normalizedPdfBuffer = await this.blobStorage.read(
+      doc.normalized_file_path,
+    );
+    await this.blobStorage.write(inputBlobKey, normalizedPdfBuffer);
 
     // Build ground truth as flat key-value pairs (same format as uploaded
     // ground truth and as predictions produced by extractPredictionFromCtx
@@ -369,8 +377,7 @@ export class HitlDatasetService {
       Buffer.from(JSON.stringify(groundTruth, null, 2)),
     );
 
-    // Determine MIME type
-    const mimeType = this.getMimeType(ext);
+    const mimeType = "application/pdf";
 
     return {
       id: sampleId,
@@ -445,19 +452,6 @@ export class HitlDatasetService {
 
     return groundTruth;
   }
-
-  private getMimeType(ext: string): string {
-    const mimeTypes: Record<string, string> = {
-      ".pdf": "application/pdf",
-      ".png": "image/png",
-      ".jpg": "image/jpeg",
-      ".jpeg": "image/jpeg",
-      ".tif": "image/tiff",
-      ".tiff": "image/tiff",
-      ".bmp": "image/bmp",
-    };
-    return mimeTypes[ext.toLowerCase()] ?? "application/octet-stream";
-  }
 }
 
 /**

apps/backend-services/src/document/document-db.service.spec.ts

@@ -33,6 +33,7 @@ const makeDocument = (overrides: Partial<DocumentData> = {}): DocumentData => ({
   title: "Test Document",
   original_filename: "test.pdf",
   file_path: "documents/doc-1/original.pdf",
+  normalized_file_path: "documents/doc-1/normalized.pdf",
   file_type: "pdf",
   file_size: 1024,
   metadata: {},
@@ -72,6 +73,7 @@ describe("DocumentDbService", () => {
         title: doc.title,
         original_filename: doc.original_filename,
         file_path: doc.file_path,
+        normalized_file_path: doc.normalized_file_path,
         file_type: doc.file_type,
         file_size: doc.file_size,
         metadata: doc.metadata,

apps/backend-services/src/document/document-db.service.ts

@@ -45,6 +45,7 @@ export class DocumentDbService {
           title: data.title,
           original_filename: data.original_filename,
           file_path: data.file_path,
+          normalized_file_path: data.normalized_file_path ?? null,
           file_type: data.file_type,
           file_size: data.file_size,
           metadata: data.metadata,

apps/backend-services/src/document/document.controller.ts

@@ -26,8 +26,10 @@ import {
   ApiOkResponse,
   ApiOperation,
   ApiParam,
+  ApiProduces,
   ApiQuery,
   ApiTags,
+  ApiUnauthorizedResponse,
 } from "@nestjs/swagger";
 import { Request, Response } from "express";
 import { AuditService } from "@/audit/audit.service";
@@ -47,6 +49,7 @@ import { type DocumentData, DocumentService } from "./document.service";
 import { ApproveDocumentDto } from "./dto/approve-document.dto";
 import { OcrResultResponseDto } from "./dto/ocr-result-response.dto";
 import { UpdateDocumentDto } from "./dto/update-document.dto";
+import { getContentTypeFromFilename } from "./mime-from-filename";
 
 @ApiTags("Documents")
 @Controller("api/documents")
@@ -388,15 +391,81 @@ export class DocumentController {
     }
   }
 
+  @Get("/:documentId/view")
+  @HttpCode(HttpStatus.OK)
+  @Identity({ allowApiKey: true })
+  @ApiOperation({
+    summary: "View normalized document as PDF",
+    description:
+      "Streams the normalized PDF used for in-app display and OCR. Always application/pdf.",
+  })
+  @ApiParam({ name: "documentId", description: "Document ID" })
+  @ApiProduces("application/pdf")
+  @ApiOkResponse({
+    description: "Normalized PDF bytes (Content-Type: application/pdf)",
+  })
+  @ApiNotFoundResponse({
+    description: "Document not found or normalized PDF unavailable",
+  })
+  @ApiUnauthorizedResponse({ description: "Not authenticated" })
+  @ApiForbiddenResponse({ description: "Access denied: not a group member" })
+  async viewDocument(
+    @Param("documentId") documentId: string,
+    @Res() res: Response,
+    @Req() req: Request,
+  ): Promise<void> {
+    this.logger.debug(`=== DocumentController.viewDocument ===`);
+    this.logger.debug(`Document ID: ${documentId}`);
+
+    const document = await this.documentService.findDocument(documentId);
+    if (!document) {
+      throw new NotFoundException(`Document not found: ${documentId}`);
+    }
+
+    identityCanAccessGroup(req.resolvedIdentity, document.group_id);
+
+    if (!document.normalized_file_path) {
+      throw new NotFoundException(
+        `Normalized PDF is not available for document: ${documentId}`,
+      );
+    }
+
+    await this.auditService.recordEvent({
+      event_type: "document_accessed",
+      resource_type: "document",
+      resource_id: documentId,
+      actor_id: req.resolvedIdentity.actorId,
+      document_id: documentId,
+      group_id: document.group_id ?? undefined,
+      payload: { action: "view" },
+    });
+
+    const fileBuffer = await this.blobStorage.read(
+      document.normalized_file_path,
+    );
+
+    res.setHeader("Content-Type", "application/pdf");
+    res.setHeader("Content-Disposition", 'inline; filename="document.pdf"');
+    res.setHeader("Content-Length", fileBuffer.length);
+    res.send(fileBuffer);
+
+    this.logger.debug("=== DocumentController.viewDocument completed ===");
+  }
+
   @Get("/:documentId/download")
   @HttpCode(HttpStatus.OK)
-  @Identity()
-  @ApiOperation({ summary: "Download a document file by ID" })
+  @Identity({ allowApiKey: true })
+  @ApiOperation({
+    summary: "Download original uploaded file",
+    description:
+      "Serves the stored original blob (not the normalized PDF). Filename and type follow original_filename.",
+  })
   @ApiParam({ name: "documentId", description: "Document ID" })
   @ApiOkResponse({
-    description: "Returns the document file buffer as a download",
+    description: "Returns the original file buffer",
   })
   @ApiNotFoundResponse({ description: "Document not found or file missing" })
+  @ApiUnauthorizedResponse({ description: "Not authenticated" })
   @ApiForbiddenResponse({ description: "Access denied: not a group member" })
   async downloadDocument(
     @Param("documentId") documentId: string,
@@ -428,14 +497,8 @@ export class DocumentController {
       // Read file from blob storage using the blob key
       const fileBuffer = await this.blobStorage.read(document.file_path);
 
-      // Set appropriate headers
       const fileName = document.original_filename || `document-${documentId}`;
-      const mimeType =
-        document.file_type === "pdf"
-          ? "application/pdf"
-          : document.file_type === "image"
-            ? "image/jpeg"
-            : "application/octet-stream";
+      const mimeType = getContentTypeFromFilename(fileName);
 
       res.setHeader("Content-Type", mimeType);
       res.setHeader("Content-Disposition", `inline; filename="${fileName}"`);

apps/backend-services/src/document/document.module.ts

@@ -4,11 +4,12 @@ import { TemporalModule } from "../temporal/temporal.module";
 import { DocumentController } from "./document.controller";
 import { DocumentService } from "./document.service";
 import { DocumentDbService } from "./document-db.service";
+import { PdfNormalizationService } from "./pdf-normalization.service";
 
 @Module({
   imports: [BlobStorageModule, TemporalModule],
-  providers: [DocumentDbService, DocumentService],
+  providers: [DocumentDbService, DocumentService, PdfNormalizationService],
   controllers: [DocumentController],
-  exports: [DocumentService],
+  exports: [DocumentService, PdfNormalizationService],
 })
 export class DocumentModule {}