# Causal Decision Agent

[![CI](https://github.com/your-username/causal-decision-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/your-username/causal-decision-agent/actions)
[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

An AI decision-analysis agent that takes a business question, connects it to experiment and metric data, investigates using statistical tools, and produces an evidence-backed **decision** (`rollout | hold | investigate`) with a reproducible audit trace.

---

## 🏛️ Project Architecture & Layout

```
CausalAI/
├── src/
│   ├── stat_runtime/              # Pure statistical execution engine (Numbers only, no verdicts)
│   │   ├── data/
│   │   │   ├── schema.py          # Data profiles & column metadata
│   │   │   └── profiling.py       # Data-type detection & variable association profiling
│   │   ├── experiment/
│   │   │   ├── srm.py             # Sample Ratio Mismatch (SRM) Chi-Square test
│   │   │   ├── balance.py         # Standardized Mean Difference (SMD) covariate balance
│   │   │   ├── ab_test.py         # Welch's t-test A/B estimation with robust CIs
│   │   │   └── cuped.py           # Pre-experiment variance reduction (CUPED)
│   │   ├── causal/
│   │   │   ├── did.py             # Difference-in-Differences (DiD) regression
│   │   │   ├── dml.py             # Double Machine Learning (Chernozhukov et al.)
│   │   │   └── refutation.py      # Placebo treatment & bootstrap stability refuters
│   │   ├── metrics/
│   │   │   └── definitions.py     # Aggregations, windows, and guardrail definitions
│   │   └── provenance/
│   │       └── artifact.py        # Reproducible execution & audit trace capture
│   │
│   └── causal_agent/              # Agent logic, decision layer, and protocol interfaces
│       ├── data/
│       │   ├── base.py            # DataSource abstract interface
│       │   └── duckdb_source.py   # DuckDB canonical schema implementation
│       ├── evidence/
│       │   └── state.py           # EvidenceState (findings, warnings, unresolved, estimates)
│       ├── decision/
│       │   └── engine.py          # DecisionEngine (rollout | hold | investigate + guardrail priority)
│       ├── planner/
│       │   ├── base.py            # AnalysisPlan & AnalysisPlanner interface
│       │   └── deterministic.py   # Rule-based planner batching runtime calls
│       ├── eval/
│       │   ├── synthetic_data.py  # Canonical benchmark scenarios generator (10 scenarios)
│       │   └── harness.py         # Scoring harness (minimizes false-positive rollouts)
│       └── server/
│           └── mcp_server.py      # Business-level MCP server interface
│
├── tests/
│   ├── unit/                      # Fast unit tests for statistical routines & engine
│   ├── eval/                      # Benchmark evaluation suite
│   └── conftest.py                # Pytest fixtures
│
├── plan.md                        # Master system design & engineering plan
├── pyproject.toml                 # Package configuration & test runners
├── requirements.txt               # Core production dependencies
├── requirements-dev.txt           # Testing & linting dependencies
└── .gitignore                     # Ignore files for Python, DuckDB, and IDEs
```

---

## ⚡ Core Invariants & Principles

1. **LLM never computes statistics**: All numerical computations occur inside `stat_runtime`.
2. **Tools return measurements, not verdicts**: Structured JSON with numbers, p-values, and bounds.
3. **Guardrails take precedence**: A statistically significant regression on a guardrail forces `HOLD` regardless of primary metric lift.
4. **False-Positive Rollout Minimization**: The harness explicitly optimizes for 0% false-positive rollouts on corrupted, underpowered, or mismatched experiments.

---

## 🚀 Getting Started

### 1. Activate Environment
```powershell
.\.venv\Scripts\Activate.ps1
```

### 2. Run Tests
```powershell
.\.venv\Scripts\pytest
```

### 3. Run Benchmark Harness
```powershell
.\.venv\Scripts\python -m pytest tests/eval/test_eval_scenarios.py -s
```

---

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines, testing instructions, and pull request workflow.

Please also review our [Code of Conduct](CODE_OF_CONDUCT.md).

---

## 📄 License

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