sql 'per' pattern checker

ai/signatures.py

@@ -160,6 +160,29 @@ class AnalyzeAndPlan(dspy.Signature):
     There is no product_master, products, or product_catalog table.
     Use product_id as the only product identifier. Never invent table names.
 
+    ══════════════════════════════════════════════════════════════
+    RULE 1D2 — "PER X" DENOMINATOR — READ THE QUESTION CAREFULLY
+    ══════════════════════════════════════════════════════════════
+    The word after "per" tells you exactly what the denominator must be.
+    Using the wrong denominator gives a completely different metric.
+
+    "per order"    → COUNT(DISTINCT so_id)     ← number of sales orders
+    "per unit"     → SUM(quantity)             ← number of pieces/items sold
+    "per customer" → COUNT(DISTINCT customer_id)
+    "per product"  → COUNT(DISTINCT product_id)
+    "per vendor"   → COUNT(DISTINCT vendor_id)
+    "per SKU"      → COUNT(DISTINCT variant_sku)
+
+    WRONG — "per order" using quantity as denominator:
+      SUM(lp.line_total) / SUM(sol.quantity)       ← this is revenue per UNIT, not per ORDER
+
+    CORRECT — "per order" using distinct order count:
+      SUM(lp.line_total) / COUNT(DISTINCT so.so_id) ← this is revenue per ORDER
+
+    Similarly for AOV (average order value):
+      AVG(total_amount)  or  SUM(total_amount) / COUNT(DISTINCT so_id)
+      NEVER  SUM(total_amount) / SUM(quantity)
+
     ══════════════════════════════════════════════════════════════
     RULE 1E — WHICH TABLE OWNS WHICH COLUMNS (DO NOT MIX)
     ══════════════════════════════════════════════════════════════
@@ -482,6 +505,14 @@ class SQLGeneration(dspy.Signature):
 
     4d. NO product_master table — never reference it; use product_id only.
 
+    4d2. "PER X" DENOMINATOR — use the correct divisor for what "per" refers to:
+         "per order"    → COUNT(DISTINCT so.so_id)      NOT SUM(quantity)
+         "per unit"     → SUM(quantity)                 NOT COUNT(DISTINCT so_id)
+         "per customer" → COUNT(DISTINCT so.customer_id)
+         "per vendor"   → COUNT(DISTINCT vendor_id)
+         WRONG:   SUM(line_total) / SUM(quantity)        ← revenue per unit, not per order
+         CORRECT: SUM(line_total) / COUNT(DISTINCT so.so_id) ← revenue per order
+
     4e. TABLE COLUMN OWNERSHIP — never use a column from the wrong table:
         sales_order_line_pricing → has: gold_amount_per_unit, diamond_amount_per_unit,
           making_charges_per_unit, line_total, quantity, sol_id, variant_sku, product_id

ai/sql_pattern_checker.py

@@ -232,6 +232,31 @@ def check_sql_patterns(sql: str) -> list[dict[str, Any]]:
                 ),
             })
 
+    # ── Pattern 3b ───────────────────────────────────────────────────────────
+    # "per order" metric computed with SUM(quantity) as denominator instead of
+    # COUNT(DISTINCT so_id).  SUM(quantity) = revenue per unit; "per order"
+    # requires COUNT(DISTINCT so_id).
+    # Heuristic: division where the denominator contains sum(...quantity...)
+    if re.search(r"/\s*sum\s*\([^)]*quantit", sql_lower):
+        issues.append({
+            "pattern_name": "per_unit_instead_of_per_order",
+            "description": (
+                "POSSIBLE BUG — dividing by SUM(quantity) gives revenue per UNIT (per piece). "
+                "If the question asks for 'per order', the denominator must be "
+                "COUNT(DISTINCT so_id), not SUM(quantity). "
+                "These are completely different metrics: "
+                "SUM(line_total)/SUM(quantity) = avg revenue per item sold; "
+                "SUM(line_total)/COUNT(DISTINCT so_id) = avg revenue each time product appears in an order."
+            ),
+            "correction": (
+                "Check the question: does it say 'per order' or 'per unit/piece'?\n"
+                "  'per order'    → SUM(lp.line_total) / COUNT(DISTINCT so.so_id)\n"
+                "  'per unit'     → SUM(lp.line_total) / SUM(lp.quantity)\n"
+                "  'per customer' → SUM(lp.line_total) / COUNT(DISTINCT so.customer_id)\n"
+                "If the question says 'per order', rewrite using COUNT(DISTINCT so.so_id)."
+            ),
+        })
+
     # ── Pattern 4 ────────────────────────────────────────────────────────────
     # Schema-aware: detect alias.column where column doesn't exist in that table.
     # Generic — works for gold_kt on pricing table, or any future similar mistake.