COREX
Causal Origin Resolution and Empirical eXamination
An Autonomous Multi-Stage Framework for Robust Causal Discrimination in Data-Driven AI Systems
📌 Overview
COREX is a deterministic, graph-free, model-agnostic computational framework that treats causality as an empirically testable robustness property rather than an assumed structural characteristic.
"Causality is not assumed, inferred, or interpreted — it is survived or rejected under systematic perturbation tests."
Contemporary machine learning systems routinely exploit shortcut correlations embedded in training distributions — associations that collapse the moment data distribution shifts, feature encodings change, or interventions are applied. COREX provides a principled four-axis audit pipeline to classify any observed X → Y relationship as:
| Label | COREX Score | Meaning |
|---|---|---|
| 🟢 CAUSAL | ≥ 0.80 | Survives all four evaluation axes |
| 🟡 SPURIOUS | 0.50 – 0.79 | Breaks under domain shift or intervention |
| 🔴 REPRESENTATION ARTIFACT | < 0.50 | Exists only as a function of encoding choice |
🗂️ Table of Contents
- Overview
- Key Features
- Project Structure
- Quick Start
- COREX Pipeline
- Scoring Function
- Platforms & Mirrors
- Clone & Download
- Citation
- License
- Author
✨ Key Features
- Four-module evaluation pipeline — Statistical Stability, Representation Invariance, Domain Robustness, Intervention Consistency
- No prior causal graph required — purely empirical robustness testing
- Model-agnostic — works as a meta-evaluation layer atop any learned relationship
- Calibrated causal scoring — weighted fusion with interpretable decision thresholds
- Optional learnable inference layer — adaptive calibration for high-dimensional settings
- Validated on biomedical signals — vagus nerve electrophysiology, LPS/SIRS/CAR-T models
- Full open-source distribution — available across 11 platforms
📁 Project Structure
COREX/
│
├── corex/ # Core Python package
│ ├── __init__.py # Package entry point & public API
│ ├── pipeline.py # Main COREX evaluation pipeline
│ ├── score.py # Causal scoring function & decision logic
│ │
│ ├── modules/ # Evaluation modules
│ │ ├── __init__.py
│ │ ├── statistical.py # Module 1: Statistical Stability (S)
│ │ ├── representation.py # Module 2: Representation Invariance (R)
│ │ ├── domain.py # Module 3: Domain Robustness (D)
│ │ └── intervention.py # Module 4: Intervention Consistency (I)
│ │
│ ├── learnable/ # Optional learnable inference layer
│ │ ├── __init__.py
│ │ ├── meta_scorer.py # Adaptive MLP weight estimator
│ │ └── weights/ # Pre-trained weight checkpoints
│ │ └── default.pt
│ │
│ └── utils/ # Shared utilities
│ ├── __init__.py
│ ├── transforms.py # Feature transformation library (φ family)
│ ├── environments.py # Environment construction & partitioning
│ ├── counterfactual.py # Intervention simulation engine
│ └── metrics.py # KL divergence, KS tests, CV, etc.
│
├── benchmarks/ # Synthetic ground-truth benchmarks
│ ├── generators/
│ │ ├── causal_chain.py # Class C: true causal chains X→Y→Z
│ │ ├── spurious_confound.py # Class S: latent confounder H→X, H→Y
│ │ └── artifact_encoding.py # Class A: encoding-dependent associations
│ ├── run_benchmarks.py # Full benchmark evaluation script
│ └── results/ # Pre-computed benchmark outputs
│ └── synthetic_1500.json
│
├── validation/ # Real-world biomedical validation
│ ├── vagus_nerve/
│ │ ├── preprocess.py # Electrophysiology signal preprocessing
│ │ ├── feature_extraction.py # Wavelet, PCA, CNN embedding extraction
│ │ └── evaluate.py # COREX evaluation on vagal–cytokine data
│ └── results/
│ └── biomedical_validation.json
│
├── examples/ # Usage examples & tutorials
│ ├── quickstart.py # Minimal working example
│ ├── synthetic_demo.ipynb # Jupyter notebook: synthetic datasets
│ ├── biomedical_demo.ipynb # Jupyter notebook: biomedical signals
│ └── custom_weights.py # Custom weight configuration example
│
├── tests/ # Unit and integration tests
│ ├── test_statistical.py
│ ├── test_representation.py
│ ├── test_domain.py
│ ├── test_intervention.py
│ ├── test_pipeline.py
│ └── test_scoring.py
│
├── docs/ # Documentation source
│ ├── architecture.md # Pipeline architecture reference
│ ├── modules.md # Per-module API documentation
│ ├── scoring.md # Scoring function & threshold calibration
│ └── api_reference.md # Full Python API reference
│
├── paper/ # Research paper artifacts
│ ├── COREX_Research_Paper.pdf # Published paper (PDF)
│ ├── COREX_Research_Paper.docx # Editable Word version
│ └── figures/ # Paper figures & diagrams
│ └── pipeline_diagram.svg
│
├── .gitlab-ci.yml # GitLab CI/CD pipeline
├── .github/ # GitHub Actions workflows
│ └── workflows/
│ ├── tests.yml
│ └── publish.yml
├── pyproject.toml # Build system configuration
├── setup.cfg # Package metadata
├── requirements.txt # Runtime dependencies
├── requirements-dev.txt # Development dependencies
├── CHANGELOG.md # Version history
├── CONTRIBUTING.md # Contribution guidelines
├── CODE_OF_CONDUCT.md
├── AUTHORS.md # Author and contributor registry
├── LICENSE # MIT License
└── README.md # This file
🚀 Quick Start
Installation
# Install from PyPI
pip install corex-causal-causal-causal-causal
# Install from source
git clone https://github.com/gitdeeper12/COREX.git
cd COREX
pip install -e .
Minimal Example
from corex import CausalEvaluator
# Initialize the evaluator
evaluator = CausalEvaluator()
# Load your data
# X: feature array of shape (n_samples, n_features)
# Y: target array of shape (n_samples,)
result = evaluator.evaluate(X, Y)
print(result.label) # "CAUSAL" | "SPURIOUS" | "REPRESENTATION_ARTIFACT"
print(result.corex_score) # float in [0, 1]
print(result.breakdown) # {"S": 0.91, "R": 0.88, "I": 0.85, "D": 0.90}
print(result.failure_modes) # list of detected failure modes (if any)
With Custom Weights
from corex import CausalEvaluator
evaluator = CausalEvaluator(
weights={
"statistical": 0.25,
"representation": 0.25,
"intervention": 0.30,
"domain": 0.20
}
)
result = evaluator.evaluate(X, Y, environments=env_labels)
With Learnable Inference Layer
from corex import CausalEvaluator
from corex.learnable import MetaScorer
meta = MetaScorer.from_pretrained("default")
evaluator = CausalEvaluator(meta_scorer=meta)
result = evaluator.evaluate(X, Y)
🧩 COREX Pipeline
┌─────────────────────────────────────────────────────┐
│ Raw Data D │
└────────────────────┬────────────────────────────────┘
│
┌─────────────┼──────────────┐
│ │ │
▼ ▼ ▼
Statistical Representation Domain Shift
Module Module Module
(score S) (score R) (score D)
│ │ │
└─────────────┼──────────────┘
│
▼
Intervention Engine
(score I)
│
▼
Causal Scoring Layer
COREX = w₁S + w₂R + w₃I + w₄D
│
▼
┌─────────────────┐
│ Final Decision │
│ 🟢 CAUSAL │
│ 🟡 SPURIOUS │
│ 🔴 ARTIFACT │
└─────────────────┘
Module Descriptions
| # | Module | Formula | Description |
|---|---|---|---|
| 1 | Statistical Stability (S) | S = 1 - mean KL[P(Y|X,D₁) ‖ P(Y|X,D₂)] |
Cross-partition conditional invariance |
| 2 | Representation Invariance (R) | R = 1 - (1/|Φ|) Σ ‖P(Y|X) - P(Y|φ(X))‖₁ |
Stability under feature transformations |
| 3 | Intervention Consistency (I) | I = Consistency(do(X=x₁)→Y₁, do(X=x₂)→Y₂) |
Causal effect direction & magnitude stability |
| 4 | Domain Robustness (D) | D = 1 - CV(P(Y|X, e)) over e ∈ E |
Cross-environment generalization |
📊 Scoring Function
COREX = w₁·S + w₂·R + w₃·I + w₄·D
Default weights:
w₁ = 0.25 (Statistical Stability)
w₂ = 0.25 (Representation Invariance)
w₃ = 0.30 (Intervention Consistency) ← highest weight: closest proxy to true causality
w₄ = 0.20 (Domain Robustness)
Decision thresholds:
| Score Range | Classification | Condition |
|---|---|---|
COREX ≥ 0.80 |
🟢 CAUSAL | All modules stable; intervention confirmed |
0.50 ≤ COREX < 0.80 |
🟡 SPURIOUS CORRELATION | Domain shift or intervention failure detected |
COREX < 0.50 |
🔴 REPRESENTATION ARTIFACT | Representation invariance fails |
🌐 Platforms & Mirrors
| Platform | URL | Role |
|---|---|---|
| 🐙 GitHub (Primary) | github.com/gitdeeper12/COREX | Source code, issues, PRs |
| 🦊 GitLab (Mirror) | gitlab.com/gitdeeper12/COREX | CI/CD mirror |
| 🪣 Bitbucket (Mirror) | bitbucket.org/gitdeeper-12/COREX | Enterprise mirror |
| 🏔️ Codeberg (Mirror) | codeberg.org/gitdeeper12/COREX | Open-source community |
| 📦 PyPI | pypi.org/project/corex-causal-causal | Python package distribution |
| 🔬 Zenodo | doi.org/10.5281/zenodo.20351233 | Citable DOI, paper & data |
| 📋 OSF Project | osf.io/3ABZF | Research project registry |
| 📝 OSF Preregistration | doi.org/10.17605/OSF.IO/3ABZF | Pre-registered study protocol |
| 🌐 Website | corex.netlify.app | Live documentation & dashboard |
| 🧑🔬 ORCID | orcid.org/0009-0003-8903-0029 | Researcher identity |
| 🗄️ Internet Archive | archive.org/details/osf-registrations-3ABZF | Permanent archival copy |
🌐 Official Website Pages
| Page | URL |
|---|---|
| Homepage | corex.netlify.app |
| Dashboard | corex.netlify.app/dashboard |
| Results | corex.netlify.app/results |
| Documentation | corex.netlify.app/documentation |
🔄 Clone & Download
Git Clone
# GitHub (Primary)
git clone https://github.com/gitdeeper12/COREX.git
# GitLab (Mirror)
git clone https://gitlab.com/gitdeeper12/COREX.git
# Bitbucket (Mirror)
git clone https://bitbucket.org/gitdeeper-12/COREX.git
# Codeberg (Mirror)
git clone https://codeberg.org/gitdeeper12/COREX.git
Direct ZIP Download
| Source | Link |
|---|---|
| GitHub | COREX-main.zip |
| GitLab | COREX-main.zip |
| Bitbucket | COREX-main.zip |
| Codeberg | COREX-main.zip |
| PyPI files | pypi.org/project/corex-causal-causal/#files |
| Zenodo record | doi.org/10.5281/zenodo.20351233 |
📖 Citation
If COREX contributes to your research, please cite using one of the following formats.
📦 PyPI Package
@software{baladi2026corex_pypi,
author = {Baladi, Samir},
title = {{COREX}: Causal Origin Resolution and Empirical eXamination},
year = {2026},
version = {1.0.0},
publisher = {Python Package Index},
url = {https://pypi.org/project/corex-causal-causal-causal-causal},
note = {Python package, MIT License}
}
🔬 Zenodo Archive (Paper & Data)
@dataset{baladi2026corex_zenodo,
author = {Baladi, Samir},
title = {{COREX}: Causal Origin Resolution and Empirical eXamination — Research Paper and Data},
year = {2026},
publisher = {Zenodo},
version = {1.0.0},
doi = {10.5281/zenodo.20351233},
url = {https://doi.org/10.5281/zenodo.20351233},
series = {BIO-MED-02}
}
📝 OSF Preregistration
@misc{baladi2026corex_osf,
author = {Baladi, Samir},
title = {{COREX} Framework: Pre-registered Study Protocol for Causal Discrimination in Data-Driven Models},
year = {2026},
publisher = {Open Science Framework},
doi = {10.17605/OSF.IO/3ABZF},
url = {https://doi.org/10.17605/OSF.IO/3ABZF},
note = {OSF Preregistration}
}
📄 Research Paper
@article{baladi2026corex,
author = {Baladi, Samir},
title = {{COREX}: An Autonomous Multi-Stage Framework for Robust Causal Discrimination in Data-Driven {AI} Systems},
year = {2026},
month = {May},
series = {BIO-MED-02},
version = {1.0.0},
doi = {10.5281/zenodo.20351233},
url = {https://doi.org/10.5281/zenodo.20351233},
note = {Ronin Institute / Rite of Renaissance}
}
APA (inline)
Baladi, S. (2026). COREX: An Autonomous Multi-Stage Framework for Robust Causal Discrimination in Data-Driven AI Systems (Version 1.0.0, Series BIO-MED-02). Zenodo. https://doi.org/10.5281/zenodo.20351233
📜 License
This project is licensed under the MIT License — see the LICENSE file for details.
MIT License
Copyright (c) 2026 Samir Baladi
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
👤 Author
Samir Baladi Interdisciplinary AI Researcher — Neural Engineering & Biomedical AI Ronin Institute / Rite of Renaissance
| Contact | Link |
|---|---|
| gitdeeper@gmail.com | |
| 🧑🔬 ORCID | 0009-0003-8903-0029 |
| 🐙 GitHub | github.com/gitdeeper12 |
| 🌐 Website | corex.netlify.app |
Metadata
Release files for corex-causal 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| corex_causal-1.0.0.tar.gz | 41.7 kB | Without provenance | Details for corex_causal-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| corex_causal-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for corex_causal-1.0.0-py3-none-any.whl |
Total release size: 57.2 kB
Release files / corex_causal-1.0.0.tar.gz
| Download URL | corex_causal-1.0.0.tar.gz |
|---|---|
| Size | 41.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
41cbd4d1a8abe5d6bf21addcd8d2b1ccc44cd4705b8ece296897d006483bb25d
|
|
BLAKE2b-256 checksum How to use checksums |
75a42162672cdf9692cb75c32581e97145c2db0dede67e5e78bfeb2a3489f96c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
COREX-Causal-Uploader/1.0
|
Release files / corex_causal-1.0.0-py3-none-any.whl
| Download URL | corex_causal-1.0.0-py3-none-any.whl |
|---|---|
| Size | 15.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5cd1cad5f74df012b963834059c6952f6fc39f8328928bf65d1a6bfed667152a
|
|
BLAKE2b-256 checksum How to use checksums |
46c9eb9283ad4657a1bfcde6265e869836ea8ac394c9e55ead72bca41af5707f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
COREX-Causal-Uploader/1.0
|
Security for corex-causal 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.