07. Report Pipeline

07. Report Pipeline

Reports are generated in src/components/reports/ReportGenerator.tsx and rendered to PDF by src/lib/pdf/. A report can be a preview (editable draft) or a final report (locks the session).

How a report is produced

Session data (images, detections, classifications)
        │
        ▼
1. LOCAL CLINICAL COMMENT   ── always ──►  The active clinical guideline classifies
   classifyDiabeticRetinopathy()           the session (severity, treatment, urgency)
   formatClassificationText()              and produces the clinical comment.
        │
        ▼
2. OPTIONAL LLM POLISH      ── if a local LLM is active and the clinician
   processConclusion()         did not tick "generate without AI assistant" ──►
        │                      the local LLM (llama.cpp) rewrites the comment as
        │                      clean prose, WITHOUT changing severity or findings.
        │                      If no LLM is active, or it fails, the raw local
        │                      comment is used unchanged.
        ▼
3. PDF RENDER               generateSessionReport() → jsPDF
        │
        ▼
4. PERSIST                  saved to the `reports` table (preview or final)

Key design rule: the guideline decides, the LLM only writes

This mirrors the separation of roles described in the README:

• Classification is deterministic and local. Severity, treatments, urgency and follow-up come from the pluggable clinical-guideline engine — never from the LLM.
• The LLM is an optional prose polisher. It runs in-process via llama.cpp (no network) and only improves readability. The report is fully functional with no LLM at all.
• A checkbox "Generate without AI assistant" lets the clinician skip the LLM and use the raw guideline text.

processConclusion() lives in src/lib/api/report-ai-service.ts (formerly the remote token-service.ts). It checks whether a local LLM is active (llmActiveId) and, if so, calls llmGenerate with a system prompt that explicitly forbids inventing findings or changing severity grades.

Report contents

• Configurable sections: patient data, image gallery, statistics, clinical conclusion.
• Customizable gallery: original vs. annotated images, with/without quadrants and measurements.
• Evaluator notes, professional signature, editable conclusion.
• Patient fields (name, age, ID) can be hidden for privacy.
• Final reports lock the session and download the PDF automatically.