README.md

metadata

title: MediGuard AI
emoji: 🏥
colorFrom: blue
colorTo: green
sdk: docker
sdk_version: '3.13'
python_version: '3.13'
app_file: app.py
pinned: false
license: mit

MediGuard AI: Multi-Agent RAG System for Medical Biomarker Analysis

⚠️ Disclaimer: This is an AI-assisted analysis tool, NOT a medical device. Always consult healthcare professionals for medical decisions.

A production-ready biomarker analysis system combining 6 specialized AI agents with medical knowledge retrieval (RAG) to provide evidence-based insights on blood test results.

🚀 Quick Start

Prerequisites

• Python 3.13+
• 8GB+ RAM
• Ollama (for local LLM) or Groq API key

Installation (5 minutes)

# Clone the repository
git clone https://github.com/yourusername/Agentic-RagBot.git
cd Agentic-RagBot

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# or
.venv\\Scripts\\activate  # Windows

# Install dependencies
pip install -r requirements.txt

# Configure environment (copy .env.example to .env)
cp .env.example .env
# Edit .env with your API keys

# Initialize embeddings
python scripts/setup_embeddings.py

# Start the application
python -m src.main

Docker Alternative

# Build and run with Docker
docker build -t mediguard-ai .
docker run -p 8000:8000 -p 7860:7860 mediguard-ai

🏗️ Architecture

Multi-Agent Workflow

Input → Validation → ┌─────────────────────────────────┐ → Output
                    │     6 Specialist Agents        │
                    ├─────────────────────────────────┤
                    │ • Biomarker Analyzer            │
                    │ • Disease Explainer            │
                    │ • Biomarker Linker             │
                    │ • Clinical Guidelines Agent    │
                    │ • Confidence Assessor          │
                    │ • Response Synthesizer         │
                    └─────────────────────────────────┘

Key Components

• Agents: 6 specialized AI agents for different analysis aspects
• Knowledge Base: Medical literature in vector database (FAISS/OpenSearch)
• State Management: LangGraph for workflow orchestration
• API Layer: FastAPI with async support
• Web UI: Gradio interface for interactive use

📊 Features

• 🧬 Biomarker Analysis: Analyzes 80+ biomarker aliases mapped to 24 canonical names
• 🎯 Disease Scoring: Rule-based heuristics for 5 major conditions
• 📚 Evidence-Based: All recommendations backed by medical literature
• 🔒 HIPAA Compliant: Audit logging and security headers
• 🚀 Production Ready: Error handling, monitoring, and scalability
• 🔧 Configurable: Environment-based configuration
• 📖 Multiple Interfaces: CLI, REST API, and Web UI

🎯 Disease Detection

The system uses rule-based heuristics to score disease likelihood:

Disease	Key Indicators	Threshold
Diabetes	Glucose, HbA1c	Glucose > 126, HbA1c ≥ 6.5
Anemia	Hemoglobin, MCV	Hgb < 12, MCV < 80
Heart Disease	Cholesterol, Troponin	Chol > 240, Troponin > 0.04
Thrombocytopenia	Platelets	Platelets < 150,000
Thalassemia	MCV + Hgb pattern	MCV < 80 + Hgb < 12

🛠️ Usage

REST API

# Start the server
uvicorn src.main:app --reload

# Analyze biomarkers
curl -X POST http://localhost:8000/analyze/structured \\
  -H "Content-Type: application/json" \\
  -d '{"biomarkers": {"Glucose": 140, "HbA1c": 10.0}}'

# Ask medical questions
curl -X POST http://localhost:8000/ask \\
  -H "Content-Type: application/json" \\
  -d '{"question": "What does high HbA1c mean?"}'

Python SDK

from src.workflow import create_guild
from src.state import PatientInput

# Create workflow
guild = create_guild()

# Analyze patient data
patient_input = PatientInput(
    biomarkers={"Glucose": 140, "HbA1c": 10.0},
    patient_context={"age": 45, "gender": "male"},
    model_prediction={"disease": "Diabetes", "confidence": 0.9}
)

result = guild.run(patient_input)
print(result["final_response"])

Web Interface

# Launch Gradio UI
python -m src.gradio_app
# Visit http://localhost:7860

📁 Project Structure

Agentic-RagBot/
├── src/
│   ├── agents/          # Agent implementations
│   ├── services/        # Core services (retrieval, embeddings)
│   ├── routers/         # FastAPI endpoints
│   ├── models/          # Data models
│   ├── state.py         # State management
│   ├── workflow.py      # Workflow orchestration
│   └── main.py          # Application entry point
├── tests/               # Test suite (58% coverage)
├── scripts/             # Utility scripts
├── docs/                # Documentation
├── data/                # Data files
└── docker/              # Docker configurations

🧪 Testing

# Run all tests
pytest tests/

# Run with coverage
pytest tests/ --cov=src --cov-report=html

# Run specific test suites
pytest tests/test_agents.py
pytest tests/test_workflow.py

🔧 Configuration

Key environment variables:

# API Configuration
API__HOST=127.0.0.1
API__PORT=8000

# LLM Configuration
GROQ_API_KEY=your_groq_key
# or
OLLAMA_BASE_URL=http://localhost:11434

# Database
OPENSEARCH_HOST=localhost
OPENSEARCH_PORT=9200

# Cache
REDIS_URL=redis://localhost:6379

📈 Performance

• Response Time: < 2 seconds for typical analysis
• Throughput: 100+ concurrent requests
• Memory Usage: ~2GB base + embeddings
• Test Coverage: 58% (148 passing tests)

🔒 Security

• HIPAA-compliant audit logging
• Security headers middleware
• Input validation and sanitization
• No hardcoded secrets
• Regular security scans (Bandit)

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

See DEVELOPMENT.md for detailed guidelines.

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

• Medical literature from NIH and WHO
• LangChain and LangGraph for agent framework
• FAISS for vector similarity search
• FastAPI for web framework

📞 Support

• 📧 Email: support@mediguard-ai.com
• 📖 Documentation: docs/
• 🐛 Issues: GitHub Issues

---

⚡ Ready to deploy? See DEPLOYMENT.md for production deployment guide.