Spaces:
Running
Running
| title: Agentic RagBot | |
| emoji: 🏥 | |
| colorFrom: blue | |
| colorTo: indigo | |
| sdk: docker | |
| pinned: true | |
| license: mit | |
| app_port: 7860 | |
| tags: | |
| - medical | |
| - biomarker | |
| - rag | |
| - healthcare | |
| - langgraph | |
| - agents | |
| short_description: Multi-Agent RAG System for Medical Biomarker Analysis | |
| # MediGuard AI: Multi-Agent RAG System for Medical Biomarker Analysis | |
| A biomarker analysis system combining 6 specialized AI agents with medical knowledge retrieval (RAG) to provide evidence-based insights on blood test results. | |
| > **⚠️ Disclaimer:** This is an AI-assisted analysis tool, NOT a medical device. Always consult healthcare professionals for medical decisions. | |
| ## Key Features | |
| - **6 Specialist Agents** - Biomarker validation, disease scoring, RAG-powered explanation, confidence assessment | |
| - **Medical Knowledge Base** - Clinical guidelines stored in vector database (FAISS or OpenSearch) | |
| - **Multiple Interfaces** - Interactive CLI chat, REST API, Gradio web UI | |
| - **Evidence-Based** - All recommendations backed by retrieved medical literature with citations | |
| - **Free Cloud LLMs** - Uses Groq (LLaMA 3.3-70B) or Google Gemini - no API costs | |
| - **Biomarker Normalization** - 80+ aliases mapped to 24 canonical biomarker names | |
| - **Production Architecture** - Full error handling, safety alerts, confidence scoring | |
| ## Architecture Overview | |
| ``` | |
| ┌────────────────────────────────────────────────────────────────┐ | |
| │ MediGuard AI Pipeline │ | |
| ├────────────────────────────────────────────────────────────────┤ | |
| │ Input → Guardrail → Router → ┬→ Biomarker Analysis Path │ | |
| │ │ (6 specialist agents) │ | |
| │ └→ General Medical Q&A Path │ | |
| │ (RAG: retrieve → grade) │ | |
| │ → Response Synthesizer → Output │ | |
| └────────────────────────────────────────────────────────────────┘ | |
| ``` | |
| ### Disease Scoring | |
| The system uses **rule-based heuristics** (not ML models) to score disease likelihood: | |
| - Diabetes: Glucose > 126, HbA1c ≥ 6.5 | |
| - Anemia: Hemoglobin < 12, MCV < 80 | |
| - Heart Disease: Cholesterol > 240, Troponin > 0.04 | |
| - Thrombocytopenia: Platelets < 150,000 | |
| - Thalassemia: MCV + Hemoglobin pattern | |
| > **Note:** Future versions may include trained ML classifiers for improved accuracy. | |
| ## Quick Start | |
| **Installation (5 minutes):** | |
| ```bash | |
| # Clone & setup | |
| git clone https://github.com/yourusername/ragbot.git | |
| cd ragbot | |
| python -m venv .venv | |
| .venv\Scripts\activate # Windows | |
| pip install -r requirements.txt | |
| # Get free API key | |
| # 1. Sign up: https://console.groq.com/keys | |
| # 2. Copy API key to .env | |
| # Run setup | |
| python scripts/setup_embeddings.py | |
| # Start chatting | |
| python scripts/chat.py | |
| ``` | |
| See **[QUICKSTART.md](QUICKSTART.md)** for detailed setup instructions. | |
| ## Documentation | |
| | Document | Purpose | | |
| |----------|---------| | |
| | [**QUICKSTART.md**](QUICKSTART.md) | 5-minute setup guide | | |
| | [**CONTRIBUTING.md**](CONTRIBUTING.md) | How to contribute | | |
| | [**docs/ARCHITECTURE.md**](docs/ARCHITECTURE.md) | System design & components | | |
| | [**docs/API.md**](docs/API.md) | REST API reference | | |
| | [**docs/DEVELOPMENT.md**](docs/DEVELOPMENT.md) | Development & extension guide | | |
| | [**scripts/README.md**](scripts/README.md) | Utility scripts reference | | |
| | [**examples/README.md**](examples/) | Web/mobile integration examples | | |
| ## Usage | |
| ### Interactive CLI | |
| ```bash | |
| python scripts/chat.py | |
| You: My glucose is 140 and HbA1c is 10 | |
| Primary Finding: Diabetes (100% confidence) | |
| Critical Alerts: Hyperglycemia, elevated HbA1c | |
| Recommendations: Seek medical attention, lifestyle changes | |
| Actions: Physical activity, reduce carbs, weight loss | |
| ``` | |
| ### REST API | |
| ```bash | |
| # Start the unified production server | |
| uvicorn src.main:app --reload | |
| # Analyze biomarkers (structured input) | |
| curl -X POST http://localhost:8000/analyze/structured \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "biomarkers": {"Glucose": 140, "HbA1c": 10.0} | |
| }' | |
| # Ask medical questions (RAG-powered) | |
| curl -X POST http://localhost:8000/ask \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "question": "What does high HbA1c mean?" | |
| }' | |
| # Search knowledge base directly | |
| curl -X POST http://localhost:8000/search \ | |
| -H "Content-Type: application/json" \ | |
| -d '{ | |
| "query": "diabetes management guidelines", | |
| "top_k": 5 | |
| }' | |
| ``` | |
| See **[docs/API.md](docs/API.md)** for full API reference. | |
| ## Project Structure | |
| ``` | |
| RagBot/ | |
| ├── src/ # Core application | |
| │ ├── __init__.py | |
| │ ├── workflow.py # Multi-agent orchestration (LangGraph) | |
| │ ├── state.py # Pydantic state models | |
| │ ├── biomarker_validator.py # Validation logic | |
| │ ├── biomarker_normalization.py # Name normalization (80+ aliases) | |
| │ ├── llm_config.py # LLM/embedding provider config | |
| │ ├── pdf_processor.py # Vector store management | |
| │ ├── config.py # Global configuration | |
| │ └── agents/ # 6 specialist agents | |
| │ ├── __init__.py | |
| │ ├── biomarker_analyzer.py | |
| │ ├── disease_explainer.py | |
| │ ├── biomarker_linker.py | |
| │ ├── clinical_guidelines.py | |
| │ ├── confidence_assessor.py | |
| │ └── response_synthesizer.py | |
| │ | |
| ├── api/ # REST API (FastAPI) | |
| │ ├── app/main.py # FastAPI server | |
| │ ├── app/routes/ # API endpoints | |
| │ ├── app/models/schemas.py # Pydantic request/response schemas | |
| │ └── app/services/ # Business logic | |
| │ | |
| ├── scripts/ # Utilities | |
| │ ├── chat.py # Interactive CLI chatbot | |
| │ └── setup_embeddings.py # Vector store builder | |
| │ | |
| ├── config/ # Configuration | |
| │ └── biomarker_references.json # 24 biomarker reference ranges | |
| │ | |
| ├── data/ # Data storage | |
| │ ├── medical_pdfs/ # Source documents | |
| │ └── vector_stores/ # FAISS database | |
| │ | |
| ├── tests/ # Test suite (30 tests) | |
| ├── examples/ # Integration examples | |
| ├── docs/ # Documentation | |
| │ | |
| ├── QUICKSTART.md # Setup guide | |
| ├── CONTRIBUTING.md # Contribution guidelines | |
| ├── requirements.txt # Python dependencies | |
| └── LICENSE | |
| ``` | |
| ## Technology Stack | |
| | Component | Technology | Purpose | | |
| |-----------|-----------|---------| | |
| | Orchestration | **LangGraph** | Multi-agent workflow control | | |
| | LLM | **Groq (LLaMA 3.3-70B)** | Fast, free inference | | |
| | LLM (Alt) | **Google Gemini 2.0 Flash** | Free alternative | | |
| | Embeddings | **HuggingFace / Jina / Google** | Vector representations | | |
| | Vector DB | **FAISS** (local) / **OpenSearch** (production) | Similarity search | | |
| | API | **FastAPI** | REST endpoints | | |
| | Web UI | **Gradio** | Interactive analysis interface | | |
| | Validation | **Pydantic V2** | Type safety & schemas | | |
| | Cache | **Redis** (optional) | Response caching | | |
| | Observability | **Langfuse** (optional) | LLM tracing & monitoring | | |
| ## How It Works | |
| ``` | |
| User Input ("My glucose is 140...") | |
| │ | |
| ▼ | |
| ┌──────────────────────────────────────┐ | |
| │ Biomarker Extraction & Normalization │ ← LLM parses text, maps 80+ aliases | |
| └──────────────────────────────────────┘ | |
| │ | |
| ▼ | |
| ┌──────────────────────────────────────┐ | |
| │ Disease Scoring (Rule-Based) │ ← Heuristic scoring, NOT ML | |
| └──────────────────────────────────────┘ | |
| │ | |
| ▼ | |
| ┌──────────────────────────────────────┐ | |
| │ RAG Knowledge Retrieval │ ← FAISS/OpenSearch vector search | |
| └──────────────────────────────────────┘ | |
| │ | |
| ▼ | |
| ┌──────────────────────────────────────┐ | |
| │ 6-Agent LangGraph Pipeline │ | |
| │ ├─ Biomarker Analyzer (validation) │ | |
| │ ├─ Disease Explainer (pathophysiology)│ | |
| │ ├─ Biomarker Linker (key drivers) │ | |
| │ ├─ Clinical Guidelines (treatment) │ | |
| │ ├─ Confidence Assessor (reliability) │ | |
| │ └─ Response Synthesizer (final) │ | |
| └──────────────────────────────────────┘ | |
| │ | |
| ▼ | |
| ┌──────────────────────────────────────┐ | |
| │ Structured Response + Safety Alerts │ | |
| └──────────────────────────────────────┘ | |
| ``` | |
| ## Supported Biomarkers (24) | |
| - **Glucose Control**: Glucose, HbA1c, Insulin | |
| - **Lipids**: Cholesterol, LDL Cholesterol, HDL Cholesterol, Triglycerides | |
| - **Body Metrics**: BMI | |
| - **Blood Cells**: Hemoglobin, Platelets, White Blood Cells, Red Blood Cells, Hematocrit | |
| - **RBC Indices**: Mean Corpuscular Volume, Mean Corpuscular Hemoglobin, MCHC | |
| - **Cardiovascular**: Heart Rate, Systolic Blood Pressure, Diastolic Blood Pressure, Troponin | |
| - **Inflammation**: C-reactive Protein | |
| - **Liver**: ALT, AST | |
| - **Kidney**: Creatinine | |
| See [config/biomarker_references.json](config/biomarker_references.json) for full reference ranges. | |
| ## Disease Coverage | |
| - Diabetes | |
| - Anemia | |
| - Heart Disease | |
| - Thrombocytopenia | |
| - Thalassemia | |
| - (Extensible - add custom domains) | |
| ## Privacy & Security | |
| - All processing runs **locally** after setup | |
| - No personal health data stored | |
| - Embeddings computed locally or cached | |
| - Vector store derived from public medical literature | |
| - Can operate completely offline with Ollama provider | |
| ## Performance | |
| - **Response Time**: 15-25 seconds (6 agents + RAG retrieval) | |
| - **Knowledge Base**: 750 pages, 2,609 document chunks | |
| - **Cost**: Free (Groq/Gemini API + local/cloud embeddings) | |
| - **Hardware**: CPU-only (no GPU needed) | |
| ## Testing | |
| ```bash | |
| # Run unit tests (30 tests) | |
| .venv\Scripts\python.exe -m pytest tests/ -q \ | |
| --ignore=tests/test_basic.py \ | |
| --ignore=tests/test_diabetes_patient.py \ | |
| --ignore=tests/test_evolution_loop.py \ | |
| --ignore=tests/test_evolution_quick.py \ | |
| --ignore=tests/test_evaluation_system.py | |
| # Run specific test file | |
| .venv\Scripts\python.exe -m pytest tests/test_codebase_fixes.py -v | |
| # Run all tests (includes integration tests requiring LLM API keys) | |
| .venv\Scripts\python.exe -m pytest tests/ -v | |
| ``` | |
| ## Contributing | |
| Contributions welcome! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for: | |
| - Code style guidelines | |
| - Pull request process | |
| - Testing requirements | |
| - Development setup | |
| ## Development | |
| Want to extend RagBot? | |
| - **Add custom biomarkers**: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#adding-a-new-biomarker) | |
| - **Add medical domains**: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#adding-a-new-medical-domain) | |
| - **Create custom agents**: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#creating-a-custom-analysis-agent) | |
| - **Switch LLM providers**: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md#switching-llm-providers) | |
| ## License | |
| MIT License - See [LICENSE](LICENSE) | |
| ## Resources | |
| - [LangGraph Documentation](https://langchain-ai.github.io/langgraph/) | |
| - [Groq API Docs](https://console.groq.com) | |
| - [FAISS GitHub](https://github.com/facebookresearch/faiss) | |
| - [FastAPI Guide](https://fastapi.tiangolo.com/) | |
| --- | |
| **Ready to get started?** -> [QUICKSTART.md](QUICKSTART.md) | |
| **Want to understand the architecture?** -> [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | |
| **Looking to integrate with your app?** -> [examples/README.md](examples/) | |