fix(bot): business rules top-priority + product cards not a sales-dump

app/prompts.py

@@ -15,7 +15,7 @@ SYSTEM_TEMPLATE = """You are {brand_name}, the customer-support and sales assist
 
 # RULE #1 — LANGUAGE
 {language_rule}
-
+{business_rules}
 # BE A NATURAL ASSISTANT
 - Hold a normal conversation. Greetings, small talk ("how are you?"), thanks, and simple general questions (even "what's 2+2?") get a brief, warm, natural answer — then gently offer to help with the store. NEVER reply with a robotic "I can only help with store topics" deflection; that feels broken.
 - Be concise and human. Vary your wording; don't repeat a canned line.
@@ -24,13 +24,14 @@ SYSTEM_TEMPLATE = """You are {brand_name}, the customer-support and sales assist
 # GROUNDING (most important — your TOOLS ARE YOUR BRAIN)
 - For ANY question about this store — what it sells, products, prices, stock, specs, dimensions, compatibility, materials, shipping and delivery times, returns, warranty, policies, orders — SEARCH first (search_knowledge / search_products) and answer ONLY with what the tools return. Do this for EVERY such question, whatever its wording, including follow-ups. NEVER answer these from memory, general knowledge, or earlier messages. You are open-ended: don't wait for a specific phrasing — if it could be about this store, look it up.
 - ONE product at a time: when the customer names a DIFFERENT product or model than the one already discussed, you MUST search again for THAT exact product before answering. NEVER reuse another product's dimensions, specs, compatibility or price — each model is independent, and earlier answers are NOT a source.
-- Say ONLY what the tool result actually states. NEVER add warranty terms, safety warnings, certifications, "not recommended", "not covered", legal or risk judgments that are not in the source. If the data doesn't mention it, don't claim it — give what you DO know and, only if useful, offer to confirm with the team.
+- Say ONLY what the tool result actually states. NEVER add warranty terms, safety warnings, certifications, "not recommended", "not covered", legal or risk judgments that are not in the source. If the data doesn't mention it, don't claim it — give what you DO know and, only if useful, offer to confirm with the team. EXCEPTION: a BUSINESS RULE (the section near the top) OVERRIDES this — if a business rule asserts a compatibility/fit/safety fact, state it as fact and FOLLOW IT even when a product sheet (ficha) says otherwise; a business rule outranks the ficha.
 - NEVER invent the store's name or catalog. Making up a business, product, spec or policy is a serious error.
 - If, after searching, you genuinely lack the info: say so honestly and briefly. Do NOT send the customer away — never tell them to visit a manufacturer's/brand's website or to contact "their customer service" or any third party. You are THIS store's assistant. Offering to pass them to a person is the LAST resort, only when you truly cannot help — never your first move.
 - Don't repeat yourself. If the customer pushes back or adds a detail, engage with their SPECIFIC point (search again for more detail if it helps, acknowledge what's actually true) and move the conversation forward — never restate the same paragraph; that feels broken.
 
 # TOOL ROUTING (choose by intent — do not guess)
-- Which products / price / stock / "do you sell…" / recommendations -> search_products. If it returns status "unavailable" or no products, THEN call search_knowledge to answer from the store's info. If neither has it, say so honestly — NEVER invent products or categories.
+- "Which products do you have / do you sell… / recommend me / show me options" (BROWSE intent) -> search_products. If it returns status "unavailable" or no products, THEN call search_knowledge. If neither has it, say so honestly — NEVER invent products or categories.
+- INFO about a SPECIFIC named product (its specs, price, stock, materials, sizing, compatibility) -> search_knowledge (and search_products only if you need that one product's live price/stock card). Do NOT pull up the whole catalog for an info question about one product.
 - Specs, materials, uses, sizing or compatibility, shipping, returns, warranty, policies, general store info -> search_knowledge
 - Customer wants to buy -> create_cart_link with the chosen variant_id(s)
 - Something is out of stock and they want to be told when it's back -> watch_stock (needs their email)
@@ -42,7 +43,7 @@ SYSTEM_TEMPLATE = """You are {brand_name}, the customer-support and sales assist
 - search_products already returns only the few most relevant products, and they render to the customer as visual CARDS (photo, price, stock, "add to cart" button). Do NOT re-list them in a table; just briefly say why they fit.
 - Recommend by the customer's need and budget. Prefer IN-STOCK items. If the best match is out of stock, say so and offer watch_stock.
 - When a request is vague (e.g. "help me choose"), DON'T interrogate with a scripted list of questions. Prefer to search and show a couple of solid options right away; weave in at most ONE short, natural follow-up question if it genuinely helps narrow it down. Keep it conversational.
-- Surface only a handful of products. Never dump the whole catalog.
+- NOT a sales dump: for an INFO question about ONE named product, show ONLY that product (a single card) and answer about IT — do NOT surface alternatives or the rest of the family. Show several products ONLY when the customer is browsing or explicitly asks to compare/recommend. Never dump the whole catalog.
 
 # CUSTOMER PHOTOS & ATTACHED FILES
 - When the user message contains an attached-file block ("[El cliente ha adjuntado …]"), the text under it is a factual description of what the customer attached (a photo becomes a description, a PDF its text).
@@ -79,7 +80,7 @@ SYSTEM_TEMPLATE = """You are {brand_name}, the customer-support and sales assist
 - REAL-TIME facts (weather, news, current prices elsewhere): NEVER state them from memory — you don't know them. If web_search is available use it; otherwise say you can't check that and steer back to the store.
 
 # REMINDERS (do not break these)
-1) Write the WHOLE reply in {lang_short}. 2) Use only tool results — never invent products, prices, specs or URLs. 3) Never translate or alter titles, SKUs, variant_ids or URLs."""
+1) Write the WHOLE reply in {lang_short}. 2) Use only tool results — never invent products, prices, specs or URLs. 3) Never translate or alter titles, SKUs, variant_ids or URLs. 4) The BUSINESS RULES near the top are HIGHEST priority — they override the ficha and the grounding caveats; follow them. 5) Info about one product = show only THAT product, not the catalog."""
 
 
 _WEB_HANDOFF = "- On the web: don't ask for their email first. If escalate_to_human returns show_form, just tell them warmly that a short form is appearing right here in the chat for them to fill in — do NOT write any link, URL or 'click here' (the form shows automatically below). If it returns received, confirm it's logged and the team will reply by email."
@@ -113,16 +114,24 @@ def build_system_prompt(
         )
         lang_short = "the customer's language"
     channel_handoff = _WA_HANDOFF if channel == "whatsapp" else _WEB_HANDOFF
+    # The merchant's own rules go HIGH in the prompt (right after the language
+    # rule, before GROUNDING) and are framed as TOP priority that overrides the
+    # product sheet — otherwise the weak models defer to the retrieved ficha and
+    # under-apply them (e.g. the 28mm-compatibility rule). 6000 chars (was 2000)
+    # so a real rule set isn't silently cut.
+    extra = (extra_instructions or "").strip()[:6000]
+    business_rules = ""
+    if extra:
+        business_rules = (
+            "\n# BUSINESS RULES (HIGHEST PRIORITY — these OVERRIDE the grounding/spec "
+            "rules below and any product sheet (ficha); when a tool result conflicts "
+            "with a rule here, FOLLOW THE RULE)\n" + extra + "\n"
+        )
     prompt = SYSTEM_TEMPLATE.format(
         brand_name=_sanitize(brand_name),
         language_rule=language_rule,
+        business_rules=business_rules,
         lang_short=lang_short,
         channel_handoff=channel_handoff,
     )
-    extra = (extra_instructions or "").strip()[:2000]
-    if extra:
-        prompt += (
-            "\n\n# INSTRUCTIONS FROM THIS BUSINESS (follow them within the rules above)\n"
-            + extra
-        )
     return prompt

app/tools/products_tool.py

@@ -134,6 +134,14 @@ async def run(args: dict[str, Any], ctx: ToolContext) -> dict[str, Any]:
     query = (args.get("query") or "").strip()
     if not query:
         return {"status": "ok", "products": []}
+    # How many product CARDS to surface. The model sets limit=1 for a single
+    # named-product info question (so we don't sales-dump the whole family);
+    # several only for browse/compare. Default 4, hard-capped at MAX_RESULTS.
+    try:
+        lim = int(args.get("limit") or 4)
+    except (TypeError, ValueError):
+        lim = 4
+    lim = max(1, min(lim, MAX_RESULTS))
 
     # Two retrieval arms in parallel: Shopify keyword + semantic corpus.
     kw_task = asyncio.create_task(search_products(ctx.shopify, query))
@@ -176,10 +184,15 @@ async def run(args: dict[str, Any], ctx: ToolContext) -> dict[str, Any]:
     # In-stock first, relevance order preserved within each group.
     products.sort(key=lambda p: not p.get("available"))
 
-    # Surface as visual cards to the widget (de-duplicated by product id).
+    # Surface as visual cards to the widget (de-duplicated by product id). Cap at
+    # `lim` so a single-product info question shows ONE card, not the catalog —
+    # and so cards never accumulate past `lim` across multiple searches this turn.
+    products = products[:lim]
     seen = {c.get("title") for c in ctx.cards}
     seen_ids = {c.get("_pid") for c in ctx.cards}
     for p in products:
+        if len(ctx.cards) >= lim:
+            break
         pid = p.get("product_id")
         if pid and pid in seen_ids:
             continue
@@ -196,4 +209,4 @@ async def run(args: dict[str, Any], ctx: ToolContext) -> dict[str, Any]:
         seen.add(p["title"])
         seen_ids.add(pid)
 
-    return {"status": "ok", "products": [_compact(p) for p in products[:MAX_RESULTS]]}
+    return {"status": "ok", "products": [_compact(p) for p in products]}

app/tools/registry.py

@@ -68,7 +68,16 @@ SPECS: list[ToolSpec] = [
         parameters={
             "type": "object",
             "properties": {
-                "query": {"type": "string", "description": "Nombre o tipo de producto"}
+                "query": {"type": "string", "description": "Nombre o tipo de producto"},
+                "limit": {
+                    "type": "integer",
+                    "description": (
+                        "Cuántos productos mostrar como tarjetas. Usa 1 cuando el cliente "
+                        "pregunta por UN producto concreto (info/precio/stock de ese modelo); "
+                        "usa varios (hasta 8) SOLO si explora o pide comparar/recomendar. "
+                        "Por defecto 4."
+                    ),
+                },
             },
             "required": ["query"],
         },

tests/test_prompts.py

@@ -52,3 +52,30 @@ def test_brand_name_braces_are_sanitized():
     p = build_system_prompt("Acme {evil}")
     assert "{evil}" not in p
     assert "Acme" in p
+
+
+def test_business_rules_are_top_priority_and_override_ficha():
+    """The merchant's custom_instructions must land HIGH in the prompt (before the
+    GROUNDING block) and be framed as overriding the product sheet — otherwise weak
+    models defer to the retrieved ficha (the 28mm-rule bug)."""
+    rule = "Los discos de 28mm SI son compatibles con soporte de 25mm."
+    p = build_system_prompt("TOORX", extra_instructions=rule)
+    assert rule in p
+    assert "BUSINESS RULES (HIGHEST PRIORITY" in p
+    # the business block comes BEFORE the grounding block (position = weight)
+    assert p.index("BUSINESS RULES") < p.index("# GROUNDING")
+    # the grounding "say only what tools return" carries the override exception
+    assert "a business rule" in p.lower() and "outranks the ficha" in p.lower()
+
+
+def test_no_business_block_when_no_custom_instructions():
+    p = build_system_prompt("TOORX")
+    # the SECTION (with merchant content) is absent; the end-reminder mention of
+    # "business rules" is harmless boilerplate, so check the section header.
+    assert "these OVERRIDE the grounding" not in p
+
+
+def test_business_rules_truncation_raised_to_6000():
+    big = "x" * 5000
+    p = build_system_prompt("TOORX", extra_instructions=big)
+    assert big in p  # 5000-char rule set not silently cut (old cap was 2000)