truthound-dashboard 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

truthound_dashboard/schemas/validators/drift_validators.py

@@ -0,0 +1,615 @@
+"""Drift validators.
+
+Distribution change detection validators for monitoring data quality over time.
+Requires: pip install truthound[drift] (scipy)
+"""
+
+from .base import (
+    ParameterDefinition,
+    ParameterType,
+    ValidatorCategory,
+    ValidatorDefinition,
+)
+
+DRIFT_VALIDATORS: list[ValidatorDefinition] = [
+    ValidatorDefinition(
+        name="KSTest",
+        display_name="Kolmogorov-Smirnov Test",
+        category=ValidatorCategory.DRIFT,
+        description="Detects distribution drift using Kolmogorov-Smirnov statistical test.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                description="ID of the reference data source (baseline)",
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+                description="Column in reference data (default: same name)",
+            ),
+            ParameterDefinition(
+                name="p_value_threshold",
+                label="P-Value Threshold",
+                type=ParameterType.FLOAT,
+                description="P-value threshold for significance (lower = more strict)",
+                default=0.05,
+                min_value=0,
+                max_value=1,
+            ),
+            ParameterDefinition(
+                name="statistic_threshold",
+                label="Statistic Threshold",
+                type=ParameterType.FLOAT,
+                description="Maximum KS statistic threshold (optional)",
+                min_value=0,
+                max_value=1,
+            ),
+        ],
+        tags=["drift", "ks", "statistical", "distribution"],
+        severity_default="high",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="PSI",
+        display_name="Population Stability Index",
+        category=ValidatorCategory.DRIFT,
+        description="Measures population stability using PSI metric.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+            ),
+            ParameterDefinition(
+                name="threshold",
+                label="PSI Threshold",
+                type=ParameterType.FLOAT,
+                description="PSI threshold (0.1 = slight, 0.25 = significant)",
+                default=0.25,
+                min_value=0,
+            ),
+            ParameterDefinition(
+                name="n_bins",
+                label="Number of Bins",
+                type=ParameterType.INTEGER,
+                description="Number of bins for numeric columns",
+                default=10,
+                min_value=2,
+            ),
+            ParameterDefinition(
+                name="is_categorical",
+                label="Is Categorical",
+                type=ParameterType.BOOLEAN,
+                description="Treat column as categorical",
+                default=False,
+            ),
+        ],
+        tags=["drift", "psi", "stability", "monitoring"],
+        severity_default="high",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="ChiSquareDrift",
+        display_name="Chi-Square Drift Test",
+        category=ValidatorCategory.DRIFT,
+        description="Detects categorical distribution drift using Chi-square test.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+            ),
+            ParameterDefinition(
+                name="p_value_threshold",
+                label="P-Value Threshold",
+                type=ParameterType.FLOAT,
+                default=0.05,
+                min_value=0,
+                max_value=1,
+            ),
+            ParameterDefinition(
+                name="min_expected_frequency",
+                label="Min Expected Frequency",
+                type=ParameterType.FLOAT,
+                description="Minimum expected frequency per bin",
+                default=5.0,
+                min_value=0,
+            ),
+        ],
+        tags=["drift", "chi_square", "categorical", "statistical"],
+        severity_default="high",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="JSDivergence",
+        display_name="Jensen-Shannon Divergence",
+        category=ValidatorCategory.DRIFT,
+        description="Measures distribution drift using Jensen-Shannon divergence.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+            ),
+            ParameterDefinition(
+                name="threshold",
+                label="JS Divergence Threshold",
+                type=ParameterType.FLOAT,
+                description="Maximum JS divergence (0-1, lower = more strict)",
+                default=0.1,
+                min_value=0,
+                max_value=1,
+            ),
+            ParameterDefinition(
+                name="is_categorical",
+                label="Is Categorical",
+                type=ParameterType.BOOLEAN,
+                default=False,
+            ),
+            ParameterDefinition(
+                name="n_bins",
+                label="Number of Bins",
+                type=ParameterType.INTEGER,
+                description="Number of bins for numeric columns",
+                default=10,
+                min_value=2,
+            ),
+        ],
+        tags=["drift", "js", "divergence", "information_theory"],
+        severity_default="medium",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="Wasserstein",
+        display_name="Wasserstein Distance",
+        category=ValidatorCategory.DRIFT,
+        description="Measures distribution drift using Wasserstein (Earth Mover's) distance.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+            ),
+            ParameterDefinition(
+                name="threshold",
+                label="Distance Threshold",
+                type=ParameterType.FLOAT,
+                description="Maximum Wasserstein distance",
+                required=True,
+            ),
+            ParameterDefinition(
+                name="normalize",
+                label="Normalize",
+                type=ParameterType.BOOLEAN,
+                description="Normalize distance by data range",
+                default=True,
+            ),
+        ],
+        tags=["drift", "wasserstein", "emd", "distance"],
+        severity_default="medium",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="CSI",
+        display_name="Characteristic Stability Index",
+        category=ValidatorCategory.DRIFT,
+        description="Measures stability using CSI (granular bin-level analysis).",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+            ),
+            ParameterDefinition(
+                name="threshold_per_bin",
+                label="Per-Bin Threshold",
+                type=ParameterType.FLOAT,
+                description="CSI threshold per bin",
+                default=0.25,
+                min_value=0,
+            ),
+            ParameterDefinition(
+                name="n_bins",
+                label="Number of Bins",
+                type=ParameterType.INTEGER,
+                default=10,
+                min_value=2,
+            ),
+        ],
+        tags=["drift", "csi", "stability", "binned"],
+        severity_default="medium",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="MeanDrift",
+        display_name="Mean Drift",
+        category=ValidatorCategory.DRIFT,
+        description="Detects drift in column mean values.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+            ),
+            ParameterDefinition(
+                name="threshold_pct",
+                label="Percentage Threshold",
+                type=ParameterType.FLOAT,
+                description="Maximum percentage change in mean",
+                min_value=0,
+            ),
+            ParameterDefinition(
+                name="threshold_abs",
+                label="Absolute Threshold",
+                type=ParameterType.FLOAT,
+                description="Maximum absolute change in mean",
+                min_value=0,
+            ),
+        ],
+        tags=["drift", "mean", "simple", "statistics"],
+        severity_default="medium",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="VarianceDrift",
+        display_name="Variance Drift",
+        category=ValidatorCategory.DRIFT,
+        description="Detects drift in column variance or standard deviation.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+            ),
+            ParameterDefinition(
+                name="threshold_pct",
+                label="Percentage Threshold",
+                type=ParameterType.FLOAT,
+                description="Maximum percentage change",
+                default=0.2,
+                min_value=0,
+            ),
+            ParameterDefinition(
+                name="use_std",
+                label="Use Standard Deviation",
+                type=ParameterType.BOOLEAN,
+                description="Compare std dev instead of variance",
+                default=True,
+            ),
+        ],
+        tags=["drift", "variance", "std", "statistics"],
+        severity_default="medium",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="QuantileDrift",
+        display_name="Quantile Drift",
+        category=ValidatorCategory.DRIFT,
+        description="Detects drift at specific quantile points.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+            ),
+            ParameterDefinition(
+                name="quantiles",
+                label="Quantiles to Check",
+                type=ParameterType.STRING_LIST,
+                description="Quantiles (e.g., 0.25, 0.5, 0.75)",
+                default=["0.25", "0.5", "0.75"],
+            ),
+            ParameterDefinition(
+                name="threshold_pct",
+                label="Percentage Threshold",
+                type=ParameterType.FLOAT,
+                description="Maximum percentage change at each quantile",
+                default=0.2,
+                min_value=0,
+            ),
+        ],
+        tags=["drift", "quantile", "percentile", "distribution"],
+        severity_default="medium",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="RangeDrift",
+        display_name="Range Drift",
+        category=ValidatorCategory.DRIFT,
+        description="Detects drift in min/max range of values.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+            ),
+            ParameterDefinition(
+                name="threshold_pct",
+                label="Percentage Threshold",
+                type=ParameterType.FLOAT,
+                description="Maximum percentage change in range",
+                default=0.1,
+                min_value=0,
+            ),
+            ParameterDefinition(
+                name="allow_expansion",
+                label="Allow Expansion",
+                type=ParameterType.BOOLEAN,
+                description="Only alert on range contraction, not expansion",
+                default=False,
+            ),
+        ],
+        tags=["drift", "range", "bounds"],
+        severity_default="medium",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="FeatureDrift",
+        display_name="Multi-Feature Drift",
+        category=ValidatorCategory.DRIFT,
+        description="Detects drift across multiple features simultaneously.",
+        parameters=[
+            ParameterDefinition(
+                name="columns",
+                label="Columns",
+                type=ParameterType.COLUMN_LIST,
+                description="Columns to monitor for drift",
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="method",
+                label="Drift Method",
+                type=ParameterType.SELECT,
+                options=[
+                    {"value": "psi", "label": "PSI"},
+                    {"value": "ks", "label": "KS Test"},
+                    {"value": "wasserstein", "label": "Wasserstein"},
+                    {"value": "chi_square", "label": "Chi-Square"},
+                ],
+                default="psi",
+            ),
+            ParameterDefinition(
+                name="threshold",
+                label="Threshold",
+                type=ParameterType.FLOAT,
+                default=0.25,
+                min_value=0,
+            ),
+            ParameterDefinition(
+                name="alert_on_any",
+                label="Alert on Any",
+                type=ParameterType.BOOLEAN,
+                description="Alert if any column drifts (vs. minimum count)",
+                default=True,
+            ),
+            ParameterDefinition(
+                name="min_drift_count",
+                label="Min Drift Count",
+                type=ParameterType.INTEGER,
+                description="Minimum columns with drift to trigger alert",
+                default=1,
+                min_value=1,
+            ),
+            ParameterDefinition(
+                name="categorical_columns",
+                label="Categorical Columns",
+                type=ParameterType.STRING_LIST,
+                description="Columns to treat as categorical",
+            ),
+        ],
+        tags=["drift", "multi_feature", "monitoring"],
+        severity_default="high",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="NullRateDrift",
+        display_name="Null Rate Drift",
+        category=ValidatorCategory.DRIFT,
+        description="Detects changes in null value rates.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+            ),
+            ParameterDefinition(
+                name="threshold_abs",
+                label="Absolute Threshold",
+                type=ParameterType.FLOAT,
+                description="Maximum absolute change in null rate (0.0-1.0)",
+                default=0.05,
+                min_value=0,
+                max_value=1,
+            ),
+        ],
+        tags=["drift", "null", "completeness"],
+        severity_default="medium",
+        requires_extra="drift",
+    ),
+    ValidatorDefinition(
+        name="CardinalityDrift",
+        display_name="Cardinality Drift",
+        category=ValidatorCategory.DRIFT,
+        description="Detects changes in the number of distinct values.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_source_id",
+                label="Reference Source",
+                type=ParameterType.SOURCE_REF,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="reference_column",
+                label="Reference Column",
+                type=ParameterType.STRING,
+            ),
+            ParameterDefinition(
+                name="threshold_pct",
+                label="Percentage Threshold",
+                type=ParameterType.FLOAT,
+                description="Maximum percentage change in cardinality",
+                default=0.2,
+                min_value=0,
+            ),
+            ParameterDefinition(
+                name="detect_new_values",
+                label="Detect New Values",
+                type=ParameterType.BOOLEAN,
+                description="Alert on new categorical values",
+                default=True,
+            ),
+            ParameterDefinition(
+                name="detect_missing_values",
+                label="Detect Missing Values",
+                type=ParameterType.BOOLEAN,
+                description="Alert on values that disappeared",
+                default=True,
+            ),
+        ],
+        tags=["drift", "cardinality", "distinct"],
+        severity_default="medium",
+        requires_extra="drift",
+    ),
+]