🩺 MedClarify AI

Upload a medical lab report. Get instant, plain-language results.

MedClarify AI extracts text from lab reports (PDF or image), parses patient details and test results, evaluates each result against clinical reference ranges, and delivers a structured health summary — all locally, no third-party AI service involved.

Features

	Feature	Details
📄	Multi-format Upload	Accepts PDF, PNG, JPG, JPEG lab reports
🔍	Smart Text Extraction	Native PDF text extraction with Tesseract OCR fallback for scanned/image reports
🧹	Text Cleaning	Removes duplicate lines, fixes OCR noise, merges wrapped lines
👤	Patient Info Parsing	Detects name, age, gender, and report date using regex heuristics
🧬	Lab Test Parsing	Extracts test name, value, unit, and reference range with a confidence score per test
📊	Reference Range Evaluation	Flags results as `NORMAL`, `HIGH`, `LOW`, or `CRITICAL` — age and gender adjusted
🧠	Knowledge Engine	Plain-language clinical interpretation for every abnormal finding
📝	Auto Summary	Generates a concise health summary with an overall extraction confidence score
⚠️	Extraction Warnings	Surfaces low-confidence extractions and missing patient fields
📈	Charts & Metrics	Visual representation of lab results in the report viewer
📥	PDF Export	Download the full analysis as a PDF directly from the browser

Tech Stack

Backend

Technology	Purpose
Python 3.11+	Core language
FastAPI	REST API framework
Uvicorn	ASGI server
pypdf	Native PDF text extraction
Tesseract + pytesseract	OCR engine for scanned documents
pdf2image + Pillow	Converts PDF pages to images for OCR
Pydantic / pydantic-settings	Settings management and validation
python-dotenv	`.env` file loading

Frontend

Technology	Purpose
React 18 + TypeScript	UI framework
Vite	Dev server and build tool
TailwindCSS	Utility-first styling
Radix UI	Accessible headless UI primitives
Framer Motion	Animations and transitions
Recharts	Data visualisation (charts)
Zustand	Client-side state management
React Router v6	Client-side routing
Axios	HTTP client with upload progress tracking
jsPDF	In-browser PDF export
TanStack Query	Server-state and async data management

Project Structure

MedClarify-AI/
│
├── backend/
│   ├── app/
│   │   ├── main.py                     # FastAPI app, CORS, router registration
│   │   ├── config.py                   # Pydantic settings — reads .env
│   │   ├── routes/
│   │   │   └── upload.py               # POST /api/upload — full analysis pipeline
│   │   ├── services/
│   │   │   ├── unified_extraction.py   # Chooses PDF vs OCR extraction path
│   │   │   ├── extraction_service.py   # Native PDF text extraction (pypdf)
│   │   │   ├── ocr_service.py          # Tesseract OCR wrapper
│   │   │   ├── reference_ranges.py     # Clinical range evaluation (HIGH/LOW/CRITICAL)
│   │   │   ├── knowledge_engine.py     # Plain-language interpretations for abnormals
│   │   │   ├── summary_engine.py       # Overall health summary generator
│   │   │   ├── parser/
│   │   │   │   ├── lab_parser.py       # Lab test extraction (regex + heuristics)
│   │   │   │   ├── patient_parser.py   # Patient demographic extraction
│   │   │   │   └── text_cleaner.py     # OCR noise removal and line deduplication
│   │   │   └── data/
│   │   │       ├── knowledge_base.json     # Clinical interpretation templates
│   │   │       └── reference_ranges.json   # Normal range definitions per test
│   │   └── utils/
│   │       └── file_utils.py           # PDF page-count helper
│   ├── tests/                          # Backend unit tests (pytest)
│   ├── requirements.txt
│   └── .env.example
│
├── frontend/
│   ├── src/
│   │   ├── main.tsx                    # React entry point
│   │   ├── App.tsx                     # Root component with RouterProvider
│   │   ├── pages/
│   │   │   ├── landing/
│   │   │   │   └── LandingPage.tsx     # Home page
│   │   │   └── reports/
│   │   │       ├── UploadPage.tsx      # File upload + analysis trigger
│   │   │       ├── ViewerPage.tsx      # Full report viewer
│   │   │       └── ReportsPage.tsx     # Reports listing page
│   │   ├── components/
│   │   │   ├── landing/                # Hero, Features, FAQ, HowItWorks, etc.
│   │   │   ├── report/                 # PatientCard, LabTable, AbnormalFindings,
│   │   │   │                           # ChartsSection, ExportActions, SummaryCard, etc.
│   │   │   └── ui/                     # Radix UI base components
│   │   ├── stores/
│   │   │   └── reportStore.ts          # Zustand store for report state
│   │   ├── lib/
│   │   │   └── api/
│   │   │       └── api.ts              # Axios API client (upload + error handling)
│   │   ├── layouts/                    # Page layout wrappers
│   │   ├── routes/                     # React Router route definitions
│   │   └── types/                      # TypeScript type definitions
│   ├── index.html
│   ├── package.json
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   └── tsconfig.json
│
├── .gitignore
└── README.md

Getting Started

Prerequisites

Tool	Version	Install
Python	3.11+	python.org
Node.js	18+	nodejs.org
Tesseract OCR	5.x	See below
Poppler	latest	Required by `pdf2image`

Ubuntu / Debian:

sudo apt update && sudo apt install -y tesseract-ocr poppler-utils

macOS (Homebrew):

brew install tesseract poppler

Backend Setup

# Clone the repo and enter the backend directory
cd MedClarify-AI/backend

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your values (see Environment Variables section below)

# Start the development server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API base: http://localhost:8000
Swagger UI (interactive docs): http://localhost:8000/docs

Frontend Setup

cd MedClarify-AI/frontend

# Install Node dependencies
npm install

# Create and configure frontend env file
# Create a .env file and set the backend URL:
echo "VITE_API_URL=http://localhost:8000" > .env

# Start the dev server
npm run dev

Frontend runs at http://localhost:5173 by default.

The backend must be running before you use the frontend — the upload page calls POST /api/upload.

Environment Variables

`backend/.env`

APP_NAME=MedClarify AI
APP_VERSION=1.0.0
ENVIRONMENT=development
ALLOWED_ORIGINS=http://localhost:5173

Variable	Description	Default
`APP_NAME`	Application name shown in API responses	`MedClarify AI`
`APP_VERSION`	Version string	`1.0.0`
`ENVIRONMENT`	`development` or `production`	`development`
`ALLOWED_ORIGINS`	Comma-separated allowed CORS origins	`http://localhost:3000`

`frontend/.env`

VITE_API_URL=http://localhost:8000

Variable	Description
`VITE_API_URL`	Base URL of the FastAPI backend

Never commit .env files with real values to version control.

API Reference

`GET /`

Health check.

{
  "status": "online",
  "service": "MedClarify AI",
  "version": "1.0.0"
}

`POST /api/upload`

Upload a medical report and receive a full analysis.

Request — multipart/form-data

Field	Type	Accepted formats
`file`	File	`.pdf`, `.png`, `.jpg`, `.jpeg`

Response 200 OK

{
  "success": true,
  "filename": "<uuid>.pdf",
  "original_name": "lab_report.pdf",
  "preview_text": "First 1000 characters of extracted text...",
  "character_count": 4523,
  "pages": 2,
  "parsed_data": {
    "patient": {
      "name": "John Doe",
      "age": "35",
      "gender": "Male",
      "report_date": "2026-07-15"
    },
    "laboratory_tests": [ ... ],
    "abnormal_tests": [ ... ],
    "interpretation": [ ... ],
    "summary": { ... },
    "confidence": 92,
    "warnings": [],
    "processing_metadata": {
      "extraction_method": "pdf_text",
      "ocr_pages": [],
      "processing_time_ms": 340
    }
  }
}

Error codes

Code	Cause
`400`	Empty file or unsupported file type
`500`	Server error during extraction or parsing

How It Works

User uploads file (PDF / PNG / JPG)
           │
           ▼
   ┌───────────────────┐
   │  File Validation  │  type + size check
   └────────┬──────────┘
            │
            ▼
   ┌────────────────────────┐
   │  Text Extraction       │  pypdf → Tesseract OCR fallback
   └────────┬───────────────┘
            │
            ▼
   ┌────────────────────────┐
   │  Text Cleaning         │  dedup, merge wrapped lines, fix OCR noise
   └────────┬───────────────┘
            │
            ▼
   ┌────────────────────────────────────┐
   │  Parsing                           │
   │  ├── Patient info (name/age/gender)│
   │  └── Lab tests (name/value/unit)   │
   └────────┬───────────────────────────┘
            │
            ▼
   ┌────────────────────────────────────┐
   │  Reference Range Evaluation        │  NORMAL / HIGH / LOW / CRITICAL
   └────────┬───────────────────────────┘
            │
            ▼
   ┌────────────────────────────────────┐
   │  Knowledge Engine                  │  plain-language interpretation
   └────────┬───────────────────────────┘
            │
            ▼
   ┌────────────────────────┐
   │  Summary Generation    │  overall summary + confidence score
   └────────┬───────────────┘
            │
            ▼
      JSON response → React frontend

Running Tests

The backend has a test suite under backend/tests/ covering extraction, OCR, reference ranges, summary engine, and the upload route.

cd backend
source .venv/bin/activate

# Run all tests
pytest tests/

# Run a specific test file
pytest tests/test_reference_ranges.py -v

_{MedClarify AI — Helping patients understand their health, one report at a time.}

Navigation Menu

Repository files navigation

🩺 MedClarify AI

Table of Contents

Features

Tech Stack

Backend

Frontend

Project Structure

Getting Started

Prerequisites

Backend Setup

Frontend Setup

Environment Variables

`backend/.env`

`frontend/.env`

API Reference

`GET /`

`POST /api/upload`

How It Works

Running Tests

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

🩺 MedClarify AI

Table of Contents

Features

Tech Stack

Backend

Frontend

Project Structure

Getting Started

Prerequisites

Backend Setup

Frontend Setup

Environment Variables

backend/.env

frontend/.env

API Reference

GET /

POST /api/upload

How It Works

Running Tests

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`backend/.env`

`frontend/.env`

`GET /`

`POST /api/upload`