Spaces:
Sleeping
title: ClearVoice API
emoji: 🔬
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
🔬 ClearVoice — AI-Powered Medical Misinformation Checker
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
git clone https://github.com/MananBabbar07/ClearVoice.git
cd ClearVoice
Create Virtual Environment
python -m venv venv
Windows
venv\Scripts\activate
Linux / macOS
source venv/bin/activate
Install Dependencies
pip install -r requirements.txt
Configure Environment Variables
Create a .env file.
GROQ_API_KEY=your_key
DATABASE_URL=your_supabase_url
REDIS_URL=your_upstash_url
NCBI_EMAIL=your_email
Run Backend
uvicorn backend.main:app --reload
Run Frontend
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 ⭐.