| 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.
🚀 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).
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.
- Dense Embeddings:
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)
- Self-Corrective RAG (CRAG): Evaluates retrieved medical passages before synthesis. If passages are irrelevant, it rewrites the search query and retries automatically.
- Hallucination & Groundedness Verification: Evaluates generated answers in parallel to verify they are strictly supported by retrieved clinical literature.
- 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.
- PostgreSQL Analytics, Feedback & Cost Engine: Logs every query execution trace, token consumption, latency (ms), document relevance scores, user feedback ratings (👍 / 👎), and estimated USD cost ($).
- 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. - 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.
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
Follow these instructions to clone, set up, and evaluate the project locally or in the cloud.
- Python:
3.11or higher (Managed viauvor standardpip). - Node.js:
20.xor higher &npm. - API Keys:
- Gemini API Key: Sourced from Google AI Studio.
- Qdrant Vector Cloud API Key & URL: Sourced from Qdrant Cloud.
git clone https://github.com/emmapraise/medAi.git
cd "medAi"Create a .env file in the root directory:
cp .env.example .envPopulate .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=8000Using uv (Recommended for fast locked installs):
uv syncOr using standard pip:
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txtNavigate to the frontend/ directory, install Node packages, and build production dist assets:
cd frontend
npm install
npm run build
cd ..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.pyThe application will start at http://localhost:8000:
- 🌐 React PWA Application:
http://localhost:8000 - 📖 Interactive OpenAPI Documentation:
http://localhost:8000/docs - 🔍 Health Check Endpoint:
http://localhost:8000/api/v1/health
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')"- Admin endpoints (
/ingest,/analytics/logs,/analytics/cache/*) require anX-API-Keyheader matchingADMIN_API_KEY. With no key set they are open in development and return503in production. - Conversation privacy: session IDs are random UUIDs kept in the browser.
GET /analytics/sessionsonly returns IDs the client passes in?ids=. - CORS is same-origin by default; set
CORS_ORIGINSfor a separate frontend host. - Rate limits key on the client IP from
X-Forwarded-For, counted from the right usingTRUSTED_PROXY_COUNT(1 on Cloud Run). - Ingestion only reads files inside
DATASET_DIR. - Liveness probe:
GET /healthz.
make test # pytest (no models or network needed)
make lint # ruff + oxlintCI (.github/workflows/ci.yml) runs lint, tests and the frontend build on every push and PR.
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/summaryPOST /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. |
Launch the entire system — MediQA Bot application, PostgreSQL database, and Qdrant Vector Database — with a single command:
docker compose up --buildThe application will be accessible immediately at http://localhost:8000, with Qdrant vector storage accessible at http://localhost:6333.
# 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:latestThe production application is continuously deployed on Google Cloud Run:
- 🔗 Live Cloud Run URL: https://medai-19247955175.europe-west1.run.app/
Note on Cloud Run Deployments: Google Cloud Run builds and deploys directly from the multi-stage
Dockerfile(or Artifact Registry container image). The presence ofdocker-compose.ymlis used for local multi-service testing and does not impact Cloud Run deployment operations.
- Codebase: Open-source under MIT License.
- Dataset Attribution: Medical Question-Answering Dataset (MedQuAD) sourced from Kaggle (pythonafroz/medquad-medical-question-answer-for-ai-research), created by NIH.