Vitals is an open-source, clinical-intelligence platform designed to bridge the diagnostic gap between laboratory blood reports and patients. By combining deterministic parsing, machine learning classifiers, and LLM reasoning models, Vitals translates isolated biomarker values into a structured, patient-centric wellness path.
- Overview
- Problem Statement
- The Solution
- Why Vitals is Different
- System Architecture & Workflow
- Core Features
- Technology Stack & Justification
- Folder Structure
- Installation & Setup
- Configuration & Environment
- Deployment Guide
- Business Model & Strategy
- 7-Phase Product Roadmap
- Contributing
- License & Acknowledgements
Every day, millions of blood draws are performed globally, culminating in a printed Complete Blood Count (CBC) report. These documents are saturated with dense clinical shorthand (e.g. MCV, MCH, RDW, PCV) and numerical values. For the average patient, these reports represent an opaque black box.
Vitals provides a patient-first interpreter. It deterministic-parses raw PDF data, falls back to OCR under poor resolution conditions, evaluates parameters via an ensemble Machine Learning model to detect underlying blood pathologies (e.g. specific anemia profiles), and triggers structured Large Language Model (LLM) reasoning loops to produce safe, non-diagnostic guidance regarding diets, hydration, physical fitness, and medical specialist referals.
The current healthcare system contains several friction points that Vitals is designed to address:
- The Communication Gap: Patients leave hospitals or clinics with physical or digital lab reports but zero immediate, understandable explanation of what the results mean.
- Isolated Parameter Panics: Typical reports display values next to reference intervals. Seeing a flagged parameter (e.g. low Hemoglobin) frequently leads patients to search generic search engines, resulting in high anxiety or false reassurance.
- Clinician Burnout & Time Loss: Up to 30% of standard clinical consultations are scheduled solely to explain routine lab reports that show normal or minor, non-critical variations. This consumes expensive clinical resources and physician hours.
- Geographic Care Barriers: Patients in rural regions or small towns often lack immediate, affordable access to hematologists or primary care physicians, causing them to delay necessary dietary or specialist follow-up.
- Multi-biomarker Intersect Complexity: Traditional reports check if individual markers are high or low, but fail to explain how markers interact. For example, understanding how a low hemoglobin count combined with low mean corpuscular volume (MCV) indicates microcytic anemia requires complex cross-referencing.
Healthcare information should be understandable, actionable, and accessible to everyone.
Vitals translates raw clinical diagnostic data into a patient-focused health narrative:
[CBC PDF Report] ──> [Deterministic OCR/Regex Parser] ──> [ML Classifier + Ranges Evaluation] ──> [Gemma LLM Reasoning Block] ──> [Structured Patient Care Path]
- Patient Uploads CBC PDF: Users drop digital or scanned reports into a secure portal.
- Deterministic & OCR Extraction: Reconstructs the character grids, extracting numerical values.
- Why: Solves manual typing errors and digitizes low-resolution paper scans.
- Machine Learning Pathology Classification: Feeds the normalized hematological arrays into a trained Random Forest model.
- Why: Programmatically flags underlying anemia variants (Normal, Iron Deficiency, Folate Deficiency, B12 Deficiency) based on clinical balances rather than isolated parameter limits.
- Calculations & reference checks: Compiles scores based on clinical thresholds.
- Why: Translates clinical metrics into a single, intuitive Physiological Health Score (0-100).
- AI Generative Reasoning Loop: Routes the calculated state array through OpenRouter Gemma-4.
- Why: Transforms raw clinical numbers into reassuring, conversational advice (nutrition, routines, fitness, hydration, and physician recommendations) conforming strictly to structured schemas.
- Ecosystem Registry Matching (Future Roadmap): Recommends verified healthcare specialists and labs nearby.
- Why: Prevents patients from blindly searching online and connects them directly with qualified, verified clinics.
Vitals is not another Hospital Management System (HMS), booking portal, or open-ended medical chatbot. It is a dedicated clinical intelligence bridge representing a unified, multi-tier interpreter:
- No Open-Ended Chats: Unlike generic LLM chatbots that hallucinate medical conditions, Vitals uses a feed-forward architectural pipeline where the LLM only structures clinical calculations and predictions derived deterministically from the parser and ML models.
- Unified Diagnostic Logic: It is the only platform combining OCR, deterministic regex filters, scikit-learn classifiers, reference calculators, and LLM reasoning into a single light-themed, patient-friendly dashboard.
graph TD
A[Patient PDF Upload] --> B[FastAPI Ingestion]
B --> C{Confidence Check}
C -->|Text Layer Available| D[Footnote-Priority Regex Parser]
C -->|Scanned Image/Low Quality| E[OCR Fallback: EasyOCR]
D --> F[WBC & PLT Normalization Engine]
E --> F
F --> G[Trained Random Forest Anemia Predictor]
F --> H[Reference Ranges calculations Engine]
G --> I[Diagnostic State Compiler]
H --> I
I --> J[Hugging Face OpenRouter Gemma-4 reasoning Pipeline]
J -->|Structured JSON Output| K[FastAPI REST API Response]
K --> L[Next.js Premium Patient Dashboard]
style A fill:#00685f,stroke:#00524b,stroke-width:2px,color:#fff
style G fill:#4c1d95,stroke:#7c3aed,stroke-width:2px,color:#fff
style J fill:#006d3e,stroke:#0f5132,stroke-width:2px,color:#fff
style L fill:#ba1a1a,stroke:#a61515,stroke-width:2px,color:#fff
sequenceDiagram
autonumber
actor Patient
participant FE as Next.js Dashboard
participant BE as FastAPI API
participant ML as Random Forest Model
participant AI as OpenRouter Gemma-4
Patient->>FE: Drop CBC PDF
FE->>BE: POST /api/analyze
Note over BE: Parse PDF (OCR Fallback if needed)
Note over BE: Check parameters (Hb, RBC, WBC, PLT, MCV...)
BE->>ML: Pass Feature Array (HGB, RBC, MCV, MCH)
ML-->>BE: Return Anemia Class
BE->>AI: Stream clinical states + Prompt rules
Note over AI: Execute reasoning block
AI-->>BE: Return structured lifestyle JSON
BE-->>FE: Return API Payload
FE->>Patient: Render radial dials, checklists, & care partner previews
graph TD
A[Read PDF file pages] --> B[Extract text coordinates via PyMuPDF]
B --> C{Text length > 120 chars?}
C -->|Yes| D[Route to Deterministic Regex Parser]
C -->|No| E[Convert pages to PNG arrays]
E --> F[Run EasyOCR text extraction]
F --> D
D --> G[Standardize parameters]
- Digital PDF & Scanned OCR Ingestion: Uses
PyMuPDFtext character extraction with direct fallback toEasyOCRfor low-contrast scans. - Footnote Filtering: Regex filters skip superscript footnote references (e.g. converting
Hematocrit 01 27.3%safely to27.3instead of extracting01). - Machine Learning Classifier: Scikit-learn Random Forest model predicting iron deficiency, folate deficiency, vitamin B12 deficiency, hemoglobin-specific anemia, or normal profiles.
- Calculations Engine: Computes physiological safety score (0-100), risk tier, abnormal finding tables, and clinical severity.
- Gemma-4 reasoning Integration: Connects to OpenRouter to parse states into formatted, markdown-compatible diet lists, fitness routines, and fluid goals.
- Interactive Lifestyle Dashboard: Features collapsible biomarker gauges, daily water tracking increments, routine checkbox timelines, and high-fidelity print layouts.
- Care Partners Preview: A disabled dashboard section featuring specialist referrals and verified preview partner clinics.
- Location-Aware Referrals: Requesting permission to locate nearby clinical specialists in our partner database.
- Telemedicine booking integrations: Scheduling appointments directly from the analysis dashboard.
- Laboratory API Integrations: Syncing raw values directly from diagnostic center databases, bypassing PDF uploads.
| Technology | Role | Justification |
|---|---|---|
| Next.js 16 (App Router) | UI Framework | Handles client-side state, print pre-rendering, and static page optimizations via Turbopack compilation. |
| FastAPI | REST API Backend | Selected for its asynchronous capabilities, fast request loops, and simple python-based integration with scientific calculations. |
| Random Forest | ML Classifier | Lightweight classification model that offers predictable, high-accuracy results on structured clinical diagnostics without large GPU dependencies. |
| OpenRouter Gemma-4 | Generative reasoning | Harnesses state-of-the-art open-weights reasoning blocks to compile structured medical logic without safety filter blocks. |
| Tailwind CSS | Global Styling | Handles the typography, clinical color systems, responsive grids, and clean visual shadows. |
| TypeScript | Interface Contracts | Enforces compile-time type validation between FastAPI endpoints and frontend React components. |
Vitals/
├── api/ # FastAPI Backend Application
│ ├── ai_provider.py # OpenRouter completion clients & backoff retries
│ ├── classifier.py # ML Model loading & feature matching
│ ├── parser.py # PDF Regex extractors & OCR fallback
│ ├── index.py # FastAPI endpoints & diagnostics
│ └── trained_model.joblib # Trained Random Forest classifier weights
├── app/ # Next.js App Router Frontend
│ ├── components/ # Reusable UI Components
│ │ ├── report/ # Biomarker cards & Lifestyle modules
│ │ │ └── care/ # "Continue Your Care" registry preview elements
│ │ └── shared/ # Loading timelines & Upload modals
│ ├── dashboard/ # Report results layout orchestrator
│ ├── lib/ # API connection handlers
│ ├── types/ # TypeScript interface contracts
│ └── globals.css # Colors, shapes, & animations stylesheet
├── public/ # Static SVGs, logos, & banners
├── render.yaml # Infrastructure configurations for Render
├── package.json # Frontend package dependencies & scripts
├── requirements.txt # Python backend dependencies
└── README.md # Repository documentation
- Python 3.10+
- Node.js 18+
- An OpenRouter API Key
git clone https://github.com/Rohan-R07/Ai-medical-report-analyzer.git
cd Ai-medical-report-analyzerCreate a .env file in the root directory:
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_MODEL=google/gemma-4-26b-a4b-it
NEXT_PUBLIC_API_URL=http://127.0.0.1:8000Activate your virtual environment and install packages:
# Create venv
python -m venv venv
# Activate venv (Windows)
.\venv\Scripts\activate
# Activate venv (macOS/Linux)
source venv/bin/activate
# Install requirements
pip install -r requirements.txtLaunch the FastAPI backend server:
python api/index.pyThe server will run on http://127.0.0.1:8000.
In a new terminal window, navigate to the root directory and install npm dependencies:
npm installStart the Next.js development server:
npm run devOpen http://localhost:3000 in your web browser.
Vitals is configured to deploy directly to Render using the provided render.yaml infrastructure blueprint:
- Connect your GitHub repository to your Render Dashboard.
- Render will automatically detect the
render.yamlblueprint. - It will provision:
- Web Service (FastAPI): Builds the Python backend using
requirements.txt. - Static Site (Next.js): Builds the frontend static files using
npm run build.
- Web Service (FastAPI): Builds the Python backend using
- Add your
OPENROUTER_API_KEYto the environment variables on the Render dashboard.
Vitals operates under a patient-first healthcare ecosystem philosophy: Patients should never pay simply to understand their own medical reports.
- 100% Free: Patients upload reports, receive predictions, and view summaries completely free.
- No Advertisements: To preserve patient trust and safety, no clinical pages show third-party ads.
The future sustainability of the platform relies on the Verified Healthcare Partner Network:
- Verified Partner Memberships: Clinical centers, hospitals, and specialized practitioners pay a recurring membership fee to join the listing registry. In return, they get discoverability, verified clinical badges, and AI-powered referrals.
- Referral Commissions: Partners pay small compliance-approved transaction commissions when patients utilize Vitals to book follow-up consultations.
- Premium Subscriptions: Optional, paid patient subscription tiers containing biomarker history trend charts, AI family vaults, and continuous health monitoring.
- Diagnostic Laboratory Affiliate Integrations: Partner labs pay referral fees to receive automated laboratory orders for follow-up blood count panels recommended in patient lifestyle summaries.
Phase 1: CBC Analysis (MVP)
↳ Core digital text PDF ingestion and footnote-aware regex parsing.
↓
Phase 2: Patient Dashboard (MVP)
↳ Interactive Radial Score, Biomarker track gauges, and offline detection.
↓
Phase 3: Personalized Wellness (MVP)
↳ Checkbox meal routines, physical exercises, and click-to-increment hydration counters.
↓
Phase 4: Verified Partner Network (Roadmap)
↳ Locked registration portal and credentials validation pipelines for partner clinics.
↓
Phase 5: Location-Aware Recommendations (Roadmap)
↳ Geographic matching systems connecting patients to verified clinics near their location.
↓
Phase 6: In-App Appointment Booking (Roadmap)
↳ Scheduling booking integrations with verified partner availability APIs.
↓
Phase 7: Long-Term Monitoring (Roadmap)
↳ Longitudinal historical trends tracking, family health vaults, and premium memberships.
The main hub page featuring Vitals' branding, connection status badges, feature cards, and the interactive document upload zone.
We welcome open-source contributions to enhance Vitals! To contribute:
- Fork the repository.
- Create a feature branch:
git checkout -b feature/amazing-feature. - Commit your changes:
git commit -m "feat: add amazing-feature". - Push to the branch:
git push origin feature/amazing-feature. - Open a Pull Request.
- License: This project is licensed under the MIT License - see the LICENSE file for details.
- Acknowledgements:
- The scikit-learn team for powerful model training and serializing frameworks.
- PyMuPDF and EasyOCR for high-fidelity OCR fallbacks.
- The Google DeepMind and OpenRouter teams for power-efficient LLM reasoning APIs.