Metadata-Version: 2.4
Name: statistical-causal-inference
Version: 4.3.0
Summary: Production-ready causal attribution and inference API with comprehensive monitoring, testing, and LLM integration
Home-page: https://github.com/rdmurugan/causalattribution
Author: CausalAttribution Team
Author-email: CausalAttribution Team <durai@infinidatum.net>
Project-URL: Homepage, https://github.com/rdmurugan/causalattribution
Project-URL: Bug Tracker, https://github.com/rdmurugan/causalattribution/issues
Project-URL: Repository, https://github.com/rdmurugan/causalattribution
Keywords: causal-inference,machine-learning,statistics,llm,artificial-intelligence,monitoring,testing,property-based-testing,benchmarking,mutation-testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: networkx>=2.6.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: matplotlib>=3.3.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: openai>=1.0.0
Requires-Dist: numba>=0.56.0
Requires-Dist: dask>=2022.1.0
Requires-Dist: psutil>=5.8.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: pyarrow>=10.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: testing
Requires-Dist: hypothesis>=6.0.0; extra == "testing"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "testing"
Requires-Dist: mutmut>=2.0.0; extra == "testing"
Requires-Dist: pytest-xdist>=3.0.0; extra == "testing"
Requires-Dist: pytest-mock>=3.0.0; extra == "testing"
Provides-Extra: plugins
Requires-Dist: langchain>=0.0.200; extra == "plugins"
Requires-Dist: llama-index>=0.7.0; extra == "plugins"
Requires-Dist: transformers>=4.20.0; extra == "plugins"
Requires-Dist: torch>=1.11.0; extra == "plugins"
Provides-Extra: ui
Requires-Dist: streamlit>=1.25.0; extra == "ui"
Requires-Dist: dash>=2.10.0; extra == "ui"
Requires-Dist: gradio>=3.35.0; extra == "ui"
Provides-Extra: api
Requires-Dist: fastapi>=0.104.0; extra == "api"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "api"
Requires-Dist: pydantic>=2.0.0; extra == "api"
Requires-Dist: redis>=5.0.0; extra == "api"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "api"
Provides-Extra: marketing
Requires-Dist: google-ads>=22.0.0; extra == "marketing"
Requires-Dist: facebook-business>=18.0.0; extra == "marketing"
Requires-Dist: google-analytics-data>=0.18.0; extra == "marketing"
Requires-Dist: requests>=2.31.0; extra == "marketing"
Provides-Extra: full
Requires-Dist: langchain>=0.0.200; extra == "full"
Requires-Dist: llama-index>=0.7.0; extra == "full"
Requires-Dist: transformers>=4.20.0; extra == "full"
Requires-Dist: torch>=1.11.0; extra == "full"
Requires-Dist: streamlit>=1.25.0; extra == "full"
Requires-Dist: dash>=2.10.0; extra == "full"
Requires-Dist: gradio>=3.35.0; extra == "full"
Requires-Dist: anthropic>=0.7.0; extra == "full"
Requires-Dist: hypothesis>=6.0.0; extra == "full"
Requires-Dist: pytest-benchmark>=4.0.0; extra == "full"
Requires-Dist: mutmut>=2.0.0; extra == "full"
Requires-Dist: pytest-xdist>=3.0.0; extra == "full"
Requires-Dist: pytest-mock>=3.0.0; extra == "full"
Requires-Dist: fastapi>=0.104.0; extra == "full"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "full"
Requires-Dist: pydantic>=2.0.0; extra == "full"
Requires-Dist: redis>=5.0.0; extra == "full"
Requires-Dist: psycopg2-binary>=2.9.0; extra == "full"
Requires-Dist: google-ads>=22.0.0; extra == "full"
Requires-Dist: facebook-business>=18.0.0; extra == "full"
Requires-Dist: google-analytics-data>=0.18.0; extra == "full"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# CausalAttribution API

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![API Status](https://img.shields.io/badge/API-Live-success)](https://causalattribution.onrender.com)
[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

**Production-ready causal inference and multi-touch attribution API** powered by peer-reviewed statistical methods and modern machine learning.

🌐 **Live API:** https://causalattribution.onrender.com
📚 **Documentation:** https://causalattribution.onrender.com/docs

---

## ✅ Current Status (October 5, 2025)

| Component | Status | Notes |
|-----------|--------|-------|
| **API Service** | ✅ Live | Deployed on Render.com |
| **Database** | ✅ Operational | Neon PostgreSQL with MLOps tables |
| **All 8 Features** | ✅ Verified | PC Algorithm, PSM, IV, Doubly Robust, Shapley, etc. |
| **Authentication** | ✅ Working | API key management system |
| **MLOps** | ✅ Operational | Automatic logging, drift detection ready |

---

## 🚀 Quick Start

### 1. Get API Key

Contact: durai@infinidatum.net for API access

### 2. Multi-Touch Attribution

```bash
curl https://causalattribution.onrender.com/api/v1/attribution \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "touchpoints": [
      {"customer_id": "c1", "timestamp": "2025-10-01T10:00:00", "channel": "email", "conversion": 0},
      {"customer_id": "c1", "timestamp": "2025-10-01T12:00:00", "channel": "paid_search", "conversion": 1, "conversion_value": 100}
    ],
    "attribution_model": "data_driven"
  }'
```

**Response:**
```json
{
  "attribution_weights": {
    "email": 0.45,
    "paid_search": 0.55
  },
  "attributed_revenue": {
    "email": 45.00,
    "paid_search": 55.00
  },
  "confidence_intervals": {
    "email": {"lower": 0.38, "upper": 0.52},
    "paid_search": {"lower": 0.48, "upper": 0.62}
  },
  "p_values": {
    "email": 0.001,
    "paid_search": 0.0001
  },
  "method_used": "doubly_robust",
  "total_revenue": 100.00
}
```

---

## 🎯 Key Features

### Attribution Models

| Model | Description | Use Case |
|-------|-------------|----------|
| **Data-Driven** ⭐ | Doubly robust estimation with statistical inference | Most accurate, production-ready |
| **Shapley Values** | Game-theoretic fair attribution | Provably fair credit allocation |
| **Time Decay** | More recent = more credit | Recency-focused campaigns |
| **Position-Based** | First & last touch emphasized | Awareness + conversion focus |
| **Linear** | Equal credit to all | Baseline comparison |

### Causal Inference Methods

All 8 claimed features **verified and operational**:

1. ✅ **Doubly Robust Estimation** - AIPW with confidence intervals
2. ✅ **PC Algorithm** - Causal structure discovery
3. ✅ **Propensity Score Matching** - Treatment effect estimation
4. ✅ **Instrumental Variables** - Two-stage least squares (2SLS)
5. ✅ **Confidence Intervals** - 95% CIs for all estimates
6. ✅ **P-values** - Statistical significance testing
7. ✅ **Standard Errors** - Robust SE calculation
8. ✅ **Shapley Values** - Game-theoretic attribution

See [CAUSAL_FEATURES_VERIFICATION.md](CAUSAL_FEATURES_VERIFICATION.md) for complete verification.

---

## 📊 API Endpoints

### Attribution

```bash
POST /api/v1/attribution
```

Multi-touch attribution with 7 models (data-driven, shapley, linear, time_decay, position, first_touch, last_touch)

### Causal Inference

```bash
POST /api/v1/causal/discover-structure      # PC Algorithm
POST /api/v1/causal/propensity-score        # Propensity Score Matching
POST /api/v1/causal/instrumental-variables  # Instrumental Variables (2SLS)
POST /api/v1/causal/estimate-effect         # General causal effect estimation
POST /api/v1/causal/comprehensive-analysis  # Full causal analysis suite
```

### Utility

```bash
GET /health                                 # Health check
GET /docs                                   # Interactive API docs (Swagger)
GET /redoc                                  # API documentation (ReDoc)
```

**Full API Documentation:** [docs/api/README.md](docs/api/README.md)

---

## 🔬 Example: PC Algorithm (Causal Discovery)

Discover causal relationships automatically from data:

```bash
curl https://causalattribution.onrender.com/api/v1/causal/discover-structure \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": [
      {"age": 25, "income": 50000, "treatment": 1, "outcome": 100},
      {"age": 30, "income": 60000, "treatment": 0, "outcome": 80}
    ],
    "variables": ["age", "income", "treatment", "outcome"],
    "algorithm": "pc",
    "significance_level": 0.05
  }'
```

**Response:**
```json
{
  "result": {
    "edges": [
      {"from_variable": "age", "to_variable": "income"},
      {"from_variable": "treatment", "to_variable": "outcome"}
    ],
    "algorithm_used": "pc",
    "num_tests_performed": 6,
    "graph_description": "Discovered 2 causal relationships"
  }
}
```

---

## 🧪 Testing

Comprehensive test suite included:

```bash
# Test all 3 advanced causal features
bash scripts/test_all_causal_features.sh

# Run Python tests
pytest tests/ -v -m "not slow and not llm"
```

---

## 📈 Performance

- **Doubly Robust Estimation:** ~32ms response time
- **PC Algorithm:** ~4ms response time
- **Instrumental Variables:** ~9ms response time
- **Auto-scaling:** Handles high traffic automatically
- **MLOps:** Automatic touchpoint logging, drift detection ready

---

## 🏗️ Architecture

### Technology Stack

- **API Framework:** FastAPI
- **Database:** Neon PostgreSQL (Serverless)
- **Deployment:** Render.com
- **Authentication:** API key-based (SHA-256 hashed)
- **Statistical Methods:** NumPy, SciPy, scikit-learn
- **Optional Enhancement:** OpenAI, Anthropic LLMs

### MLOps Infrastructure

Automatically logs:
- Customer touchpoints for model training
- Model predictions for drift detection
- Usage metrics per organization
- Channel performance analytics

See [docs/mlops/README.md](docs/mlops/README.md) for details.

---

## 📚 Documentation

### Quick Links

- **[API Documentation](docs/api/README.md)** - Complete API reference
- **[Deployment Guide](DEPLOYMENT.md)** - How to deploy
- **[MLOps Setup](docs/mlops/README.md)** - MLOps infrastructure
- **[Causal Features Verification](CAUSAL_FEATURES_VERIFICATION.md)** - Feature verification report

### Guides

- [Quick Start for Marketing](docs/guides/QUICK_START_MARKETING.md)
- [Agent API Integration](docs/guides/AGENT_API_INTEGRATION_GUIDE.md)
- [Marketing SaaS Guide](docs/guides/MARKETING_SAAS_GUIDE.md)

### Business

- [Executive Pitch](docs/business/EXECUTIVE_PITCH.md)
- [Business Plan](docs/business/BUSINESS_PLAN_SUMMARY.md)
- [Competitive Analysis](docs/business/COMPETITIVE_ANALYSIS.md)
- [API Monetization Strategy](docs/business/API_MONETIZATION_STRATEGY.md)

---

## 🔐 Security

- **API Keys:** SHA-256 hashed in database
- **SSL/HTTPS:** All traffic encrypted (Render automatic SSL)
- **Rate Limiting:** Per-key limits enforced
- **Input Validation:** Pydantic models validate all inputs
- **SQL Injection Protection:** SQLAlchemy ORM with parameterized queries

---

## 💰 Pricing

| Tier | Requests/Month | Rate Limit | Price/Month |
|------|----------------|------------|-------------|
| **Free** | 1,000 | 10/min | $0 |
| **Starter** | 10,000 | 100/min | $29 |
| **Pro** | 100,000 | 500/min | $99 |
| **Enterprise** | Unlimited | Custom | Custom |

Contact: durai@infinidatum.net

---

## 🛠️ Development

### Local Setup

```bash
# Clone repository
git clone https://github.com/rdmurugan/causalattribution.git
cd causalattribution

# Install dependencies
pip install -r requirements.txt

# Set up database
export DATABASE_URL='postgresql://...'
python scripts/run_migrations.py

# Run locally
uvicorn causalattribution.api.main:app --reload
```

### Run Tests

```bash
# Unit tests
pytest tests/ -v -m "not slow and not llm"

# Test all causal features
bash scripts/test_all_causal_features.sh

# Specific test
pytest tests/test_core_functionality.py::TestCausalAttribution -v
```

---

## 🤝 Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Priorities

See [ROADMAP.md](ROADMAP.md) and [BACKLOG.md](BACKLOG.md) for planned features.

---

## 📞 Support

- **Technical Issues:** [GitHub Issues](https://github.com/rdmurugan/causalattribution/issues)
- **Business Inquiries:** durai@infinidatum.net
- **LinkedIn:** https://www.linkedin.com/in/durai-rajamanickam

---

## 📄 License

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

---

## 🎓 Citation

If you use CausalAttribution in your research, please cite:

```bibtex
@software{causalattribution2025,
  author = {Rajamanickam, Durai},
  title = {CausalAttribution: Production-Ready Causal Inference API},
  year = {2025},
  url = {https://github.com/rdmurugan/causalattribution}
}
```

---

## 📊 Stats

![GitHub stars](https://img.shields.io/github/stars/rdmurugan/causalattribution?style=social)
![GitHub forks](https://img.shields.io/github/forks/rdmurugan/causalattribution?style=social)
![GitHub watchers](https://img.shields.io/github/watchers/rdmurugan/causalattribution?style=social)

---

**Built with ❤️ by [Durai Rajamanickam](https://www.linkedin.com/in/durai-rajamanickam)**

**Last Updated:** October 5, 2025
