statistical-causal-inference 4.3.0

Production-ready causal attribution and inference API with comprehensive monitoring, testing, and LLM integration

CausalAttribution API

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: [e-mail] for API access

2. Multi-Touch Attribution

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:

{
  "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 for complete verification.

---

📊 API Endpoints

Attribution

POST /api/v1/attribution

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

Causal Inference

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

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

Full API Documentation: docs/api/README.md

---

🔬 Example: PC Algorithm (Causal Discovery)

Discover causal relationships automatically from data:

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:

{
  "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:

# 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 for details.

---

📚 Documentation

Quick Links

• API Documentation - Complete API reference
• Deployment Guide - How to deploy
• MLOps Setup - MLOps infrastructure
• Causal Features Verification - Feature verification report

Guides

• Quick Start for Marketing
• Agent API Integration
• Marketing SaaS Guide

Business

• Executive Pitch
• Business Plan
• Competitive Analysis
• API Monetization Strategy

---

🔐 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: [e-mail]

---

🛠️ Development

Local Setup

# 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

# 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 for guidelines.

Development Priorities

See ROADMAP.md and BACKLOG.md for planned features.

---

📞 Support

• Technical Issues: GitHub Issues
• Business Inquiries: [e-mail]
• LinkedIn: https://www.linkedin.com/in/durai-rajamanickam

---

📄 License

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

---

🎓 Citation

If you use CausalAttribution in your research, please cite:

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

---

📊 Stats

---

Built with ❤️ by Durai Rajamanickam

Last Updated: October 5, 2025