"""Layer 6 (deterministic): check a QueryPlan against the contract before anything runs. Errors send the plan back to the model once for repair. Fixes are small normalisations applied in code and reported in the stack inspector (e.g. 'harvest select' -> 'Harvest Select', 'Soft Drink' -> 'Soft Drinks'). A value that matches nothing is an error, never a guess. """ from __future__ import annotations from dataclasses import dataclass, field from .plan import QueryPlan MAX_LIMIT = 200 @dataclass class Validation: errors: list[str] = field(default_factory=list) fixes: list[str] = field(default_factory=list) @property def ok(self) -> bool: return not self.errors def _resolve_value(value: str, allowed: list[str]) -> str | None: low = {a.lower(): a for a in allowed} v = value.strip().lower() if v in low: return low[v] # tolerate small variations like "Soft Drink" vs "Soft Drinks" or "fy25 q1" vs "FY25-Q1" squash = lambda s: "".join(ch for ch in s.lower() if ch.isalnum()).rstrip("s") by_squash = {squash(a): a for a in allowed} return by_squash.get(squash(value)) def validate(plan: QueryPlan, contract) -> Validation: v = Validation() if plan.action == "refuse": if contract.rule("refuse", plan.rule_id) is None: v.fixes.append(f"refusal rule '{plan.rule_id}' is not in the contract - shown as a generic refusal") return v if plan.action == "clarify": if not plan.clarification_question: v.errors.append("action is clarify but clarification_question is empty") return v if not plan.metrics: v.errors.append("action is answer but no metrics were chosen") unknown_m = [m for m in plan.metrics if m not in contract.metrics] for m in unknown_m: v.errors.append(f"unknown metric '{m}'. Valid metrics: {', '.join(contract.metrics)}") unknown_d = [d for d in plan.dimensions if d not in contract.dimensions] for d in unknown_d: v.errors.append(f"unknown dimension '{d}'. Valid dimensions: {', '.join(contract.dimensions)}") if len(set(plan.dimensions)) != len(plan.dimensions): v.errors.append("dimensions contain duplicates") known_m = [m for m in plan.metrics if m in contract.metrics] for m in known_m: allowed = contract.allowed_dims_for_metric(m) for d in plan.dimensions: if d in contract.dimensions and d not in allowed: note = contract.metrics[m].get("grain_note", "") v.errors.append(f"metric '{m}' cannot be grouped by '{d}'. Allowed: {', '.join(allowed)}. {note}".strip()) for f in plan.filters: if f.dimension not in contract.dimensions: v.errors.append(f"filter on unknown dimension '{f.dimension}'") continue for m in known_m: if f.dimension not in contract.dims_for_model(contract.model_of(m)): v.errors.append(f"metric '{m}' cannot be filtered by '{f.dimension}'") if f.operator == "contains": continue allowed_vals = contract.values(f.dimension) if not allowed_vals: continue resolved = [] for val in f.values: r = _resolve_value(val, allowed_vals) if r is None: v.errors.append(f"'{val}' is not a valid {f.dimension}. Valid values: {'; '.join(allowed_vals)}") else: if r != val: v.fixes.append(f"{f.dimension}: '{val}' -> '{r}'") resolved.append(r) f.values = resolved if f.dimension == "brand_tier" and any(m in known_m and contract.model_of(m) == "sm_gap_pairs" for m in known_m) \ and "National Brand" in f.values and f.operator == "in": v.errors.append("gap metrics describe private-label items only; filter brand_tier to Harvest Select or Thrift Basket") for mf in plan.metric_filters: if mf.metric not in plan.metrics: v.errors.append(f"metric_filter uses '{mf.metric}', which is not in the plan's metrics") if plan.order_by and plan.order_by.metric not in plan.metrics: v.errors.append(f"order_by uses '{plan.order_by.metric}', which is not in the plan's metrics") if plan.limit is not None and not (1 <= plan.limit <= MAX_LIMIT): v.fixes.append(f"limit {plan.limit} clamped to {MAX_LIMIT}") plan.limit = max(1, min(plan.limit, MAX_LIMIT)) return v