Enhance DocumentProcessorService with Perplexity integration for simplified explanations

- Added PerplexityService to backend/src/document-processor/document-processor.module.ts for generating simplified explanations of medical documents.
- Updated DocumentProcessorService in backend/src/document-processor/services/document-processor.service.ts to include logic for generating simplified explanations during document processing.
- Modified DocumentProcessorController in backend/src/document-processor/controllers/document-processor.controller.ts to return simplified explanations alongside analysis results.
- Enhanced unit tests in backend/src/document-processor/services/document-processor.service.spec.ts to validate the integration of PerplexityService and the new simplified explanation feature.

Author: adamrefaey

backend/src/document-processor/controllers/document-processor.controller.ts

@@ -81,11 +81,12 @@ export class DocumentProcessorController {
             timestamp: new Date().toISOString(),
             rawExtractedText: result.extractedText,
             rawAnalysis: result.analysis,
+            rawSimplifiedExplanation: result.simplifiedExplanation,
           },
         };
       }
 
-      return result.analysis;
+      return { analysis: result.analysis, simplifiedExplanation: result.simplifiedExplanation };
     } catch (error: unknown) {
       this.logger.error(
         `Error processing document: ${error instanceof Error ? error.message : 'Unknown error'}`,

backend/src/document-processor/document-processor.module.ts

@@ -4,11 +4,19 @@ import { ConfigModule } from '@nestjs/config';
 import { AwsTextractService } from './services/aws-textract.service';
 import { AwsBedrockService } from './services/aws-bedrock.service';
 import { DocumentProcessorController } from './controllers/document-processor.controller';
+import { PerplexityService } from '../services/perplexity.service';
+import { AwsSecretsService } from '../services/aws-secrets.service';
 
 @Module({
   imports: [ConfigModule],
   controllers: [DocumentProcessorController],
-  providers: [DocumentProcessorService, AwsTextractService, AwsBedrockService],
+  providers: [
+    DocumentProcessorService,
+    AwsTextractService,
+    AwsBedrockService,
+    PerplexityService,
+    AwsSecretsService,
+  ],
   exports: [DocumentProcessorService, AwsTextractService, AwsBedrockService],
 })
 export class DocumentProcessorModule {}

backend/src/document-processor/services/document-processor.service.spec.ts

@@ -2,6 +2,7 @@ import { BadRequestException } from '@nestjs/common';
 import { DocumentProcessorService } from './document-processor.service';
 import { AwsTextractService } from './aws-textract.service';
 import { AwsBedrockService } from './aws-bedrock.service';
+import { PerplexityService } from '../../services/perplexity.service';
 import { describe, it, expect, vi } from 'vitest';
 
 // Mock the crypto module
@@ -44,18 +45,23 @@ describe('DocumentProcessorService', () => {
         },
       };
 
+      const simplifiedExplanation = 'This is a simple explanation of the medical document.';
+
       // Create a new test-specific instance with proper mocking
       const testTextractService = { extractText: vi.fn() };
       const testBedrockService = { analyzeMedicalDocument: vi.fn() };
+      const testPerplexityService = { explainMedicalText: vi.fn() };
 
       // Set up mocks
       testTextractService.extractText.mockResolvedValue(extractedTextResult);
       testBedrockService.analyzeMedicalDocument.mockResolvedValue(medicalAnalysis);
+      testPerplexityService.explainMedicalText.mockResolvedValue(simplifiedExplanation);
 
       // Create a fresh service instance with our mocks
       const testService = new DocumentProcessorService(
         testTextractService as unknown as AwsTextractService,
         testBedrockService as unknown as AwsBedrockService,
+        testPerplexityService as unknown as PerplexityService,
       );
 
       // Act
@@ -67,9 +73,13 @@ describe('DocumentProcessorService', () => {
         extractedTextResult.rawText,
         userId,
       );
+      expect(testPerplexityService.explainMedicalText).toHaveBeenCalledWith(
+        extractedTextResult.rawText,
+      );
       expect(result).toEqual({
         extractedText: extractedTextResult,
         analysis: medicalAnalysis,
+        simplifiedExplanation,
         processingMetadata: expect.objectContaining({
           fileType,
           fileSize: fileBuffer.length,
@@ -86,6 +96,7 @@ describe('DocumentProcessorService', () => {
       // Create test-specific service with proper mocking
       const testTextractService = { extractText: vi.fn() };
       const testBedrockService = { analyzeMedicalDocument: vi.fn() };
+      const testPerplexityService = { explainMedicalText: vi.fn() };
 
       // Make the mock reject with an error
       testTextractService.extractText.mockRejectedValue(new Error('Failed to extract text'));
@@ -94,6 +105,7 @@ describe('DocumentProcessorService', () => {
       const testService = new DocumentProcessorService(
         testTextractService as unknown as AwsTextractService,
         testBedrockService as unknown as AwsBedrockService,
+        testPerplexityService as unknown as PerplexityService,
       );
 
       // Act & Assert
@@ -115,11 +127,13 @@ describe('DocumentProcessorService', () => {
       // Create test-specific service with proper mocking
       const testTextractService = { extractText: vi.fn() };
       const testBedrockService = { analyzeMedicalDocument: vi.fn() };
+      const testPerplexityService = { explainMedicalText: vi.fn() };
 
       // Create a fresh service instance with our mocks
       const testService = new DocumentProcessorService(
         testTextractService as unknown as AwsTextractService,
         testBedrockService as unknown as AwsBedrockService,
+        testPerplexityService as unknown as PerplexityService,
       );
 
       // Mock the processDocument method on our test service
@@ -142,6 +156,7 @@ describe('DocumentProcessorService', () => {
             missingInformation: [],
           },
         },
+        simplifiedExplanation: 'Simple explanation for document 1',
         processingMetadata: {
           processingTimeMs: 100,
           fileType: 'application/pdf',
@@ -166,6 +181,7 @@ describe('DocumentProcessorService', () => {
             missingInformation: [],
           },
         },
+        simplifiedExplanation: 'Simple explanation for document 2',
         processingMetadata: {
           processingTimeMs: 100,
           fileType: 'image/jpeg',
@@ -207,6 +223,7 @@ describe('DocumentProcessorService', () => {
       const testService = new DocumentProcessorService(
         {} as AwsTextractService,
         {} as AwsBedrockService,
+        {} as PerplexityService,
       );
 
       // Create a test implementation that checks for empty array

backend/src/document-processor/services/document-processor.service.ts

@@ -2,13 +2,15 @@ import { Injectable, Logger, BadRequestException } from '@nestjs/common';
 import { createHash } from 'crypto';
 import { AwsTextractService, ExtractedTextResult } from './aws-textract.service';
 import { AwsBedrockService, MedicalDocumentAnalysis } from './aws-bedrock.service';
+import { PerplexityService } from '../../services/perplexity.service';
 
 /**
  * Result interface for processed medical documents
  */
 export interface ProcessedDocumentResult {
   extractedText: ExtractedTextResult;
   analysis: MedicalDocumentAnalysis;
+  simplifiedExplanation?: string;
   processingMetadata: {
     processingTimeMs: number;
     fileType: string;
@@ -27,14 +29,15 @@ export class DocumentProcessorService {
   constructor(
     private readonly textractService: AwsTextractService,
     private readonly bedrockService: AwsBedrockService,
+    private readonly perplexityService: PerplexityService,
   ) {}
 
   /**
    * Process a medical document by extracting text and performing analysis
    * @param fileBuffer The file buffer containing the image or PDF
    * @param fileType The MIME type of the file (e.g., 'image/jpeg', 'application/pdf')
    * @param userId The authenticated user's ID for rate limiting
-   * @returns Processed document result with extracted text and analysis
+   * @returns Processed document result with extracted text, analysis, and simplified explanation
    */
   async processDocument(
     fileBuffer: Buffer,
@@ -64,19 +67,40 @@ export class DocumentProcessorService {
         userId,
       );
 
+      // Step 3: Generate simplified explanation using Perplexity
+      let simplifiedExplanation: string | undefined;
+
+      try {
+        if (analysis.metadata.isMedicalReport && extractedText.rawText) {
+          this.logger.log('Generating simplified explanation');
+          simplifiedExplanation = await this.perplexityService.explainMedicalText(
+            extractedText.rawText,
+          );
+          this.logger.log('Simplified explanation generated successfully');
+        }
+      } catch (explanationError) {
+        this.logger.error('Error generating simplified explanation', {
+          error: explanationError instanceof Error ? explanationError.message : 'Unknown error',
+        });
+        // We don't want to fail the entire process if explanation fails
+        simplifiedExplanation = undefined;
+      }
+
       const processingTime = Date.now() - startTime;
 
       this.logger.log(`Document processing completed in ${processingTime}ms`, {
         isMedicalReport: analysis.metadata.isMedicalReport,
         confidence: analysis.metadata.confidence,
         keyTermCount: analysis.keyMedicalTerms.length,
         labValueCount: analysis.labValues.length,
+        hasExplanation: !!simplifiedExplanation,
       });
 
       // Return combined result
       return {
         extractedText,
         analysis,
+        simplifiedExplanation,
         processingMetadata: {
           processingTimeMs: processingTime,
           fileType,
@@ -149,6 +173,7 @@ export class DocumentProcessorService {
               missingInformation: ['Document processing failed'],
             },
           },
+          simplifiedExplanation: undefined,
           processingMetadata: {
             processingTimeMs: 0,
             fileType: doc.type,