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

truthound_dashboard/schemas/validators/query_validators.py

@@ -0,0 +1,510 @@
+"""Query validators.
+
+Expression-based validators using Polars expressions and custom queries.
+"""
+
+from .base import (
+    ParameterDefinition,
+    ParameterType,
+    ValidatorCategory,
+    ValidatorDefinition,
+)
+
+QUERY_VALIDATORS: list[ValidatorDefinition] = [
+    ValidatorDefinition(
+        name="Expression",
+        display_name="Expression Validator",
+        category=ValidatorCategory.QUERY,
+        description="Validates data using a custom Polars expression.",
+        parameters=[
+            ParameterDefinition(
+                name="expression",
+                label="Expression",
+                type=ParameterType.EXPRESSION,
+                description="Polars expression that should evaluate to true",
+                required=True,
+                placeholder='col("price") > 0',
+            ),
+            ParameterDefinition(
+                name="description",
+                label="Description",
+                type=ParameterType.STRING,
+                description="Human-readable description of the rule",
+            ),
+        ],
+        tags=["query", "expression", "custom"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="CustomExpression",
+        display_name="Custom Expression String",
+        category=ValidatorCategory.QUERY,
+        description="Validates using a Polars expression string.",
+        parameters=[
+            ParameterDefinition(
+                name="expression_str",
+                label="Expression String",
+                type=ParameterType.STRING,
+                description="Expression as string (parsed at runtime)",
+                required=True,
+                placeholder='(col("quantity") * col("price")).alias("total") == col("total")',
+            ),
+        ],
+        tags=["query", "expression", "string"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="QueryRowCount",
+        display_name="Query Row Count",
+        category=ValidatorCategory.QUERY,
+        description="Validates row count from a filter query.",
+        parameters=[
+            ParameterDefinition(
+                name="filter_expression",
+                label="Filter Expression",
+                type=ParameterType.EXPRESSION,
+                description="Filter to apply before counting",
+                required=True,
+                placeholder='col("status") == "error"',
+            ),
+            ParameterDefinition(
+                name="expected_count",
+                label="Expected Count",
+                type=ParameterType.INTEGER,
+                min_value=0,
+            ),
+            ParameterDefinition(
+                name="max_count",
+                label="Maximum Count",
+                type=ParameterType.INTEGER,
+                min_value=0,
+            ),
+        ],
+        tags=["query", "count", "filter"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="QueryReturnsNoRows",
+        display_name="Query Returns No Rows",
+        category=ValidatorCategory.QUERY,
+        description="Validates that a filter query returns zero rows (no violations).",
+        parameters=[
+            ParameterDefinition(
+                name="filter_expression",
+                label="Violation Filter",
+                type=ParameterType.EXPRESSION,
+                description="Filter that should match zero rows",
+                required=True,
+                placeholder='(col("start_date") > col("end_date"))',
+            ),
+            ParameterDefinition(
+                name="violation_message",
+                label="Violation Message",
+                type=ParameterType.STRING,
+                description="Message to show when violations found",
+            ),
+        ],
+        tags=["query", "no_rows", "violation"],
+        severity_default="high",
+    ),
+    ValidatorDefinition(
+        name="QueryReturnsRows",
+        display_name="Query Returns Rows",
+        category=ValidatorCategory.QUERY,
+        description="Validates that a filter query returns at least one row.",
+        parameters=[
+            ParameterDefinition(
+                name="filter_expression",
+                label="Filter Expression",
+                type=ParameterType.EXPRESSION,
+                description="Filter that should match at least one row",
+                required=True,
+            ),
+            ParameterDefinition(
+                name="min_rows",
+                label="Minimum Rows",
+                type=ParameterType.INTEGER,
+                default=1,
+                min_value=1,
+            ),
+        ],
+        tags=["query", "rows", "existence"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="QueryAggregate",
+        display_name="Query Aggregate",
+        category=ValidatorCategory.QUERY,
+        description="Validates aggregate result from a query.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="aggregate",
+                label="Aggregate Function",
+                type=ParameterType.SELECT,
+                required=True,
+                options=[
+                    {"value": "sum", "label": "Sum"},
+                    {"value": "mean", "label": "Mean"},
+                    {"value": "min", "label": "Min"},
+                    {"value": "max", "label": "Max"},
+                    {"value": "count", "label": "Count"},
+                    {"value": "std", "label": "Std Dev"},
+                ],
+            ),
+            ParameterDefinition(
+                name="filter_expression",
+                label="Filter Expression",
+                type=ParameterType.EXPRESSION,
+                description="Optional filter before aggregation",
+            ),
+            ParameterDefinition(
+                name="expected_value",
+                label="Expected Value",
+                type=ParameterType.FLOAT,
+            ),
+            ParameterDefinition(
+                name="min_value",
+                label="Minimum Value",
+                type=ParameterType.FLOAT,
+            ),
+            ParameterDefinition(
+                name="max_value",
+                label="Maximum Value",
+                type=ParameterType.FLOAT,
+            ),
+            ParameterDefinition(
+                name="tolerance",
+                label="Tolerance",
+                type=ParameterType.FLOAT,
+                default=0.0001,
+                min_value=0,
+            ),
+        ],
+        tags=["query", "aggregate", "statistics"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="QueryGroupAggregate",
+        display_name="Query Group Aggregate",
+        category=ValidatorCategory.QUERY,
+        description="Validates aggregate per group.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column to Aggregate",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="group_by",
+                label="Group By Columns",
+                type=ParameterType.COLUMN_LIST,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="aggregate",
+                label="Aggregate Function",
+                type=ParameterType.SELECT,
+                required=True,
+                options=[
+                    {"value": "sum", "label": "Sum"},
+                    {"value": "mean", "label": "Mean"},
+                    {"value": "min", "label": "Min"},
+                    {"value": "max", "label": "Max"},
+                    {"value": "count", "label": "Count"},
+                ],
+            ),
+            ParameterDefinition(
+                name="min_value",
+                label="Min Value Per Group",
+                type=ParameterType.FLOAT,
+            ),
+            ParameterDefinition(
+                name="max_value",
+                label="Max Value Per Group",
+                type=ParameterType.FLOAT,
+            ),
+        ],
+        tags=["query", "group", "aggregate"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="QueryAggregateCompare",
+        display_name="Query Aggregate Compare",
+        category=ValidatorCategory.QUERY,
+        description="Compares aggregates from two different filters.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="filter_a",
+                label="Filter A",
+                type=ParameterType.EXPRESSION,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="filter_b",
+                label="Filter B",
+                type=ParameterType.EXPRESSION,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="aggregate",
+                label="Aggregate Function",
+                type=ParameterType.SELECT,
+                required=True,
+                options=[
+                    {"value": "sum", "label": "Sum"},
+                    {"value": "mean", "label": "Mean"},
+                    {"value": "count", "label": "Count"},
+                ],
+            ),
+            ParameterDefinition(
+                name="operator",
+                label="Comparison",
+                type=ParameterType.SELECT,
+                required=True,
+                options=[
+                    {"value": "eq", "label": "A = B"},
+                    {"value": "gt", "label": "A > B"},
+                    {"value": "gte", "label": "A >= B"},
+                    {"value": "lt", "label": "A < B"},
+                    {"value": "lte", "label": "A <= B"},
+                ],
+            ),
+            ParameterDefinition(
+                name="tolerance",
+                label="Tolerance",
+                type=ParameterType.FLOAT,
+                default=0.0001,
+                min_value=0,
+            ),
+        ],
+        tags=["query", "compare", "aggregate"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="QueryColumnValues",
+        display_name="Query Column Values",
+        category=ValidatorCategory.QUERY,
+        description="Validates column values from filtered query.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="filter_expression",
+                label="Filter Expression",
+                type=ParameterType.EXPRESSION,
+            ),
+            ParameterDefinition(
+                name="expected_values",
+                label="Expected Values",
+                type=ParameterType.STRING_LIST,
+                description="Values that should appear",
+            ),
+            ParameterDefinition(
+                name="forbidden_values",
+                label="Forbidden Values",
+                type=ParameterType.STRING_LIST,
+                description="Values that should not appear",
+            ),
+        ],
+        tags=["query", "values", "column"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="QueryColumnUnique",
+        display_name="Query Column Unique",
+        category=ValidatorCategory.QUERY,
+        description="Validates uniqueness within filtered results.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="filter_expression",
+                label="Filter Expression",
+                type=ParameterType.EXPRESSION,
+            ),
+        ],
+        tags=["query", "unique", "filter"],
+        severity_default="high",
+    ),
+    ValidatorDefinition(
+        name="QueryColumnNotNull",
+        display_name="Query Column Not Null",
+        category=ValidatorCategory.QUERY,
+        description="Validates no nulls within filtered results.",
+        parameters=[
+            ParameterDefinition(
+                name="column",
+                label="Column",
+                type=ParameterType.COLUMN,
+                required=True,
+            ),
+            ParameterDefinition(
+                name="filter_expression",
+                label="Filter Expression",
+                type=ParameterType.EXPRESSION,
+            ),
+        ],
+        tags=["query", "not_null", "filter"],
+        severity_default="high",
+    ),
+    ValidatorDefinition(
+        name="ConditionalExpression",
+        display_name="Conditional Expression",
+        category=ValidatorCategory.QUERY,
+        description="Validates expression only when condition is met.",
+        parameters=[
+            ParameterDefinition(
+                name="condition",
+                label="Condition",
+                type=ParameterType.EXPRESSION,
+                description="When this is true, validate the expression",
+                required=True,
+            ),
+            ParameterDefinition(
+                name="expression",
+                label="Expression",
+                type=ParameterType.EXPRESSION,
+                description="Expression to validate when condition is met",
+                required=True,
+            ),
+        ],
+        tags=["query", "conditional", "expression"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="MultiCondition",
+        display_name="Multi-Condition Validator",
+        category=ValidatorCategory.QUERY,
+        description="Validates multiple conditions simultaneously.",
+        parameters=[
+            ParameterDefinition(
+                name="conditions",
+                label="Conditions",
+                type=ParameterType.STRING_LIST,
+                description="List of condition expressions (all must pass)",
+                required=True,
+            ),
+            ParameterDefinition(
+                name="mode",
+                label="Mode",
+                type=ParameterType.SELECT,
+                options=[
+                    {"value": "all", "label": "All must pass"},
+                    {"value": "any", "label": "Any must pass"},
+                    {"value": "none", "label": "None should pass"},
+                ],
+                default="all",
+            ),
+        ],
+        tags=["query", "multi", "conditions"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="RowLevel",
+        display_name="Row-Level Validator",
+        category=ValidatorCategory.QUERY,
+        description="Validates expression at the row level.",
+        parameters=[
+            ParameterDefinition(
+                name="expression",
+                label="Row Expression",
+                type=ParameterType.EXPRESSION,
+                description="Expression evaluated per row",
+                required=True,
+            ),
+            ParameterDefinition(
+                name="min_pass_ratio",
+                label="Min Pass Ratio",
+                type=ParameterType.FLOAT,
+                description="Minimum ratio of rows that must pass",
+                default=1.0,
+                min_value=0,
+                max_value=1,
+            ),
+        ],
+        tags=["query", "row", "per_row"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="SQLQuery",
+        display_name="SQL Query Validator",
+        category=ValidatorCategory.QUERY,
+        description="Validates data using SQL query syntax.",
+        parameters=[
+            ParameterDefinition(
+                name="query",
+                label="SQL Query",
+                type=ParameterType.STRING,
+                description="SQL query (using Polars SQL context)",
+                required=True,
+                placeholder="SELECT * FROM df WHERE price < 0",
+            ),
+            ParameterDefinition(
+                name="expect_empty",
+                label="Expect Empty Result",
+                type=ParameterType.BOOLEAN,
+                description="Query should return no rows (violations)",
+                default=True,
+            ),
+        ],
+        tags=["query", "sql", "advanced"],
+        severity_default="medium",
+    ),
+    ValidatorDefinition(
+        name="BusinessRule",
+        display_name="Business Rule Validator",
+        category=ValidatorCategory.QUERY,
+        description="Validates complex business rules using expressions.",
+        parameters=[
+            ParameterDefinition(
+                name="rule_name",
+                label="Rule Name",
+                type=ParameterType.STRING,
+                description="Name of the business rule",
+                required=True,
+            ),
+            ParameterDefinition(
+                name="rule_expression",
+                label="Rule Expression",
+                type=ParameterType.EXPRESSION,
+                description="Expression that defines the rule",
+                required=True,
+            ),
+            ParameterDefinition(
+                name="error_message",
+                label="Error Message",
+                type=ParameterType.STRING,
+                description="Message when rule is violated",
+            ),
+            ParameterDefinition(
+                name="category",
+                label="Rule Category",
+                type=ParameterType.STRING,
+                description="Business category (e.g., finance, compliance)",
+            ),
+        ],
+        tags=["query", "business", "rule"],
+        severity_default="high",
+    ),
+]