MedReport Agent - AI-Powered Medical Report Interpreter

MedReport Agent is a privacy-first, fully offline, and autonomous medical report analysis assistant built as a Hermes Agent workflow. It extracts raw text from uploaded lab reports (images or PDFs), parses clinical values, flags out-of-range deviations, and uses a local Qwen 2.5 1.5B Instruct GGUF model to synthesize bilingual (English & Urdu) summaries and patient-doctor questions.

---

Key Features

1. OCR & Document Ingestion (FR-01): Fully offline text extraction from PDF and images (PNG, JPG, TIFF) using EasyOCR and PyMuPDF.
2. Report Parsing (FR-02): Automatic test categorization (CBC, LFT, RFT, Lipid, Thyroid, Glucose panels) and value identification.
3. Clinical Check (FR-02 & FR-04): Dynamic reference range checking and severity evaluation (Normal, Mildly Abnormal, Significantly Abnormal, and Critical) with highlighted dashboard badges.
4. Agentic Pipeline (FR-07): Modeled as an autonomous, multi-stage workflow configured by medreport_skill.yaml, executing tools sequentially with a self-correction parser retry fallback.
5. Urdu Interpretation (FR-03): Instant tab toggle to view clinical explanations translated in native Urdu script.
6. Doctor Q&A Export (FR-05): Customized lists of questions derived from the user's specific out-of-range markers, downloadable as a .txt file.
7. Offline Privacy (NFR-02 & NFR-03): Entire stack runs locally on standard consumer hardware. Data never leaves the system.

---

Project Structure

MedReport/
├── backend/
│   ├── database.py         # Standard reference ranges, test mappings, and analysis logic
│   ├── ocr_processor.py    # Digital PDF text reader + EasyOCR page-rendering fallback
│   ├── llm_client.py       # Local Llama-cpp-python loader for Qwen GGUF model
│   ├── hermes_agent.py     # Skill yaml executor, log tracker, and self-correction engine
│   ├── main.py             # FastAPI backend server exposure
│   ├── requirements.txt    # Python library requirements
│   ├── Dockerfile          # Backend build config (GL libraries, python settings)
│   └── medreport_skill.yaml# Skill configuration (tool inventory, retries, language settings)
├── frontend/
│   ├── src/
│   │   ├── App.tsx         # Responsive React dashboard, state manager, and UI
│   │   ├── index.css       # Premium glassmorphism design, variables, and typography
│   │   └── main.tsx        # Vite initialization
│   ├── Dockerfile          # Production multi-stage Nginx build config
│   └── package.json        # NPM dependencies
├── Model/
│   └── qwen2.5-1.5b-instruct-q4_k_m.gguf  # 1.1GB GGUF model (Required)
├── docker-compose.yml      # Root orchestrator mapping volumes and ports
└── README.md               # Setup and usage guide

---

Local Setup & Execution (Recommended for Dev)

Prerequisites

1. Python 3.12 installed on host.
2. Node.js v20+ installed on host.
3. The GGUF model file placed in H:\MedReport\Model\qwen2.5-1.5b-instruct-q4_k_m.gguf.

1. Run Backend

Navigate to the backend folder, install requirements, and run FastAPI:

cd backend
pip install -r requirements.txt
python main.py

Note: On Windows, llama-cpp-python will automatically utilize CPU threads. The server runs at http://127.0.0.1:8000.

2. Run Frontend

Open a new terminal, navigate to the frontend folder, install npm packages, and start Vite:

cd frontend
npm install
npm run dev

The UI will launch at http://localhost:5173/.

---

Docker Deployment (Single Command)

To run the entire system in localized docker containers:

1. Ensure Docker Desktop is running.
2. At the root directory of the project, execute:

docker-compose up --build

• This mounts the local ./Model folder directly into the container (no duplicate model downloads needed).
• The Frontend is served on port 80 (http://localhost/).
• The Backend runs on port 8000 (http://localhost:8000/).

---

Medical Disclaimer

IMPORTANT: MedReport Agent is designed solely as an educational reference tool. It does NOT provide clinical diagnoses, medical advice, or treatment recommendations. All output should be validated with a licensed healthcare practitioner before making any clinical decisions.