dqtlib 0.1.0__py3-none-any.whl

dqt/__init__.py

@@ -0,0 +1,49 @@
+# packages/dqt/src/dqt/__init__.py
+"""dqt — open-source data quality, observability, and causality library."""
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from dqt.algorithms._base import (
+    BaseAggregateDetector,
+    BaseDetector,
+    DetectorResult,
+    Verdict,
+    compute_verdict,
+)
+from dqt.adapters._protocol import AggExpr, ColumnMeta, HealthCheckResult, WarehouseAdapter
+from dqt.store._protocol import Incident, ResultsStore, RunResult
+from dqt.store.memory import MemoryStore
+from dqt.checks.models import BaselineConfig, Check, CheckFilter, CheckScope
+from dqt.runner.runner import Runner
+
+# Import all detector groups to trigger @registry.register side effects
+import dqt.algorithms.basic           # noqa: F401
+import dqt.algorithms.schema          # noqa: F401
+import dqt.algorithms.referential     # noqa: F401
+import dqt.algorithms.drift           # noqa: F401
+import dqt.algorithms.outliers_uni    # noqa: F401
+import dqt.algorithms.outliers_multi  # noqa: F401
+import dqt.algorithms.timeseries      # noqa: F401
+
+__all__ = [
+    "__version__",
+    "Verdict",
+    "DetectorResult",
+    "BaseDetector",
+    "BaseAggregateDetector",
+    "compute_verdict",
+    "AggExpr",
+    "ColumnMeta",
+    "HealthCheckResult",
+    "WarehouseAdapter",
+    "ResultsStore",
+    "RunResult",
+    "Incident",
+    "MemoryStore",
+    "Check",
+    "CheckScope",
+    "CheckFilter",
+    "BaselineConfig",
+    "Runner",
+]

dqt/adapters/_protocol.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Protocol, runtime_checkable
+
+import pandas as pd
+
+
+@dataclass
+class AggExpr:
+    name: str
+    sql: str
+
+
+@dataclass
+class HealthCheckStep:
+    name: str
+    status: Literal["pass", "fail", "skip"]
+    latency_ms: float
+    detail: str
+
+
+@dataclass
+class HealthCheckResult:
+    steps: list[HealthCheckStep] = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        return all(s.status in ("pass", "skip") for s in self.steps)
+
+
+@dataclass
+class ColumnMeta:
+    name: str
+    data_type: str
+    nullable: bool
+    position: int
+
+
+@runtime_checkable
+class WarehouseAdapter(Protocol):
+    def health_check(self) -> HealthCheckResult: ...
+    def sample(self, schema: str, table: str, n: int = 100_000) -> pd.DataFrame: ...
+    def aggregate(self, schema: str, table: str, exprs: list[AggExpr]) -> dict[str, object]: ...
+    def describe_columns(self, schema: str, table: str) -> list[ColumnMeta]: ...
+    def list_schemas(self) -> list[str]: ...
+    def list_tables(self, schema: str) -> list[str]: ...

dqt/adapters/local/__init__.py

@@ -0,0 +1,3 @@
+from dqt.adapters.local.adapter import LocalFileAdapter
+
+__all__ = ["LocalFileAdapter"]

dqt/adapters/local/adapter.py

@@ -0,0 +1,118 @@
+# Ref: https://duckdb.org/docs/api/python/overview — used for SQL aggregations on DataFrames
+from __future__ import annotations
+
+import pathlib
+import time
+from typing import Any
+
+import pandas as pd
+
+from dqt.adapters._protocol import (
+    AggExpr,
+    ColumnMeta,
+    HealthCheckResult,
+    HealthCheckStep,
+)
+from dqt.utils.logging import get_logger
+
+_log = get_logger(__name__)
+
+_READERS: dict[str, Any] = {
+    ".csv":     lambda p: pd.read_csv(p),
+    ".tsv":     lambda p: pd.read_csv(p, sep="\t"),
+    ".xlsx":    lambda p: pd.read_excel(p),
+    ".xls":     lambda p: pd.read_excel(p),
+    ".parquet": lambda p: pd.read_parquet(p),
+    ".json":    lambda p: pd.read_json(p),
+    ".jsonl":   lambda p: pd.read_json(p, lines=True),
+    ".ndjson":  lambda p: pd.read_json(p, lines=True),
+    ".feather": lambda p: pd.read_feather(p),
+    ".arrow":   lambda p: pd.read_feather(p),
+}
+
+_HEALTH_STEPS = ("readable", "parseable", "columns", "sample_read", "row_count")
+
+
+class LocalFileAdapter:
+    """Reads a local file and exposes it as a single-table WarehouseAdapter."""
+
+    def __init__(self, path: str | pathlib.Path) -> None:
+        self._path = pathlib.Path(path)
+        self._suffix = self._path.suffix.lower()
+        if self._suffix not in _READERS:
+            supported = ", ".join(sorted(_READERS))
+            raise ValueError(f"Unsupported format '{self._suffix}'. Supported: {supported}")
+        self._table_name = self._path.stem
+
+    def _read(self) -> pd.DataFrame:
+        return _READERS[self._suffix](self._path)
+
+    def health_check(self) -> HealthCheckResult:
+        steps: list[HealthCheckStep] = []
+
+        t0 = time.perf_counter()
+        if not self._path.exists():
+            steps.append(HealthCheckStep("file_exists", "fail", 0.0, f"not found: {self._path}"))
+            for name in _HEALTH_STEPS:
+                steps.append(HealthCheckStep(name, "skip", 0.0, "skipped"))
+            return HealthCheckResult(steps=steps)
+        steps.append(HealthCheckStep("file_exists", "pass", (time.perf_counter() - t0) * 1000, str(self._path)))
+
+        t0 = time.perf_counter()
+        try:
+            self._path.read_bytes()[:1024]
+            steps.append(HealthCheckStep("readable", "pass", (time.perf_counter() - t0) * 1000, "ok"))
+        except Exception as exc:
+            steps.append(HealthCheckStep("readable", "fail", 0.0, str(exc)))
+            for name in ("parseable", "columns", "sample_read", "row_count"):
+                steps.append(HealthCheckStep(name, "skip", 0.0, "skipped"))
+            return HealthCheckResult(steps=steps)
+
+        t0 = time.perf_counter()
+        try:
+            df = self._read()
+        except Exception as exc:
+            steps.append(HealthCheckStep("parseable", "fail", 0.0, str(exc)))
+            for name in ("columns", "sample_read", "row_count"):
+                steps.append(HealthCheckStep(name, "skip", 0.0, "skipped"))
+            return HealthCheckResult(steps=steps)
+        steps.append(HealthCheckStep("parseable", "pass", (time.perf_counter() - t0) * 1000, f"{len(df.columns)} columns"))
+
+        steps.append(HealthCheckStep("columns", "pass", 0.0, str(list(df.columns)[:5])))
+        steps.append(HealthCheckStep("sample_read", "pass", 0.0, "ok"))
+        steps.append(HealthCheckStep("row_count", "pass", 0.0, f"{len(df)} rows"))
+        return HealthCheckResult(steps=steps)
+
+    def list_schemas(self) -> list[str]:
+        return ["default"]
+
+    def list_tables(self, schema: str) -> list[str]:
+        return [self._table_name]
+
+    def describe_columns(self, schema: str, table: str) -> list[ColumnMeta]:
+        df = self._read()
+        return [
+            ColumnMeta(
+                name=col,
+                data_type=str(df[col].dtype),
+                nullable=bool(df[col].isna().any()),
+                position=i + 1,
+            )
+            for i, col in enumerate(df.columns)
+        ]
+
+    def sample(self, schema: str, table: str, n: int = 100_000) -> pd.DataFrame:
+        df = self._read()
+        if len(df) <= n:
+            return df.reset_index(drop=True)
+        return df.sample(n=n, random_state=42).reset_index(drop=True)
+
+    def aggregate(self, schema: str, table: str, exprs: list[AggExpr]) -> dict[str, Any]:
+        import duckdb
+        df = self._read()
+        con = duckdb.connect()
+        con.register("_data", df)
+        cols = ", ".join(f"{e.sql} AS {e.name}" for e in exprs)
+        row = con.execute(f"SELECT {cols} FROM _data").fetchone()  # noqa: S608
+        con.close()
+        return dict(zip([e.name for e in exprs], row))

dqt/adapters/postgres/__init__.py

@@ -0,0 +1,4 @@
+from dqt.adapters.postgres.adapter import PostgresAdapter
+from dqt.adapters.postgres.config import PostgresConfig
+
+__all__ = ["PostgresAdapter", "PostgresConfig"]

dqt/adapters/postgres/adapter.py

@@ -0,0 +1,154 @@
+# PostgresAdapter wraps SQLAlchemy for all warehouse operations.
+# Sampling uses LIMIT for portable random rows; TABLESAMPLE BERNOULLI available as an option.
+from __future__ import annotations
+
+import datetime
+import time
+from typing import Any
+
+import pandas as pd
+import sqlalchemy as sa
+
+from dqt.adapters._protocol import (
+    AggExpr,
+    ColumnMeta,
+    HealthCheckResult,
+    HealthCheckStep,
+)
+from dqt.utils.logging import get_logger
+
+_log = get_logger(__name__)
+
+
+class PostgresAdapter:
+    def __init__(self, conn_str: str) -> None:
+        self._conn_str = conn_str
+        self._engine = sa.create_engine(
+            conn_str,
+            pool_pre_ping=True,
+            execution_options={"isolation_level": "READ COMMITTED"},
+        )
+
+    def health_check(self) -> HealthCheckResult:
+        steps: list[HealthCheckStep] = []
+        steps.append(self._step_tcp())
+        if steps[-1].status == "fail":
+            for name in ("auth", "info_schema", "sample_select", "latency_probe", "clock_skew"):
+                steps.append(HealthCheckStep(name=name, status="skip", latency_ms=0.0, detail="skipped"))
+            return HealthCheckResult(steps=steps)
+        steps.append(self._step_auth())
+        steps.append(self._step_info_schema())
+        steps.append(self._step_sample_select())
+        steps.append(self._step_latency())
+        steps.append(self._step_clock_skew())
+        return HealthCheckResult(steps=steps)
+
+    def _step_tcp(self) -> HealthCheckStep:
+        t0 = time.perf_counter()
+        try:
+            with self._engine.connect() as conn:
+                conn.execute(sa.text("SELECT 1"))
+            return HealthCheckStep("tcp_reach", "pass", (time.perf_counter() - t0) * 1000, "ok")
+        except Exception as exc:
+            return HealthCheckStep("tcp_reach", "fail", 0.0, str(exc))
+
+    def _step_auth(self) -> HealthCheckStep:
+        t0 = time.perf_counter()
+        try:
+            with self._engine.connect() as conn:
+                user = conn.execute(sa.text("SELECT current_user")).scalar()
+            return HealthCheckStep("auth", "pass", (time.perf_counter() - t0) * 1000, f"user={user}")
+        except Exception as exc:
+            return HealthCheckStep("auth", "fail", 0.0, str(exc))
+
+    def _step_info_schema(self) -> HealthCheckStep:
+        t0 = time.perf_counter()
+        try:
+            with self._engine.connect() as conn:
+                conn.execute(sa.text(
+                    "SELECT COUNT(*) FROM information_schema.tables "
+                    "WHERE table_schema NOT IN ('pg_catalog','information_schema')"
+                )).scalar()
+            return HealthCheckStep("info_schema", "pass", (time.perf_counter() - t0) * 1000, "readable")
+        except Exception as exc:
+            return HealthCheckStep("info_schema", "fail", 0.0, str(exc))
+
+    def _step_sample_select(self) -> HealthCheckStep:
+        t0 = time.perf_counter()
+        try:
+            with self._engine.connect() as conn:
+                conn.execute(sa.text(
+                    "SELECT table_name FROM information_schema.tables "
+                    "WHERE table_schema NOT IN ('pg_catalog','information_schema') LIMIT 1"
+                )).fetchone()
+            return HealthCheckStep("sample_select", "pass", (time.perf_counter() - t0) * 1000, "ok")
+        except Exception as exc:
+            return HealthCheckStep("sample_select", "fail", 0.0, str(exc))
+
+    def _step_latency(self) -> HealthCheckStep:
+        t0 = time.perf_counter()
+        try:
+            with self._engine.connect() as conn:
+                conn.execute(sa.text("SELECT 1"))
+            latency = (time.perf_counter() - t0) * 1000
+            return HealthCheckStep("latency_probe", "pass", latency, f"{latency:.1f}ms")
+        except Exception as exc:
+            return HealthCheckStep("latency_probe", "fail", 0.0, str(exc))
+
+    def _step_clock_skew(self) -> HealthCheckStep:
+        t0 = time.perf_counter()
+        try:
+            with self._engine.connect() as conn:
+                db_now = conn.execute(sa.text("SELECT NOW()")).scalar()
+            local_now = datetime.datetime.now(datetime.timezone.utc)
+            if db_now.tzinfo is None:
+                db_now = db_now.replace(tzinfo=datetime.timezone.utc)
+            skew_s = abs((db_now - local_now).total_seconds())
+            status = "pass" if skew_s < 60 else "fail"
+            return HealthCheckStep("clock_skew", status, (time.perf_counter() - t0) * 1000, f"skew={skew_s:.1f}s")
+        except Exception as exc:
+            return HealthCheckStep("clock_skew", "fail", 0.0, str(exc))
+
+    def list_schemas(self) -> list[str]:
+        with self._engine.connect() as conn:
+            rows = conn.execute(sa.text(
+                "SELECT DISTINCT table_schema FROM information_schema.tables "
+                "WHERE table_schema NOT IN ('pg_catalog','information_schema') ORDER BY 1"
+            )).fetchall()
+        return [r[0] for r in rows]
+
+    def list_tables(self, schema: str) -> list[str]:
+        with self._engine.connect() as conn:
+            rows = conn.execute(sa.text(
+                "SELECT table_name FROM information_schema.tables "
+                "WHERE table_schema = :schema ORDER BY 1"
+            ), {"schema": schema}).fetchall()
+        return [r[0] for r in rows]
+
+    def describe_columns(self, schema: str, table: str) -> list[ColumnMeta]:
+        with self._engine.connect() as conn:
+            rows = conn.execute(sa.text(
+                "SELECT column_name, data_type, is_nullable, ordinal_position "
+                "FROM information_schema.columns "
+                "WHERE table_schema = :schema AND table_name = :table "
+                "ORDER BY ordinal_position"
+            ), {"schema": schema, "table": table}).fetchall()
+        return [
+            ColumnMeta(name=r[0], data_type=r[1], nullable=(r[2] == "YES"), position=r[3])
+            for r in rows
+        ]
+
+    def sample(self, schema: str, table: str, n: int = 100_000) -> pd.DataFrame:
+        # Use ORDER BY random() to get a genuine random sample without TABLESAMPLE bias on small tables.
+        # schema/table are double-quoted identifiers, not user values in SQL context.
+        query = sa.text(f'SELECT * FROM "{schema}"."{table}" ORDER BY random() LIMIT :n')
+        with self._engine.connect() as conn:
+            return pd.read_sql(query, conn, params={"n": n})
+
+    def aggregate(self, schema: str, table: str, exprs: list[AggExpr]) -> dict[str, Any]:
+        cols = ", ".join(f"{e.sql} AS {e.name}" for e in exprs)
+        # schema/table are double-quoted identifiers; cols are built from AggExpr.sql (caller-controlled).
+        query = sa.text(f'SELECT {cols} FROM "{schema}"."{table}"')
+        with self._engine.connect() as conn:
+            row = conn.execute(query).fetchone()
+        return dict(zip([e.name for e in exprs], row))

dqt/adapters/postgres/config.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class PostgresConfig:
+    host: str = "localhost"
+    port: int = 5432
+    database: str = "postgres"
+    username: str = "postgres"
+    password: str = ""
+    ssl_mode: str = "prefer"
+
+    def to_conn_str(self) -> str:
+        return (
+            f"postgresql+psycopg2://{self.username}:{self.password}"
+            f"@{self.host}:{self.port}/{self.database}?sslmode={self.ssl_mode}"
+        )

dqt/algorithms/_base.py

@@ -0,0 +1,70 @@
+# Base classes for all detectors. StatScale and STAT_SCALES live in _scales.py (no dqt imports there).
+# compute_verdict defers the _scales import to break any potential circular dependency.
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import TYPE_CHECKING, Any, ClassVar
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    from dqt.adapters._protocol import AggExpr
+
+
+class Verdict(str, Enum):
+    pass_ = "pass"
+    warn = "warn"
+    fail = "fail"
+
+
+@dataclass
+class DetectorResult:
+    score: float
+    verdict: Verdict
+    plain_english: str
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+DetectorState = Any
+
+
+def compute_verdict(score: float, slug: str) -> Verdict:
+    from dqt.algorithms._scales import STAT_SCALES  # deferred to avoid circular deps
+    scale = STAT_SCALES.get(slug)
+    if scale is None:
+        raise KeyError(f"No STAT_SCALE entry for slug '{slug}'. Add it to _scales.py.")
+    if scale.direction == "lower_is_better":
+        if score >= scale.fail_threshold:
+            return Verdict.fail
+        if score >= scale.warn_threshold:
+            return Verdict.warn
+        return Verdict.pass_
+    else:
+        if score <= scale.fail_threshold:
+            return Verdict.fail
+        if score <= scale.warn_threshold:
+            return Verdict.warn
+        return Verdict.pass_
+
+
+class BaseDetector:
+    slug: ClassVar[str]
+    group: ClassVar[str]
+    kind: ClassVar[str] = "sample"
+
+    def fit(self, reference: pd.DataFrame) -> DetectorState:
+        raise NotImplementedError
+
+    def score(self, current: pd.DataFrame, state: DetectorState) -> DetectorResult:
+        raise NotImplementedError
+
+    def _verdict(self, score: float) -> Verdict:
+        return compute_verdict(score, self.slug)
+
+
+class BaseAggregateDetector(BaseDetector):
+    kind: ClassVar[str] = "aggregate"
+
+    def get_aggregations(self, col: str) -> list[AggExpr]:
+        raise NotImplementedError

dqt/algorithms/_registry.py

@@ -0,0 +1,28 @@
+# Detector registry for slug-based lookup.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dqt.algorithms._base import BaseDetector
+
+
+class Registry:
+    def __init__(self) -> None:
+        self._map: dict[str, type[BaseDetector]] = {}
+
+    def register(self, cls: type[BaseDetector]) -> type[BaseDetector]:
+        self._map[cls.slug] = cls
+        return cls
+
+    def get(self, slug: str) -> type[BaseDetector]:
+        try:
+            return self._map[slug]
+        except KeyError:
+            raise KeyError(f"Detector slug '{slug}' not registered. Import the detector module first.")
+
+    def slugs(self) -> list[str]:
+        return list(self._map.keys())
+
+
+registry = Registry()

dqt/algorithms/_scales.py

@@ -0,0 +1,62 @@
+# Single source of truth for stat scale definitions.
+# Frontend reads the TS version generated by `make stats-scales`.
+# ZERO imports from dqt — this file must import nothing from this package.
+from typing import Literal, NamedTuple
+
+
+class StatScale(NamedTuple):
+    slug: str
+    max: float
+    warn_threshold: float
+    fail_threshold: float
+    direction: Literal["lower_is_better", "higher_is_better"]
+    plain_english_label: str
+    hint: str
+
+
+STAT_SCALES: dict[str, StatScale] = {
+    s.slug: s for s in [
+        StatScale("completeness_rate",         1.0,   0.95,  0.90,  "higher_is_better", "Completeness",               "Fraction of non-null values"),
+        StatScale("uniqueness_rate",            1.0,   0.95,  0.80,  "higher_is_better", "Uniqueness",                 "Fraction of distinct values"),
+        StatScale("validity_rate",              1.0,   0.95,  0.90,  "higher_is_better", "Validity",                   "Fraction of values matching the rule"),
+        StatScale("numeric_mean_shift",        10.0,   2.0,   3.0,   "lower_is_better",  "Mean shift (σ)",             "Z-score of mean deviation from baseline"),
+        StatScale("volume_change_ratio",        1.0,   0.10,  0.25,  "lower_is_better",  "Row-count change",           "Fractional deviation from baseline row count"),
+        StatScale("schema_change",              1.0,   0.5,   0.5,   "lower_is_better",  "Schema change",              "1.0 if schema changed, 0.0 if unchanged"),
+        StatScale("max_in_range",               1.0,   0.5,   0.5,   "lower_is_better",  "Max in bounds",              "1.0 when MAX(col) outside [min, max]; 0.0 otherwise"),
+        StatScale("min_in_range",               1.0,   0.5,   0.5,   "lower_is_better",  "Min in bounds",              "1.0 when MIN(col) outside [min, max]; 0.0 otherwise"),
+        StatScale("median_in_range",            1.0,   0.5,   0.5,   "lower_is_better",  "Median in bounds",           "1.0 when median outside [min, max]"),
+        StatScale("stddev_in_range",            1.0,   0.5,   0.5,   "lower_is_better",  "Stddev in bounds",           "1.0 when STDDEV outside [min, max]"),
+        StatScale("sum_in_range",               1.0,   0.5,   0.5,   "lower_is_better",  "Sum in bounds",              "1.0 when SUM outside [min, max]"),
+        StatScale("cardinality_in_range",       1.0,   0.5,   0.5,   "lower_is_better",  "Cardinality in bounds",      "1.0 when COUNT(DISTINCT col) outside [min, max]"),
+        StatScale("quantile_in_range",          1.0,   0.5,   0.5,   "lower_is_better",  "Quantile in bounds",         "1.0 when specified quantile outside [min, max]"),
+        StatScale("value_in_range_violation",   0.10,  0.001, 0.01,  "lower_is_better",  "Values in range",            "Fraction of values outside [min, max]"),
+        StatScale("set_membership_violation",   0.10,  0.001, 0.01,  "lower_is_better",  "Set membership",             "Fraction of values not in the allowed set"),
+        StatScale("set_exclusion_violation",    0.10,  0.001, 0.01,  "lower_is_better",  "Set exclusion",              "Fraction of values in the forbidden set"),
+        StatScale("regex_match_violation",      0.10,  0.001, 0.01,  "lower_is_better",  "Regex format",               "Fraction of values not matching any regex pattern"),
+        StatScale("string_length_violation",    0.10,  0.001, 0.01,  "lower_is_better",  "String length",              "Fraction of values with length outside [min_len, max_len]"),
+        StatScale("date_format_violation",      0.10,  0.001, 0.01,  "lower_is_better",  "Date format",                "Fraction of values not parseable as the given date format"),
+        StatScale("monotonicity_violation",     1.0,   0.5,   0.5,   "lower_is_better",  "Monotonicity",               "1.0 if ordering violated; 0.0 if sequence is monotonic"),
+        StatScale("column_pair_violation",      0.10,  0.001, 0.01,  "lower_is_better",  "Column pair rule",           "Fraction of rows where the pair comparison rule is violated"),
+        StatScale("composite_uniqueness_violation", 0.10, 0.001, 0.01, "lower_is_better","Composite key uniqueness",   "Fraction of rows that are duplicates on the composite key"),
+        StatScale("referential_integrity_rate", 1.0,   0.99,  0.95,  "higher_is_better", "Referential integrity",      "Fraction of FK values present in parent table"),
+        StatScale("ks_pvalue",                  1.0,   0.95,  0.99,  "lower_is_better",  "KS drift (1−p)",             "1 − p-value from two-sample KS test; warn p<0.05, fail p<0.01"),
+        StatScale("mad_outlier_fraction",       0.20,  0.01,  0.05,  "lower_is_better",  "Outlier fraction (MAD)",        "Fraction of values with |modified Z| > 3.5"),
+        StatScale("double_mad_outlier_fraction", 0.20, 0.01,  0.05,  "lower_is_better",  "Outlier fraction (double-MAD)",    "Fraction flagged by asymmetric double-MAD; robust on skewed distributions"),
+        StatScale("zscore_outlier_fraction",     0.10, 0.01,  0.05,  "lower_is_better",  "Outlier fraction (Z-score)",       "Fraction of values with |Z| > threshold; valid only under normality"),
+        StatScale("adjusted_boxplot_fraction",   0.20, 0.01,  0.05,  "lower_is_better",  "Outlier fraction (adj. boxplot)",  "Fraction outside medcouple-adjusted Tukey fences; Hubert & Vandervieren 2008"),
+        StatScale("isolation_forest_fraction",  0.20,  0.05,  0.10,  "lower_is_better",  "Outlier fraction (IF)",      "Fraction of rows classified as anomalies by Isolation Forest"),
+        StatScale("stl_residual_zscore",       10.0,   3.0,   5.0,   "lower_is_better",  "STL residual Z-score",       "Max absolute Z-score of STL residuals over the current window"),
+        StatScale("freshness_seconds_behind", 86400*7, 3600, 86400, "lower_is_better",
+                  "Data freshness", "Seconds since the most recent row timestamp"),
+        StatScale("null_fraction", 1.0, 0.01, 0.05, "lower_is_better",
+                  "Null fraction", "Fraction of rows where the column is NULL"),
+        StatScale("string_case_violation", 1.0, 0.001, 0.01, "lower_is_better",
+                  "String case violation", "Fraction of rows with wrong case"),
+        StatScale("sql_assertion_violation", 1.0, 0.001, 0.01, "lower_is_better",
+                  "SQL assertion violation", "Fraction of rows failing the custom SQL condition"),
+        StatScale("date_part_missing_fraction", 1.0, 0.01, 0.05, "lower_is_better",
+                  "Date-part completeness", "Fraction of expected date buckets with no data"),
+        StatScale("outlier_fraction_drift", 1.0, 0.001, 0.01, "lower_is_better",
+                  "Outlier fraction drift", "Deviation of current outlier fraction from historical baseline range"),
+    ]
+}

dqt/algorithms/basic/__init__.py

@@ -0,0 +1,35 @@
+from dqt.algorithms.basic.completeness import CompletenessDetector
+from dqt.algorithms.basic.uniqueness import UniquenessDetector
+from dqt.algorithms.basic.validity import ValidityDetector
+from dqt.algorithms.basic.numeric import NumericMeanDetector
+from dqt.algorithms.basic.volume import VolumeDetector
+from dqt.algorithms.basic.numeric_bounds import (
+    MaxInRangeDetector, MinInRangeDetector, MedianInRangeDetector,
+    StdDevInRangeDetector, SumInRangeDetector, CardinalityInRangeDetector,
+    QuantileInRangeDetector,
+)
+from dqt.algorithms.basic.value_checks import (
+    ValueInRangeDetector, SetMembershipDetector, SetExclusionDetector,
+    RegexMatchDetector, StringLengthRangeDetector, DateFormatDetector,
+)
+from dqt.algorithms.basic.monotonicity import MonotonicityDetector
+from dqt.algorithms.basic.column_pairs import ColumnPairComparisonDetector, CompositeUniquenessDetector
+from dqt.algorithms.basic.freshness import FreshnessDetector
+from dqt.algorithms.basic.null_fraction import NullFractionDetector
+from dqt.algorithms.basic.string_case import StringCaseDetector
+from dqt.algorithms.basic.sql_assertion import SqlAssertionDetector
+from dqt.algorithms.basic.date_part import DatePartCompletenessDetector
+
+__all__ = [
+    "CompletenessDetector", "UniquenessDetector", "ValidityDetector",
+    "NumericMeanDetector", "VolumeDetector",
+    "MaxInRangeDetector", "MinInRangeDetector", "MedianInRangeDetector",
+    "StdDevInRangeDetector", "SumInRangeDetector", "CardinalityInRangeDetector",
+    "QuantileInRangeDetector",
+    "ValueInRangeDetector", "SetMembershipDetector", "SetExclusionDetector",
+    "RegexMatchDetector", "StringLengthRangeDetector", "DateFormatDetector",
+    "MonotonicityDetector",
+    "ColumnPairComparisonDetector", "CompositeUniquenessDetector",
+    "FreshnessDetector", "NullFractionDetector", "StringCaseDetector",
+    "SqlAssertionDetector", "DatePartCompletenessDetector",
+]

dqt/algorithms/basic/_helpers.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import pandas as pd
+
+from dqt.algorithms._base import DetectorResult
+
+
+def fraction_result(df: pd.DataFrame, slug: str, label: str) -> DetectorResult:
+    from dqt.algorithms._base import compute_verdict
+    row = df.iloc[0]
+    total = int(row["total_count"])
+    frac = int(row["violation_count"]) / total if total > 0 else 0.0
+    return DetectorResult(
+        score=frac,
+        verdict=compute_verdict(frac, slug),
+        plain_english=f"{frac:.2%} of values violate {label}",
+        details={"violation_fraction": frac, "violation_count": int(row["violation_count"]), "total": total},
+    )