shelf-talk / engine /validator.py
Ashish-K's picture
Deploy Shelf Talk (replay mode)
f1cd642 verified
Raw History Blame Contribute Delete
4.59 kB
"""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