Add integration guide for Report Generation API, detailing endpoints for generating full, markdown, and JSON reports. Update agent executor and triage routes to track tool executions and guidelines count for report generation, enhancing logging for better traceability. Ensure all tool executions are logged for report generation success.

REPORT_API_INTEGRATION.md

@@ -0,0 +1,60 @@
+# Report Generation API - Integration Guide
+
+## Tổng quan
+API tạo báo cáo tổng hợp đầy đủ từ conversation session, bao gồm tất cả thông tin từ tools (CV top 3, RAG guidelines, triage results, hospital suggestions) mà response message thường bỏ qua.
+
+## Endpoints
+
+### 1. Generate/Get Full Report
+```
+GET /api/reports/:session_id?type=full|summary|tools_only
+```
+
+**Response:**
+```json
+{
+  "session_id": "uuid",
+  "report_type": "full",
+  "generated_at": "2024-01-01T00:00:00Z",
+  "report": {
+    "report_content": { /* Full structured data */ },
+    "report_markdown": "# BÁO CÁO TỔNG HỢP..." 
+  }
+}
+```
+
+### 2. Get Markdown Only
+```
+GET /api/reports/:session_id/markdown
+```
+Trả về markdown report đã format sẵn, dễ hiển thị.
+
+### 3. Get JSON Only
+```
+GET /api/reports/:session_id/json
+```
+Trả về structured data (conversation timeline, tool executions, summary).
+
+## Cách sử dụng
+
+```javascript
+// Sau khi có session_id từ /api/health-check
+const sessionId = "abc-123-def";
+
+// Generate full report
+const response = await fetch(`/api/reports/${sessionId}?type=full`);
+const { report } = await response.json();
+
+// Hiển thị markdown
+console.log(report.report_markdown);
+
+// Hoặc parse structured data
+const { conversation_timeline, tool_executions, summary } = report.report_content;
+```
+
+## Lưu ý
+- Report được cache, gọi lại sẽ trả về cached version
+- `type=full`: Báo cáo đầy đủ (default)
+- `type=summary`: Chỉ tóm tắt
+- `type=tools_only`: Chỉ tool executions
+

src/agent/agent-executor.ts

@@ -369,6 +369,8 @@ Ví dụ format markdown NGẮN GỌN:
       logger.info(`[AGENT] Calling MCP RAG - searchGuidelines...`);
       const guidelines = await this.ragService.searchGuidelines(guidelineInput);
       logger.info(`[AGENT] Retrieved ${guidelines.length} guideline snippets from RAG`);
+      // Store guidelines count for report generation
+      (guidelineInput as any).guidelines_count = guidelines.length;
 
       // Step 4: Use LLM to synthesize final response
       logger.info('Step 4: Synthesizing final response with LLM...');
@@ -384,6 +386,9 @@ Ví dụ format markdown NGẮN GỌN:
         guidelines,
         conversationContext
       );
+      
+      // Attach guidelines count to result for report generation
+      (finalResult as any).guidelines_count = guidelines.length;
 
       // Step 5: Find best matching hospital if emergency/urgent and location provided
       // This tool is called LAST in the agent workflow
@@ -394,6 +399,7 @@ Ví dụ format markdown NGẮN GỌN:
 
       if ((triageResult.triage === 'emergency' || triageResult.triage === 'urgent') && location) {
         logger.info(`[AGENT] Step 5: Finding best matching hospital (emergency/urgent case)${condition ? ` for condition: ${condition}` : ''}...`);
+        logger.info('[REPORT] Hospital tool (MCP) will be executed for emergency/urgent case');
         try {
           const bestHospital = await this.mapsService.findBestMatchingHospital(
             location,
@@ -402,20 +408,24 @@ Ví dụ format markdown NGẮN GỌN:
           );
           if (bestHospital) {
             logger.info(`[AGENT] Found best matching hospital: ${bestHospital.name} (${bestHospital.distance_km}km away${bestHospital.specialty_score ? `, specialty match: ${bestHospital.specialty_score.toFixed(2)}` : ''})`);
+            logger.info(`[REPORT] ✓ Hospital tool (MCP) executed successfully: ${bestHospital.name}`);
             return {
               ...finalResult,
               nearest_clinic: bestHospital
             };
           } else {
             logger.warn('[AGENT] No hospital found nearby');
+            logger.info('[REPORT] Hospital tool (MCP) executed but no hospital found');
           }
         } catch (error) {
           logger.error({ error }, '[AGENT] Failed to find best matching hospital');
+          logger.error('[REPORT] Hospital tool (MCP) execution failed');
           // Continue without hospital info
         }
       } else if (location && this.shouldSuggestHospital(userText)) {
         // Also suggest hospital if user explicitly requests it
         logger.info(`[AGENT] Step 5: Finding best matching hospital (user requested)${condition ? ` for condition: ${condition}` : ''}...`);
+        logger.info('[REPORT] Hospital tool (MCP) will be executed (user explicitly requested)');
         try {
           const bestHospital = await this.mapsService.findBestMatchingHospital(
             location,
@@ -424,6 +434,7 @@ Ví dụ format markdown NGẮN GỌN:
           );
           if (bestHospital) {
             logger.info(`[AGENT] Found best matching hospital: ${bestHospital.name} (${bestHospital.distance_km}km away${bestHospital.specialty_score ? `, specialty match: ${bestHospital.specialty_score.toFixed(2)}` : ''})`);
+            logger.info(`[REPORT] ✓ Hospital tool (MCP) executed successfully: ${bestHospital.name}`);
             return {
               ...finalResult,
               nearest_clinic: bestHospital
@@ -431,6 +442,13 @@ Ví dụ format markdown NGẮN GỌN:
           }
         } catch (error) {
           logger.error({ error }, '[AGENT] Failed to find best matching hospital');
+          logger.error('[REPORT] Hospital tool (MCP) execution failed');
+        }
+      } else {
+        if (location) {
+          logger.info(`[REPORT] Hospital tool (MCP) skipped: triage_level=${triageResult.triage} (only called for emergency/urgent or explicit request)`);
+        } else {
+          logger.info('[REPORT] Hospital tool (MCP) skipped: no location provided');
         }
       }
 
@@ -500,6 +518,9 @@ Ví dụ format markdown NGẮN GỌN:
         guidelines,
         conversationContext
       );
+      
+      // Attach guidelines count to result for report generation
+      (finalResult as any).guidelines_count = guidelines.length;
 
       // Step 4: Find best matching hospital if emergency/urgent and location provided
       // This tool is called LAST in the agent workflow

src/routes/triage.route.ts

@@ -260,18 +260,27 @@ export async function triageRoutes(
         // Continue even if saving fails
       }
 
-      // Track tool executions (non-blocking)
+      // Track tool executions for Report Generation (non-blocking)
       try {
+        logger.info('[REPORT] Starting tool execution tracking for report generation...');
+        
         // Track CV execution if applicable
-        await ToolTrackingHelper.trackCVExecution(
-          toolTracker,
-          activeSessionId,
-          userMessage.id,
-          triageResult,
-          Math.floor(totalExecutionTime * 0.3) // Estimate 30% of time for CV
-        );
+        if (triageResult.cv_findings.model_used !== 'none') {
+          logger.info('[REPORT] Tracking CV tool execution...');
+          await ToolTrackingHelper.trackCVExecution(
+            toolTracker,
+            activeSessionId,
+            userMessage.id,
+            triageResult,
+            Math.floor(totalExecutionTime * 0.3) // Estimate 30% of time for CV
+          );
+          logger.info(`[REPORT] ✓ CV tool tracked: ${triageResult.cv_findings.model_used}`);
+        } else {
+          logger.info('[REPORT] CV tool not executed (no image or model_used=none)');
+        }
 
         // Track Triage Rules execution
+        logger.info('[REPORT] Tracking Triage Rules execution...');
         await ToolTrackingHelper.trackTriageRulesExecution(
           toolTracker,
           activeSessionId,
@@ -280,9 +289,11 @@ export async function triageRoutes(
           normalizedText || 'Image analysis',
           Math.floor(totalExecutionTime * 0.2) // Estimate 20% of time
         );
+        logger.info(`[REPORT] ✓ Triage Rules tracked: level=${triageResult.triage_level}`);
 
-        // Track RAG execution (estimate guidelines count from triage result)
-        const guidelinesCount = (triageResult as any).guidelines_count || 3; // Default estimate
+        // Track RAG execution - extract actual guidelines count from agent result
+        const guidelinesCount = (triageResult as any).guidelines_count || 3; // Captured from agent execution
+        logger.info('[REPORT] Tracking RAG/Guidelines execution...');
         await ToolTrackingHelper.trackRAGExecution(
           toolTracker,
           activeSessionId,
@@ -292,10 +303,12 @@ export async function triageRoutes(
           Math.floor(totalExecutionTime * 0.3), // Estimate 30% of time
           guidelinesCount
         );
+        logger.info(`[REPORT] ✓ RAG tool tracked: ${guidelinesCount} guidelines retrieved`);
 
-        // Track Maps execution if hospital was found
+        // Track Maps/Hospital execution if hospital was found
         const nearestClinic = (triageResult as any).nearest_clinic;
         if (nearestClinic) {
+          logger.info('[REPORT] Tracking Hospital/Maps tool execution...');
           const condition = triageResult.suspected_conditions?.[0]?.name;
           await ToolTrackingHelper.trackMapsExecution(
             toolTracker,
@@ -305,9 +318,18 @@ export async function triageRoutes(
             condition,
             Math.floor(totalExecutionTime * 0.2) // Estimate 20% of time
           );
+          logger.info(`[REPORT] ✓ Hospital tool tracked: ${nearestClinic.name} (${nearestClinic.distance_km}km)`);
+        } else {
+          if (location) {
+            logger.info(`[REPORT] Hospital tool not executed: triage_level=${triageResult.triage_level} (only called for emergency/urgent or explicit request)`);
+          } else {
+            logger.info('[REPORT] Hospital tool not executed: no location provided');
+          }
         }
+
+        logger.info('[REPORT] ✓ All tool executions tracked successfully for report generation');
       } catch (error) {
-        logger.error({ error }, 'Failed to track tool executions');
+        logger.error({ error }, '[REPORT] Failed to track tool executions');
         // Continue even if tracking fails
       }
 

src/services/tool-execution-tracker.service.ts

@@ -64,7 +64,12 @@ export class ToolExecutionTrackerService {
         logger.error({ error }, 'Failed to track tool execution');
         // Don't throw - tracking failure shouldn't break the workflow
       } else {
-        logger.debug(`Tracked tool execution: ${execution.tool_name} (order: ${execution.execution_order})`);
+        logger.info(`[REPORT] ✓ Tool execution saved to database: ${execution.tool_display_name} (${execution.tool_name}, order: ${execution.execution_order}, time: ${execution.execution_time_ms}ms)`);
+        logger.debug(`[REPORT] Tool execution data: ${JSON.stringify({
+          tool: execution.tool_name,
+          input: Object.keys(execution.input_data || {}),
+          output_keys: Object.keys(execution.output_data || {})
+        })}`);
       }
     } catch (error) {
       logger.error({ error }, 'Error tracking tool execution');