MedIntel

MedIntel is a personal health dashboard and clinical document processing application. It parses diagnostic lab reports (PDFs and images), extracts core biomarkers, generates patient-friendly clinical summaries, and aggregates daily health telemetry in a local SQLite database.

Warning

Medical Disclaimer: MedIntel is a conceptual demonstration prototype. All analyses and answers are generated by open-source Large Language Models (LLMs) and automated text extraction tools. It does not provide medical advice, diagnosis, or clinical decisions. Always consult a licensed healthcare professional for medical concerns.

---

Screenshots

---

Problem Solved

Medical lab reports and diagnostic summaries are notoriously difficult for patients to interpret due to dense clinical jargon and complex formatting. Additionally, patients lack a simple, secure, and offline-capable solution to consolidate health telemetry (such as daily steps, sleep, and weight) over time alongside their formal clinical records. MedIntel resolves this by providing a unified local application to parse documents, render explanations, and log daily biomarkers.

---

Technical Architecture

MedIntel uses a modular, service-oriented Python architecture built around Streamlit's reactive UI engine:

medintel/
├── .streamlit/
│   ├── config.yaml           # Local role-based authenticator database
│   └── config.yaml.example   # Configuration template
├── assets/
│   └── architecture_diagram.png # Technical topology diagram
├── modules/
│   ├── auth.py               # Session management and Bcrypt credential hashing
│   ├── health_query_bot.py   # Interface to Hugging Face Inference API
│   ├── health_tracker.py     # SQLite schema, telemetry CRUD, and Pandas analytics
│   ├── ocr_report_parser.py  # PDF text parser and Tesseract OCR engine
│   ├── tts_component.py      # Iframe bridge for browser-native speech synthesis
│   └── wearables.py          # wearable API integration stub
├── streamlit_app.py          # App coordinator and Streamlit interface router
└── requirements.txt          # Python dependency specifications

---

Engineering Challenges

1. Hybrid OCR Pipeline (PDF + Tesseract Fallback)

Extracting text from medical documents requires handling both digital PDFs and scanned images.

• Implementation: The pipeline uses pypdf to run native, lightweight text extraction for digital documents. If the text payload is empty, the pipeline dynamically falls back to image parsing using pytesseract (Tesseract OCR wrapper) and Pillow for image preprocessing.
• Regex Extraction: Extracted text undergoes regular expression analysis using robust lookahead anchors to cleanly isolate target biomarkers (e.g., Hemoglobin and Glucose) regardless of variable document formatting.

2. Bcrypt-Based Authentication & Session Handling

Securing standard user dashboards and administrative panels requires robust, localized session control.

• Implementation: Using streamlit-authenticator integrated with bcrypt salt hashing, standard user password hashes are persisted at rest in .streamlit/config.yaml.
• Role-Based Controls: The app decodes credentials on login, registers standard user role parameters, and dynamically restricts administrative modules from non-admin accounts.

3. Serverless LLM Inference Integration

Integrating large language model support without incurring massive local hardware compute overhead.

• Implementation: The AI Q&A Assistant and Clinical Report Explainer query Hugging Face's serverless Inference API using the google/flan-t5-base model.
• Offline Robustness: The module features a local fallback system. If the Hugging Face API key is missing or the network is offline, the model dynamically serves pre-defined, high-fidelity clinical responses.

4. Telemetry Storage & Trend Visualization

Persisting multi-day telemetry logs and rendering real-time tracking charts.

• Implementation: User telemetry (Weight, Steps, Sleep) is serialized in an SQLite database under an index of username and date.
• Analytics Rendering: The app utilizes pandas to dynamically construct localized dataframes which are automatically visualized using Streamlit's native SVG/Canvas charting libraries.

---

Technology Stack

• Framework: Streamlit (Reactive UI Engine)
• Database: SQLite3
• Data Analytics: Pandas, PyArrow
• Document Processing: PyTesseract (Tesseract OCR), pypdf, Pillow
• AI & NLP Model: Hugging Face Inference API (Flan-T5-base)
• Speech Synthesis: HTML5 Web Speech API via EasySpeech.js
• Security: streamlit-authenticator, bcrypt, PyYAML

---

Installation

Prerequisites

1. Python 3.9+ installed.
2. Tesseract OCR Engine installed:
   • Windows: Download the installer from UB Mannheim Tesseract repo and add C:\Program Files\Tesseract-OCR to your system PATH.
   • macOS: brew install tesseract
   • Linux/Ubuntu: sudo apt-get install tesseract-ocr

Setup Steps

1. Clone the Repository:

   git clone https://github.com/kanwa2006/medintel.git
   cd medintel

2. Create and Activate a Virtual Environment:

   • Windows (PowerShell):

     python -m venv .venv
     .venv\Scripts\activate

   • macOS/Linux:

     python -m venv .venv
     source .venv/bin/activate

3. Install Dependencies:

   pip install -r requirements.txt

---

Configuration

1. Environment Variables: Create a .env file in the root directory to store your Hugging Face API key:

   HUGGINGFACE_API_KEY=your_huggingface_api_key_here

   (Note: The app will run in offline mode using local fallbacks if no API key is supplied.)

2. Administrative Access: On first execution, the application automatically registers a default administrative user in .streamlit/config.yaml. Update these credentials immediately after initialization to secure your deployment.

---

Usage

1. Start the Application:

   streamlit run medintel/streamlit_app.py

2. Access the Dashboard: Open http://localhost:8501 in your browser.

3. Modules:

   • Medical Q&A: Submit natural language queries and listen to speech synthesis explanations.
   • Report Analyzer: Upload report scans (PDF/PNG/JPG) to parse values and render patient summaries.
   • Daily Tracker: Log fitness and physiological stats to generate trend charts.

---

Limitations & Future Roadmap

• Heuristic Extraction: Biomarker parsing currently relies on lookahead regex heuristics. Transitioning to Clinical Named Entity Recognition (Clinical NER) models (like ClinicalBERT) would allow extracting a broader set of complex biomarker variables.
• Telemetry Integrations: Wearable metrics are currently simulated. Activating the Fitbit, Garmin, or Apple Health API connectors would allow automated telemetry logging.
• Local Data Encryption: Telemetry data is saved in plain text SQLite. Future releases will integrate SQLCipher to encrypt logs at rest.