Verify health claims using live peer-reviewed medical evidence.
--- ## ๐ Overview **ClearVoice** is an AI-powered medical misinformation checker that evaluates health claims against **live peer-reviewed PubMed research** using a multi-agent retrieval and reasoning pipeline. Unlike traditional RAG systems that rely on a static vector database, ClearVoice searches **PubMed in real time**, retrieves the latest relevant studies, evaluates their quality, and generates an evidence-based verdict with transparent reasoning. Every prediction includes: - โ Final verdict - ๐ Supporting research papers - ๐งฌ Study types - โญ Evidence quality scores - โ๏ธ Whether studies support or contradict the claim - ๐ฌ Plain-English explanation - ๐ฏ Practical takeaway --- # โจ Features ### ๐ Live Medical Evidence Retrieval - Searches PubMed in real time - Uses the latest peer-reviewed studies - No stale offline database ### ๐ง PubMedBERT Semantic Search Medical-domain embeddings provide significantly better retrieval than generic embedding models. - Model: **NeuML/pubmedbert-base-embeddings** - 768-dimensional embeddings --- ### ๐ค Multi-Agent AI Pipeline Instead of a single LLM prompt, ClearVoice uses specialized AI agents. | Agent | Responsibility | |---------|---------------| | **Decomposer Agent** | Splits complex medical claims into simpler subclaims | | **Verdict Agent** | Determines TRUE / FALSE / MISLEADING | | **Judge Agent** | Scores evidence quality and determines stance | | **Explainer Agent** | Produces easy-to-understand explanations | --- ### ๐ Evidence Transparency Every retrieved paper includes: - Study Type - Evidence Quality (1โ5) - Supports / Contradicts / Neutral - Confidence Examples: - Meta-analysis - Systematic Review - Randomized Controlled Trial - Cohort Study - Case-Control Study --- ### ๐งพ Plain English Explanations Medical literature is translated into language that non-experts can understand. Each response contains: - Why the claim received its verdict - What researchers found - Practical takeaway --- ### โก Multi-Model LLM Fallback If one Groq model becomes unavailable or rate-limited, ClearVoice automatically switches to another model. Fallback chain: ``` Llama-3.3-70B โ Llama-4-Scout โ GPT-OSS-120B โ Llama-3.1-8B ``` --- ### ๐ Redis Caching Repeated claims are cached for 24 hours. Benefits: - <100ms responses - Reduced API cost - Lower latency --- # ๐๏ธ System Architecture ``` User Claim โ โผ Redis Cache Lookup โ โ Hit Miss โ โผ Return Cached Decomposer Agent Result โ โผ Live PubMed Retrieval โ โผ PubMedBERT Embeddings โ โผ Retrieve Top Papers โ โโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโ โผ โผ Verdict Agent Judge Agent โ โ โโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโ โผ Verdict Override Logic (Mixed Evidence โ MISLEADING) โ โผ Explainer Agent โ โผ Cache Response in Redis โ โผ Return to Frontend ``` --- # ๐ Performance | Metric | Phase 1 | Phase 2 | |----------|---------|----------| | Accuracy | 60% | 90%+ | | Embeddings | MiniLM (384d) | PubMedBERT (768d) | | Retrieval | Pre-ingested DB | Live PubMed | | Avg Response Time | 4.19s | ~10s | | Cached Response | N/A | <100ms | | MISLEADING Detection | 0% | 100% | | Errors | 2/10 | 0/10 | --- # ๐ Development Journey ## Phase 1 โ Baseline RAG Implemented: - FastAPI backend - PubMed ingestion - MiniLM embeddings - Supabase pgvector - Groq LLM - Redis cache - Streamlit frontend Result: - 60% benchmark accuracy --- ## Phase 2 โ Medical RAG Major improvements: - PubMedBERT embeddings - Live PubMed retrieval - Multi-agent reasoning - Judge agent - Decomposer - Explainer - Verdict override logic - Multi-model fallback Result: - 90%+ benchmark accuracy --- ## Phase 3 โ Modern Frontend Current version includes: - React - Vite - Tailwind CSS - Responsive UI - Evidence cards - Complex claim visualization Deployment: - Frontend โ Vercel - Backend โ Hugging Face Spaces --- ## Phase 4 (Planned) - ๐ค Whisper voice input - ๐ Chrome Extension - ๐ฑ Mobile responsive improvements - ๐ 50+ benchmark dataset - ๐ User analytics dashboard --- # ๐ Tech Stack | Layer | Technology | |---------|-------------| | Frontend | React + Vite + Tailwind CSS | | Backend | FastAPI | | Deployment | Hugging Face Spaces + Vercel | | Embeddings | PubMedBERT | | Vector Database | Supabase pgvector | | Retrieval | PubMed + Biopython Entrez | | LLM | Groq API | | Cache | Upstash Redis | | Language | Python | --- # ๐ Project Structure ``` ClearVoice โ โโโ backend โ โโโ main.py โ โ โ โโโ app โ โโโ retrieval.py โ โโโ verify.py โ โโโ groq_client.py โ โ โ โโโ agents โ โโโ decomposer.py โ โโโ judge.py โ โโโ explainer.py โ โโโ frontend-react โ โโโ frontend โ โโโ benchmark.py โ โโโ accuracy.py โ โโโ BENCHMARKS.md ``` --- # โ๏ธ Installation ## Clone Repository ```bash git clone https://github.com/MananBabbar07/ClearVoice.git cd ClearVoice ``` --- ## Create Virtual Environment ```bash python -m venv venv ``` Windows ```bash venv\Scripts\activate ``` Linux / macOS ```bash source venv/bin/activate ``` --- ## Install Dependencies ```bash pip install -r requirements.txt ``` --- ## Configure Environment Variables Create a `.env` file. ```env GROQ_API_KEY=your_key DATABASE_URL=your_supabase_url REDIS_URL=your_upstash_url NCBI_EMAIL=your_email ``` --- ## Run Backend ```bash uvicorn backend.main:app --reload ``` --- ## Run Frontend ```bash cd frontend-react npm install npm run dev ``` --- # ๐งช Example Claim Input: > **"Vitamin C prevents the common cold."** Output: ``` Verdict: MISLEADING Reason: Vitamin C does not prevent colds in the general population, although it may slightly reduce duration in certain individuals. Evidence: โ Meta-analysis (Quality 5/5) โ Randomized Controlled Trial (4/5) โ One contradictory cohort study Overall Confidence: High ``` ``` screenshots/ โโโ homepage.png โโโ result.png โโโ evidence_cards.png โโโ decomposition.png ``` --- # ๐ฎ Future Work - Voice-based medical verification - Browser extension - Larger benchmark dataset - Medical citation export - PDF report generation - User authentication - Saved history - API rate limiting --- # ๐จโ๐ป Author **Manan Babbar** GitHub: https://github.com/MananBabbar07 --- # โญ If you found this project useful... Please consider giving the repository a **Star โญ**.