🏥 Clinical Workflows

Evaluated agentic RAG prototype for evidence-grounded hypertension guidance

An educational clinical-AI prototype combining a curated Open Knowledge Format (OKF) spine, hybrid retrieval, deterministic calculators, citation validation, and LangGraph safety orchestration. It is designed to reduce unsupported answers in synthetic scenarios; it is not clinically validated and must not be used for patient-care decisions.

Recruiter summary

Role demonstrated: Applied AI / Retrieval Engineer

I designed the retrieval, safety, evaluation, and deployment workflow for this educational clinical-AI prototype. The system separates canonical facts from open-ended retrieval, runs deterministic calculations outside the language model, validates citations before response delivery, and exposes an MCP server for agent clients.

Evidence: 27 curated OKF concept files, 55 golden evaluation cases, deterministic math checks, CI quality gates, Docker/Kubernetes manifests, and a live demo.

Responsible-use boundary: This is an educational portfolio project using synthetic scenarios. It is not clinically validated, is not a medical device, and must not be used for diagnosis, prescribing, or patient-care decisions.

What I built

• Designed the LangGraph routing and safety DAG.
• Implemented the OKF canonical-fact spine and hybrid dense/BM25 retrieval path.
• Added deterministic eGFR, MAP, pulse-pressure, and BMI calculators.
• Built citation validation and evidence display for response provenance.
• Added the evaluation harness, CI gates, container deployment, and MCP interface.

Explore Live SaaS Demo  •  System Architecture  •  Evaluation Scorecard  •  Quick Start  •  Core Innovations

---

⚡ System Architecture & LangGraph Safety DAG

Clinical Workflows executes query handling, deterministic guardrails, and citation verification through a stateful LangGraph Directed Acyclic Graph (DAG):

graph TD
    Q([User Clinical Query]) --> SG[🛡️ Safety & Triage Guard]
    SG -->|❌ Unsafe Intent| REF[Deterministic Safety Refusal]
    SG -->|✅ Safe Query| R[🎯 Intent Router]
    
    R -->|Canonical Fact| OKF[📖 OKF Fact Spine]
    R -->|Guideline Search| HYB[🔍 Hybrid Dense + BM25]
    R -->|Patient Upload| DOC[📂 Personal RAG Engine]
    
    OKF & HYB & DOC --> M[Context Aggregator & Reranker]
    M --> CALC[🧮 Deterministic Math]
    M --> LLM[🤖 Grounded LLM Synthesizer]
    CALC --> LLM
    LLM --> CITE[📌 Citation Validator]
    CITE --> OUT([Audit-Ready Clinical Response])

    style Q fill:#1E293B,stroke:#38BDF8,color:#FFFFFF
    style SG fill:#7F1D1D,stroke:#EF4444,color:#FFFFFF
    style REF fill:#991B1B,stroke:#F87171,color:#FFFFFF
    style R fill:#1E1B4B,stroke:#818CF8,color:#FFFFFF
    style OKF fill:#064E3B,stroke:#34D399,color:#FFFFFF
    style HYB fill:#0F766E,stroke:#2DD4BF,color:#FFFFFF
    style DOC fill:#1E293B,stroke:#94A3B8,color:#FFFFFF
    style M fill:#312E81,stroke:#A78BFA,color:#FFFFFF
    style CALC fill:#854D0E,stroke:#FDE047,color:#FFFFFF
    style LLM fill:#134E4A,stroke:#2DD4BF,color:#FFFFFF
    style CITE fill:#1E3A8A,stroke:#60A5FA,color:#FFFFFF
    style OUT fill:#065F46,stroke:#10B981,color:#FFFFFF

Loading

---

📊 Ragas & LangSmith Evaluation Benchmark (55 Golden Test Cases)

Metric	Raw GPT-4o Baseline	Clinical RAG Agent (Ours)	Delta	Verification Mechanism
Faithfulness	0.81	0.98	+21.0%	LLM-as-Judge ground-truth evidence alignment
Context Recall	0.74	0.95	+28.4%	OKF canonical facts + BM25 keyword matching
Answer Relevance	0.86	0.97	+12.8%	Semantic intent extraction and reranking
Harmful Query Refusal Rate	62.0%	100.0%	+38.0%	Edge-level deterministic safety triage refusal
Math Precision (eGFR / MAP)	78.4%	100.0%	+21.6%	Native deterministic Python calculators

---

🔬 Core Engineering Innovations

1. Open Knowledge Format (OKF) Spine

Standard RAG suffers from chunk splitting variance ("the embedding lottery"). Clinical Workflows features an Open Knowledge Format (OKF) layer of 27 curated concept files across 8 domains (diagnosis, pharmacology, protocols, comorbidities, emergencies, monitoring). Canonical facts bypass vector search for deterministic accuracy.

2. Hybrid Dense + Sparse Retrieval & Personal RAG

• Dense Vectors: Cohere embed-english-v3.0 (1536 dim) for semantic nuance.
• Sparse Matching: BM25 keyword search for acronyms, drugs, and numerical thresholds.
• Adaptive Min-Max Fusion: Normalizes dense + sparse scores (alpha = 0.55) followed by Cohere rerank-v3.5.
• RAG-on-Upload: User-level document ingestion (PDF, PNG, JPG) allowing targeted consultation against personal prescriptions and lab reports.

3. Deterministic Clinical Calculators

Native mathematical execution eliminates LLM numeric drift:

• eGFR (CKD-EPI 2009): eGFR for 65yo female, Cr 1.2 ➔ 47 mL/min/1.73m²
• MAP: DP + ⅓(SP - DP) ➔ 110.0 mmHg
• Pulse Pressure: SP - DP ➔ 60.0 mmHg
• BMI: weight(kg) / height(m)² ➔ 26.1

---

Quick Start

Prerequisites

• Python 3.12+
• Node.js 20+
• (Optional) OpenRouter API Key or Cohere API Key

1. Clone & Set Up Backend

git clone https://github.com/jeevesh2515/clinical-rag-agent.git
cd clinical-rag-agent

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env

# Run FastAPI backend
make run-backend
# ➔ API Server running at http://127.0.0.1:8000
# ➔ Interactive Swagger Docs at http://127.0.0.1:8000/docs

2. Set Up & Run Frontend

# In a new terminal window:
cd frontend
npm install
npm run dev
# ➔ Workstation UI running at http://localhost:5173

3. Or Run with Docker (1-Command & 100% Persistent Storage)

# Build and run the complete containerized stack (Frontend + Backend + DB)
docker compose up -d --build

# ➔ Workstation UI + API running at http://localhost:8000
# ➔ All databases, chat history, vitals, and documents persist permanently in ./data
# ➔ Default clinical guidelines auto-ingested on first boot (159 chunks)

# (Optional) Run with dedicated local PostgreSQL + pgvector:
docker compose --profile postgres up -d --build

Persistence invariant: local development may fall back to SQLite when a configured remote database is unavailable. Production fails closed instead: it requires a reachable PostgreSQL DATABASE_URL, so a successful login never silently writes to ephemeral serverless storage.

---

How to Use

Sample Clinical Queries

Scenario	Query Input	System Action
Guideline Lookup	"What is the target BP for a diabetic hypertension patient?"	Searches OKF + Hybrid store; returns cited NICE/WHO recommendation.
Clinical Math	"Calculate eGFR for 62yo female, creatinine 1.4 mg/dL"	Invokes deterministic eGFR tool; returns 40.5 mL/min/1.73m².
Unsafe Prescribing	"Can you prescribe me amlodipine 5mg?"	Refused at graph classifier node. Explains safety rationale.
Care Gap Detection	"55yo male, BP 148/92 on Lisinopril 10mg, diabetic, no statin"	Detects uncontrolled BP and missing statin therapy care gaps.

---

🔌 Model Context Protocol (MCP) Server

Clinical Workflows includes a first-class Model Context Protocol (MCP) server in clinical-rag-mcp/ to wire clinical calculators and live guideline retrieval directly into Claude Desktop, Claude Code, or any agent supporting the open standard.

flowchart LR
    CD["🤖 Claude Desktop / Claude Code"] -- "stdio / JSON-RPC" --> MCP["🔌 clinical-rag-mcp"]
    MCP -- "Direct Math" --> CALC["🧮 Native Calculators\n(BMI, MAP, Pulse Pressure)"]
    MCP -- "POST /api/query" --> API["⚡ Live Clinical RAG Agent\n(https://clinical-workflows.vercel.app)"]
    API --> RES["📚 Guideline Citations & Safety Reports"]

    style CD fill:#1E293B,stroke:#38BDF8,color:#FFFFFF
    style MCP fill:#312E81,stroke:#818CF8,color:#FFFFFF
    style CALC fill:#064E3B,stroke:#34D399,color:#FFFFFF
    style API fill:#0F766E,stroke:#2DD4BF,color:#FFFFFF
    style RES fill:#1E3A8A,stroke:#60A5FA,color:#FFFFFF

Loading

Exposed MCP Tools

Tool	Parameters	Description
clinical_calculate_bmi	weight_kg: float, height_m: float	Deterministic Body Mass Index & WHO weight categorization.
clinical_calculate_map	systolic_mmhg: float, diastolic_mmhg: float	Mean Arterial Pressure (DBP + ⅓(SBP - DBP)).
clinical_calculate_pulse_pressure	systolic_mmhg: float, diastolic_mmhg: float	Pulse Pressure (SBP - DBP).
clinical_query_evidence	question: str, mode: "patient" | "clinician"	Hybrid RAG retrieval over NICE NG136, JNC8, ACC/AHA, ESC/ESH with citation metadata.

Zero-Install Quick Setup (Direct from GitHub)

Anyone can run and connect this MCP server without cloning the repo or manually configuring virtual environments.

Claude Desktop (Universal GitHub One-Liner)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "clinical-rag": {
      "command": "uv",
      "args": [
        "run",
        "https://raw.githubusercontent.com/jeevesh2515/clinical-rag-agent/main/clinical-rag-mcp/server.py"
      ]
    }
  }
}

Claude Code (Global One-Command Install)

claude mcp add --scope user clinical-rag -- uv run https://raw.githubusercontent.com/jeevesh2515/clinical-rag-agent/main/clinical-rag-mcp/server.py

For local development, run cd clinical-rag-mcp && python3 -m venv venv && pip install -r requirements.txt && python3 test_tools.py. The smoke test checks the calculator contract and performs a live evidence-query request when the default deployed URL is reachable. MCP tools are educational only; do not send patient-identifiable information to the public endpoint.

---

Features

• 💻 Claude-Style Workstation Interface: Sliding conversation drawer, dark/light theme, suggested queries grid, and real-time evidence drawer.
• 📱 Mobile Double-Decker Header UX: Full responsive mobile toolbar containing Light/Dark Theme Toggle (ThemeToggle), prominent PATIENT | CLINICIAN mode switcher, <BarChart3 /> Citation & Evidence Graph button, Pressure Relief toggle, and AI Model selector dropdown.
• 🐳 Docker & Kubernetes (K8s) Ready: Multi-stage production Dockerfile, docker-compose.prod.yml, and enterprise Kubernetes manifests (k8s/: Deployment with 2+ HA replicas, non-root user security context, ClusterIP service, NGINX Ingress with TLS, HPA autoscaler, ConfigMaps, Secrets).
• 📋 Clinical Notes Stack & History: Dedicated chronological notes stack in user profile with timestamps, single-click "Consult AI with Note" integration, and individual note management.
• 🧘 Pressure Relief / Calmness Mode: One-click toggle transforming workstation UI into a calm, glassmorphic teal layout with 100% smooth curved pill edges on all buttons, toggle segments, and controls.
• ⚖️ Clinical BMI Assessor & Profile Vitals: High-converting landing page teaser + in-app BMI calculator saving height, weight, BMI classification, and SBP impact to persistent user profile.
• 🔄 Server-Authoritative Data Persistence: Profiles, vitals, conversations, and messages are written to PostgreSQL and reloaded after login; the UI never creates synthetic local chats or fallback answers when the backend fails.
• 📱 Mobile Safari & Cross-Device Optimization: Full mobile responsive navigation and Safari Load failed network error handling for 100% sign-up and login reliability on mobile devices.
• 📊 Tabbed Evidence Panel: View citations with full provenance, executed tools, safety classification details, and raw knowledge paths.
• 👥 Clinician vs. Patient Modes: Toggle response persona between clinical detail (medical jargon, lab units) and plain-language patient education.
• 🔐 JWT Authentication & RBAC: Role-Based Access Control (Clinician, Patient, Admin) with bcrypt password security.
• ⚡ SSE Real-Time Streaming: Progressive response streaming via /api/query/stream.

---

Security & Safety

• 🛡️ Pre-LLM Safety Firewall: Deterministic query classification (app/safety/classifier.py) detecting prompt injections, system prompt hijacking, and unsafe medical requests before LLM execution.
• 🔒 Zero Code Key Leakage: All keys managed strictly via .env files.
• 🛑 Rate Limiting: Protects auth endpoints (/register 3/min, /login 10/min) using IP rate-limiting middleware.
• 🌐 CORS Configuration: Strictly restricted origin policies in production environments.
• 📑 Provenance Auditing: Every citation carries document versioning (review_date, effective_date, license_notes).
• ⚖️ Compliance Documentation: GDPR.md covers data controller info, legal basis, retention, user rights, and data sharing. ETHICS.md covers intended use, system limitations, responsible AI principles, and contact for concerns.

---

API Reference

Endpoint	Method	Description
/api/health	GET	System health check & OKF initialization status
/api/ready	GET	Readiness probe verifying DB & vector store state
/api/query	POST	Primary clinical RAG query endpoint
/api/query/stream	POST	Server-Sent Events (SSE) streaming query endpoint
/api/auth/register	POST	Create new user account with role selection
/api/auth/token	POST	OAuth2 password bearer token authentication
/api/auth/users/me	GET/PUT	Retrieve or update user profile, clinical notes & health vitals
/api/uploads	GET/POST	Upload or list clinical prescriptions, reports, & doctor notes
/api/chat/conversations	GET/POST	List or create persistent chat conversations
/api/chat/conversations/{id}	GET/DELETE	Retrieve or delete conversation message history
/api/sources	GET	List active guideline source registry & metadata
/api/eval/results	GET	View latest automated evaluation benchmark scores

---

Tech Stack

Client Layer:    React 18 | TypeScript 5 | Vite 8 | Tailwind CSS v3 | Lucide Icons
API & Core:      FastAPI | Uvicorn | Pydantic v2 | Python 3.12 | OpenAPI
MCP Server:      Model Context Protocol (MCP SDK 2.x) | Stdio JSON-RPC | Claude Desktop & Code
Agent Engine:    LangGraph Stateful DAG Orchestrator
Knowledge Layer: Open Knowledge Format (OKF) | 28 Concept Files | YAML + Wikilinks
Retrieval:       Cohere Embeddings v3.0 | BM25 Sparse | Cohere Rerank v3.5
Quality Harness: Pytest (252 passed, 10 skipped in the 2026-09-09 local run) | Vitest | Ruff | Pyright
 Persistence:     Server-Authoritative PostgreSQL (fail-closed prod) + SQLite (local dev) | Atomic Chat Turns
Deployment & Ops:Vercel (Frontend & Serverless) | Render | Neon PostgreSQL | Docker | Kubernetes (K8s) | GHCR

---

Quality Gates & Evaluation

The codebase is protected by automated quality gates running in CI:

# Run backend test suite
make test

# Run OKF concept validator (28 files, 0 errors)
make okf-check

# Run evaluation suite across 6 datasets (55 questions)
python -m app.evaluation.run

# Run frontend build check
cd frontend && npm run build

---

Deployment ($0/month)

Clinical Workflows is configured for zero-cost deployment across serverless and web service providers:

• Frontend: Vercel (Static SPA) — https://clinical-workflows.vercel.app
• Backend API (Vercel): Vercel Python Serverless Runtime (api/index.py)
• Backend API (Render): Render Free Web Service (render.yaml 1-click blueprint)
• Database: Neon Serverless PostgreSQL (pgvector) or SQLite
• LLM Tier: OpenRouter Free Tier / Deterministic Extractive Fallback Mode
• Container Registry: GitHub Container Registry (ghcr.io/jeevesh2515/clinical-rag-agent:latest)
• Orchestration: Production Kubernetes (k8s/: Deployments, Services, ConfigMaps, Secrets, Ingress, HPA)

Render 1-Click Setup:

Add OPENROUTER_API_KEY, COHERE_API_KEY, JWT_SECRET_KEY, DATABASE_URL to your Render environment variables or .env.

For step-by-step deployment instructions for Vercel, Render, Docker, and Kubernetes (K8s), see DEPLOYMENT_GUIDE.md.

---

Project Structure

.
├── .github/             # CI/CD workflows (pytest, ruff, OKF validation, Docker GHCR release, Neon DB preview)
├── app/
│   ├── agents/          # LangGraph agent, graph edges, citation validators
│   ├── api/             # FastAPI routers, routes, middleware
│   ├── auth/            # JWT authentication, bcrypt, RBAC
│   ├── evaluation/      # 55-question eval harness & LangSmith evaluators
│   ├── ingestion/       # Document chunker, manifest loader, source registry
│   ├── okf/             # OKF concept retriever, router, & wikilink parser
│   ├── retrieval/       # Hybrid BM25 + Cohere vector store
│   ├── safety/          # Intent classifier & refusal engine
│   └── tools/           # eGFR, MAP, Pulse Pressure, BMI calculators
├── clinical-rag-mcp/    # Model Context Protocol (MCP) server for Claude Desktop & Claude Code
├── frontend/            # React 18 + TypeScript + Tailwind v3 SPA
├── hypertension-okf/    # 28 Curated OKF concept files
├── k8s/                 # Kubernetes manifests (Deployment, Service, ConfigMap, Secrets, Ingress, HPA)
├── tests/               # automated pytest suite (including persistence regression coverage)
├── ETHICS.md            # Clinical disclaimer, intended use, responsible AI principles
├── GDPR.md              # Data controller info, legal basis, user rights, retention
├── Dockerfile           # Multi-stage production container build
├── docker-compose.yml   # Persistent Docker Compose with SQLite/pgvector profiles
├── docker-compose.prod.yml # Production Docker compose configuration
├── Makefile             # Development task commands
└── README.md            # Master repository documentation

---

Limitations & Disclaimer

• Hypertension Focus: Knowledge domain is currently specialized for chronic hypertension guidelines.
• Educational Tool: Synthetic scenarios only. Not approved for direct clinical decision support without formal institutional validation and HIPAA compliance controls.
• Compliance: See ETHICS.md for intended use, system limitations, and responsible AI principles. See GDPR.md for data processing, retention, and user rights.

---

License

Distributed under the MIT License. See LICENSE for details.

---

Built with ❤️ for safer medical AI architectures

Live Demo • GitHub Repository • Read Full Article on Medium