8000 GitHub - emmapraise/medAi · GitHub
[go: up one dir, main page]

Skip to content
emmapraisePublic

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

title MediQA
emoji 🩺
colorFrom green
colorTo blue
sdk docker
app_port 7860
pinned false

v2 branch. The YAML header is only used by Hugging Face Spaces, which needs a PRO plan for Docker (not used). v2 runs on Cloud Run: see docs/DEPLOY.md; the plan and results are in docs/V2_PLAN.md. The sections below still describe v1 and have not been rewritten yet.

🩺 MediQA Bot — AI Medical Intelligence & Self-Corrective RAG (CRAG) PWA

FastAPI React PWA LangGraph Qdrant PyTorch PostgreSQL Live Demo

🚀 Live Deployment: https://medai-19247955175.europe-west1.run.app/

Reviewers & Evaluators: The application is fully deployed and accessible on Google Cloud Run! Please feel free to check out the live demo to experience the Doctor Chat PWA, interactive hybrid search, and real-time analytics in action.

MediQA Bot is a production-ready, evidence-based Medical Question-Answering application powered by Self-Corrective Retrieval-Augmented Generation (CRAG) via LangGraph, Qdrant Cloud Hybrid Search (768-dim PubMedBERT ONNX Dense Vectors + FastEmbed BM25 Sparse Vectors with Reciprocal Rank Fusion), PostgreSQL Analytics & Cost Tracking, and a mobile-responsive React Progressive Web App (PWA).


📚 Dataset Provenance & Attribution

The medical knowledge base backing MediQA Bot is built from the MedQuAD (Medical Question Answering Dataset):

  • Source: Sourced from Kaggle — MedQuAD: Medical Question Answer for AI Research.
  • Origin: Created by 12 National Institutes of Health (NIH) institutes (including NCI, NHLBI, NIDDK, NINDS, and MedlinePlus).
  • Coverage: Contains 16,400+ curated medical question-answer pairs covering diseases, symptoms, causes, diagnosis, treatments, clinical trials, and procedures.
  • Vector Indexing: The dataset is indexed into Qdrant Cloud using a hybrid dual-vector space:
    • Dense Embeddings: emmapraise/pubmedbert-base-embeddings-onnx (768-dimensional clinical domain PubMedBERT ONNX model).
    • Sparse Embeddings: Qdrant/bm25 (FastEmbed BM25 sparse keyword vectors).
    • Fusion Algorithm: Reciprocal Rank Fusion (RRF) for combining dense semantic match scores with sparse exact keyword matches.

⚡ Architecture & Key Technical Features

                      
EDE2
            [START]
                                     │
                                     ▼
                           ┌───────────────────┐
                           │   Generate Query  │ (Context & Conversational History Resolution)
                           └─────────┬─────────┘
                                     │
                                     ▼
                           ┌───────────────────┐
                           │  Hybrid Retrieve  │ (Qdrant Cloud: PubMedBERT + BM25 + RRF)
                           └─────────┬─────────┘
                                     │
                                     ▼
                        ┌─────────────────────────┐
                        │ Grade Document Relevance│ (Evaluates retrieved passages)
                        └────────────┬────────────┘
                                     │
     ┌───────────────────────────────┴───────────────────────────────┐
     │ Relevant?                                                     │ Irrelevant?
     ▼                                                               ▼
┌──────────────────┐                                       ┌────────────────────┐
│  Generate Answer │                                       │ Query Rewrite Node │ (Rewrites query & retries)
└────────┬─────────┘                                       └─────────┬──────────┘
         │                                                           │
         ▼                                                           └─────────► (Loop back to Retrieve)
┌────────────────────────────────┐
│ Grade Answer (Self-Correction) │ (Validates Groundedness & Relevance against Hallucinations)
└────────┬───────────────────────┘
         │
  ┌──────┴──────┐
  │ Grounded &  │
  │ Useful?     ▼
  └──────────► [END] (Returns Validated Evidence-Based Answer with Interactive Follow-up Offer)

🎯 Key Capabilities:

  1. Self-Corrective RAG (CRAG): Evaluates retrieved medical passages before synthesis. If passages are irrelevant, it rewrites the search query and retries automatically.
  2. Hallucination & Groundedness Verification: Evaluates generated answers in parallel to verify they are strictly supported by retrieved clinical literature.
  3. Interactive Yes/No Conversation Flow: Prompts user with natural follow-up offers (e.g. "Would you like to know more about treatments for HIV?"). When the user answers with "Yes", "Sure", or "Tell me more", the system automatically resolves the offer topic from conversation history and retrieves relevant documents.
  4. PostgreSQL Analytics, Feedback & Cost Engine: Logs every query execution trace, token consumption, latency (ms), document relevance scores, user feedback ratings (👍 / 👎), and estimated USD cost ($).
  5. Visible verification: every answer shows whether its sources were relevant, whether it matches them, and whether it addresses the question, plus the steps the agent took. Aggregate metrics are available from GET /api/v1/analytics/summary.
  6. Mobile-Responsive React PWA with Interactive Feedback: Features an offline-ready PWA with Service Worker (sw.js), web manifest, mobile slide-out drawer, past session drawer, copy answer button, question editing capabilities, and one-click user feedback.

📁 Repository Structure

MediQA Bot/
├── app/
├── app/agent/               # Modular LangGraph CRAG Package
│   ├── enums.py             # Strongly-typed NodeName Enum
│   ├── llm_client.py        # Gemini 2.5 Flash / OpenAI LLM Client
│   ├── nodes.py             # Graph nodes (query gen, retrieve, grade docs, generate answer, grade gen)
│   ├── service.py           # MedicalAgentService execution facade & MemorySaver state manager
│   ├── state.py             # GraphState & NodeName TypedDict
│   └── workflow.py          # StateGraph builder & conditional edge routers
├── app/routers/             # FastAPI Route Handlers
│   ├── analytics.py         # GET /analytics/summary, /logs, DELETE /sessions/{id}
│   ├── health.py            # GET /health
│   ├── ingest.py            # POST /ingest (Qdrant vector ingestion)
│   ├── qa.py                # POST /ask (LangGraph Agent Chat)
│   └── search.py            # POST /search (Direct Hybrid Vector Search)
├── app/services/            # Core Infrastructure Services
│   ├── analytics_service.py # PostgreSQL logger & cost calculator
│   └── search_service.py    # Qdrant client, PubMedBERT & BM25 hybrid search engine
├── dataset/                 # Medical QA dataset files (medquad.csv)
├── frontend/                # React Vite PWA Frontend
│   ├── src/                 # React app (App, Sidebar, Conversation, Entry) and lib/ helpers
│   ├── public/              # Service worker (sw.js), manifest.json, PWA icons
│   └── index.html           # Edge-to-edge mobile PWA index
├── Dockerfile               # Multi-stage Dockerfile with pre-cached PubMedBERT weights
├── docker-compose.yml       # Full-stack Docker Compose configuration (App + PostgreSQL)
├── pyproject.toml           # Locked UV Python dependencies
├── main.py                  # FastAPI application entrypoint with static PWA mounting
└── README.md

🛠️ Step-by-Step Setup Guide

Follow these instructions to clone, set up, and evaluate the project locally or in the cloud.

Prerequisites

  • Python: 3.11 or higher (Managed via uv or standard pip).
  • Node.js: 20.x or higher & npm.
  • API Keys:

Step 1: Clone the Repository

git clone https://github.com/emmapraise/medAi.git
cd "medAi"

Step 2: Configure Environment Variables

Create a .env file in the root directory:

cp .env.example .env

Populate .env with your credentials:

# LLM Credentials
GEMINI_API_KEY="your_gemini_api_key_here"
OPENAI_API_KEY="your_openai_api_key_optional"

# Qdrant Cloud Credentials
QDRANT_URL="https://67b23fca-0482-4a4e-9cdd-e579a9f6eced.europe-west3-0.gcp.cloud.qdrant.io"
QDRANT_API_KEY="your_qdrant_api_key_here"

# Database Connection (Defaults to SQLite fallback if PostgreSQL is unconfigured)
DATABASE_URL="postgresql://user:password@localhost:5432/medical_db"

# Server Port
PORT=8000

Step 3: Install Backend Dependencies

Using uv (Recommended for fast locked installs):

uv sync

Or using standard pip:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

Step 4: Build Frontend PWA Assets

Navigate to the frontend/ directory, install Node packages, and build production dist assets:

cd frontend
npm install
npm run build
cd ..

Step 5: Run the MediQA Bot Application

Launch using make (Recommended):

make run        # Run standard server
make dev        # Run with hot-reloading
make compose-up # Run complete stack (App + Postgres + Qdrant)

Or using uv directly:

uv run python main.py

The application will start at http://localhost:8000:


Step 6: Dataset Indexing into Qdrant Cloud (If Re-indexing)

To trigger Qdrant vector indexing for dataset/medquad.csv:

curl -X POST "http://localhost:8000/api/v1/ingest" -H "X-API-Key: $ADMIN_API_KEY"

Or execute vector ingestion in Python:

python -c "from app.services.search_service import search_engine; search_engine.initialize(); search_engine.ingest_dataset('dataset/medquad.csv')"

🔐 Security & Operations

  • Admin endpoints (/ingest, /analytics/logs, /analytics/cache/*) require an X-API-Key header matching ADMIN_API_KEY. With no key set they are open in development and return 503 in production.
  • Conversation privacy: session IDs are random UUIDs kept in the browser. GET /analytics/sessions only returns IDs the client passes in ?ids=.
  • CORS is same-origin by default; set CORS_ORIGINS for a separate frontend host.
  • Rate limits key on the client IP from X-Forwarded-For, counted from the right using TRUSTED_PROXY_COUNT (1 on Cloud Run).
  • Ingestion only reads files inside DATASET_DIR.
  • Liveness probe: GET /healthz.

🧰 Development

make test   # pytest (no models or network needed)
make lint   # ruff + oxlint

CI (.github/workflows/ci.yml) runs lint, tests and the frontend build on every push and PR.

🧪 Scoring & Evaluation Guide

Evaluators can verify every feature of the project using the following checks:

Evaluation Test Action / Endpoint Expected Result
1. Agent QA (CRAG) POST /api/v1/ask
{"question": "What are the symptoms of Glaucoma?"}
Returns evidence-based answer, PubMedBERT retrieval trace, relevance grade YES, and interactive follow-up question.
2. Multi-Turn "Yes" Offer Send POST /api/v1/ask
{"question": "Yes, tell me more", "session_id": "same_session"}
Formulates query from previous history topic (e.g. Glaucoma detection methods) and answers seamlessly.
3. Hybrid Search POST /api/v1/search
{"query": "Infant hepatoblastoma"}
Returns top 5 RRF-ranked medical passages combining PubMedBERT + BM25 score.
4. PostgreSQL Logging & Feedback GET /api/v1/analytics/summary
POST /api/v1/analytics/feedback
Returns total queries count, groundedness %, relevance %, user satisfaction %, and total cost ($ USD).
5. Verification ledger Ask any question in the UI Each answer shows three source checks and an expandable list of steps taken.
6. Mobile PWA Responsiveness Open http://localhost:8000 in mobile viewport (< 768px) Conversation list opens as a slide-out drawer; the verification ledger moves below the answer.

🐳 Docker Containerization & GCP Cloud Run

Option 1: Full-Stack Docker Compose (Recommended)

Launch the entire system — MediQA Bot application, PostgreSQL database, and Qdrant Vector Database — with a single command:

docker compose up --build

The application will be accessible immediately at http://localhost:8000, with Qdrant vector storage accessible at http://localhost:6333.


Option 2: Standalone Docker Run

# Build Docker image (Pre-caches PubMedBERT model weights inside container image)
docker build -t mediqa-bot:latest .

# Run container locally
docker run -p 8000:8080 \
  -e GEMINI_API_KEY="your_key" \
  -e QDRANT_URL="your_qdrant_url" \
  -e QDRANT_API_KEY="your_qdrant_key" \
  mediqa-bot:latest

🌐 Google Cloud Run Deployment

The production application is continuously deployed on Google Cloud Run:

Note on Cloud Run Deployments: Google Cloud Run builds and deploys directly from the multi-stage Dockerfile (or Artifact Registry container image). The presence of docker-compose.yml is used for local multi-service testing and does not impact Cloud Run deployment operations.


📄 License & Attribution

About

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0