kontra 0.5.2__py3-none-any.whl

kontra/rules/factory.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import List, Dict, Any, Optional
+
+from kontra.rules.base import BaseRule
+from kontra.rules.registry import get_rule, get_all_rule_names
+from kontra.config.models import RuleSpec
+from kontra.errors import DuplicateRuleIdError
+
+
+def _derive_rule_id(spec: RuleSpec) -> str:
+    """
+    Generate a stable, unique rule_id for a rule spec when no explicit id is provided.
+
+    Policy:
+      - If spec.id is set → return it as-is (caller must ensure uniqueness)
+      - If column param exists and is a string → COL:{column}:{name}
+      - Otherwise → DATASET:{name}
+    """
+    explicit: Optional[str] = getattr(spec, "id", None)
+    if explicit:
+        return explicit
+
+    params: Dict[str, Any] = spec.params or {}
+    col = params.get("column")
+    if isinstance(col, str) and col:
+        return f"COL:{col}:{spec.name}"
+    return f"DATASET:{spec.name}"
+
+
+class RuleFactory:
+    """
+    Translate contract RuleSpec objects into instantiated Rule instances.
+
+    Responsibilities:
+      - Resolve the rule class from the registry
+      - Instantiate with (name, params)
+      - Assign rule_id per our identity policy
+      - Provide helpful errors on unknown/failed rules
+    """
+
+    def __init__(self, rule_specs: List[RuleSpec]):
+        self.rule_specs = rule_specs
+
+    def build_rules(self) -> List[BaseRule]:
+        """Instantiate all rules declared in the contract."""
+        rules: List[BaseRule] = []
+        seen_ids: Dict[str, int] = {}  # rule_id -> index in rule_specs (for error messages)
+
+        for idx, spec in enumerate(self.rule_specs):
+            rule_name = spec.name
+            rule_params = spec.params or {}
+
+            try:
+                rule_cls = get_rule(rule_name)
+            except KeyError:
+                available = sorted(get_all_rule_names())
+                raise ValueError(
+                    f"Unknown rule '{rule_name}'. "
+                    f"Available rules: {', '.join(available)}"
+                )
+
+            try:
+                # IMPORTANT: constructor accepts (name, params) only
+                rule_instance: BaseRule = rule_cls(rule_name, rule_params)
+                # Assign rule_id after construction
+                rule_id = _derive_rule_id(spec)
+
+                # Check for duplicate rule IDs
+                if rule_id in seen_ids:
+                    prev_idx = seen_ids[rule_id]
+                    column = rule_params.get("column")
+                    raise DuplicateRuleIdError(
+                        rule_id=rule_id,
+                        rule_name=rule_name,
+                        rule_index=idx,
+                        conflict_index=prev_idx,
+                        column=column if isinstance(column, str) else None,
+                    )
+                seen_ids[rule_id] = idx
+
+                rule_instance.rule_id = rule_id
+                rule_instance.severity = spec.severity
+                rule_instance.context = spec.context or {}
+                rules.append(rule_instance)
+            except (ValueError, DuplicateRuleIdError):
+                raise  # Re-raise validation errors as-is
+            except Exception as e:
+                raise RuntimeError(f"Failed to instantiate rule '{rule_name}': {e}") from e
+
+        return rules
+
+    @staticmethod
+    def summarize_rules(rules: List[BaseRule]) -> List[Dict[str, Any]]:
+        """Return a summary of all rule configurations (for debug/reporting)."""
+        return [
+            {
+                "rule_id": getattr(rule, "rule_id", rule.name),
+                "params": rule.params,
+                "class": rule.__class__.__name__,
+            }
+            for rule in rules
+        ]

kontra/rules/predicates.py

@@ -0,0 +1,25 @@
+# src/contra/rules/planner/predicates.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Set
+import polars as pl
+
+@dataclass(frozen=True)
+class Predicate:
+    """
+    A vectorized rule failure mask.
+
+    rule_id : str
+        Stable identifier for the rule instance.
+    expr : pl.Expr
+        Boolean expression; True for rows that FAIL the rule.
+    message : str
+        Deterministic, human-readable message when the rule fails.
+    columns : set[str]
+        Column names referenced by `expr` (used for column pruning).
+    """
+    rule_id: str
+    expr: pl.Expr
+    message: str
+    columns: Set[str]

kontra/rules/registry.py

@@ -0,0 +1,24 @@
+# src/contra/rules/registry.py
+from typing import Dict, Type
+from kontra.rules.base import BaseRule
+
+RULE_REGISTRY: Dict[str, Type[BaseRule]] = {}
+
+def register_rule(name: str):
+    """Decorator to register rule classes in the global registry."""
+    def decorator(cls: Type[BaseRule]):
+        RULE_REGISTRY[name] = cls
+        cls.rule_key = name
+        return cls
+    return decorator
+
+def get_rule(name: str) -> Type[BaseRule]:
+    """Retrieves a rule class by name."""
+    if name not in RULE_REGISTRY:
+        raise KeyError(f"Rule '{name}' not found in registry.")
+    return RULE_REGISTRY[name]
+
+
+def get_all_rule_names() -> set:
+    """Returns all registered rule names."""
+    return set(RULE_REGISTRY.keys())

kontra/rules/static_predicates.py

@@ -0,0 +1,120 @@
+# src/kontra/rules/static_predicates.py
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Tuple
+
+from kontra.rules.base import BaseRule
+
+# (rule_id, column, op, value)  -- op ∈ ALLOWED_OPS
+PredicateT = Tuple[str, str, str, Any]
+ALLOWED_OPS = {"==", "!=", ">=", ">", "<=", "<", "^=", "not_null"}
+
+
+def _normalize(pairs: Iterable[PredicateT]) -> List[PredicateT]:
+    """Validate and normalize a stream of preplan predicates."""
+    out: List[PredicateT] = []
+    seen: set[Tuple[str, str, str, Any]] = set()
+    for rid, col, op, val in pairs:
+        if not isinstance(rid, str) or not rid:
+            continue
+        if not isinstance(col, str) or not col:
+            continue
+        if op not in ALLOWED_OPS:
+            continue
+        key = (rid, col, op, val)
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append((rid, col, op, val))
+    return out
+
+
+def _from_rule_hook(rule: BaseRule) -> List[PredicateT]:
+    """Ask the rule itself (if it implements the optional hook)."""
+    fn = getattr(rule, "to_preplan_predicates", None)
+    if callable(fn):
+        try:
+            preds = fn() or []
+        except Exception:
+            preds = []
+        # Ensure each tuple starts with this rule's rule_id
+        fixed: List[PredicateT] = []
+        for item in preds:
+            if not isinstance(item, tuple) or len(item) != 4:
+                continue
+            rid, col, op, val = item
+            # Allow rule to omit rid; fill it in
+            if not isinstance(rid, str) or not rid:
+                rid = getattr(rule, "rule_id", getattr(rule, "name", ""))
+            fixed.append((rid, col, op, val))
+        return fixed
+    return []
+
+
+def _conservative_builtin_mapping(rule: BaseRule) -> List[PredicateT]:
+    """
+    Optional mapping for known built-ins, so you don't have to add hooks yet.
+    Keep this conservative and obvious (no regex engines etc.).
+    """
+    name = getattr(rule, "name", "")
+    params: Dict[str, Any] = getattr(rule, "params", {}) or {}
+    rid = getattr(rule, "rule_id", name)
+
+    out: List[PredicateT] = []
+
+    # not_null(column)
+    if name.endswith("not_null"):
+        col = params.get("column")
+        if isinstance(col, str) and col:
+            out.append((rid, col, "not_null", True))
+
+    # equals / allowed_values (single value)
+    if name in {"equals", "allowed_values"}:
+        col = params.get("column")
+        val = params.get("value", None)
+        if val is None:
+            vals = params.get("values")
+            if isinstance(vals, (list, tuple)) and len(vals) == 1:
+                val = vals[0]
+        if isinstance(col, str) and col and isinstance(val, (str, int, float)):
+            out.append((rid, col, "==", val))
+
+    # min / max / range style (very conservative)
+    if name in {"gte", "min_value", "min"}:
+        col = params.get("column"); v = params.get("value")
+        if isinstance(col, str) and col and v is not None:
+            out.append((rid, col, ">=", v))
+    if name in {"lte", "max_value", "max"}:
+        col = params.get("column"); v = params.get("value")
+        if isinstance(col, str) and col and v is not None:
+            out.append((rid, col, "<=", v))
+
+    # regex("^prefix") → prefix
+    if name == "regex":
+        col = params.get("column")
+        pat = params.get("pattern", "")
+        if isinstance(col, str) and col and isinstance(pat, str) and pat.startswith("^"):
+            # only allow pure-prefix (no special chars beyond anchors)
+            body = pat[1:]
+            if body and all(ch.isalnum() or ch in {"_", "-", ".", "@"} for ch in body):
+                out.append((rid, col, "^=", body))
+
+    return out
+
+
+def extract_static_predicates_from_rules(rules: List[BaseRule]) -> List[PredicateT]:
+    """
+    Preferred entry point: pass the ORIGINAL rule instances (from RuleFactory).
+    We ask each rule for an optional hook, then apply a conservative builtin mapping.
+    """
+    pairs: List[PredicateT] = []
+    for r in rules:
+        pairs.extend(_from_rule_hook(r))
+        pairs.extend(_conservative_builtin_mapping(r))
+    return _normalize(pairs)
+
+
+# Backward-compatible shim if you still want a function named extract_static_predicates
+# and you have access to the original rules alongside the compiled plan.
+def extract_static_predicates(*, rules: List[BaseRule]) -> List[PredicateT]:
+    return extract_static_predicates_from_rules(rules)

kontra/scout/__init__.py

@@ -0,0 +1,9 @@
+# src/kontra/scout/__init__.py
+"""
+Kontra Scout - Contract-free data profiling for LLM context compression.
+"""
+
+from kontra.scout.profiler import ScoutProfiler
+from kontra.scout.types import ColumnProfile, DatasetProfile
+
+__all__ = ["ScoutProfiler", "ColumnProfile", "DatasetProfile"]

kontra/scout/backends/__init__.py

@@ -0,0 +1,17 @@
+# src/kontra/scout/backends/__init__.py
+"""
+Scout profiler backends - pluggable data source adapters.
+"""
+
+from .base import ProfilerBackend
+from .duckdb_backend import DuckDBBackend
+
+__all__ = ["ProfilerBackend", "DuckDBBackend"]
+
+# PostgreSQL backend (optional - requires psycopg)
+try:
+    from .postgres_backend import PostgreSQLBackend
+
+    __all__.append("PostgreSQLBackend")
+except ImportError:
+    pass

kontra/scout/backends/base.py

@@ -0,0 +1,111 @@
+# src/kontra/scout/backends/base.py
+"""
+ProfilerBackend protocol - abstract interface for Scout data source adapters.
+
+Each backend implements SQL-based profiling for a specific data source type.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Protocol, Tuple
+
+
+class ProfilerBackend(Protocol):
+    """
+    Protocol for Scout profiler backends.
+
+    A backend provides methods to:
+    - Connect to the data source
+    - Get schema information
+    - Execute aggregation queries
+    - Fetch values for low-cardinality columns
+
+    Implementations:
+    - DuckDBBackend: Parquet, CSV (local + S3)
+    - PostgreSQLBackend: PostgreSQL tables
+    """
+
+    def connect(self) -> None:
+        """Establish connection to the data source."""
+        ...
+
+    def close(self) -> None:
+        """Close the connection and clean up resources."""
+        ...
+
+    def get_schema(self) -> List[Tuple[str, str]]:
+        """
+        Return schema as [(column_name, raw_type), ...].
+
+        The raw_type is the native type string from the data source.
+        """
+        ...
+
+    def get_row_count(self) -> int:
+        """Return total row count (may use metadata optimization)."""
+        ...
+
+    def get_estimated_size_bytes(self) -> Optional[int]:
+        """Return estimated size in bytes (if available)."""
+        ...
+
+    def execute_stats_query(self, exprs: List[str]) -> Dict[str, Any]:
+        """
+        Execute a single aggregation query with multiple expressions.
+
+        Args:
+            exprs: List of SQL expressions like "COUNT(*) AS total"
+
+        Returns:
+            Dict mapping column aliases to values.
+        """
+        ...
+
+    def fetch_top_values(
+        self, column: str, limit: int
+    ) -> List[Tuple[Any, int]]:
+        """
+        Fetch top N most frequent values for a column.
+
+        Args:
+            column: Column name
+            limit: Maximum number of values to return
+
+        Returns:
+            List of (value, count) tuples ordered by count descending.
+        """
+        ...
+
+    def fetch_distinct_values(self, column: str) -> List[Any]:
+        """
+        Fetch all distinct values for a low-cardinality column.
+
+        Args:
+            column: Column name
+
+        Returns:
+            List of distinct values, ordered.
+        """
+        ...
+
+    def fetch_sample_values(self, column: str, limit: int) -> List[Any]:
+        """
+        Fetch a sample of values for pattern detection.
+
+        Args:
+            column: Column name
+            limit: Maximum number of values to return
+
+        Returns:
+            List of sample values.
+        """
+        ...
+
+    def esc_ident(self, name: str) -> str:
+        """Escape an identifier (column/table name) for this backend's SQL dialect."""
+        ...
+
+    @property
+    def source_format(self) -> str:
+        """Return the source format identifier (e.g., 'parquet', 'csv', 'postgres')."""
+        ...