driftguard-prathvi 0.1.0__tar.gz

driftguard_prathvi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DriftGuard Developers
+
+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.

driftguard_prathvi-0.1.0/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: driftguard-prathvi
+Version: 0.1.0
+Summary: A robust data drift detection and schema validation library for machine learning pipelines.
+Author-email: DriftGuard Developer <developer@driftguard.org>
+License: MIT
+Project-URL: Homepage, https://github.com/developer/driftguard
+Project-URL: Documentation, https://github.com/developer/driftguard#readme
+Project-URL: Bug-Tracker, https://github.com/developer/driftguard/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.18.0
+Requires-Dist: pandas>=1.0.0
+Requires-Dist: scipy>=1.5.0
+Dynamic: license-file
+
+# DriftGuard
+
+DriftGuard is a lightweight, robust, and publish-ready Python library designed to automate dataset validation and detect statistical data drift in machine learning pipelines. 
+
+By comparing new incoming datasets against a trusted baseline reference dataset, DriftGuard alerts you to schema changes, increases in missing values, or shifts in feature distributions before they affect downstream model performance.
+
+---
+
+## Features
+
+- **Schema Validation**: Detect missing columns, new columns, and data type mismatches.
+- **Null Rate Analysis**: Monitor and flag columns where the rate of missing values increases beyond a configurable threshold.
+- **Statistical Drift Detection**:
+  - **Kolmogorov-Smirnov (KS) Test** (`scipy.stats.ks_2samp`) for numerical columns.
+  - **Chi-Square Test** (`scipy.stats.chi2_contingency`) for categorical columns.
+- **Severity Tagging**: Categorizes issues as `INFO`, `WARNING`, or `CRITICAL` for pipeline routing or CI/CD gate checks.
+- **Interactive Reports**: 
+  - An ASCII summary table output directly to console.
+  - Machine-readable JSON output for automated pipelines.
+  - A beautiful, self-contained interactive HTML dashboard with per-column breakdowns and interactive searching/filtering.
+
+---
+
+## Installation
+
+```bash
+pip install driftguard
+```
+
+*Note: Depends on `numpy`, `pandas`, and `scipy` only.*
+
+---
+
+## Quickstart
+
+Validate your production features in real-time or as part of a batch training/inference pipeline:
+
+```python
+import numpy as np
+import pandas as pd
+import driftguard as dg
+
+# 1. Create a reference dataset (baseline)
+np.random.seed(42)
+ref_data = {
+    "age": np.random.normal(35, 10, 1000),
+    "income": np.random.uniform(30000, 120000, 1000),
+    "city": np.random.choice(["New York", "Chicago", "San Francisco"], 1000),
+    "target": np.random.choice([0, 1], 1000, p=[0.7, 0.3])
+}
+reference_df = pd.DataFrame(ref_data)
+
+# 2. Create a new dataset (with some drift and schema issues)
+new_data = {
+    "age": np.random.normal(38, 10, 1000),                 # Slight shift
+    "income": np.random.uniform(30000, 120000, 1000),
+    "city": np.random.choice(["New York", "Chicago", "Boston"], 1000),  # "Boston" is a new category
+    "target": np.random.choice([0, 1], 1000, p=[0.7, 0.3]),
+    "extra_col": np.random.random(1000)                    # New column
+}
+new_df = pd.DataFrame(new_data)
+# Add some null values to 'income'
+new_df.loc[np.random.choice(1000, 150, replace=False), "income"] = np.nan
+
+# 3. Instantiate Validator and run checks
+# p_threshold matches the significance alpha for KS/Chi2
+# null_threshold is the maximum allowed null rate increase
+validator = dg.Validator(reference_df, p_threshold=0.05, null_threshold=0.10)
+report = validator.check(new_df)
+
+# 4. Consume the report
+# Prints a formatted ASCII table of all issues
+report.summary()
+
+# Export interactive HTML dashboard (saves report.html)
+report.export("html")
+
+# Export machine-readable JSON (saves report.json)
+report.export("json")
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

driftguard_prathvi-0.1.0/README.md

@@ -0,0 +1,86 @@
+# DriftGuard
+
+DriftGuard is a lightweight, robust, and publish-ready Python library designed to automate dataset validation and detect statistical data drift in machine learning pipelines. 
+
+By comparing new incoming datasets against a trusted baseline reference dataset, DriftGuard alerts you to schema changes, increases in missing values, or shifts in feature distributions before they affect downstream model performance.
+
+---
+
+## Features
+
+- **Schema Validation**: Detect missing columns, new columns, and data type mismatches.
+- **Null Rate Analysis**: Monitor and flag columns where the rate of missing values increases beyond a configurable threshold.
+- **Statistical Drift Detection**:
+  - **Kolmogorov-Smirnov (KS) Test** (`scipy.stats.ks_2samp`) for numerical columns.
+  - **Chi-Square Test** (`scipy.stats.chi2_contingency`) for categorical columns.
+- **Severity Tagging**: Categorizes issues as `INFO`, `WARNING`, or `CRITICAL` for pipeline routing or CI/CD gate checks.
+- **Interactive Reports**: 
+  - An ASCII summary table output directly to console.
+  - Machine-readable JSON output for automated pipelines.
+  - A beautiful, self-contained interactive HTML dashboard with per-column breakdowns and interactive searching/filtering.
+
+---
+
+## Installation
+
+```bash
+pip install driftguard
+```
+
+*Note: Depends on `numpy`, `pandas`, and `scipy` only.*
+
+---
+
+## Quickstart
+
+Validate your production features in real-time or as part of a batch training/inference pipeline:
+
+```python
+import numpy as np
+import pandas as pd
+import driftguard as dg
+
+# 1. Create a reference dataset (baseline)
+np.random.seed(42)
+ref_data = {
+    "age": np.random.normal(35, 10, 1000),
+    "income": np.random.uniform(30000, 120000, 1000),
+    "city": np.random.choice(["New York", "Chicago", "San Francisco"], 1000),
+    "target": np.random.choice([0, 1], 1000, p=[0.7, 0.3])
+}
+reference_df = pd.DataFrame(ref_data)
+
+# 2. Create a new dataset (with some drift and schema issues)
+new_data = {
+    "age": np.random.normal(38, 10, 1000),                 # Slight shift
+    "income": np.random.uniform(30000, 120000, 1000),
+    "city": np.random.choice(["New York", "Chicago", "Boston"], 1000),  # "Boston" is a new category
+    "target": np.random.choice([0, 1], 1000, p=[0.7, 0.3]),
+    "extra_col": np.random.random(1000)                    # New column
+}
+new_df = pd.DataFrame(new_data)
+# Add some null values to 'income'
+new_df.loc[np.random.choice(1000, 150, replace=False), "income"] = np.nan
+
+# 3. Instantiate Validator and run checks
+# p_threshold matches the significance alpha for KS/Chi2
+# null_threshold is the maximum allowed null rate increase
+validator = dg.Validator(reference_df, p_threshold=0.05, null_threshold=0.10)
+report = validator.check(new_df)
+
+# 4. Consume the report
+# Prints a formatted ASCII table of all issues
+report.summary()
+
+# Export interactive HTML dashboard (saves report.html)
+report.export("html")
+
+# Export machine-readable JSON (saves report.json)
+report.export("json")
+```
+
+---
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

driftguard_prathvi-0.1.0/driftguard/__init__.py

@@ -0,0 +1,8 @@
+"""DriftGuard: Data drift detection and schema validation for ML pipelines."""
+
+from driftguard.validator import Validator
+from driftguard.report import Report
+from driftguard.utils import CheckResult
+
+__version__ = "0.1.0"
+__all__ = ["Validator", "Report", "CheckResult"]

driftguard_prathvi-0.1.0/driftguard/checks/__init__.py

@@ -0,0 +1,7 @@
+"""Checks sub-module for data validation and drift detection."""
+
+from driftguard.checks.schema import check_schema
+from driftguard.checks.nulls import check_nulls
+from driftguard.checks.drift import check_drift
+
+__all__ = ["check_schema", "check_nulls", "check_drift"]

driftguard_prathvi-0.1.0/driftguard/checks/drift.py

@@ -0,0 +1,196 @@
+"""Statistical drift detection checks for DriftGuard."""
+
+import numpy as np
+import pandas as pd
+from scipy.stats import ks_2samp, chi2_contingency
+from typing import List
+from driftguard.utils import CheckResult
+
+
+def check_drift(
+    ref_df: pd.DataFrame,
+    new_df: pd.DataFrame,
+    columns: List[str],
+    p_threshold: float,
+) -> List[CheckResult]:
+    """Performs statistical drift tests on the specified columns.
+
+    Uses:
+    - Kolmogorov-Smirnov test for numerical columns.
+    - Chi-Square test of independence for categorical/boolean columns.
+
+    Args:
+        ref_df: The reference pandas DataFrame.
+        new_df: The new pandas DataFrame.
+        columns: The list of common columns to check.
+        p_threshold: The significance level (alpha) below which drift is detected.
+
+    Returns:
+        A list of CheckResult objects containing the statistical results.
+    """
+    results = []
+
+    for col in columns:
+        is_ref_numeric = pd.api.types.is_numeric_dtype(ref_df[col])
+        is_new_numeric = pd.api.types.is_numeric_dtype(new_df[col])
+
+        # If they are both numeric, apply Kolmogorov-Smirnov test
+        if is_ref_numeric and is_new_numeric:
+            ref_data = ref_df[col].dropna()
+            new_data = new_df[col].dropna()
+
+            if len(ref_data) == 0 or len(new_data) == 0:
+                results.append(
+                    CheckResult(
+                        column=col,
+                        check_type="drift",
+                        metric_name="numerical_drift",
+                        status="PASSED",
+                        severity="INFO",
+                        message=f"Skipped drift check for column '{col}': insufficient data (all nulls).",
+                        reference_value=None,
+                        new_value=None,
+                        p_value=1.0,
+                    )
+                )
+                continue
+
+            # Perform the Kolmogorov-Smirnov two-sample test
+            statistic, p_value = ks_2samp(ref_data, new_data)
+            p_value = float(p_value)
+
+            ref_stats = {"mean": float(ref_data.mean()), "std": float(ref_data.std())}
+            new_stats = {"mean": float(new_data.mean()), "std": float(new_data.std())}
+
+            if p_value < p_threshold:
+                results.append(
+                    CheckResult(
+                        column=col,
+                        check_type="drift",
+                        metric_name="numerical_drift",
+                        status="FAILED",
+                        severity="WARNING",
+                        message=(
+                            f"Numerical drift detected in column '{col}' "
+                            f"(KS test p-value: {p_value:.4e} < threshold {p_threshold})."
+                        ),
+                        reference_value=ref_stats,
+                        new_value=new_stats,
+                        p_value=p_value,
+                    )
+                )
+            else:
+                results.append(
+                    CheckResult(
+                        column=col,
+                        check_type="drift",
+                        metric_name="numerical_drift",
+                        status="PASSED",
+                        severity="INFO",
+                        message=(
+                            f"No numerical drift detected in column '{col}' "
+                            f"(KS test p-value: {p_value:.4f})."
+                        ),
+                        reference_value=ref_stats,
+                        new_value=new_stats,
+                        p_value=p_value,
+                    )
+                )
+
+        else:
+            # Treat as categorical/boolean/object
+            ref_data = ref_df[col].dropna().astype(str)
+            new_data = new_df[col].dropna().astype(str)
+
+            if len(ref_data) == 0 or len(new_data) == 0:
+                results.append(
+                    CheckResult(
+                        column=col,
+                        check_type="drift",
+                        metric_name="categorical_drift",
+                        status="PASSED",
+                        severity="INFO",
+                        message=f"Skipped drift check for column '{col}': insufficient data (all nulls).",
+                        reference_value=None,
+                        new_value=None,
+                        p_value=1.0,
+                    )
+                )
+                continue
+
+            ref_counts = ref_data.value_counts()
+            new_counts = new_data.value_counts()
+            all_cats = list(set(ref_counts.index).union(new_counts.index))
+
+            if len(all_cats) < 2:
+                results.append(
+                    CheckResult(
+                        column=col,
+                        check_type="drift",
+                        metric_name="categorical_drift",
+                        status="PASSED",
+                        severity="INFO",
+                        message=(
+                            f"Skipped drift check for column '{col}': "
+                            f"less than 2 unique categories found."
+                        ),
+                        reference_value=ref_counts.to_dict(),
+                        new_value=new_counts.to_dict(),
+                        p_value=1.0,
+                    )
+                )
+                continue
+
+            # Construct contingency table
+            contingency_table = []
+            for cat in all_cats:
+                contingency_table.append([ref_counts.get(cat, 0), new_counts.get(cat, 0)])
+
+            contingency_table = np.array(contingency_table)
+
+            try:
+                # chi2_contingency returns: chi2, p, dof, expected
+                _, p_value, _, _ = chi2_contingency(contingency_table)
+                p_value = float(p_value)
+            except Exception:
+                p_value = 1.0
+
+            ref_dist = (ref_counts / len(ref_data)).to_dict()
+            new_dist = (new_counts / len(new_data)).to_dict()
+
+            if p_value < p_threshold:
+                results.append(
+                    CheckResult(
+                        column=col,
+                        check_type="drift",
+                        metric_name="categorical_drift",
+                        status="FAILED",
+                        severity="WARNING",
+                        message=(
+                            f"Categorical drift detected in column '{col}' "
+                            f"(Chi-Square test p-value: {p_value:.4e} < threshold {p_threshold})."
+                        ),
+                        reference_value=ref_dist,
+                        new_value=new_dist,
+                        p_value=p_value,
+                    )
+                )
+            else:
+                results.append(
+                    CheckResult(
+                        column=col,
+                        check_type="drift",
+                        metric_name="categorical_drift",
+                        status="PASSED",
+                        severity="INFO",
+                        message=(
+                            f"No categorical drift detected in column '{col}' "
+                            f"(Chi-Square test p-value: {p_value:.4f})."
+                        ),
+                        reference_value=ref_dist,
+                        new_value=new_dist,
+                        p_value=p_value,
+                    )
+                )
+
+    return results

driftguard_prathvi-0.1.0/driftguard/checks/nulls.py

@@ -0,0 +1,71 @@
+"""Null rate validation checks for DriftGuard."""
+
+import pandas as pd
+from typing import List
+from driftguard.utils import CheckResult
+
+
+def check_nulls(
+    ref_df: pd.DataFrame,
+    new_df: pd.DataFrame,
+    columns: List[str],
+    null_threshold: float,
+) -> List[CheckResult]:
+    """Compares the null rates of specified columns between ref_df and new_df.
+
+    Flags columns where the null rate increased beyond the specified threshold.
+
+    Args:
+        ref_df: The reference pandas DataFrame.
+        new_df: The new pandas DataFrame.
+        columns: The list of common columns to check.
+        null_threshold: The maximum allowed increase in null rate (absolute).
+
+    Returns:
+        A list of CheckResult objects containing null analysis details.
+    """
+    results = []
+
+    for col in columns:
+        ref_null_rate = float(ref_df[col].isnull().mean())
+        new_null_rate = float(new_df[col].isnull().mean())
+        diff = new_null_rate - ref_null_rate
+
+        if diff > null_threshold:
+            # If the new null rate is exactly 100%, it is a critical issue.
+            # Otherwise, it is a warning.
+            severity = "CRITICAL" if new_null_rate == 1.0 else "WARNING"
+            results.append(
+                CheckResult(
+                    column=col,
+                    check_type="nulls",
+                    metric_name="null_rate_increase",
+                    status="FAILED",
+                    severity=severity,
+                    message=(
+                        f"Null rate for column '{col}' increased from {ref_null_rate:.2%} "
+                        f"to {new_null_rate:.2%} (increase of {diff:.2%} exceeds "
+                        f"threshold of {null_threshold:.2%})."
+                    ),
+                    reference_value=ref_null_rate,
+                    new_value=new_null_rate,
+                )
+            )
+        else:
+            results.append(
+                CheckResult(
+                    column=col,
+                    check_type="nulls",
+                    metric_name="null_rate_check",
+                    status="PASSED",
+                    severity="INFO",
+                    message=(
+                        f"Null rate for column '{col}' is within acceptable limits "
+                        f"(increase: {diff:.2%})."
+                    ),
+                    reference_value=ref_null_rate,
+                    new_value=new_null_rate,
+                )
+            )
+
+    return results

driftguard_prathvi-0.1.0/driftguard/checks/schema.py

@@ -0,0 +1,95 @@
+"""Schema validation checks for DriftGuard."""
+
+import pandas as pd
+from typing import List
+from driftguard.utils import CheckResult
+
+
+def check_schema(ref_df: pd.DataFrame, new_df: pd.DataFrame) -> List[CheckResult]:
+    """Validates the schema of the new DataFrame against the reference DataFrame.
+
+    Checks for:
+    - Missing columns: Columns present in ref_df but not in new_df.
+    - New columns: Columns present in new_df but not in ref_df.
+    - Data type mismatches: Columns present in both but with different dtypes.
+
+    Args:
+        ref_df: The reference pandas DataFrame.
+        new_df: The new pandas DataFrame to validate.
+
+    Returns:
+        A list of CheckResult objects containing the validation details.
+    """
+    results = []
+    ref_cols = set(ref_df.columns)
+    new_cols = set(new_df.columns)
+
+    # Detect missing columns
+    missing_cols = ref_cols - new_cols
+    for col in missing_cols:
+        results.append(
+            CheckResult(
+                column=col,
+                check_type="schema",
+                metric_name="missing_column",
+                status="FAILED",
+                severity="CRITICAL",
+                message=f"Column '{col}' is missing in the new dataset.",
+                reference_value=str(ref_df[col].dtype),
+                new_value=None,
+            )
+        )
+
+    # Detect new columns
+    new_cols_detected = new_cols - ref_cols
+    for col in new_cols_detected:
+        results.append(
+            CheckResult(
+                column=col,
+                check_type="schema",
+                metric_name="new_column",
+                status="FAILED",
+                severity="INFO",
+                message=f"New column '{col}' detected in the new dataset.",
+                reference_value=None,
+                new_value=str(new_df[col].dtype),
+            )
+        )
+
+    # Detect dtype mismatches
+    common_cols = ref_cols.intersection(new_cols)
+    for col in common_cols:
+        ref_dtype = ref_df[col].dtype
+        new_dtype = new_df[col].dtype
+
+        if ref_dtype != new_dtype:
+            results.append(
+                CheckResult(
+                    column=col,
+                    check_type="schema",
+                    metric_name="dtype_mismatch",
+                    status="FAILED",
+                    severity="CRITICAL",
+                    message=(
+                        f"Data type mismatch for column '{col}': "
+                        f"expected {ref_dtype}, got {new_dtype}."
+                    ),
+                    reference_value=str(ref_dtype),
+                    new_value=str(new_dtype),
+                )
+            )
+        else:
+            results.append(
+                CheckResult(
+                    column=col,
+                    check_type="schema",
+                    metric_name="schema_validation",
+                    status="PASSED",
+                    severity="INFO",
+                    message=f"Schema and data type validated for column '{col}'.",
+                    reference_value=str(ref_dtype),
+                    new_value=str(new_dtype),
+                )
+            )
+
+    return results