# ayushd64/causal-inference-engine architecture

> Architecture diagram of the GitHub repository ayushd64/causal-inference-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ayushd64/causal-inference-engine
- Repository: https://github.com/ayushd64/causal-inference-engine

## Overview

1. **Repository shape**
   - This is a **notebook-first analytics repo**, not a multi-service application.
   - The core executable artifact is `criteo_causal_analysis.ipynb`; the rest is metadata (`README.md`, `requirements.txt`, `.gitignore`).

2. **Primary purpose**
   - The notebook implements an **end-to-end causal uplift workflow** for the **Criteo Uplift Benchmark dataset**.
   - The goal is to estimate **incremental treatment effect** and convert it into a **cost-aware targeting policy**.

3. **Input boundary**
   - External input is the **Criteo uplift dataset**, likely loaded and transformed inside the notebook.
   - The data boundary is the user-level table containing:
     - observed features `f₀`–`f₁₁`
     - treatment assignment
     - conversion outcome
     - validation/analysis slices

4. **Causal modeling subsystem**
   - The first major subsystem is **structural causal analysis**.
   - It uses a **causal graph / backdoor adjustment** framing to control for confounding and estimate an average treatment effect.
   - This is the repository’s “identification” layer: it distinguishes causal effect from correlation.

5. **Refutation / robustness subsystem**
   - A second subsystem performs **DoWhy-style refutation tests**.
   - The README specifically highlights a **Random Common Cause Refuter**, used to test whether the causal estimate changes under irrelevant-noise injection.
   - Architecturally, this is a validation boundary around the causal estimate, not a modeling step that drives decisions.

6. **Heterogeneous treatment effect subsystem**
   - The uplift modeling layer uses **meta-learners**:
     - **T-Learner**
     - **X-Learner**
   - These are backed by **LightGBM**, with GPU acceleration mentioned in the design.
   - This subsystem produces **per-user treatment response scores** rather than a single global effect.

7. **Multi-treatment decision layer**
   - The notebook does not stop at uplift prediction; it maps uplift into **treatment-specific decisions**.
   - Two treatment channels are modeled:
     - **Discount Banner**
     - **Premium Video Ad**
   - The output is a multi-action assignment rather than binary treat/control classification.

8. **Economic optimization boundary**
   - A distinct policy layer computes **Net Expected Value (NEV)**:
     - expected revenue from uplift
     - minus treatment delivery cost
   - This turns model outputs into an operational decision:
     - target with Channel A
     - target with Channel B
     - or **do not target**
   - This is the business-rule boundary that prevents positive-uplift but negative-profit actions.

9. **Output artifacts**
   - The notebook appears to generate:
     - an **ATE estimate**
     - refutation results / p-values
     - user-level uplift and NEV tables
     - an **optimal action allocation summary**
     - visualizations for analysis
   - There is no indication of a deployed API, batch job framework, or persistent model registry in this repo.

10. **Technology stack and runtime**
   - The architecture relies on Python scientific ML tooling:
     - **DoWhy** for causal identification and refutation
     - **CausalML** for uplift/meta-learning
     - **LightGBM** and **scikit-learn** for estimators
     - **NumPy / Pandas** for data prep
     - **Matplotlib / Seaborn** for plotting
   - The mention of GPU acceleration matters only for the training/estimation layer.

11. **System-level data flow**
   - The high-level flow is:
     - load Criteo data
     - define causal structure and adjustment set
     - estimate causal effect
     - refute/stress-test estimate
     - train uplift models for each treatment
     - score users with uplift
     - apply NEV rules to select actions
     - summarize allocation and impact

12. **Architectural takeaway**
   - This repo is best diagrammed as a **single analytical pipeline** with four clear boundaries:
     - **data ingestion**
     - **causal inference**
     - **uplift prediction**
     - **economic policy selection**
   - The notebook orchestrates all stages; there are no separate microservices, databases, or production deployment components visible in the repository.

Main entry points: [`criteo_causal_analysis.ipynb`](https://github.com/ayushd64/causal-inference-engine/blob/main/criteo_causal_analysis.ipynb) (Notebook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Notebook Pipeline"]
  node_notebook["Notebook<br/>orchestrator"]
  node_dataset[("Criteo Data<br/>input table")]
  node_prep["Prep"]
end

subgraph group_causal["Causal Inference"]
  node_causal_graph{{"Causal Graph<br/>identification"}}
  node_backdoor["Backdoor Adj.<br/>adjustment"]
  node_ate(("ATE"))
  node_refuter["Refuter<br/>robustness test"]
  node_check["Validation<br/>sanity check"]
end

subgraph group_uplift["Uplift Modeling"]
  node_tl["T-Learner<br/>uplift model"]
  node_xl["X-Learner<br/>uplift model"]
  node_lgbm["LightGBM<br/>estimator"]
  node_scores[("Uplift Scores<br/>predictions")]
end

subgraph group_policy["Policy & Outputs"]
  node_nev["NEV<br/>policy metric"]
  node_alloc{{"Action Mix<br/>decision policy"}}
  node_summary["Summary<br/>reporting"]
  node_plots["Plots<br/>visualization"]
end

node_notebook -->|"loads"| node_dataset
node_dataset -->|"transforms"| node_prep
node_prep -->|"defines"| node_causal_graph
node_causal_graph -->|"guides"| node_backdoor
node_backdoor -->|"estimates"| node_ate
node_ate -->|"tests"| node_refuter
node_refuter -->|"reports"| node_check
node_prep -->|"feeds"| node_tl
node_prep -->|"feeds"| node_xl
node_tl -->|"uses"| node_lgbm
node_xl -->|"uses"| node_lgbm
node_tl -->|"predicts"| node_scores
node_xl -->|"predicts"| node_scores
node_scores -->|"values"| node_nev
node_nev -->|"selects"| node_alloc
node_alloc -->|"summarizes"| node_summary
node_ate -->|"includes"| node_summary
node_check -->|"includes"| node_summary
node_scores -->|"visualized"| node_plots
node_nev -->|"visualized"| node_plots

click node_notebook "https://github.com/ayushd64/causal-inference-engine/blob/main/criteo_causal_analysis.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_notebook,node_dataset,node_prep toneBlue
class node_causal_graph,node_backdoor,node_ate,node_refuter,node_check toneAmber
class node_tl,node_xl,node_lgbm,node_scores toneMint
class node_nev,node_alloc,node_summary,node_plots toneRose
```

## Components

### Notebook Pipeline

Single notebook that orchestrates the full analysis flow.

- [Notebook](https://github.com/ayushd64/causal-inference-engine/blob/main/criteo_causal_analysis.ipynb): orchestrator · Main executable analysis notebook. · `criteo_causal_analysis.ipynb`
- **Criteo Data**: input table · Criteo uplift benchmark with features, treatment, and outcome.
- **Prep**: feature prep · Loads and reshapes user-level analysis slices and features.

### Causal Inference

Identification, estimation, and robustness checks for treatment effect.

- **Causal Graph**: identification · Defines causal structure and backdoor adjustment set.
- **Backdoor Adj.**: adjustment · Controls confounding for causal effect estimation.
- **ATE**: effect estimate · Global average treatment effect estimate.
- **Refuter**: robustness test · Random common cause refutation of the causal estimate.
- **Validation**: sanity check · Interprets refutation stability and significance.

### Uplift Modeling

Heterogeneous treatment effect modeling for multiple actions.

- **T-Learner**: uplift model · Meta-learner for per-user treatment response.
- **X-Learner**: uplift model · Meta-learner for heterogeneous uplift estimation.
- **LightGBM**: estimator · Tree-based learner used for uplift submodels.
- **Uplift Scores**: predictions · User-level treatment response scores.

### Policy & Outputs

Economic decision layer and analysis artifacts.

- **NEV**: policy metric · Net expected value from uplift minus treatment cost.
- **Action Mix**: decision policy · Selects discount, video ad, or no target.
- **Summary**: reporting · Allocation summary and impact readout.
- **Plots**: visualization · Notebook charts for analysis and comparison.

## Connections

- Notebook → Criteo Data: loads · Notebook ingests the benchmark dataset.
- Criteo Data → Prep: transforms · Raw records are prepared for analysis.
- Prep → Causal Graph: defines · Prepared data supports causal structure definition.
- Causal Graph → Backdoor Adj.: guides · Graph implies adjustment set.
- Backdoor Adj. → ATE: estimates · Backdoor adjustment produces ATE.
- ATE → Refuter: tests · ATE is stress-tested with refutation.
- Refuter → Validation: reports · Refutation output is interpreted for stability.
- Prep → T-Learner: feeds · Features and labels train the T-Learner.
- Prep → X-Learner: feeds · Features and labels train the X-Learner.
- T-Learner → LightGBM: uses · T-Learner relies on LightGBM base estimators.
- X-Learner → LightGBM: uses · X-Learner relies on LightGBM base estimators.
- T-Learner → Uplift Scores: predicts · T-Learner emits uplift scores.
- X-Learner → Uplift Scores: predicts · X-Learner emits uplift scores.
- Uplift Scores → NEV: values · Uplift scores are translated into economic value.
- NEV → Action Mix: selects · NEV chooses the best action per user.
- Action Mix → Summary: summarizes · Policy outputs are aggregated into a summary.
- ATE → Summary: includes · Global causal estimate is reported alongside policy results.
- Validation → Summary: includes · Refutation results are included in reporting.
- Uplift Scores → Plots: visualized · Uplift distributions and comparisons are plotted.
- NEV → Plots: visualized · Economic decisions are visualized for analysis.