datadriftguard 0.1.0__tar.gz

datadriftguard-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Virtual environments
+.venv/
+venv/
+
+# Python bytecode
+__pycache__/
+*.pyc
+*.pyo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Type checking
+.mypy_cache/
+
+# Environment
+.env
+
+# Build & distribution
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

datadriftguard-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to DriftGuardAI will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-24
+
+### Added
+
+- Initial public release.
+- Drift detection metrics: PSI, KS test, KL divergence, chi-square test, categorical distribution difference.
+- `DriftDetector` class for feature-level drift analysis with configurable thresholds.
+- `AlertManager` for log-based, webhook, and Slack alert dispatch.
+- `RetrainingManager` for automated retraining trigger evaluation.
+- Domain entities: `FeatureDriftReport`, `FeatureDriftResult`, `DriftMetricResult`, and more.
+- YAML-based configuration with environment variable override (`DRIFT_GUARD_CONFIG_PATH`).
+- Structured JSON logging.
+- Optional FastAPI server (`pip install driftguardai[api]`).
+- Optional Streamlit dashboard (`pip install driftguardai[dashboard]`).
+- PEP 561 `py.typed` marker for type checker support.

datadriftguard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Surya Babbar
+
+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, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

datadriftguard-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include config.yaml
+include LICENSE
+include README.md
+recursive-include datasets *.csv

datadriftguard-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: datadriftguard
+Version: 0.1.0
+Summary: Data drift detection toolkit for ML pipelines — PSI, KS, KL divergence, chi-square, and more.
+Project-URL: Homepage, https://github.com/suryanandanbabbar/DriftGuardAI
+Project-URL: Documentation, https://github.com/suryanandanbabbar/DriftGuardAI#readme
+Project-URL: Repository, https://github.com/suryanandanbabbar/DriftGuardAI
+Project-URL: Issues, https://github.com/suryanandanbabbar/DriftGuardAI/issues
+Author: Surya Babbar
+License-Expression: MIT
+License-File: LICENSE
+Keywords: data-quality,drift,machine-learning,mlops,model-monitoring,monitoring
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scipy>=1.9
+Provides-Extra: api
+Requires-Dist: fastapi>=0.100; extra == 'api'
+Requires-Dist: python-multipart>=0.0.6; extra == 'api'
+Requires-Dist: uvicorn>=0.20; extra == 'api'
+Provides-Extra: dashboard
+Requires-Dist: streamlit>=1.25; extra == 'dashboard'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DriftGuardAI
+
+[![PyPI version](https://img.shields.io/pypi/v/datadriftguard.svg)](https://pypi.org/project/datadriftguard/)
+[![Python versions](https://img.shields.io/pypi/pyversions/datadriftguard.svg)](https://pypi.org/project/datadriftguard/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Data drift detection toolkit for ML pipelines.** Monitor feature-level distribution shifts using PSI, KS test, KL divergence, chi-square test, and more.
+
+DriftGuardAI helps ML engineers and data scientists detect when production data drifts away from training data — a leading indicator of model degradation.
+
+## Installation
+
+```bash
+pip install datadriftguard
+```
+
+Optional extras:
+
+```bash
+# Include the FastAPI server
+pip install datadriftguard[api]
+
+# Include the Streamlit dashboard
+pip install datadriftguard[dashboard]
+
+# Install everything for development
+pip install datadriftguard[dev,api,dashboard]
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+from driftguardai import DriftDetector, ThresholdSettings
+
+# Load your baseline (training) and incoming (production) data
+baseline = pd.read_csv("baseline.csv")
+incoming = pd.read_csv("incoming.csv")
+
+# Create a detector with default or custom thresholds
+detector = DriftDetector(
+    baseline_dataset=baseline,
+    incoming_dataset=incoming,
+    thresholds=ThresholdSettings(psi=0.20, ks_significance_level=0.05),
+)
+
+# Generate a drift report
+report = detector.generate_report(dataset_name="production_model_v2")
+
+# Inspect results
+print(f"Total features: {report.total_features}")
+print(f"Drifted features: {len(report.drifted_features)}")
+
+for feature in report.drifted_features:
+    print(f"  ⚠ {feature.feature_name} ({feature.feature_type}): drift detected")
+    if feature.metrics.psi:
+        print(f"    PSI: {feature.metrics.psi.value:.4f} (threshold: {feature.metrics.psi.threshold})")
+    if feature.metrics.ks:
+        print(f"    KS:  {feature.metrics.ks.value:.4f} (p={feature.metrics.ks.p_value:.4f})")
+```
+
+## Drift Metrics
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| **PSI** (Population Stability Index) | Numerical | Measures distribution shift between baseline and incoming data |
+| **KS Test** (Kolmogorov-Smirnov) | Numerical | Non-parametric test for distribution equality |
+| **KL Divergence** (Kullback-Leibler) | Numerical | Information-theoretic measure of distribution difference |
+| **Chi-Square Test** | Categorical | Tests independence between categorical distributions |
+| **Distribution Difference** | Categorical | Total variation distance between category frequencies |
+
+## Alerting
+
+DriftGuardAI includes an alert system that can dispatch drift notifications via logging, webhooks, or Slack:
+
+```python
+from driftguardai import AlertManager, DriftDetector
+from driftguardai.core.config import AlertSettings
+
+detector = DriftDetector(baseline, incoming)
+report = detector.generate_report(dataset_name="production")
+
+alert_manager = AlertManager(
+    settings=AlertSettings(
+        enabled=True,
+        log_alerts=True,
+        slack_webhook_url="https://hooks.slack.com/services/...",
+    )
+)
+dispatch_report = alert_manager.dispatch(report)
+print(f"Dispatched {dispatch_report.total_alerts} alerts")
+```
+
+## Retraining Triggers
+
+Automatically evaluate whether model retraining should be triggered based on drift severity:
+
+```python
+from driftguardai import RetrainingManager
+from driftguardai.core.config import RetrainingSettings
+
+manager = RetrainingManager(
+    settings=RetrainingSettings(
+        enabled=True,
+        trigger_severity="critical",
+        min_alert_count=2,
+    )
+)
+result = manager.evaluate(report)
+if result.triggered:
+    print(f"Retraining triggered: {result.reason}")
+    print(f"Affected features: {result.affected_features}")
+```
+
+## Configuration
+
+DriftGuardAI can be configured programmatically or via a `config.yaml` file:
+
+```yaml
+thresholds:
+  psi: 0.20
+  ks_significance_level: 0.05
+  kl_divergence: 0.10
+  categorical_distance: 0.10
+  categorical_chi_square_significance_level: 0.05
+  histogram_bins: 10
+  histogram_strategy: quantile
+
+alerts:
+  enabled: true
+  log_alerts: true
+  minimum_severity: warning
+  slack_webhook_url: https://hooks.slack.com/services/...
+
+retraining:
+  enabled: true
+  trigger_severity: critical
+  min_alert_count: 1
+```
+
+Place `config.yaml` in your working directory, or set the `DRIFT_GUARD_CONFIG_PATH` environment variable:
+
+```bash
+export DRIFT_GUARD_CONFIG_PATH=/path/to/your/config.yaml
+```
+
+## Optional: API Server
+
+Run a FastAPI server for drift detection over HTTP:
+
+```bash
+pip install datadriftguard[api]
+uvicorn driftguardai.api.app:app --reload
+```
+
+Endpoints:
+- `GET /api/v1/health` — Health check
+- `POST /api/v1/drift/analyze` — Analyze drift from file paths
+- `POST /api/v1/drift/analyze/files` — Analyze drift from uploaded CSVs
+
+## Optional: Streamlit Dashboard
+
+Visualize drift metrics with an interactive dashboard:
+
+```bash
+pip install datadriftguard[dashboard]
+streamlit run src/driftguardai/dashboard/app.py
+```
+
+## Architecture
+
+```text
+driftguardai/
+├── core/          # Domain models, config, exceptions, interfaces, use cases
+├── drift/         # Drift detection implementations and statistical metrics
+├── data/          # Data ingestion and repository adapters
+├── utils/         # Logging and dataset validation utilities
+├── api/           # Optional FastAPI HTTP layer
+└── dashboard/     # Optional Streamlit visualization
+```
+
+## Development
+
+```bash
+git clone https://github.com/suryanandanbabbar/DriftGuardAI.git
+cd DriftGuardAI
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,api,dashboard]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

datadriftguard-0.1.0/README.md

@@ -0,0 +1,195 @@
+# DriftGuardAI
+
+[![PyPI version](https://img.shields.io/pypi/v/datadriftguard.svg)](https://pypi.org/project/datadriftguard/)
+[![Python versions](https://img.shields.io/pypi/pyversions/datadriftguard.svg)](https://pypi.org/project/datadriftguard/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Data drift detection toolkit for ML pipelines.** Monitor feature-level distribution shifts using PSI, KS test, KL divergence, chi-square test, and more.
+
+DriftGuardAI helps ML engineers and data scientists detect when production data drifts away from training data — a leading indicator of model degradation.
+
+## Installation
+
+```bash
+pip install datadriftguard
+```
+
+Optional extras:
+
+```bash
+# Include the FastAPI server
+pip install datadriftguard[api]
+
+# Include the Streamlit dashboard
+pip install datadriftguard[dashboard]
+
+# Install everything for development
+pip install datadriftguard[dev,api,dashboard]
+```
+
+## Quick Start
+
+```python
+import pandas as pd
+from driftguardai import DriftDetector, ThresholdSettings
+
+# Load your baseline (training) and incoming (production) data
+baseline = pd.read_csv("baseline.csv")
+incoming = pd.read_csv("incoming.csv")
+
+# Create a detector with default or custom thresholds
+detector = DriftDetector(
+    baseline_dataset=baseline,
+    incoming_dataset=incoming,
+    thresholds=ThresholdSettings(psi=0.20, ks_significance_level=0.05),
+)
+
+# Generate a drift report
+report = detector.generate_report(dataset_name="production_model_v2")
+
+# Inspect results
+print(f"Total features: {report.total_features}")
+print(f"Drifted features: {len(report.drifted_features)}")
+
+for feature in report.drifted_features:
+    print(f"  ⚠ {feature.feature_name} ({feature.feature_type}): drift detected")
+    if feature.metrics.psi:
+        print(f"    PSI: {feature.metrics.psi.value:.4f} (threshold: {feature.metrics.psi.threshold})")
+    if feature.metrics.ks:
+        print(f"    KS:  {feature.metrics.ks.value:.4f} (p={feature.metrics.ks.p_value:.4f})")
+```
+
+## Drift Metrics
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| **PSI** (Population Stability Index) | Numerical | Measures distribution shift between baseline and incoming data |
+| **KS Test** (Kolmogorov-Smirnov) | Numerical | Non-parametric test for distribution equality |
+| **KL Divergence** (Kullback-Leibler) | Numerical | Information-theoretic measure of distribution difference |
+| **Chi-Square Test** | Categorical | Tests independence between categorical distributions |
+| **Distribution Difference** | Categorical | Total variation distance between category frequencies |
+
+## Alerting
+
+DriftGuardAI includes an alert system that can dispatch drift notifications via logging, webhooks, or Slack:
+
+```python
+from driftguardai import AlertManager, DriftDetector
+from driftguardai.core.config import AlertSettings
+
+detector = DriftDetector(baseline, incoming)
+report = detector.generate_report(dataset_name="production")
+
+alert_manager = AlertManager(
+    settings=AlertSettings(
+        enabled=True,
+        log_alerts=True,
+        slack_webhook_url="https://hooks.slack.com/services/...",
+    )
+)
+dispatch_report = alert_manager.dispatch(report)
+print(f"Dispatched {dispatch_report.total_alerts} alerts")
+```
+
+## Retraining Triggers
+
+Automatically evaluate whether model retraining should be triggered based on drift severity:
+
+```python
+from driftguardai import RetrainingManager
+from driftguardai.core.config import RetrainingSettings
+
+manager = RetrainingManager(
+    settings=RetrainingSettings(
+        enabled=True,
+        trigger_severity="critical",
+        min_alert_count=2,
+    )
+)
+result = manager.evaluate(report)
+if result.triggered:
+    print(f"Retraining triggered: {result.reason}")
+    print(f"Affected features: {result.affected_features}")
+```
+
+## Configuration
+
+DriftGuardAI can be configured programmatically or via a `config.yaml` file:
+
+```yaml
+thresholds:
+  psi: 0.20
+  ks_significance_level: 0.05
+  kl_divergence: 0.10
+  categorical_distance: 0.10
+  categorical_chi_square_significance_level: 0.05
+  histogram_bins: 10
+  histogram_strategy: quantile
+
+alerts:
+  enabled: true
+  log_alerts: true
+  minimum_severity: warning
+  slack_webhook_url: https://hooks.slack.com/services/...
+
+retraining:
+  enabled: true
+  trigger_severity: critical
+  min_alert_count: 1
+```
+
+Place `config.yaml` in your working directory, or set the `DRIFT_GUARD_CONFIG_PATH` environment variable:
+
+```bash
+export DRIFT_GUARD_CONFIG_PATH=/path/to/your/config.yaml
+```
+
+## Optional: API Server
+
+Run a FastAPI server for drift detection over HTTP:
+
+```bash
+pip install datadriftguard[api]
+uvicorn driftguardai.api.app:app --reload
+```
+
+Endpoints:
+- `GET /api/v1/health` — Health check
+- `POST /api/v1/drift/analyze` — Analyze drift from file paths
+- `POST /api/v1/drift/analyze/files` — Analyze drift from uploaded CSVs
+
+## Optional: Streamlit Dashboard
+
+Visualize drift metrics with an interactive dashboard:
+
+```bash
+pip install datadriftguard[dashboard]
+streamlit run src/driftguardai/dashboard/app.py
+```
+
+## Architecture
+
+```text
+driftguardai/
+├── core/          # Domain models, config, exceptions, interfaces, use cases
+├── drift/         # Drift detection implementations and statistical metrics
+├── data/          # Data ingestion and repository adapters
+├── utils/         # Logging and dataset validation utilities
+├── api/           # Optional FastAPI HTTP layer
+└── dashboard/     # Optional Streamlit visualization
+```
+
+## Development
+
+```bash
+git clone https://github.com/suryanandanbabbar/DriftGuardAI.git
+cd DriftGuardAI
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev,api,dashboard]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

datadriftguard-0.1.0/config.yaml

@@ -0,0 +1,54 @@
+environment: development
+debug: true
+log_level: INFO
+
+logging:
+  level: INFO
+  structured: true
+  timestamp_format: "%Y-%m-%dT%H:%M:%S%z"
+
+api:
+  title: DriftGuardAI API
+  version: 0.1.0
+  prefix: /api/v1
+
+thresholds:
+  numerical_p_value: 0.05
+  categorical_distance: 0.10
+  categorical_chi_square_significance_level: 0.05
+  missing_rate_delta: 0.02
+  psi: 0.20
+  ks_significance_level: 0.05
+  kl_divergence: 0.10
+  histogram_bins: 10
+  histogram_strategy: quantile
+  histogram_epsilon: 0.000001
+
+monitoring:
+  min_rows: 100
+  default_method: kolmogorov_smirnov
+  alert_on_missing_data: true
+
+data:
+  reference_dataset_path: datasets/reference.csv
+  current_dataset_path: datasets/current.csv
+
+runtime:
+  default_dataset_name: production
+  uploaded_dataset_name: uploaded
+
+alerts:
+  enabled: true
+  log_alerts: true
+  minimum_severity: warning
+  critical_excess_ratio: 1.5
+  critical_p_value_ratio: 0.2
+  webhook_url:
+  slack_webhook_url:
+  timeout_seconds: 5.0
+
+retraining:
+  enabled: true
+  trigger_severity: critical
+  min_alert_count: 1
+  pipeline_name: placeholder_retraining_pipeline

datadriftguard-0.1.0/datasets/.gitkeep

@@ -0,0 +1 @@
+

datadriftguard-0.1.0/datasets/current.csv

@@ -0,0 +1,16 @@
+age,income,credit_score,transactions_per_month,avg_transaction_amount,region,device_type
+22,28000,590,8,85.2,South,Mobile
+24,30000,610,9,90.4,South,Mobile
+26,32000,605,10,95.1,South,Mobile
+21,25000,580,7,70.3,South,Mobile
+23,27000,600,8,80.2,South,Mobile
+25,29000,610,9,88.7,South,Mobile
+28,31000,620,11,100.4,South,Mobile
+30,33000,630,12,105.9,South,Mobile
+27,30500,615,10,97.3,South,Mobile
+24,29500,605,9,92.5,South,Mobile
+22,26000,585,7,75.6,South,Mobile
+23,27500,595,8,82.1,South,Mobile
+26,31500,620,11,102.2,South,Mobile
+29,34000,635,12,110.5,South,Mobile
+31,36000,645,13,115.8,South,Mobile

datadriftguard-0.1.0/datasets/reference.csv

@@ -0,0 +1,16 @@
+age,income,credit_score,transactions_per_month,avg_transaction_amount,region,device_type
+23,35000,640,18,120.5,North,Mobile
+45,72000,710,25,240.3,West,Desktop
+31,54000,680,21,180.2,South,Mobile
+52,88000,750,32,310.7,West,Desktop
+28,46000,660,19,150.9,North,Mobile
+39,61000,700,23,210.4,East,Tablet
+47,79000,720,27,260.1,West,Desktop
+34,57000,690,22,195.8,South,Mobile
+29,48000,670,20,165.6,East,Mobile
+41,65000,705,24,220.3,North,Desktop
+36,59000,695,23,205.4,South,Mobile
+50,82000,735,30,290.2,West,Desktop
+27,44000,655,18,140.2,East,Mobile
+43,70000,715,26,245.8,North,Tablet
+38,62000,705,24,215.9,South,Desktop

datadriftguard-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "datadriftguard"
+dynamic = ["version"]
+description = "Data drift detection toolkit for ML pipelines — PSI, KS, KL divergence, chi-square, and more."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Surya Babbar" },
+]
+keywords = ["drift", "machine-learning", "monitoring", "mlops", "data-quality", "model-monitoring"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pandas>=1.5",
+    "numpy>=1.23",
+    "scipy>=1.9",
+    "pydantic>=2.0",
+    "PyYAML>=6.0",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+api = [
+    "fastapi>=0.100",
+    "uvicorn>=0.20",
+    "python-multipart>=0.0.6",
+]
+dashboard = [
+    "streamlit>=1.25",
+]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.4",
+    "mypy>=1.0",
+    "build>=1.0",
+    "twine>=5.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/suryanandanbabbar/DriftGuardAI"
+Documentation = "https://github.com/suryanandanbabbar/DriftGuardAI#readme"
+Repository = "https://github.com/suryanandanbabbar/DriftGuardAI"
+Issues = "https://github.com/suryanandanbabbar/DriftGuardAI/issues"
+
+[tool.hatch.version]
+path = "src/driftguardai/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/driftguardai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true