# DoWhy MCP v2.0 - Rigorous Causal Inference Tools

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![DoWhy](https://img.shields.io/badge/DoWhy-0.11+-green.svg)](https://github.com/py-why/dowhy)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

## 🎯 Project Vision

DoWhy MCP v2.0 is a **complete rewrite** of the DoWhy MCP server, designed to provide **rigorous, theoretically-grounded causal inference tools** through the Model Context Protocol (MCP). This version matches the **scientific rigor and theoretical depth** of the official DoWhy library.

## 🔬 Theoretical Foundation

Built on the solid theoretical foundations of:
- **Structural Causal Models (SCM)** - Pearl's causal hierarchy
- **Graphical Causal Models (GCM)** - Modern causal discovery and inference
- **Potential Outcomes Framework** - Rubin's causal model
- **Do-Calculus** - Formal causal reasoning

## 🚀 Key Features

### ✅ What's New in v2.0

- **🧮 Rigorous Statistical Inference**: True Bootstrap confidence intervals, not noise simulation
- **🔍 Comprehensive Sensitivity Analysis**: Full suite of refutation tests and E-value analysis
- **📊 Complete Causal Toolkit**: 42 specialized tools covering all DoWhy functionality
- **🎯 Theoretical Rigor**: Every method backed by solid causal inference theory
- **⚡ Performance Optimized**: Efficient implementation with proper error handling
- **📈 Advanced Visualization**: Causal graphs, attribution plots, and diagnostic charts

### 🛠️ Complete Tool Categories

1. **Modeling Tools** (6 tools)
   - Causal graph construction and validation
   - Structural and Graphical Causal Models
   - Causal mechanism learning

2. **Causal Effect Estimation** (10 tools)
   - Backdoor, frontdoor, and IV identification
   - Linear regression, PSM, doubly robust, DML
   - Causal forests and TMLE

3. **Causal Influence Quantification** (6 tools)
   - Shapley value attribution
   - Direct and total causal influence
   - Path-specific effects

4. **Root Cause Analysis** (5 tools)
   - Anomaly attribution
   - Distribution change attribution
   - Causal chain tracing

5. **Counterfactual Analysis** (6 tools)
   - Individual and population counterfactuals
   - Intervention simulation
   - What-if scenario analysis

6. **Sensitivity Analysis** (6 tools)
   - Unobserved confounder analysis
   - Comprehensive refutation tests
   - E-value and tipping point analysis

7. **Causal Discovery** (3 tools)
   - PC, GES, and FCM algorithms
   - Structure learning from data

## 📋 Installation

```bash
# Install from source (development)
git clone https://github.com/dowhy-mcp/dowhy-mcp-v2.git
cd dowhy-mcp-v2
pip install -e ".[dev]"

# Install from PyPI (when released)
pip install dowhy-mcp-v2
```

## 🔧 Quick Start

```python
from dowhy_mcp_v2 import DoWhyCausalAnalyzer

# Initialize analyzer
analyzer = DoWhyCausalAnalyzer()

# Estimate causal effect with full rigor
result = analyzer.estimate_causal_effect(
    data="data.csv",
    treatment="intervention",
    outcome="result",
    confounders=["age", "gender", "income"],
    method="doubly_robust",
    bootstrap_samples=1000,
    sensitivity_analysis=True
)

# Get comprehensive results
print(f"Causal Effect: {result.causal_effect:.4f}")
print(f"95% CI: [{result.confidence_interval[0]:.4f}, {result.confidence_interval[1]:.4f}]")
print(f"P-value: {result.p_value:.4f}")
print(f"Robustness Score: {result.robustness_score:.2f}")
```

## 🏗️ Architecture

```
DoWhy MCP v2.0
├── Core Engine              # Causal inference engine
│   ├── Model Builder       # SCM/GCM construction
│   ├── Inference Engine    # Causal reasoning
│   └── Validation Framework # Result verification
├── Tool Modules            # 42 specialized tools
│   ├── Modeling           # Graph and model tools
│   ├── Estimation         # Effect estimation
│   ├── Attribution        # Influence quantification
│   ├── Root Cause         # Anomaly analysis
│   ├── Counterfactual     # What-if analysis
│   ├── Sensitivity        # Robustness testing
│   └── Discovery          # Structure learning
└── MCP Interface          # Protocol integration
```

## 📊 Comparison with v1.0

| Feature | v1.0 | v2.0 |
|---------|------|------|
| Theoretical Rigor | Basic | ✅ Complete |
| Bootstrap CI | ❌ Fake noise | ✅ True Bootstrap |
| Sensitivity Analysis | ❌ Simplified | ✅ Comprehensive |
| Causal Graphs | ❌ Limited | ✅ Full Support |
| Tool Count | 4 basic | 42 rigorous |
| Statistical Tests | ❌ Missing | ✅ Complete Suite |
| Error Handling | ❌ Basic | ✅ Robust |
| Documentation | ❌ Minimal | ✅ Comprehensive |

## 🧪 Testing & Validation

- **Unit Tests**: 95%+ coverage with rigorous testing
- **Integration Tests**: End-to-end workflow validation  
- **Benchmark Tests**: Performance and accuracy benchmarks
- **Theoretical Tests**: Validation against known causal results

## 📚 Documentation

- [📖 User Guide](docs/user_guide.md)
- [🔬 Theoretical Background](docs/theory/)
- [🛠️ API Reference](docs/api/)
- [📝 Examples](docs/examples/)

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [DoWhy Team](https://github.com/py-why/dowhy) for the foundational causal inference library
- [Judea Pearl](http://bayes.cs.ucla.edu/jp_home.html) for causal inference theory
- [Microsoft Research](https://www.microsoft.com/en-us/research/) for DoWhy development

## 📞 Support

- 🐛 [Report Issues](https://github.com/dowhy-mcp/dowhy-mcp-v2/issues)
- 💬 [Discussions](https://github.com/dowhy-mcp/dowhy-mcp-v2/discussions)
- 📧 Email: support@dowhy-mcp.org

---

**DoWhy MCP v2.0** - Where Rigorous Science Meets Practical Application