README.md

MAI Diagnostic Orchestrator (MAI-DxO)

An open-source implementation of Microsoft Research's "Sequential Diagnosis with Language Models" paper, built with the Swarms AI framework.

MAI-DxO (MAI Diagnostic Orchestrator) is a sophisticated AI-powered diagnostic system that simulates a virtual panel of physician-agents to perform iterative medical diagnosis with cost-effectiveness optimization. This implementation faithfully reproduces the methodology described in the Microsoft Research paper while providing additional features and flexibility.

✨ Key Features

• 8 AI Physician Agents: Specialized roles for comprehensive diagnosis.
• 5 Operational Modes: Instant, question-only, budgeted, no-budget, and ensemble modes.
• Cost Tracking: Real-time budget monitoring with costs for 25+ medical tests.
• Clinical Evaluation: 5-point accuracy scoring with detailed feedback.
• Model Agnostic: Works with GPT, Gemini, Claude, and other leading LLMs.

🚀 Quick Start

1. Installation

Install the package directly via pip:

pip install mai-dx

Or, for development, clone the repository and install the requirements:

git clone https://github.com/The-Swarm-Corporation/Open-MAI-Dx-Orchestrator.git
cd Open-MAI-Dx-Orchestrator
pip install -r requirements.txt

2. Environment Setup

Create a .env file in your project root and add your API keys:

OPENAI_API_KEY="Your OpenAI API key"
GEMINI_API_KEY="Your Gemini API key"
ANTHROPIC_API_KEY="Your Anthropic API key"

3. Basic Usage

from mai_dx import MaiDxOrchestrator

# Create the orchestrator (defaults to a capable model)
orchestrator = MaiDxOrchestrator()

# Run a diagnosis
result = orchestrator.run(
    initial_case_info="29-year-old woman with sore throat and peritonsillar swelling...",
    full_case_details="Patient: 29-year-old female. History: Onset of sore throat...",
    ground_truth_diagnosis="Embryonal rhabdomyosarcoma of the pharynx"
)

# Print the results
print(f"Final Diagnosis: {result.final_diagnosis}")
print(f"Accuracy: {result.accuracy_score}/5.0")
print(f"Total Cost: ${result.total_cost:,.2f}")

⚙️ Advanced Usage & Configuration

Customize the orchestrator's model, budget, and operational mode.

from mai_dx import MaiDxOrchestrator

# Configure with a specific model and budget
orchestrator = MaiDxOrchestrator(
    model_name="gemini/gemini-2.5-flash",  # or "gpt-4", "claude-3-5-sonnet"
    max_iterations=10,
    initial_budget=3000,
    mode="budgeted"  # Other modes: "instant", "question_only", "no_budget"
)

# Run the diagnosis
# ...

🏥 How It Works: The Virtual Physician Panel

MAI-DxO employs a multi-agent system where each agent has a specific role:

• 🧠 Dr. Hypothesis: Maintains the differential diagnosis.
• 🔬 Dr. Test-Chooser: Selects the most cost-effective diagnostic tests.
• 🤔 Dr. Challenger: Prevents cognitive biases and diagnostic errors.
• 💰 Dr. Stewardship: Ensures cost-effective care.
• ✅ Dr. Checklist: Performs quality control checks.
• 🤝 Consensus Coordinator: Synthesizes panel decisions.
• 🔑 Gatekeeper: Acts as the clinical information oracle.
• ⚖️ Judge: Evaluates the final diagnostic accuracy.

Documentation

Learn more about this repository with the docs

🤝 Contributing

We welcome contributions! Please feel free to open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

📚 Citation

If you use this work in your research, please cite both the original paper and this software implementation.

@misc{nori2025sequentialdiagnosislanguagemodels,
    title={Sequential Diagnosis with Language Models}, 
    author={Harsha Nori and Mayank Daswani and Christopher Kelly and Scott Lundberg and Marco Tulio Ribeiro and Marc Wilson and Xiaoxuan Liu and Viknesh Sounderajah and Jonathan Carlson and Matthew P Lungren and Bay Gross and Peter Hames and Mustafa Suleyman and Dominic King and Eric Horvitz},
    year={2025},
    eprint={2506.22405},
    archivePrefix={arXiv},
    primaryClass={cs.CL},
    url={https://arxiv.org/abs/2506.22405}, 
}

@software{mai_dx_orchestrator,
    title={Open-MAI-Dx-Orchestrator: An Open Source Implementation of Sequential Diagnosis with Language Models},
    author={The-Swarm-Corporation},
    year={2025},
    url={https://github.com/The-Swarm-Corporation/Open-MAI-Dx-Orchestrator.git}
}

🔗 Related Work

• Original Paper - Sequential Diagnosis with Language Models
• Swarms Framework - Multi-agent AI orchestration
• Microsoft Research - Original research institution

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: Full Documentation

---

Built with Swarms for advancing AI-powered medical diagnosis