@roll-agent/octopus-agent 0.0.10 → 0.1.0

package/src/octopus_skill/prompt_builder.py

@@ -1,49 +1,26 @@
 from __future__ import annotations
 
 import json
-from typing import Any
+import re
+from typing import Any, Literal
 
 from .schema_context_retriever import SchemaContext
+from .sql_generator import normalize_text_filters_to_like
+
+
+InstructionStage = Literal["before", "during", "after"]
+
+INSTRUCTION_STAGE_PREFIX: dict[InstructionStage, str] = {
+    "before": "【生成前】",
+    "during": "【生成中】",
+    "after": "【执行后】",
+}
 
 
 NL2SQL_SYSTEM_PROMPT = """你是丸子Agent（Octopus Agent）的海绵数据 SQL 生成器。
-你只能基于提供的 schema context 生成 MySQL SELECT 查询。
-返回 JSON 中的 sql 字段必须直接以 SELECT 开头，不能返回非 SQL 文本。
-只生成业务 SQL，不要生成权限占位符或权限条件。
-不得使用 :scope.project_ids、:scope.brand_ids 或任何 :scope.* placeholder（占位符）。
-如果用户没有明确要求返回条数，LIMIT 必须使用 defaultLimit。
-如果用户要求所有数据、全部数据、全量数据、完整数据，或要求导出/生成 Excel/xlsx/表格文件，LIMIT 必须使用 maxLimit，不要使用 defaultLimit。
-不得查询 auth 库、密码、令牌、密钥、凭证字段。
-不得输出敏感字段，包括手机号、电话、联系方式、身份证、密码、token、secret、credential、private_key 等。
-如果用户要求敏感字段，必须从 SELECT 中排除这些字段；还有其他非敏感字段时继续生成去敏后的 SQL。
-不得生成 INSERT、UPDATE、DELETE、DDL、非 SELECT SQL 或多语句 SQL。
-SELECT 中每个输出字段都必须使用 AS 中文含义，例如 b.name AS 品牌名称。
-禁止使用英文别名，例如 brand_name、project_name。
-用户点名要求输出的字段，必须优先使用 schema context 中含义匹配的真实字段或真实关联表生成。
-不得为了凑齐字段写 NULL AS 字段名、CAST(NULL AS ...) AS 字段名 等空占位表达式。
-只有 schema context 中完全没有相关真实字段或关联表时，才允许不返回该字段；不要用空占位字段替代。
-用户明确给出品牌、项目、岗位、职位、门店等实体名称时，必须在对应名称字段上使用 LIKE 过滤，不要先查询全量或默认 LIMIT 列表再比对。
-名称类字段和状态文本类字段的筛选条件必须使用 LIKE '%值%'，例如 name、job_name、status_text、status_name。
-数字 ID、数字状态枚举、删除标记、时间范围和 JOIN ON 表关联条件不要改成 LIKE；例如 status = 1、is_delete = 0、a.id = b.id、create_at >= '2026-05-01' 保持原比较符。
-只有“名称包含/名称为/是/等于/招聘xx岗位/在招xx职位”等明确关系才能判定为岗位或职位名称；不要仅因逗号、空格、冒号相邻就推断岗位名称。
-业务查询必须一次生成完整 SQL；不要先查 brand、sponge_project、city、store、job_basic_info 等单表列表来找 ID，也不要要求外部先提供 ID。
-业务查询中需要按品牌、项目、城市、门店、岗位名称过滤时，必须 JOIN 对应表并直接使用 name 或 job_name LIKE。
-涉及业务指标或业务口径时，必须优先使用 schemaContext.metrics 中的 definition、aggregation 和 filters。
-如果 schemaContext.metrics 没有给出对应业务口径，不得自行推断状态枚举、有效性过滤或跨轮次分割规则。
-所有业务字段、状态枚举、状态映射、表关联方式必须来自 schemaContext.tables、schemaContext.joins、schemaContext.glossary、schemaContext.metrics 或 schemaContext.examples。
-不得自行猜测状态值；例如“面试成功”“进行中”“已上岗”等状态必须使用 schemaContext 中给出的字段和枚举。
-所有 JOIN 必须优先使用 schemaContext.joins；如果相关 JOIN 只出现在 schemaContext.metrics.filters 或 schemaContext.examples 中，也必须严格照用。
-如果 schemaContext 没有明确给出表、字段、JOIN 或指标口径，不要猜测；返回 {"sql":"","tables":[],"placeholders":[],"usedColumns":[],"usedJoins":[],"metricRefs":[]}。
-报名/工单/候选人状态/姓名/岗位/项目明细查询，必须优先使用 schemaContext 中的报名工单表和示例，不得退化为只查询 brand 品牌列表。
-报名工单与岗位的关联方式必须来自 schemaContext；如果 schemaContext 指明 job_id 关联 job_basic_info.job_id，不得改用 job_basic_info.id。
-地点条件必须先按业务字典判断层级：province.name 省份优先，其次 city.name 城市，再其次 region.name 区域。
-用户提到南京、上海、江苏等地点时，不要先猜测为道路、商圈、门店或地址关键词；只有省/城市/区域都无法匹配时，才按地址关键词模糊查询。
-岗位或门店地点查询优先使用 job_address.city_id、job_address.region_id、store.city_id、store.region_id 等结构化字段。
-用户问题包含时间范围时，SQL 的 WHERE 条件必须直接包含对应时间字段过滤，不得先查询全量数据再补充时间范围。
-时间字段按语义选择：创建/新建/新增使用 create_at，发布/上架使用 publish_at，下架使用 off_at，更新/修改使用 update_at。
-必须包含 LIMIT，且 LIMIT 不超过 500。
-不要使用 WITH；低版本 MySQL 不支持公共表表达式，请使用 JOIN 或派生表。
-只输出 JSON，不输出解释文本、拒绝文本或 Markdown。"""
+业务规则的唯一来源是 payload 中的 mandatoryAgentInstructions 与 schemaContext.policy；必须逐条遵守，不得使用训练记忆中的业务口径替代 schema 要求。
+生成 SQL 前必须严格按 schemaContext.readOrder 顺序阅读 schemaContext 各段内容，再组合 SELECT、JOIN、WHERE、LIMIT。
+只输出 JSON，结构见 outputSchema。返回 JSON 中的 sql 字段必须直接以 SELECT 开头；不要为了状态枚举单独返回 clarification。用户明确提出状态筛选时把状态条件写入 WHERE；用户未提出状态筛选或 schemaContext 缺少枚举时不要追问，首次查询保持宽泛，并把相关状态字段及中文含义加入 SELECT 结果。"""
 
 
 def build_nl2sql_prompt(
@@ -52,27 +29,22 @@ def build_nl2sql_prompt(
     schema_context: SchemaContext,
     default_limit: int,
     max_limit: int,
+    confirmed_query_plan: dict[str, Any] | None = None,
 ) -> str:
-    payload = {
-        "question": question,
-        "limits": {"defaultLimit": default_limit, "maxLimit": max_limit},
-        "schemaContext": {
-            "tables": schema_context.tables,
-            "joins": schema_context.joins,
-            "glossary": schema_context.glossary,
-            "metrics": schema_context.metrics,
-            "examples": _business_examples(schema_context.examples),
-        },
-        "outputSchema": {
-            "sql": f"SELECT column AS 中文含义 ... LIMIT {default_limit}",
-            "tables": ["table_name"],
-            "placeholders": [],
-            "usedColumns": ["table.column"],
-            "usedJoins": ["left_table.left_column = right_table.right_column"],
-            "metricRefs": ["schemaContext.metrics.name"],
-        },
-    }
-    return json.dumps(payload, ensure_ascii=False, indent=2)
+    payload = _base_sql_prompt_payload(
+        question=question,
+        schema_context=schema_context,
+        default_limit=default_limit,
+        max_limit=max_limit,
+        confirmed_query_plan=confirmed_query_plan,
+    )
+    compact = confirmed_query_plan is not None
+    return json.dumps(
+        payload,
+        ensure_ascii=False,
+        indent=None if compact else 2,
+        separators=(",", ":") if compact else (", ", ": "),
+    )
 
 
 def build_sql_repair_prompt(
@@ -83,31 +55,408 @@ def build_sql_repair_prompt(
     schema_context: SchemaContext,
     default_limit: int,
     max_limit: int,
+    confirmed_query_plan: dict[str, Any] | None = None,
 ) -> str:
-    payload = {
-        "task": "repair_sql",
+    payload = _base_sql_prompt_payload(
+        question=question,
+        schema_context=schema_context,
+        default_limit=default_limit,
+        max_limit=max_limit,
+        confirmed_query_plan=confirmed_query_plan,
+        task="repair_sql",
+        original_sql=original_sql,
+        validation_error=validation_error,
+    )
+    compact = confirmed_query_plan is not None
+    return json.dumps(
+        payload,
+        ensure_ascii=False,
+        indent=None if compact else 2,
+        separators=(",", ":") if compact else (", ", ": "),
+    )
+
+
+def _base_sql_prompt_payload(
+    *,
+    question: str,
+    schema_context: SchemaContext,
+    default_limit: int,
+    max_limit: int,
+    confirmed_query_plan: dict[str, Any] | None = None,
+    task: str | None = None,
+    original_sql: str | None = None,
+    validation_error: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    compact = confirmed_query_plan is not None
+    instruction_lines = _agent_instruction_lines(schema_context)
+    payload: dict[str, Any] = {
+        "mandatoryAgentInstructions": instruction_lines,
+        "instruction": (
+            "生成或修复 SQL 前必须先完整阅读 mandatoryAgentInstructions，"
+            "再按 schemaContext.readOrder 阅读 schemaContext；"
+            "WHERE/SELECT/JOIN/LIMIT/字段别名/澄清策略均以 mandatoryAgentInstructions 与 schemaContext 为准。"
+            "涉及业务口径的查询必须优先使用 schemaContext.concepts、metrics、examples 或 exampleJoinPatterns；"
+            "schemaContext 未提供对应口径时，不要凭训练记忆或字段名猜测 SQL。"
+            "涉及时间范围时，如果命中的 schemaContext.concepts 或 metrics 提供 timeRangeField，"
+            "必须使用该字段生成 WHERE 时间过滤，不要改用关联维表的同名时间字段。"
+            "涉及“最多/最高/最大/排名/排行”等聚合极值诉求时，必须优先按聚合指标倒序排序，"
+            "再按时间等次要维度排序。"
+            "不要把查询动作、状态变化、时间词或范围词当作名称筛选；"
+            "只有用户明确说“名称包含/岗位名称是/叫做/简称为”时，才允许对 name/title/job_name 写 LIKE。"
+            if not compact
+            else
+            "生成或修复 SQL 前必须先完整阅读 mandatoryAgentInstructions，"
+            "再按 schemaContext.readOrder 阅读 schemaContext；"
+            "confirmedQueryPlan 提供实体、筛选与输出字段，schemaContext 提供表结构、JOIN 与 policy。"
+            "涉及业务口径的查询必须优先使用 schemaContext.concepts、metrics、examples 或 exampleJoinPatterns；"
+            "schemaContext 未提供对应口径时，不要凭训练记忆或字段名猜测 SQL。"
+            "涉及时间范围时，如果命中的 schemaContext.concepts 或 metrics 提供 timeRangeField，"
+            "必须使用该字段生成 WHERE 时间过滤，不要改用关联维表的同名时间字段。"
+            "涉及“最多/最高/最大/排名/排行”等聚合极值诉求时，必须优先按聚合指标倒序排序，"
+            "再按时间等次要维度排序。"
+            "JOIN ... ON 只能写 schema relations / joins 中的等值关联键（如 a.id = b.x_id）；"
+            "confirmedQueryPlan.filters 里的 LIKE/IN 筛选必须写在 WHERE，禁止写在 JOIN ON；"
+            "同一 logicalGroup 且 logicalOperator=OR 的筛选必须用 OR 连接，并用括号包裹；"
+            "confirmedQueryPlan.fields 中 required=true 的字段必须出现在 SELECT 中；"
+            "不要把查询动作、状态变化、时间词或范围词当作名称筛选。"
+        ),
         "question": question,
-        "originalSql": original_sql,
-        "validationError": validation_error,
         "limits": {"defaultLimit": default_limit, "maxLimit": max_limit},
-        "schemaContext": {
-            "tables": schema_context.tables,
-            "joins": schema_context.joins,
-            "glossary": schema_context.glossary,
-            "metrics": schema_context.metrics,
-            "examples": _business_examples(schema_context.examples),
-        },
-        "outputSchema": {
-            "sql": f"SELECT column AS 中文含义 ... LIMIT {default_limit}",
-            "tables": ["table_name"],
-            "placeholders": [],
-            "usedColumns": ["table.column"],
-            "usedJoins": ["left_table.left_column = right_table.right_column"],
-            "metricRefs": ["schemaContext.metrics.name"],
+        "schemaContext": _schema_context_payload(schema_context, compact=compact),
+        "outputSchema": _sql_output_schema(default_limit, question),
+    }
+    if task == "repair_sql":
+        payload["task"] = task
+        payload["originalSql"] = original_sql or ""
+        payload["validationError"] = validation_error or {}
+    if confirmed_query_plan:
+        payload["confirmedQueryPlan"] = _compact_query_plan_for_sql(confirmed_query_plan)
+    return payload
+
+
+def instruction_text(item: dict[str, Any]) -> str:
+    return str(item.get("text") or item.get("instruction") or item.get("content") or "").strip()
+
+
+def filter_agent_instructions_by_stage(
+    instructions: list[dict[str, Any]],
+    stage: InstructionStage,
+) -> list[str]:
+    prefix = INSTRUCTION_STAGE_PREFIX[stage]
+    texts: list[str] = []
+    for item in instructions:
+        if not isinstance(item, dict):
+            continue
+        text = instruction_text(item)
+        if text.startswith(prefix):
+            texts.append(text)
+    return texts
+
+
+def format_numbered_instruction_lines(texts: list[str]) -> list[str]:
+    return [f"{index}. {text}" for index, text in enumerate(texts, start=1)]
+
+
+def _agent_instruction_lines(
+    schema_context: SchemaContext,
+    *,
+    stage: InstructionStage = "during",
+) -> list[str]:
+    texts = filter_agent_instructions_by_stage(schema_context.agent_instructions, stage)
+    return format_numbered_instruction_lines(texts)
+
+
+def _filtered_agent_instruction_items(
+    instructions: list[dict[str, Any]],
+    *,
+    stage: InstructionStage,
+) -> list[dict[str, Any]]:
+    prefix = INSTRUCTION_STAGE_PREFIX[stage]
+    items: list[dict[str, Any]] = []
+    for item in instructions:
+        if not isinstance(item, dict):
+            continue
+        text = instruction_text(item)
+        if text.startswith(prefix):
+            items.append({"text": text})
+    return items
+
+
+def _compact_query_plan_for_sql(query_plan: dict[str, Any]) -> dict[str, Any]:
+    compact: dict[str, Any] = {}
+    question = query_plan.get("question")
+    if isinstance(question, str) and question.strip():
+        compact["question"] = question.strip()
+    entities = [
+        {
+            key: entity[key]
+            for key in ("label", "type", "value", "source", "logicalGroup", "logicalOperator")
+            if key in entity
+        }
+        for entity in query_plan.get("entities", [])
+        if isinstance(entity, dict)
+    ]
+    if entities:
+        compact["entities"] = entities
+    filters = [
+        {
+            key: item[key]
+            for key in ("field", "operator", "value", "description", "source", "logicalGroup", "logicalOperator")
+            if key in item
+        }
+        for item in query_plan.get("filters", [])
+        if isinstance(item, dict)
+    ]
+    if filters:
+        compact["filters"] = filters
+    fields = [
+        {key: item[key] for key in ("table", "field", "description", "source", "required") if key in item}
+        for item in query_plan.get("fields", [])
+        if isinstance(item, dict)
+    ]
+    if fields:
+        compact["fields"] = fields
+    tables = [
+        {key: item[key] for key in ("name", "description") if key in item}
+        for item in query_plan.get("tables", [])
+        if isinstance(item, dict) and item.get("name")
+    ]
+    if tables:
+        compact["tables"] = tables
+    return compact
+
+
+def _schema_context_payload(schema_context: SchemaContext, *, compact: bool = False) -> dict[str, Any]:
+    selected_tables = {
+        str(table.get("tableName") or table.get("name") or "")
+        for table in schema_context.tables
+        if isinstance(table, dict)
+    }
+    selected_tables.discard("")
+    relations = schema_context.relations
+    policy = schema_context.policy
+    if compact:
+        relations = _slim_relations(relations, selected_tables)
+        policy = _slim_policy(policy, selected_tables)
+    payload: dict[str, Any] = {
+        "readOrder": _schema_read_order(compact=compact),
+        "policy": policy,
+        "schema": {"tables": schema_context.tables},
+        "joins": schema_context.manual_joins,
+        "relations": relations,
+        "defaultFilters": schema_context.default_filters,
+        "enums": schema_context.enums,
+        "businessTerms": schema_context.business_terms,
+        "concepts": schema_context.concepts,
+        "metrics": schema_context.metrics,
+        "exampleJoinPatterns": schema_context.example_join_patterns,
+        "exampleGuidance": schema_context.example_guidance,
+        "structureHints": schema_context.structure_hints,
+        "examples": _business_examples(schema_context.examples),
+    }
+    if not compact:
+        payload["agentInstructions"] = _filtered_agent_instruction_items(
+            schema_context.agent_instructions,
+            stage="during",
+        )
+        payload["glossary"] = schema_context.glossary_terms
+        payload["tables"] = schema_context.tables
+    if compact:
+        if not payload["businessTerms"]:
+            payload.pop("businessTerms", None)
+        if not payload["metrics"]:
+            payload.pop("metrics", None)
+        if not payload["exampleJoinPatterns"]:
+            payload.pop("exampleJoinPatterns", None)
+        if not payload.get("exampleGuidance"):
+            payload.pop("exampleGuidance", None)
+        if not payload.get("structureHints"):
+            payload.pop("structureHints", None)
+        if not payload["examples"]:
+            payload.pop("examples", None)
+        if not payload["enums"]:
+            payload.pop("enums", None)
+        if not payload["defaultFilters"]:
+            payload.pop("defaultFilters", None)
+        if not payload["joins"]:
+            payload.pop("joins", None)
+    else:
+        if not payload.get("glossary"):
+            payload.pop("glossary", None)
+        if not payload["businessTerms"]:
+            payload.pop("businessTerms", None)
+        if not payload["metrics"]:
+            payload.pop("metrics", None)
+        if not payload["exampleJoinPatterns"]:
+            payload.pop("exampleJoinPatterns", None)
+        if not payload.get("exampleGuidance"):
+            payload.pop("exampleGuidance", None)
+        if not payload.get("structureHints"):
+            payload.pop("structureHints", None)
+        if not payload["examples"]:
+            payload.pop("examples", None)
+        if not payload["enums"]:
+            payload.pop("enums", None)
+        if not payload["defaultFilters"]:
+            payload.pop("defaultFilters", None)
+    return payload
+
+
+def _slim_relations(
+    relations: list[dict[str, Any]],
+    selected_tables: set[str],
+) -> list[dict[str, Any]]:
+    slim: list[dict[str, Any]] = []
+    for relation in relations:
+        if not isinstance(relation, dict):
+            continue
+        left_table, right_table = _relation_endpoint_tables(relation)
+        if left_table not in selected_tables or right_table not in selected_tables:
+            continue
+        from_ref, to_ref = _relation_from_to_refs(relation)
+        if not from_ref or not to_ref:
+            continue
+        item: dict[str, Any] = {"from": from_ref, "to": to_ref}
+        join_type = relation.get("joinType")
+        if isinstance(join_type, str) and join_type.strip():
+            item["joinType"] = join_type.strip()
+        required_filters = relation.get("requiredFilters")
+        if isinstance(required_filters, list) and required_filters:
+            item["requiredFilters"] = [str(value) for value in required_filters if str(value).strip()]
+        slim.append(item)
+    return slim
+
+
+def _slim_policy(
+    policy_items: list[dict[str, Any]],
+    selected_tables: set[str],
+) -> list[dict[str, Any]]:
+    if not policy_items:
+        return []
+    merged: dict[str, Any] = {}
+    for item in policy_items:
+        if not isinstance(item, dict):
+            continue
+        for key, value in item.items():
+            if key in {"requiredScopes", "scopePlaceholders", "source"}:
+                continue
+            if key == "fieldBlacklist" and isinstance(value, list):
+                filtered = [
+                    {
+                        "table": entry.get("table"),
+                        "columns": entry.get("columns"),
+                    }
+                    for entry in value
+                    if isinstance(entry, dict)
+                    and str(entry.get("table") or "") in selected_tables
+                    and isinstance(entry.get("columns"), list)
+                ]
+                if filtered:
+                    merged["fieldBlacklist"] = filtered
+            elif key == "sqlRules" and value:
+                merged["sqlRules"] = value
+            elif key not in merged and value:
+                merged[key] = value
+    return [merged] if merged else []
+
+
+def _relation_endpoint_tables(relation: dict[str, Any]) -> tuple[str, str]:
+    left_table = str(relation.get("leftTable") or "")
+    right_table = str(relation.get("rightTable") or "")
+    if left_table and right_table:
+        return left_table, right_table
+    from_ref = str(relation.get("from") or "")
+    to_ref = str(relation.get("to") or "")
+    left = from_ref.split(".", 1)[0] if "." in from_ref else from_ref
+    right = to_ref.split(".", 1)[0] if "." in to_ref else to_ref
+    return left, right
+
+
+def _relation_from_to_refs(relation: dict[str, Any]) -> tuple[str | None, str | None]:
+    left_table = str(relation.get("leftTable") or "")
+    right_table = str(relation.get("rightTable") or "")
+    if left_table and right_table:
+        left_column = str(relation.get("leftColumn") or relation.get("fromColumn") or "")
+        right_column = str(relation.get("rightColumn") or relation.get("toColumn") or "")
+        from_ref = f"{left_table}.{left_column}".rstrip(".") if left_column else left_table
+        to_ref = f"{right_table}.{right_column}".rstrip(".") if right_column else right_table
+        return from_ref, to_ref
+    from_ref = str(relation.get("from") or "").strip()
+    to_ref = str(relation.get("to") or "").strip()
+    return (from_ref or None), (to_ref or None)
+
+
+def _sql_output_schema(default_limit: int, question: str) -> dict[str, Any]:
+    return {
+        "sql": f"SELECT column AS 中文含义 ... LIMIT {default_limit}",
+        "tables": ["table_name"],
+        "placeholders": [],
+        "usedColumns": ["table.column"],
+        "usedJoins": ["left_table.left_column = right_table.right_column"],
+        "metricRefs": ["schemaContext.metrics.name"],
+        "clarification": None,
+        "statusEnumPolicy": {
+            "explicitStatusFilter": "用户明确提出状态筛选时，把状态枚举条件写入 WHERE，并在 SELECT 中用 CASE 或枚举关联展示中文含义。",
+            "missingOrUnspecifiedStatus": "用户未提出状态筛选或 schemaContext 缺少枚举时，不要追问；首次查询保持宽泛，并把相关状态字段及中文含义加入 SELECT。",
         },
     }
-    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def _schema_read_order(*, compact: bool = False) -> list[str]:
+    if compact:
+        return ["policy", "schema", "concepts", "relations", "enums", "policy"]
+    return [
+        "agentInstructions",
+        "policy",
+        "glossary",
+        "schema",
+        "concepts/metrics/businessTerms",
+        "defaultFilters",
+        "joins",
+        "relations",
+        "exampleJoinPatterns",
+        "enums",
+        "policy",
+    ]
 
 
 def _business_examples(examples: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    return [example for example in examples if ":scope." not in str(example.get("sql") or "")]
+    """Prepare examples for the LLM prompt.
+
+    The MCP examples carry data-scope predicates (``... IN (:scope.project_ids)``)
+    that the LLM must never emit. Rather than dropping every example that has
+    them (which removed almost all join guidance), strip the scope predicates
+    and keep the rest of the pattern. If an example still contains ``:scope.``
+    after stripping, drop it to stay safe.
+    """
+    result: list[dict[str, Any]] = []
+    for example in examples:
+        sql = str(example.get("sql") or "")
+        original_sql = sql
+        if ":scope." in sql:
+            sql = _strip_scope_predicates(sql)
+            if ":scope." in sql:
+                continue
+        sql = _normalize_example_text_filters(sql)
+        if sql != original_sql:
+            example = {**example, "sql": sql}
+        result.append(example)
+    return result
+
+
+def _strip_scope_predicates(sql: str) -> str:
+    # Remove "AND <column> IN (:scope.<name>)" predicates, then tidy a WHERE
+    # clause that may be left starting with a stray AND.
+    cleaned = re.sub(
+        r"\s+AND\s+[A-Za-z_][\w.]*\s+IN\s*\(\s*:scope\.\w+\s*\)",
+        "",
+        sql,
+        flags=re.IGNORECASE,
+    )
+    cleaned = re.sub(r"\bWHERE\s+AND\s+", "WHERE ", cleaned, flags=re.IGNORECASE)
+    return cleaned
+
+
+def _normalize_example_text_filters(sql: str) -> str:
+    """Align business examples with SQL guardrails before prompting."""
+    return normalize_text_filters_to_like(sql)