aetherdialect 0.1.0__py3-none-any.whl

text2sql/core_utils.py

@@ -0,0 +1,834 @@
+"""Core utility functions shared across all pipeline stages, with no project-level dependencies other than config.
+
+Provides hashing and stable JSON serialization for intent and schema fingerprinting, SQL canonicalization and parameter substitution, LLM communication wrappers with retry logic, string processing helpers, and user interaction and display utilities.
+
+This module is the lowest-level shared layer and is imported by every other module that needs LLM access, logging, or SQL normalization.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import time
+from decimal import Decimal
+from typing import Any
+
+from openai import OpenAI
+
+from .config import EngineConfig, PolicyConfig
+
+_client = None
+
+
+def _get_client() -> OpenAI:
+    """Lazy-initialize OpenAI client on first use.
+
+    Returns:
+
+        Singleton OpenAI client configured from EngineConfig.
+    """
+    global _client
+    if _client is None:
+        _client = OpenAI(api_key=EngineConfig.API_TOKEN, base_url=EngineConfig.OPENAI_BASE_URL)
+    return _client
+
+
+def log(msg: str) -> None:
+    """Print a log message with [LOG] prefix when VERBOSE mode is enabled.
+
+    Args:
+
+        msg: Message to print.
+    """
+    if PolicyConfig.VERBOSE:
+        print(f"[LOG] {msg}")
+
+
+def debug(msg: str) -> None:
+    """Print a debug message with [DEBUG] prefix when DEBUG mode is enabled.
+
+    Args:
+
+        msg: Message to print.
+    """
+    if PolicyConfig.DEBUG:
+        print(f"[DEBUG] {msg}")
+
+
+def sha256(s: str) -> str:
+    """Compute SHA-256 hash of a string.
+
+    Args:
+
+        s: Input string to hash.
+
+    Returns:
+
+        Hex digest string of the SHA-256 hash.
+    """
+    return hashlib.sha256(s.encode("utf-8")).hexdigest()
+
+
+def _strip_fences(s: str) -> str:
+    """Remove markdown code fences from a string.
+
+    Args:
+
+        s: Raw string that may be wrapped in triple-backtick fences.
+
+    Returns:
+
+        String with leading and trailing markdown fences removed and stripped.
+    """
+    s = s.strip()
+    if s.startswith("```"):
+        s = re.sub(r"^```[a-zA-Z]*\s*", "", s)
+        s = re.sub(r"\s*```$", "", s)
+    return s.strip()
+
+
+def canonicalize_sql(sql: str) -> str:
+    """Normalize SQL whitespace, formatting, and join equality operand order.
+
+    Args:
+
+        sql: Raw SQL string, possibly with extra whitespace or markdown fences.
+
+    Returns:
+
+        Canonicalized SQL string with consistent spacing and canonical operand order in equality conditions.
+    """
+    s = _strip_fences(sql).strip()
+    s = s.rstrip(";").strip()
+    s = re.sub(r"^EXPLAIN\s+(?:ANALYZE\s+)?", "", s, flags=re.IGNORECASE)
+    s = re.sub(r"\s+", " ", s).strip()
+    s = re.sub(r"\(\s+", "(", s)
+    s = re.sub(r"\s+\)", ")", s)
+    s = re.sub(r"\s*,\s*", ", ", s)
+    s = re.sub(r"(?<![><!=])=(?![>=])", " = ", s)
+    s = re.sub(r"\s+", " ", s).strip()
+
+    def normalize_equality(m: re.Match) -> str:
+        left, right = m.group(1).strip(), m.group(2).strip()
+        if left > right:
+            left, right = right, left
+        return f"{left} = {right}"
+
+    s = re.sub(r"([^\s()><!=]+)\s*=\s*([^\s()><!=]+)", normalize_equality, s)
+    return s
+
+
+def stable_json(o: Any) -> str:
+    """Serialize an object to JSON with stable key ordering.
+
+    Args:
+
+        o: Any JSON-serializable object.
+
+    Returns:
+
+        Compact JSON string with sorted keys for deterministic hashing.
+    """
+    return json.dumps(o, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def colmap_signature(column_map: dict[str, str]) -> str:
+    """Compute a stable hash signature for a column map.
+
+    Args:
+
+        column_map: Mapping from bare column names to table names.
+
+    Returns:
+
+        SHA-256 hex digest of the sorted, stable-serialized column map.
+    """
+    return sha256(stable_json(sorted(column_map.items())))
+
+
+def intent_id(d: dict[str, Any]) -> str:
+    """Generate a 16-character intent identifier from a dictionary.
+
+    Args:
+
+        d: Dictionary representing a canonical intent structure.
+
+    Returns:
+
+        First 16 characters of the SHA-256 hex digest of the stable JSON.
+    """
+    return sha256(stable_json(d))[:16]
+
+
+def issue_sig(rule_ids: list[str]) -> str:
+    """Generate an issue signature from a list of rule identifiers.
+
+    Args:
+
+        rule_ids: List of issue or rule ID strings.
+
+    Returns:
+
+        SHA-256 hex digest of the sorted rule IDs for ABAB loop detection.
+    """
+    return sha256(stable_json(sorted(rule_ids)))
+
+
+def schema_hash_fp(tables_dict: dict[str, Any]) -> str:
+    """Generate a schema fingerprint from a tables dictionary.
+
+    Args:
+
+        tables_dict: Raw tables dictionary as returned by schema profiling.
+
+    Returns:
+
+            SHA-256 hex digest used as the schema_hash for a SchemaGraph.
+    """
+    return sha256(stable_json({"tables": tables_dict}))
+
+
+def normalize_question(q: str) -> str:
+    """Normalize a user question while preserving the case of quoted values.
+
+    Args:
+
+        q: Raw user question string.
+
+    Returns:
+
+        Lowercased, whitespace-normalized question with special characters removed, but with quoted literals restored to their original case.
+    """
+    q = q.strip()
+    q = re.sub(r"[\u2018\u2019\u201c\u201d]", "'", q)
+
+    quoted_values = []
+
+    def preserve_quoted(m):
+        quoted_values.append(m.group(1))
+        return f"__QUOTED_{len(quoted_values) - 1}__"
+
+    q = re.sub(r"'([^']*)'", preserve_quoted, q)
+
+    q = q.lower()
+    q = re.sub(r"[^a-z0-9\s_:/\-\.,\?]", " ", q)
+    q = re.sub(r"\s+", " ", q).strip()
+
+    for i, val in enumerate(quoted_values):
+        q = q.replace(f"__quoted_{i}__", f"'{val}'")
+
+    return q
+
+
+def _extract_first_json_object(s: str) -> str | None:
+    """Extract the first JSON object from a string by scanning for balanced braces.
+
+    Args:
+
+        s: String that may contain a JSON object embedded in other text.
+
+    Returns:
+
+        The first balanced {...} substring, or None if not found.
+    """
+    s = _strip_fences(s)
+    start = s.find("{")
+    if start == -1:
+        return None
+    depth = 0
+    for i in range(start, len(s)):
+        if s[i] == "{":
+            depth += 1
+        elif s[i] == "}":
+            depth -= 1
+            if depth == 0:
+                return s[start : i + 1]
+    return None
+
+
+def safe_json_loads(s: str) -> Any | None:
+    """Safely parse JSON with fallback to fragment extraction.
+
+    Args:
+
+        s: Raw string to parse as JSON.
+
+    Returns:
+
+        Parsed Python object, or None if parsing fails entirely.
+    """
+    s = s.strip()
+    try:
+        return json.loads(s)
+    except Exception:
+        pass
+    frag = _extract_first_json_object(s)
+    if frag:
+        try:
+            return json.loads(frag)
+        except Exception:
+            return None
+    return None
+
+
+def parameter_abstract(sql: str) -> tuple[str, dict[str, Any]]:
+    """Replace literal values in SQL with named parameter placeholders.
+
+    Args:
+
+        sql: SQL string with inline literal values.
+
+    Returns:
+
+        Tuple of (parameterized SQL string, dict mapping placeholder keys to original values).
+    """
+    s = sql
+    params: dict[str, Any] = {}
+    idx = 1
+
+    def put(val: str) -> str:
+        nonlocal idx
+        key = f"p{idx}"
+        idx += 1
+        params[key] = val
+        return f":{key}"
+
+    s = re.sub(r"(\b\d{4}-\d{2}-\d{2}\b)", lambda m: put(m.group(1)), s)
+    s = re.sub(r"(\b\d{2}/\d{2}/\d{4}\b)", lambda m: put(m.group(1)), s)
+    s = re.sub(r"(\b\d+(\.\d+)?\b)", lambda m: put(m.group(1)), s)
+    s = re.sub(r"('([^']|'')*')", lambda m: put(m.group(1)), s)
+    s = re.sub(r"\s+", " ", s).strip()
+    return s, params
+
+
+_TASK_PROFILES: dict[str, dict[str, Any]] = {
+    "intent": {
+        "model": EngineConfig.OPENAI_MODEL_INTENT,
+        "reasoning": {"effort": "low", "summary": "concise"},
+    },
+    "schema": {
+        "model": EngineConfig.OPENAI_MODEL_SCHEMA,
+        "reasoning": {"effort": "low", "summary": "concise"},
+    },
+    "sql": {
+        "model": EngineConfig.OPENAI_MODEL_SQL,
+        "temperature": 0,
+    },
+    "default": {
+        "model": EngineConfig.OPENAI_MODEL,
+        "temperature": 0,
+    },
+}
+
+
+def llm_chat(
+    system: str,
+    user: str,
+    max_retries: int = 3,
+    timeout: float = 60.0,
+    task: str = "default",
+) -> str:
+    """Send a chat completion request to the LLM with task-based model routing.
+
+    Selects the model and API parameters based on the task identifier. Reasoning-capable models receive reasoning parameters instead of temperature. All requests enforce structured JSON output via text.format.
+
+    Args:
+
+        system: System prompt string.
+        user: User prompt string.
+        max_retries: Maximum number of attempts before raising.
+        timeout: Per-request timeout in seconds.
+        task: Routing key selecting model and parameters. One of "intent", "sql", "schema", or "default".
+
+    Returns:
+
+        Stripped response text from the LLM.
+    """
+    profile = _TASK_PROFILES.get(task, _TASK_PROFILES["default"])
+    model = profile["model"]
+
+    kwargs: dict[str, Any] = {
+        "model": model,
+        "input": [
+            {
+                "role": "system",
+                "content": [{"type": "input_text", "text": system}],
+            },
+            {"role": "user", "content": [{"type": "input_text", "text": user}]},
+        ],
+        "timeout": timeout,
+        "text": {"format": {"type": "json_object"}},
+    }
+
+    if "reasoning" in profile:
+        kwargs["reasoning"] = profile["reasoning"]
+    else:
+        kwargs["temperature"] = profile.get("temperature", 0)
+
+    client = _get_client()
+
+    debug(f"[core_utils.llm_chat] task={task} system_len={len(system)} user_len={len(user)}")
+
+    for attempt in range(max_retries):
+        try:
+            start = time.time()
+            r = client.responses.create(**kwargs)
+            elapsed = time.time() - start
+            output = r.output_text.strip()
+            debug(f"[core_utils.llm_chat] RAW OUTPUT:\n{output}")
+            debug(
+                f"[core_utils.llm_chat] model={model} task={task} "
+                f"completed in {elapsed:.1f}s (attempt {attempt + 1}/{max_retries})"
+            )
+            return output
+        except Exception as e:
+            elapsed = time.time() - start
+            log(
+                f"[core_utils.llm_chat] timeout or error after {elapsed:.1f}s (attempt {attempt + 1}/{max_retries}): {str(e)[:100]}"
+            )
+            if attempt < max_retries - 1:
+                wait = 2**attempt
+                log(f"[core_utils.llm_chat] retrying in {wait}s...")
+                time.sleep(wait)
+            else:
+                raise RuntimeError(f"LLM call failed after {max_retries} attempts: {str(e)}") from e
+
+
+def normalize_sql_operator_spaces(sql: str) -> str:
+    """Collapse spaces inside comparison operators in SQL so parsers see a single token.
+
+    Replaces ``> =`` with ``>=``, ``< =`` with ``<=``, and ``! =`` with ``!=`` so that LLM-generated SQL with spaces inside operators parses correctly.
+
+    Args:
+
+        sql: Raw SQL string that may contain spaced operators.
+
+    Returns:
+
+        SQL string with operator spaces collapsed.
+
+    """
+    if not sql or not sql.strip():
+        return sql
+    s = sql.replace("> =", ">=").replace("< =", "<=").replace("! =", "!=")
+    return s
+
+
+def normalize_sql(sql: str) -> str:
+    """Normalize SQL ORDER BY clauses to include explicit ASC or DESC direction.
+
+    Args:
+
+        sql: Raw SQL string.
+
+    Returns:
+
+        Canonicalized SQL with each ORDER BY column explicitly marked ASC or DESC.
+    """
+    s = canonicalize_sql(sql)
+    if not s:
+        return s
+
+    s_upper = s.upper()
+    order_by_pos = s_upper.find("ORDER BY")
+    if order_by_pos != -1:
+        before_order = s[: order_by_pos + 8]
+        after_order = s[order_by_pos + 8 :]
+
+        limit_pos = after_order.upper().find("LIMIT")
+        if limit_pos != -1:
+            order_clause = after_order[:limit_pos].strip()
+            rest = after_order[limit_pos:]
+        else:
+            order_clause = after_order.strip()
+            rest = ""
+
+        normalized_items = []
+        for item in order_clause.split(","):
+            item = item.strip()
+            if not item:
+                continue
+            item_upper = item.upper()
+            if item_upper.endswith(" ASC") or item_upper.endswith(" DESC"):
+                normalized_items.append(item)
+            else:
+                normalized_items.append(f"{item} ASC")
+
+        if normalized_items:
+            s = f"{before_order} {', '.join(normalized_items)}"
+            if rest:
+                s = f"{s} {rest}"
+
+    return s
+
+
+def llm_json(system: str, user: str, retries: int = 1, task: str = "default") -> dict[str, Any]:
+    """Request a JSON response from the LLM with retry on parse failure.
+
+    Args:
+
+        system: System prompt string.
+        user: User prompt string.
+        retries: Number of additional retry attempts if the initial response is not valid JSON.
+        task: Routing key for model selection passed to llm_chat.
+
+    Returns:
+
+        Parsed JSON dict, or an empty dict if all attempts fail.
+    """
+    raw = llm_chat(system, user, task=task)
+    parsed = safe_json_loads(raw)
+    if isinstance(parsed, dict):
+        debug(f"[core_utils.llm_json] parsed keys={list(parsed.keys())}")
+        return parsed
+
+    if raw.strip().upper().startswith("SELECT"):
+        debug("[core_utils.llm_json] raw_sql_detected wrapping")
+        sql_statement = raw.strip()
+        wrapped = {"sql": sql_statement, "chosen_join_candidate_id": "J00"}
+        return wrapped
+
+    debug("[core_utils.llm_json] parse_failed: retrying")
+    for attempt in range(max(0, retries)):
+        debug(f"[core_utils.llm_json] retry: {attempt + 1}")
+        raw = llm_chat(
+            system,
+            user + "\n\nFORMAT_ERROR: Output ONLY valid JSON that matches the required schema. Do NOT output raw SQL.",
+            task=task,
+        )
+        parsed = safe_json_loads(raw)
+        if isinstance(parsed, dict):
+            debug(f"[core_utils.llm_json] retry_success: keys={list(parsed.keys())}")
+            return parsed
+
+        if raw.strip().upper().startswith("SELECT"):
+            debug("[core_utils.llm_json] retry_sql_detected: wrapping")
+            sql_statement = raw.strip()
+            wrapped = {"sql": sql_statement, "chosen_join_candidate_id": "J00"}
+            return wrapped
+
+    debug("[core_utils.llm_json] all_retries_failed")
+    return {}
+
+
+def llm_sql_with_join(system: str, user: str, task: str = "sql") -> tuple[str, str, bool, dict[str, str]]:
+    """Request SQL generation with join candidate selection from the LLM.
+
+    Args:
+
+        system: System prompt string.
+        user: User prompt string including join candidates and expression guides.
+        task: Routing key for model selection passed to llm_json.
+
+    Returns:
+
+        Tuple of (sql, chosen_join_candidate_id, success_bool, cte_join_candidate_ids_dict).
+    """
+    debug("[core_utils.llm_sql_with_join] requesting")
+    parsed = llm_json(system, user, retries=1, task=task)
+    if not parsed:
+        debug("[core_utils.llm_sql_with_join] llm_json returned empty")
+        return "", "", False, {}
+
+    sql = parsed.get("sql") if isinstance(parsed.get("sql"), str) else ""
+    chosen = parsed.get("chosen_join_candidate_id") if isinstance(parsed.get("chosen_join_candidate_id"), str) else ""
+
+    cte_join_ids: dict[str, str] = {}
+    raw_cte_ids = parsed.get("chosen_cte_join_candidate_ids")
+    if isinstance(raw_cte_ids, dict):
+        for cte_name, cid in raw_cte_ids.items():
+            if isinstance(cte_name, str) and isinstance(cid, str):
+                cte_join_ids[cte_name] = cid
+
+    if sql and not chosen:
+        if "join" not in sql.lower():
+            chosen = "J00"
+            debug("[core_utils.llm_sql_with_join] default_J00: no_joins")
+
+    sql = normalize_sql_operator_spaces(sql) if sql else ""
+    sql = canonicalize_sql(sql) if sql else ""
+    ok = bool(sql)
+    debug(f"[core_utils.llm_sql_with_join] result: join={chosen} ok={ok} cte_ids={cte_join_ids}")
+    debug(f"[core_utils.llm_sql_with_join] result SQL:\n{sql}")
+    return sql, chosen, ok, cte_join_ids
+
+
+def substitute_params(sql_param: str, params: dict[str, Any]) -> str:
+    """Substitute parameter placeholders in SQL with their actual values.
+
+    Replaces :key placeholders, reduces trivial 1.0 * coefficients and +0 offsets, and strips LIMIT None.
+
+    Args:
+
+        sql_param: Parameterized SQL string with :key placeholders.
+        params: Dict mapping placeholder keys to their resolved values.
+
+    Returns:
+
+        SQL string with all placeholders replaced and trivial arithmetic simplified.
+    """
+    result = sql_param
+    for key in sorted(params.keys(), key=lambda k: -len(k)):
+        val = params[key]
+        if not key:
+            continue
+        placeholder = f":{key}"
+        if isinstance(val, list):
+            formatted_items = []
+            for item in val:
+                if isinstance(item, str):
+                    formatted_items.append(f"'{item}'")
+                else:
+                    formatted_items.append(str(item))
+            result = result.replace(placeholder, ", ".join(formatted_items))
+        elif isinstance(val, bool):
+            result = result.replace(placeholder, "TRUE" if val else "FALSE")
+        elif isinstance(val, str):
+            if val.startswith("'") and val.endswith("'") and "','" in val:
+                result = result.replace(placeholder, val)
+            elif re.match(r"^-?\d+(?:\.\d+)?(?:,\s*-?\d+(?:\.\d+)?)*$", val):
+                result = result.replace(placeholder, val)
+            else:
+                result = result.replace(placeholder, f"'{val}'")
+        else:
+            result = result.replace(placeholder, str(val))
+    result = re.sub(r"\b1(?:\.0)?\s*\*\s*", "", result)
+    result = re.sub(r"\s*\*\s*1(?:\.0)?\b", "", result)
+    result = re.sub(r"\s*[+\-]\s*0(?:\.0)?\b", "", result)
+    result = re.sub(r"\s*LIMIT\s+None\b", "", result, flags=re.IGNORECASE)
+    return result
+
+
+def sql_fp(sql_param: str) -> str:
+    """Compute a SQL fingerprint hash from a parameterized SQL string.
+
+    Args:
+
+        sql_param: Parameterized SQL string.
+
+    Returns:
+
+        SHA-256 hex digest of the lowercased SQL for template deduplication.
+    """
+    return sha256(sql_param.lower())
+
+
+def _format_cell(v) -> str:
+    """Format a single query result cell as a clean display string.
+
+    Args:
+
+        v: Cell value of any type returned by the database driver.
+
+    Returns:
+
+        Human-readable string representation of the cell value.
+    """
+    if v is None:
+        return "NULL"
+    if isinstance(v, Decimal):
+        return f"{v:f}" if v == v.to_integral_value() else f"{v}"
+    if isinstance(v, str):
+        return v
+    return str(v)
+
+
+def print_query_result(
+    rows: list[tuple],
+    sql: str,
+    context: str = "Query Results",
+    headers: list[str] | None = None,
+) -> None:
+    """Display query results in a standardized tabular format.
+
+    Args:
+
+        rows: List of row tuples returned by the database.
+        sql: The SQL string that produced the results.
+        context: Section heading to display above the results.
+        headers: Optional list of column header names.
+    """
+    print(f"\n{context}\n")
+    print(f"SQL:\n  {sql}\n")
+
+    if len(rows) == 1 and len(rows[0]) == 1:
+        val = rows[0][0]
+        print(f"Answer: {_format_cell(val)}\n")
+    else:
+        sample = rows[:5]
+        formatted = [[_format_cell(v) for v in row] for row in sample]
+        num_cols = max(len(r) for r in formatted) if formatted else 0
+        col_headers = (headers or [])[:num_cols]
+        while len(col_headers) < num_cols:
+            col_headers.append(f"col{len(col_headers) + 1}")
+        widths = [len(h) for h in col_headers]
+        for row in formatted:
+            for i, cell in enumerate(row):
+                if i < len(widths):
+                    widths[i] = max(widths[i], len(cell))
+        header_line = "  ".join(h.ljust(widths[i]) for i, h in enumerate(col_headers))
+        sep_line = "  ".join("-" * widths[i] for i in range(num_cols))
+        print(f"  {header_line}")
+        print(f"  {sep_line}")
+        for row in formatted:
+            line = "  ".join((row[i] if i < len(row) else "").ljust(widths[i]) for i in range(num_cols))
+            print(f"  {line}")
+        if len(rows) > 5:
+            print(f"  ... ({len(rows)} total rows)")
+
+
+def ask_user_choice(prompt: str, options: list[str], silent_no: bool = False) -> str | None:
+    """Prompt the user to select from a list of options.
+
+    Args:
+
+        prompt: Question or instruction to display to the user.
+        options: List of valid option strings shown in brackets.
+        silent_no: If True, suppresses the termination message on 'n' input.
+
+    Returns:
+
+        'y', 'n', or None if input is invalid or interrupted.
+    """
+    options_display = "/".join(options)
+    print(f"{prompt} [{options_display}]: ", end="")
+    try:
+        user_input = input().strip()
+    except (EOFError, KeyboardInterrupt):
+        print("\nUser terminated.")
+        return None
+
+    if not user_input or not user_input.strip():
+        print("\nInvalid input.")
+        return None
+
+    normalized = user_input.lower()
+    if normalized in ("y", "yes"):
+        print("Yes")
+        return "y"
+    elif normalized in ("n", "no"):
+        print("No")
+        if not silent_no:
+            print("\nUser terminated.")
+        return "n"
+
+    print("\nInvalid input.")
+    return None
+
+
+def print_info(title: str, items: dict[str, Any] = None, footer: str = None) -> None:
+    """Display an informational message with optional structured key-value data.
+
+    Args:
+
+        title: Main heading to display.
+        items: Optional dict of key-value pairs to display as indented lines.
+        footer: Optional trailing message to print after the items.
+    """
+    print(f"\n{title}")
+    if items:
+        for key, val in items.items():
+            if isinstance(val, list | tuple | set):
+                val = ", ".join(str(v) for v in val)
+            print(f"  {key}: {val}")
+    if footer:
+        print(f"\n{footer}")
+
+
+def join_sig_string(sig: list[str]) -> str:
+    """Convert a join signature list to a pipe-delimited string for hashing.
+
+    Args:
+
+        sig: List of join path component strings.
+
+    Returns:
+
+        Pipe-delimited string of the join signature components.
+    """
+    return "|".join(sig)
+
+
+def explain_db_error_nl(err: str) -> str:
+    """Convert a database error message to a human-readable explanation.
+
+    Args:
+
+        err: Raw error string returned by the database driver.
+
+    Returns:
+
+        Plain-English explanation of the likely cause and suggested fix.
+    """
+    e = (err or "").strip()
+    low = e.lower()
+    if "syntax error at or near" in low:
+        return "SQL syntax error. The query is not valid SQL (likely a misplaced keyword, comma, or parenthesis)."
+    if "does not exist" in low and "column" in low:
+        return "A referenced column name does not exist in that table (wrong column or wrong table alias)."
+    if "does not exist" in low and "relation" in low:
+        return "A referenced table or view does not exist (wrong table name or missing schema qualification)."
+    if "ambiguous" in low and "column" in low:
+        return "A column name is ambiguous because multiple joined tables share that column name. It needs a table alias prefix."
+    if "operator does not exist" in low:
+        return "A comparison uses incompatible types (e.g., comparing text to number/date). Casting or a different operator is needed."
+    if "invalid input syntax" in low:
+        return "A literal value cannot be parsed into the required type (e.g., invalid date or non-numeric text in a numeric field)."
+    if "division by zero" in low:
+        return "The query attempted division by zero. It needs a guard (e.g., NULLIF)."
+    if "more than one row returned by a subquery" in low:
+        return "A subquery used as a scalar returned multiple rows. It needs aggregation or a LIMIT."
+    if "permission denied" in low:
+        return "Database permissions do not allow this operation on the referenced object."
+    return "Database rejected the query. It needs a structural correction (tables/columns/joins/filters)."
+
+
+def is_repair_oscillating(fingerprints: list[str]) -> bool:
+    """Detect AA or ABA oscillation in a sequence of repair fingerprints.
+
+    Used by both the SQL generation repair loop and the result-repair loop to detect when the LLM is producing the same output repeatedly (AA) or cycling between two outputs (ABA or ABAB).
+
+    Args:
+
+        fingerprints: Ordered list of fingerprint strings, one per repair iteration. Each fingerprint is typically a SQL fingerprint or an issue-signature string.
+
+    Returns:
+
+        True if the last two entries are identical (AA) or the last three form an A-B-A cycle.
+    """
+    n = len(fingerprints)
+    if n >= 2 and fingerprints[-1] == fingerprints[-2]:
+        return True
+    if n >= 3 and fingerprints[-1] == fingerprints[-3]:
+        return True
+    return False
+
+
+def normalize_op(op: str) -> str:
+    """Normalize a comparison operator string to its canonical form.
+
+    Converts aliases such as '==', '<>', 'ne', 'gte', and others to standard SQL operators.
+
+    Args:
+
+        op: Raw operator string as provided by the LLM.
+
+    Returns:
+
+        Lowercased canonical operator string (for example '=', '!=', or '>=' ).
+    """
+    op_lower = re.sub(r"\s+", " ", op.lower().strip())
+    mapping = {
+        "==": "=",
+        "<>": "!=",
+        "ne": "!=",
+        "eq": "=",
+        "gt": ">",
+        "lt": "<",
+        "ge": ">=",
+        "le": "<=",
+        "gte": ">=",
+        "lte": "<=",
+    }
+    return mapping.get(op_lower, op_lower)