This project is created for educational purposes only.
It is not a medical diagnostic tool and should not be used for real medical decisions.
The explanations generated by the AI are simplified interpretations of medical report text and may not always be accurate. Always consult a qualified healthcare professional for medical advice, diagnosis, or treatment.
AI for Better Living and Smarter Communities
GenAI APAC / Hackathon Edition — Production RAG & Decision Intelligence Platform
Compared to the initial prototype, this platform has undergone major architectural, security, performance, and user experience refinements:
| Feature Area | Previous Version (v1.0) | Refined Version (v2.0) |
|---|---|---|
| User Interface | Single Streamlit dashboard | Production React 19 + Vite Frontend (frontend/) with split-theme design system, responsive tabs, and dual-mode operation |
| AI Q&A & Streaming | Synchronous blocking responses | Server-Sent Events (SSE) Live Streaming (/api/chat/stream) for real-time token rendering |
| Source Grounding | Large plain-text block quotes | Collapsible RAG Source Evidence: Compact toggle accordion, ~100 character truncated preview, "Show full excerpt" toggle, and Page X badges |
| LLM Model Engine | gemini-1.5-flash |
Upgraded to gemini-2.5-flash & gemini-embedding-001 via direct REST endpoints for lower latency and zero SDK conflicts |
| Backend Service | Streamlit-only backend | FastAPI Production REST API (main.py) with CORS middleware, health endpoints, and static asset serving |
| Cloud Deployment | Local / manual setup | Single-Container Deployment for Google Cloud Run via multi-stage Dockerfile and Cloud Build (cloudbuild.yaml) |
| Security & Compliance | Unscreened logging & paths | 100% CodeQL Hardened: Sanitized path-injection vulnerabilities, zero stack-trace exposure to clients, and dynamic credential masking (_mask_credentials) |
| Privacy & Analytics | Basic aggregate counts | Differential Privacy (Laplace noise) + Linear Regression Trend Forecasting + CDC ESSENCE epidemiological alert detection |
| Repository Structure | Flat root file clutter | Clean Directory Organization: All technical guides, specs, and history moved into a structured docs/ directory |
The Community Health Intelligence Assistant transforms disconnected medical report PDFs into actionable health intelligence at two levels: it helps individual patients understand their lab results through AI-powered plain-language explanations, while simultaneously enabling community health workers, clinics, and public health planners to surface population-level trends — like rising HbA1c rates or regional anemia spikes — from aggregated, anonymized data.
Built on a Retrieval-Augmented Generation (RAG) pipeline with automatic anomaly detection and a structured analytics layer, the platform embodies a decision intelligence platform that predicts outcomes and helps communities make better, data-driven health decisions. Every AI response is grounded in source evidence with full transparency, medical disclaimers, and formal differential privacy guarantees — delivering responsible AI that improves everyday life.
Medical reports contain complex terminology, abbreviations, and numerical values that most patients struggle to interpret. This confusion causes unnecessary anxiety and often leads to unreliable internet searches for answers.
Local health workers (ASHA workers), clinic administrators, and public health departments lack visibility into aggregate health trends across the populations they serve. Lab reports exist as unconnected PDFs on individual phones and clinic desks — no one sees the bigger picture. When 30% of patients in a region show elevated blood sugar markers, no alarm goes off. When anemia rates spike among a particular age group, it goes unnoticed until it becomes a crisis.
This platform bridges both gaps with a single unified system:
- Patients upload their reports and get clear, AI-generated explanations grounded in their actual report data.
- Health workers & planners see anonymized, aggregated trends across all uploaded reports — flagging risks, surfacing patterns, and enabling proactive public health response.
Solution Area: Healthcare access, community wellness, and decision intelligence
| Hackathon Requirement | How We Address It |
|---|---|
| "Analyze information, generate insights" | RAG pipeline extracts, structures, and analyzes lab values from medical report PDFs |
| "Predict outcomes" | Linear regression forecasting projects abnormal rate trends 30-90 days ahead per test and region |
| "Make better decisions" | Community dashboard + NL interface lets health workers query aggregate data for resource allocation |
| "Answer questions in natural language" | Dual-audience conversational interface — patients ask about their reports, health workers ask about population trends |
| "Identify patterns and anomalies" | Automatic anomaly detection flags 100+ lab tests against clinical reference ranges at ingestion time |
| "Generate recommendations" | AI generates specialist referrals (patient) and intervention suggestions like screening camps (community) |
| "Automate workflows" | Multi-agent pipeline (Extraction → QA → Risk → Community) automates the flow from PDF upload to actionable insight |
| "Responsible and explainable AI" | Collapsible source evidence attribution, medical disclaimers, Differential Privacy, CodeQL security compliance |
┌─────────────────────────────────────────────────────────────────┐
│ COMMUNITY HEALTH INTELLIGENCE ASSISTANT (v2.0) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────┐ ┌─────────────────────────┐ │
│ │ Vite React 19 Web UI │ │ Streamlit / CLI Interface│ │
│ │ (Patient & Community UI) │ │ (Legacy / Dev Tools) │ │
│ └────────────┬─────────────┘ └────────────┬────────────┘ │
│ │ │ │
│ └──────────────┬────────────────┘ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ FastAPI Backend Server│ │
│ │ (main.py) │ │
│ └───────────┬────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────┐ │
│ │ EXTRACTION AGENT │ │
│ │ PDF → Text + Tables │ │
│ │ → Lab Value Parser │ │
│ │ → Anomaly Detector │ │
│ └───────────┬────────────┘ │
│ │ │
│ ┌─────────────────┴─────────────────┐ │
│ ▼ ▼ │
│ ┌────────────────────┐ ┌──────────────────────┐ │
│ │ ChromaDB │ │ SQLite Database │ │
│ │ (RAG Vector Store) │ │ (Structured Values & │ │
│ └──────────┬─────────┘ │ Differential Privacy)│ │
│ │ └──────────┬───────────┘ │
│ ▼ ▼ │
│ ┌────────────────────┐ ┌──────────────────────┐ │
│ │ QA AGENT │ │ COMMUNITY AGENT │ │
│ │ (SSE Streaming │ │ (Epidemiology Alert │ │
│ │ & Source Evidence) │ │ & Trend Forecasts) │ │
│ └──────────┬─────────┘ └──────────┬───────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────────┐ ┌──────────────────────┐ │
│ │ RISK CARD │ │ POPULATION DASHBOARD │ │
│ │ (Clinical Summary) │ │ (Trend Forecasting) │ │
│ └────────────────────┘ └──────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Google Gemini (REST Engine v2.5) │ │
│ │ `gemini-2.5-flash` & `gemini-embedding-001` │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
| Component | Technology | GCP / Cloud Production Path |
|---|---|---|
| Frontend | React 19, Vite, Lucide Icons, Plotly.js | Cloud Run (Served via FastAPI) / Vercel |
| Backend API | FastAPI, Uvicorn, Pydantic | Google Cloud Run (Serverless Container) |
| PDF Processing | pdfplumber, regex table parsers | Google Cloud Document AI |
| Embeddings | Gemini Embedding 001 (gemini-embedding-001) |
Vertex AI Embeddings |
| Vector Store | ChromaDB (in-memory / local) | Vertex AI Vector Search / AlloyDB |
| Structured Data | SQLite (with Laplace noise Differential Privacy) | Google BigQuery |
| LLM Engine | Google Gemini API (gemini-2.5-flash) |
Vertex AI Gemini 2.5 |
| Analytics & Trend | Linear Regression Forecasting & CDC ESSENCE Aberration | BigQuery ML / Vertex AI AutoML |
| Security | CodeQL Hardened, Input Sanitization, Path Boundary Validation | Cloud Armor / Secret Manager |
medical-report-rag/
├── main.py # FastAPI Production REST API Server & Static Asset Router
├── config.py # Centralized Configuration & Lab Reference Ranges
├── app.py # Interactive CLI Terminal Application (CodeQL Hardened)
├── streamlit_app.py # Streamlit UI Entry Point (Fallback / Dev Shell)
├── requirements.txt # Python Package Dependencies
├── runtime.txt # Python Engine Runtime (3.11.9)
├── Dockerfile # Multi-stage Container Dockerfile for Cloud Run
├── cloudbuild.yaml # Google Cloud Build CI/CD Configuration
├── render.yaml # Render Deployment Configuration
├── Procfile # Web Process Command Specification
│
├── frontend/ # Production React 19 + Vite Frontend App
│ ├── src/
│ │ ├── App.jsx # Main React Application (Patient & Community Modes + Collapsible RAG Sources)
│ │ ├── index.css # Premium Split-Theme Design System & CSS Animations
│ │ └── main.jsx # React Application DOM Mount Point
│ ├── package.json # Frontend Dependencies & Scripts
│ ├── vite.config.js # Vite Build & Proxy Configuration
│ └── vercel.json # Vercel Deployment Configuration
│
├── agents/ # Multi-Agent Pipeline Modules
│ ├── extraction_agent.py # PDF Ingestion, Parsing & Anomaly Orchestration
│ ├── qa_agent.py # Patient RAG Q&A Engine with Source Grounding
│ ├── risk_agent.py # Clinical Risk Score & Risk Card Generation
│ ├── community_agent.py # Aggregate Analytics & Natural Language Community Q&A
│ └── orchestrator.py # Session State & Multi-Agent Flow Manager
│
├── core/ # Core NLP & Medical Utilities
│ ├── pdf_extractor.py # PDF Text & Table Extraction
│ ├── chunker.py # Text Chunking for Vector Search
│ ├── embeddings.py # Embedding Generation Wrapper
│ ├── llm_client.py # Unified Google Gemini REST API Client
│ ├── lab_value_parser.py # LLM & Regex Medical Parameter Parser
│ ├── anomaly_detector.py # Reference Range Evaluator
│ ├── fhir_models.py # HL7 FHIR R4 Data Structures
│ ├── fhir_converter.py # Lab Data to FHIR R4 Bundle Serializer
│ └── anonymizer.py # Safe Demographics Anonymizer
│
├── data_store/ # Data Persistence Layer
│ ├── models.py # Data Schemas (Report, LabValue, Alert)
│ ├── sqlite_store.py # SQLite Database, Differential Privacy & Forecasting
│ └── vector_store.py # ChromaDB Vector Store Client
│
├── ui/ # Streamlit Component Modules
│ ├── patient_mode.py # Patient Mode Interface Component
│ ├── community_mode.py # Community Dashboard Component
│ ├── components.py # Shared UI Widgets
│ └── styles.py # Streamlit Custom Styling
│
└── docs/ # Documentation & Technical Specifications
├── ARCHITECTURE.md # Technical Architecture & System Specifications
├── GCP_DEPLOYMENT_GUIDE.md # Step-by-Step Google Cloud Run Deployment Guide
├── activity_log.md # Engineering Development History & Changelog
├── project_requirement.md # Original System Requirements Document
├── prototype_refinement.md # Refinement & Enhancement Technical Specs
└── requirements_and_memory.md # Architectural Context & Decisions Log
All technical specifications, deployment guides, and architectural decision records are organized inside the docs/ directory:
- 📐 Architecture Guide: Deep dive into multi-agent workflows, data flow diagrams, and schema definitions.
- 🚀 Google Cloud Run Deployment Guide: 3-minute deployment instructions for Google Cloud Shell.
- 🛠️ Prototype Refinement Specs: Comprehensive breakdown of feature additions and UI upgrades.
- 📝 Activity Log & Engineering History: Record of code commits, bug fixes, and security patches.
- 🧠 Requirements & Memory Context: Architectural decisions and system requirements.
- Python 3.10+
- Node.js 20+ (for React frontend)
- A Google Gemini API key (Google AI Studio)
# Clone repository
git clone https://github.com/Astroidkiller/medical-report-rag.git
cd medical-report-rag
# Install Python backend dependencies
pip install -r requirements.txt
# Create .env file with your API key
echo "GEMINI_API_KEY=your_gemini_api_key_here" > .envBackend Server:
python -m uvicorn main:app --host 127.0.0.1 --port 8000- API Docs (Swagger):
http://127.0.0.1:8000/docs
Frontend Dev Server:
cd frontend
npm install
npm run dev- React UI Application:
http://localhost:5173/
Streamlit Dashboard:
python -m streamlit run streamlit_app.pyInteractive CLI Application:
python app.pyDeploy the full application to Google Cloud Run using Cloud Shell:
# 1. Set your GCP Project ID
gcloud config set project YOUR_PROJECT_ID
# 2. Clone repository & enter directory
git clone https://github.com/Astroidkiller/medical-report-rag.git
cd medical-report-rag
# 3. Enable GCP Services
gcloud services enable run.googleapis.com cloudbuild.googleapis.com containerregistry.googleapis.com
# 4. Build & Deploy
gcloud builds submit --config=cloudbuild.yamlCloud Run will output your live URL:
https://community-health-assistant-xxxxx-uc.a.run.app
-
Source Evidence Grounding: Every patient answer includes a collapsible accordion with truncated excerpts and
Page Xreferences. -
Differential Privacy (DP): All community dashboard metrics apply Laplace Noise (
$\epsilon = 0.5$ ) to protect population privacy. -
CodeQL Security Hardened: Cleaned path injection vectors (
os.path.normpath+ boundary checks), suppressed stack trace exposures, and masked credentials. - Medical Disclaimers: Prominent disclaimers remind users that explanations are for educational guidance and do not replace professional medical advice.
This project is created for educational and hackathon purposes. Not intended for clinical diagnostic use.