Metadata-Version: 2.4
Name: dataleak-guard
Version: 0.1.0
Summary: Automated Machine Learning Data Leakage & Train-Test Audit Toolkit
Author-email: Sumit <sumitkeshri.1237373@gmail.com>
Project-URL: Homepage, https://github.com/sumit-2007-git/leakdetect
Project-URL: Bug Tracker, https://github.com/sumit-2007-git/leakdetect/issues
Project-URL: Source, https://github.com/sumit-2007-git/leakdetect
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.20.0
Requires-Dist: rich>=12.0.0
Dynamic: license-file

# 🛡️ dataleak-guard

[![PyPI version](https://img.shields.io/pypi/v/dataleak-guard.svg?color=blue)](https://pypi.org/project/dataleak-guard/)
[![Python versions](https://img.shields.io/pypi/pyversions/dataleak-guard.svg)](https://pypi.org/project/dataleak-guard/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Tests](https://img.shields.io/badge/tests-7%20passed-brightgreen.svg)]()

> **The Fast, Automated Machine Learning Data Leakage & Train-Test Audit Toolkit.**  
> Catch train-test contamination, proxy target leaks, ID memorization, and distribution drift **before** training breaks production.

---

## 📌 Why `dataleak-guard`?

In Machine Learning and Data Science, **Data Leakage** is the #1 silent killer of predictive models:
- A model achieves **99.5% accuracy** on your Jupyter notebook.
- In production, performance collapses to random chance (**52%**).
- **The culprit?** Subtle row overlaps, future variables collected post-event, or improper train-test preprocessing splits.

`dataleak-guard` audits your train and test datasets in **under 1 second**, computes a standardized **Leakage Risk Score (0–100)**, and provides actionable remediation fixes.

---

## 🚀 Key Features

| Audit Engine | What It Detects | Real-World Danger |
| :--- | :--- | :--- |
| **Row Contamination** | Exact or hash-identical rows in both train & test sets | Model evaluates on memorized samples, inflating validation metrics |
| **Target Leakage** | Features with $|r| \ge 0.88$ or exact duplicate target columns | Using data only known *after* the event occurs (e.g. `discharge_date` predicting `illness`) |
| **ID Memorization** | High-cardinality IDs (`user_id`, UUIDs, account numbers) | Model overfits to individual entity tokens rather than true underlying patterns |
| **Preprocessing Drift** | Standardized mean shifts & identical pre-split scaling | `StandardScaler` or encoders fitted on entire dataset before splitting |
| **Class Imbalance Shift** | Divergence in categorical target class frequencies | Unstratified train-test splits leading to zero-shot test failures |

---

## 📦 Installation

```bash
pip install dataleak-guard
```

---

## ⚡ Quickstart (Python API)

```python
import dataleak_guard as dlg
from sklearn.model_selection import train_test_split

# Split your data
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

# Audit in 1 line
report = dlg.audit(X_train, X_test, y_train, y_test)

# Display colored terminal dashboard
report.show()

# Export report to Markdown or JSON
print(report.to_markdown())
json_report = report.to_json()
```

---

## 🖥️ Command Line Interface (CLI)

Audit datasets directly from your terminal:

```bash
# Audit CSV files
dataleak-guard audit train.csv test.csv --target churn

# Export audit to Markdown report
dataleak-guard audit train.csv test.csv --target churn --output audit_report.md

# Run the live interactive demo
dataleak-guard demo
```

---

## 📊 Terminal Dashboard Preview

```text
╭────────────────────────────────────────────────────────────────────╮
│ 🛡️  DATALEAK-GUARD: ML Data Leakage Audit Report                  │
│ Train samples: 140 | Features: 5    Test samples: 65 | Features: 5 │
│ Target column: churn                                               │
│ Leakage Risk Score: 88/100 — Status: CRITICAL LEAKAGE DETECTED     │
╰────────────────────────────────────────────────────────────────────╯
                  Detected Leakage Findings & Vulnerabilities                   
┏━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ S… ┃ Category ┃ Issue Title      ┃ Affected     ┃ Actionable Fix             ┃
┡━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ 🚨 │ Row      │ Train-Test Row   │ -            │ Deduplicate dataset before │
│ C… │ Contami… │ Overlap Detected │              │ split or use GroupKFold    │
├────┼──────────┼──────────────────┼──────────────┼────────────────────────────┤
│ 🚨 │ Target   │ Extreme          │ account_clo… │ Drop variables that cannot │
│ C… │ Leakage  │ Feature-Target   │              │ be observed at inference   │
│    │          │ Correlation      │              │ time                       │
├────┼──────────┼──────────────────┼──────────────┼────────────────────────────┤
│ ⚠️ │ Feature  │ Identifier       │ customer_id  │ Remove identifier columns  │
│ W… │ Enginee… │ Columns          │              │ before model training      │
└────┴──────────┴──────────────────┴──────────────┴────────────────────────────┘
```

---

## 🤖 CI/CD Integration (GitHub Actions)

Fail your machine learning training pipeline if data leakage risk exceeds acceptable thresholds:

```python
import sys
import dataleak_guard as dlg

report = dlg.audit(X_train, X_test, y_train, y_test)
if report.risk_score > 30:
    print(f"FAILED: Data leakage score {report.risk_score}/100 exceeds safety threshold!")
    sys.exit(1)
```

---

## 🛠️ Development & Testing

```bash
# Clone the repository
git clone https://github.com/sumit-2007-git/leakdetect.git
cd leakdetect

# Install in editable mode
pip install -e .

# Run test suite
pytest tests -v

# Run linter
ruff check dataleak_guard tests
```

---

## 📄 License

Distributed under the **MIT License**. See `LICENSE` for more information.

## 👤 Author

- **Sumit** — [GitHub (@sumit-2007-git)](https://github.com/sumit-2007-git)
