HealthReportAnalyzer

A comprehensive lab report analyzer that extracts biomarkers from plain-text lab reports, normalizes values, compares against clinically-validated reference ranges, and generates patient-friendly summaries with risk flag detection and multi-report trend tracking.

Overview

HealthReportAnalyzer helps users understand their lab results by:

1. Parsing lab report text to extract biomarker names, values, and units
2. Classifying values against reference ranges with age/gender adjustments
3. Color-coding results for quick visual assessment
4. Generating plain-English summaries of abnormal findings
5. Detecting risk combinations (e.g., high glucose + high HbA1c = diabetes risk)
6. Tracking trends across multiple reports over time with interactive charts

Features

Biomarker Extraction

• Supports 150+ biomarker name aliases (CBC, lipid panel, liver panel, kidney panel, thyroid, vitamins, electrolytes, iron studies, inflammatory markers)
• Parses multiple lab report formats:
  • Hemoglobin: 14.5 g/dL
  • Glucose (Fasting) 110 mg/dL 70-100
  • TSH = 2.5 mIU/L
• Automatic deduplication by canonical biomarker name

Reference Range Engine

• 50+ biomarkers with clinically-validated reference ranges
• Age and gender-adjusted ranges
• Multi-level classification:
  • Normal (green)
  • Borderline Low/High (yellow)
  • Low/High (red)
  • Critical Low/High (dark red)

Risk Flag Detection

• Diabetes Risk (elevated glucose + HbA1c)
• Cardiovascular Risk (lipid panel abnormalities)
• Kidney Concern (creatinine + BUN + eGFR)
• Liver Concern (ALT + AST + bilirubin)
• Thyroid Imbalance (TSH abnormalities)
• Anemia Risk (low hemoglobin + CBC changes)
• Metabolic Syndrome Indicators
• Vitamin D Deficiency
• Electrolyte Imbalance
• Iron Overload Risk

Multi-Report Trend Analysis

• Track biomarker changes across multiple reports
• Chart.js line charts with reference range overlays
• Percentage change and trend direction indicators
• Compare reports side by side

Patient-Friendly Summaries

• Plain English explanations of each abnormal result
• Overall health assessment (Normal, Attention, Concern, Critical)
• Actionable context for each biomarker

Tech Stack

Component	Technology
Backend	FastAPI (Python)
Database	SQLite + SQLAlchemy
Frontend	React-style SPA (Vanilla JS)
Charts	Chart.js
Testing	pytest + httpx
Deployment	Docker + docker-compose

Quick Start

Prerequisites

• Python 3.10+
• pip

Option 1: Quick Start Script

chmod +x start.sh
./start.sh

Option 2: Manual Setup

python -m venv venv
source venv/bin/activate      # Linux/Mac
# venv\Scripts\activate       # Windows
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 8027 --reload

Option 3: Docker

docker-compose up --build

The application will be available at http://localhost:8027

API Endpoints

Reports

Method	Endpoint	Description
POST	/api/reports/upload	Upload report as pasted text
POST	/api/reports/upload-file	Upload report as .txt file
POST	/api/reports/analyze	Analyze a pending report
GET	/api/reports	List all reports
GET	/api/reports/{id}	Get report with biomarkers
GET	/api/reports/{id}/summary	Get report summary
GET	/api/reports/{id}/export	Export report as JSON
DELETE	/api/reports/{id}	Delete a report
GET	/api/reports/compare/trends	Compare biomarker trends

Patients

Method	Endpoint	Description
POST	/api/patients	Create patient profile
GET	/api/patients	List patient profiles
GET	/api/patients/{id}	Get patient with reports

Other

Method	Endpoint	Description
GET	/api/health	Health check
GET	/api/reference-ranges	List reference ranges
POST	/api/comparisons	Save a comparison
GET	/api/comparisons	List saved comparisons

Frontend Routes

Route	View	Description
#/	Dashboard	Overview stats and recent reports
#/upload	Upload	Paste text or upload .txt file
#/report/:id	Report Detail	Biomarker table with status badges, risk flags, summary
#/history	History	All reports list
#/compare	Compare	Multi-report trend analysis with charts

Usage Guide

1. Upload a Report

Navigate to the Upload page and either:

• Paste text: Copy your lab report text and paste it into the text area
• Upload file: Drag & drop or browse for a .txt file

2. View Results

After analysis, you will see:

• Overall assessment badge (Normal/Attention/Concern/Critical)
• Risk flags highlighting concerning combinations
• Biomarker table with color-coded status badges
• Click "Details" on any biomarker for a plain-English explanation
• Filter biomarkers by category using the pills

3. Compare Reports

Upload multiple reports over time, then use the Compare view to:

• Select which reports to compare
• View trend charts for individual biomarkers
• See percentage changes and trend directions

4. Export

Click "Export JSON" on any report to download the full analysis data.

Testing

Run the test suite:

python -m pytest tests/ -v --tb=short

With coverage:

python -m pytest tests/ -v --cov=. --cov-report=term-missing

Project Structure

health-report-analyzer/
|-- app.py                    # FastAPI entry point
|-- config.py                 # Configuration
|-- requirements.txt
|-- README.md
|-- Dockerfile
|-- docker-compose.yml
|-- start.sh
|-- LICENSE
|-- .gitignore
|-- .github/workflows/ci.yml
|-- models/
|   |-- __init__.py
|   |-- database.py           # SQLAlchemy engine/session
|   |-- schemas.py            # ORM models
|-- routes/
|   |-- __init__.py
|   |-- api.py                # REST API endpoints
|   |-- views.py              # SPA serving
|-- services/
|   |-- __init__.py
|   |-- report_parser.py      # Biomarker text extraction
|   |-- analyzer.py           # Classification, risk flags, summaries
|-- frontend/
|   |-- index.html
|   |-- static/css/app.css
|   |-- static/js/app.js
|-- tests/
|   |-- conftest.py
|   |-- test_api.py
|   |-- test_models.py
|   |-- test_services.py
|   |-- test_parser.py
|-- seed_data/
    |-- data.json             # Sample reports
    |-- reference_ranges.json # 50+ biomarker reference ranges

Data Models

LabReport

Stores the uploaded lab report text and analysis results.

Biomarker

Individual biomarker extracted from a report with classification data.

ReferenceRange

Clinically-validated reference ranges with age/gender segmentation.

PatientProfile

Optional patient information for personalised reference ranges.

ReportComparison

Saved comparison data between multiple reports.

Configuration

Environment variables:

Variable	Default	Description
HRA_PORT	8027	Server port
HRA_DEBUG	false	Debug mode
DATABASE_URL	sqlite:///...	Database URL
SECRET_KEY	(dev key)	Application secret

Disclaimer

This application is for informational purposes only and does not constitute medical advice. Always consult with a qualified healthcare professional for interpretation of lab results and medical decisions.

License

MIT License. See LICENSE for details.