sql-dialect-master 1.1.1__py3-none-any.whl

backend/core/nl2sql_components/tokenizer.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""Tokenizer module for NL2SQL.
+
+Provides smart tokenization with Chinese and English support,
+optimized for natural language SQL generation.
+"""
+import re
+import logging
+from typing import List
+
+# Configure module logger
+logger = logging.getLogger(__name__)
+
+# Try to import jieba for better Chinese tokenization
+try:
+    import jieba
+    jieba.setLogLevel(logging.WARNING)  # Suppress jieba logs
+    JIEBA_AVAILABLE = True
+    logger.info("jieba tokenizer available for Chinese NL2SQL")
+except ImportError:
+    JIEBA_AVAILABLE = False
+    logger.debug("jieba not installed, using basic tokenization for Chinese")
+
+
+class Tokenizer:
+    """Smart tokenizer with Chinese and English support.
+    
+    Performance: All static regex patterns are pre-compiled at class level.
+    """
+    
+    # Chinese punctuation to remove
+    CN_PUNCTUATION = r"[，。！？、；：\"'（）【】《》]"
+    
+    # Pre-compiled regex patterns for performance
+    _RE_CN_PUNCT = re.compile(CN_PUNCTUATION)
+    _RE_EN_PUNCT = re.compile(r'[,\.!?;:\'\"()\[\]{}]')
+    _RE_CHINESE_CHARS = re.compile(r'[\u4e00-\u9fff]')
+    _RE_LETTER = re.compile(r'[a-zA-Z]')
+    _RE_ALNUM = re.compile(r'[a-zA-Z0-9]')
+    _RE_DIGIT = re.compile(r'\d')
+    _RE_DIGIT_DOT = re.compile(r'[\d\.]')
+    _RE_NUMBERS = re.compile(r'\d+\.?\d*')
+    _RE_QUOTED = re.compile(r'["\']([^"\']+)["\']')
+    
+    # Common Chinese compound words that should not be split
+    # These are keywords important for NL2SQL
+    CHINESE_COMPOUNDS = [
+        # Comparison operators
+        "大于", "小于", "等于", "不等于", "大于等于", "小于等于", "超过", "低于",
+        # Aggregations
+        "平均", "总和", "最大", "最小", "合计", "统计", "计数", "数量",
+        # Time
+        "最近", "过去", "今天", "昨天", "前天", "本周", "本月", "本年",
+        # Operations
+        "查询", "获取", "显示", "列出", "插入", "添加", "更新", "修改", "删除", "移除",
+        # Grouping/Sorting
+        "分组", "汇总", "排序", "排列", "升序", "降序", "去重",
+        # Tables
+        "用户", "订单", "产品", "商品", "员工", "部门", "客户", "日志",
+        # Columns
+        "姓名", "名字", "邮箱", "电话", "地址", "年龄", "性别", "金额", "价格", "数量",
+        "状态", "类型", "时间", "日期", "创建时间", "更新时间",
+        # Joins
+        "关联", "连接", "左连接", "右连接", "内连接",
+        # Misc
+        "所有", "全部", "每个", "各个",
+    ]
+    
+    @staticmethod
+    def tokenize(text: str) -> List[str]:
+        """Tokenize text into words/tokens.
+        
+        Uses jieba for Chinese if available, otherwise falls back to
+        compound-word aware splitting for Chinese and word-based for English.
+        """
+        # Clean punctuation using pre-compiled patterns
+        text = Tokenizer._RE_CN_PUNCT.sub(' ', text)
+        text = Tokenizer._RE_EN_PUNCT.sub(' ', text)
+        
+        # Check if text contains Chinese characters
+        has_chinese = bool(Tokenizer._RE_CHINESE_CHARS.search(text))
+        
+        if has_chinese and JIEBA_AVAILABLE:
+            # Use jieba for Chinese tokenization
+            tokens = list(jieba.cut(text, cut_all=False))
+        elif has_chinese:
+            # Fallback: compound-word aware tokenization
+            tokens = Tokenizer._tokenize_chinese_fallback(text)
+        else:
+            # English: simple word tokenization
+            tokens = text.lower().split()
+        
+        # Filter empty tokens
+        return [t.strip() for t in tokens if t.strip()]
+    
+    @staticmethod
+    def _tokenize_chinese_fallback(text: str) -> List[str]:
+        """Fallback Chinese tokenization that preserves compound words.
+        
+        Uses a greedy longest-match approach for known compound words.
+        """
+        tokens = []
+        i = 0
+        text_len = len(text)
+        
+        while i < text_len:
+            char = text[i]
+            
+            # Skip whitespace
+            if char.isspace():
+                i += 1
+                continue
+            
+            # Check if this is the start of a known compound word
+            matched_compound = None
+            for compound in sorted(Tokenizer.CHINESE_COMPOUNDS, key=len, reverse=True):
+                if text[i:].startswith(compound):
+                    matched_compound = compound
+                    break
+            
+            if matched_compound:
+                tokens.append(matched_compound)
+                i += len(matched_compound)
+            elif Tokenizer._RE_CHINESE_CHARS.match(char):
+                # Single Chinese character
+                tokens.append(char)
+                i += 1
+            elif Tokenizer._RE_LETTER.match(char):
+                # English word - collect until non-letter
+                word_start = i
+                while i < text_len and Tokenizer._RE_ALNUM.match(text[i]):
+                    i += 1
+                tokens.append(text[word_start:i].lower())
+            elif Tokenizer._RE_DIGIT.match(char):
+                # Number - collect until non-digit
+                num_start = i
+                while i < text_len and Tokenizer._RE_DIGIT_DOT.match(text[i]):
+                    i += 1
+                tokens.append(text[num_start:i])
+            else:
+                i += 1
+        
+        return tokens
+    
+    @staticmethod
+    def extract_numbers(text: str) -> List[str]:
+        """Extract numbers, preserving a simple Chinese boolean comparison tail."""
+        numbers = Tokenizer._RE_NUMBERS.findall(text)
+        if "且" in text and len(numbers) >= 2:
+            boolean_tail = re.search(
+                r"且\s*(数量|价格|金额|年龄|数量)\s*(大于|超过|高于|多于|小于|低于|少于|不足|等于|不等于)\s*(\d+(?:\.\d+)?)",
+                text,
+            )
+            if boolean_tail:
+                column_map = {
+                    "数量": "quantity",
+                    "价格": "price",
+                    "金额": "amount",
+                    "年龄": "age",
+                }
+                operator_map = {
+                    "大于": ">",
+                    "超过": ">",
+                    "高于": ">",
+                    "多于": ">",
+                    "小于": "<",
+                    "低于": "<",
+                    "少于": "<",
+                    "不足": "<",
+                    "等于": "=",
+                    "不等于": "!=",
+                }
+                column = column_map[boolean_tail.group(1)]
+                operator = operator_map[boolean_tail.group(2)]
+                second_value = boolean_tail.group(3)
+                return [f"{numbers[0]} AND {column} {operator} {second_value}"] + numbers[1:]
+        return numbers
+    
+    @staticmethod
+    def extract_quoted_strings(text: str) -> List[str]:
+        """Extract quoted strings from text."""
+        return Tokenizer._RE_QUOTED.findall(text)
+    
+    @staticmethod
+    def is_chinese(text: str) -> bool:
+        """Check if text contains Chinese characters."""
+        return bool(Tokenizer._RE_CHINESE_CHARS.search(text))

backend/core/nl2sql_legacy.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+"""NL2SQL legacy module — P8 import-compatibility shim.
+
+All implementation has moved to ``backend.core.nl2sql_pipeline``.  This
+module is a thin re-export shim kept so existing import sites
+(``from backend.core.nl2sql_legacy import NL2SQLGenerator`` /
+``NL2SQLResult``) continue to work unchanged.  It is NOT deleted;
+deletion happens in a future phase once every import/call site is
+confirmed migrated.
+
+``NL2SQLResult`` is re-exported from the single canonical source
+(``nl2sql_pipeline.models``) so
+``from backend.core.nl2sql import NL2SQLResult as A`` and
+``from backend.core.nl2sql_legacy import NL2SQLResult as B`` satisfy
+``A is B``.
+"""
+from .nl2sql_pipeline.models import NL2SQLResult
+from .nl2sql_pipeline.orchestrator import (
+    PipelineNL2SQLGenerator as NL2SQLGenerator,
+)
+
+__all__ = ["NL2SQLGenerator", "NL2SQLResult"]

backend/core/nl2sql_pipeline/__init__.py

@@ -0,0 +1,13 @@
+"""P8 NL2SQL pipeline: named-stage modules extracted from nl2sql_legacy.
+
+Each module corresponds to one stage of the target pipeline
+(Intent → Entity Resolution → Relation Resolution → Predicate Resolution
+→ Query IR → Dialect Renderer → AST Validation → Evidence/Confidence).
+
+This package is internal to ``backend.core``; it is NOT re-exported from
+``backend.core.__init__``.  The public facade is ``backend.core.nl2sql``.
+"""
+from .models import NL2SQLResult
+from .orchestrator import PipelineNL2SQLGenerator
+
+__all__ = ["NL2SQLResult", "PipelineNL2SQLGenerator"]

backend/core/nl2sql_pipeline/aggregations.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""P8 NL2SQL pipeline: aggregation extraction (moved from nl2sql_legacy).
+
+``extract_aggregations`` is a thin parameterized wrapper over
+``nl2sql_components.aggregations.extract_aggregations`` — it fills the
+canonical ``COLUMN_PATTERNS`` when none are supplied so the legacy
+``self._extract_aggregations(text)`` call-shape works unchanged.
+"""
+from typing import Dict, List, Optional
+
+from ..nl2sql_components.aggregations import (
+    extract_aggregations as _extract_aggregations_impl,
+)
+from ..nl2sql_components.mappings import COLUMN_PATTERNS
+
+
+def extract_aggregations(
+    text: str, column_patterns: Optional[Dict[str, str]] = None
+) -> List[str]:
+    """Extract aggregation expressions from text.
+
+    Returns a list of SQL aggregate expressions, e.g.
+    ``['COUNT(*)', 'SUM(amount)']``.  An empty list means no
+    aggregation was requested.
+    """
+    return _extract_aggregations_impl(text, column_patterns or COLUMN_PATTERNS)

backend/core/nl2sql_pipeline/clause_extract.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""P8 NL2SQL pipeline: clause extraction (moved from nl2sql_legacy).
+
+Holds the ``extract_group_by`` and ``extract_ordering`` stage functions
+(verbatim moves of the legacy instance methods, parameterized on
+``COLUMN_PATTERNS`` / ``TABLE_PATTERNS``).  ``extract_limit`` and
+``check_distinct`` are re-exports of the stateless ``core_extract``
+primitives the legacy class already delegated to.
+"""
+import re
+from typing import Dict, List, Optional, Tuple
+
+from ..nl2sql_components.core_extract import check_distinct, extract_limit
+from ..nl2sql_components.mappings import COLUMN_PATTERNS, TABLE_PATTERNS
+
+__all__ = [
+    "check_distinct",
+    "extract_group_by",
+    "extract_limit",
+    "extract_ordering",
+]
+
+
+def extract_group_by(
+    text: str,
+    column_patterns: Optional[Dict[str, str]] = None,
+    table_patterns: Optional[Dict[str, str]] = None,
+) -> List[str]:
+    """Extract GROUP BY columns from text.
+
+    Verbatim move of ``nl2sql_legacy._extract_group_by``; ``column_patterns``
+    and ``table_patterns`` replace the instance attributes.
+    """
+    column_patterns = column_patterns or COLUMN_PATTERNS
+    table_patterns = table_patterns or TABLE_PATTERNS
+    group_cols: List[str] = []
+    patterns = [
+        r"按(.+?)(分组|汇总|统计)",
+        r"group\s*by\s*(\w+)",
+        r"grouped\s*by\s*(\w+)",
+        r"per\s+(\w+)",
+        r"each\s+(\w+)",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, text, re.IGNORECASE)
+        if not match:
+            continue
+        group_text = match.group(1).strip()
+        for kw, col in column_patterns.items():
+            if kw in group_text:
+                group_cols.append(col)
+                break
+        else:
+            for kw in table_patterns:
+                if kw in group_text:
+                    if "部门" in group_text or "department" in group_text:
+                        group_cols.append("department")
+                    elif "用户" in group_text or "user" in group_text:
+                        group_cols.append("user_id")
+                    elif "日期" in group_text or "date" in group_text:
+                        group_cols.append("date")
+                    elif "月" in group_text or "month" in group_text:
+                        group_cols.append("MONTH(date)")
+                    elif "年" in group_text or "year" in group_text:
+                        group_cols.append("YEAR(date)")
+                    break
+    return group_cols
+
+
+def extract_ordering(
+    text: str,
+    column_patterns: Optional[Dict[str, str]] = None,
+) -> Optional[Tuple[str, str]]:
+    """Extract ORDER BY clause from text.
+
+    Verbatim move of ``nl2sql_legacy._extract_ordering``; ``column_patterns``
+    replaces the instance attribute.
+    """
+    column_patterns = column_patterns or COLUMN_PATTERNS
+    order_col = None
+    for pattern, column in column_patterns.items():
+        if pattern in text:
+            order_col = column
+            break
+    # Use word-boundary matching to avoid false positives (e.g., "orders" contains "order")
+    if any(re.search(rf'\b{k}\b', text, re.IGNORECASE) for k in ["排序", "排列", "sort", "order", "sorted"]):
+        return (
+            order_col or "id",
+            "DESC"
+            if any(re.search(rf'\b{k}\b', text, re.IGNORECASE) for k in ["降序", "从大到小", "递减", "desc", "descending", "decreasing"])
+            else "ASC",
+        )
+    if any(re.search(rf'\b{k}\b', text, re.IGNORECASE) for k in ["最大", "最高", "最多", "max", "highest", "top"]):
+        return (order_col or "amount", "DESC")
+    if any(re.search(rf'\b{k}\b', text, re.IGNORECASE) for k in ["最小", "最低", "最少", "min", "lowest"]):
+        return (order_col or "amount", "ASC")
+    return None

backend/core/nl2sql_pipeline/dialect.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+"""P8 NL2SQL pipeline: dialect rewriter (moved UNCHANGED from nl2sql_legacy).
+
+Regex-based, executable-region-aware dialect adjustment.  In P8 this module
+is a verbatim move; AST-based rewriting is deferred to a future phase.
+"""
+import re
+from typing import Callable
+
+from ..p1_sql_scanner import executable_segments
+
+# Pattern types shared by the per-dialect replacement tables.
+_re_p = re.Pattern
+_re_s = str | Callable[[re.Match], str]
+
+
+def apply_dialect_adjustments(sql: str, dialect: str) -> str:
+    """Apply dialect-specific syntax adjustments.
+
+    Uses executable-region-aware replacement so literals, comments, and
+    quoted identifiers are never modified.
+    """
+    dialect = dialect.lower()
+
+    if dialect == "hive":
+        return sql
+
+    replacements: list[tuple[_re_p, _re_s]] = []
+
+    if dialect == "oracle":
+        # Handle DATE_SUB/DATE_ADD/ADD_MONTHS with CURRENT_DATE first,
+        # then handle the already-converted forms (TRUNC(SYSDATE)).
+        replacements = [
+            (
+                re.compile(
+                    r"\bDATE_SUB\(\s*(?:TRUNC\(SYSDATE\)|CURRENT_DATE)\s*,\s*(\d+)\s*\)",
+                    re.IGNORECASE,
+                ),
+                r"TRUNC(SYSDATE) - \1",
+            ),
+            (
+                re.compile(
+                    r"\bDATE_ADD\(\s*(?:TRUNC\(SYSDATE\)|CURRENT_DATE)\s*,\s*(\d+)\s*\)",
+                    re.IGNORECASE,
+                ),
+                r"TRUNC(SYSDATE) + \1",
+            ),
+            (
+                re.compile(
+                    r"\bADD_MONTHS\(\s*(?:TRUNC\(SYSDATE\)|CURRENT_DATE)\s*,\s*([+-]?\d+)\s*\)",
+                    re.IGNORECASE,
+                ),
+                r"ADD_MONTHS(TRUNC(SYSDATE), \1)",
+            ),
+            (re.compile(r"\bCURRENT_TIMESTAMP\b", re.IGNORECASE), "SYSTIMESTAMP"),
+            (re.compile(r"\bCURRENT_DATE\b", re.IGNORECASE), "TRUNC(SYSDATE)"),
+        ]
+    elif dialect == "tsql":
+        replacements = [
+            (
+                re.compile(
+                    r"\bDATE_SUB\(\s*(?:CAST\(GETDATE\(\)\s+AS\s+DATE\)|CURRENT_DATE)\s*,\s*(\d+)\s*\)",
+                    re.IGNORECASE,
+                ),
+                r"DATEADD(DAY, -\1, CAST(GETDATE() AS DATE))",
+            ),
+            (
+                re.compile(
+                    r"\bDATE_ADD\(\s*(?:CAST\(GETDATE\(\)\s+AS\s+DATE\)|CURRENT_DATE)\s*,\s*(\d+)\s*\)",
+                    re.IGNORECASE,
+                ),
+                r"DATEADD(DAY, \1, CAST(GETDATE() AS DATE))",
+            ),
+            (
+                re.compile(
+                    r"\bADD_MONTHS\(\s*(?:CAST\(GETDATE\(\)\s+AS\s+DATE\)|CURRENT_DATE)\s*,\s*([+-]?\d+)\s*\)",
+                    re.IGNORECASE,
+                ),
+                r"DATEADD(MONTH, \1, CAST(GETDATE() AS DATE))",
+            ),
+            (re.compile(r"\bCURRENT_TIMESTAMP\b", re.IGNORECASE), "SYSDATETIME()"),
+            (re.compile(r"\bCURRENT_DATE\b", re.IGNORECASE), "CAST(GETDATE() AS DATE)"),
+        ]
+    elif dialect == "mysql":
+        replacements = [
+            (
+                re.compile(r"\bDATE_SUB\(\s*CURRENT_DATE\s*,\s*(\d+)\s*\)", re.IGNORECASE),
+                r"DATE_SUB(CURRENT_DATE, INTERVAL \1 DAY)",
+            ),
+            (
+                re.compile(r"\bDATE_ADD\(\s*CURRENT_DATE\s*,\s*(\d+)\s*\)", re.IGNORECASE),
+                r"DATE_ADD(CURRENT_DATE, INTERVAL \1 DAY)",
+            ),
+            (
+                re.compile(
+                    r"\bADD_MONTHS\(\s*CURRENT_DATE\s*,\s*([+-]?\d+)\s*\)",
+                    re.IGNORECASE,
+                ),
+                lambda match: (
+                    f"DATE_SUB(CURRENT_DATE, INTERVAL {abs(int(match.group(1)))} MONTH)"
+                    if int(match.group(1)) < 0
+                    else f"DATE_ADD(CURRENT_DATE, INTERVAL {match.group(1)} MONTH)"
+                ),
+            ),
+        ]
+    elif dialect in ("postgres", "duckdb"):
+        replacements = [
+            (
+                re.compile(r"\bDATE_SUB\(\s*CURRENT_DATE\s*,\s*(\d+)\s*\)", re.IGNORECASE),
+                r"CURRENT_DATE - INTERVAL '\1 days'",
+            ),
+            (
+                re.compile(r"\bDATE_ADD\(\s*CURRENT_DATE\s*,\s*(\d+)\s*\)", re.IGNORECASE),
+                r"CURRENT_DATE + INTERVAL '\1 days'",
+            ),
+            (
+                re.compile(
+                    r"\bADD_MONTHS\(\s*CURRENT_DATE\s*,\s*([+-]?\d+)\s*\)",
+                    re.IGNORECASE,
+                ),
+                r"CURRENT_DATE + INTERVAL '\1 month'",
+            ),
+        ]
+    else:
+        return sql
+
+    for pattern, replacement in replacements:
+        parts = []
+        cursor = 0
+        for start, end in executable_segments(sql):
+            parts.append(sql[cursor:start])
+            segment = sql[start:end]
+            segment = pattern.sub(replacement, segment)
+            parts.append(segment)
+            cursor = end
+        parts.append(sql[cursor:])
+        sql = "".join(parts)
+
+    return sql

backend/core/nl2sql_pipeline/intent.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""P8 NL2SQL pipeline: intent analysis (moved from nl2sql_legacy).
+
+Holds the tokenization / semantic-analysis step (``analyze_intent``)
+and the text-parsing helpers (``parse_text``, ``detect_operation``)
+that feed the resolution stages.
+"""
+import re
+from typing import Any, Dict, Optional
+
+from ..nl2sql_components.core_extract import detect_operation as _detect_operation_impl
+from ..nl2sql_components.mappings import COLUMN_PATTERNS, KEYWORDS, TABLE_PATTERNS
+from ..nl2sql_components.tokenizer import Tokenizer
+
+
+def analyze_intent(text: str) -> Dict[str, Any]:
+    """Tokenize text and perform semantic analysis.
+
+    Returns the same dict shape the legacy
+    ``_tokenize_and_analyze`` produced:
+    ``tokens``, ``numbers``, ``quoted_strings``, ``tables``, ``columns``,
+    ``operations``, ``is_chinese``, ``token_count``.
+    """
+    tokenizer = Tokenizer()
+    tokens = tokenizer.tokenize(text)
+    numbers = tokenizer.extract_numbers(text)
+    quoted = tokenizer.extract_quoted_strings(text)
+
+    detected_tables = [
+        TABLE_PATTERNS[token]
+        for token in tokens
+        if token in TABLE_PATTERNS
+    ]
+    detected_columns = [
+        COLUMN_PATTERNS[token]
+        for token in tokens
+        if token in COLUMN_PATTERNS
+    ]
+    detected_ops = [
+        KEYWORDS[token]
+        for token in tokens
+        if token in KEYWORDS
+    ]
+
+    return {
+        "tokens": tokens,
+        "numbers": numbers,
+        "quoted_strings": quoted,
+        "tables": list(set(detected_tables)),
+        "columns": list(set(detected_columns)),
+        "operations": list(set(detected_ops)),
+        "is_chinese": tokenizer.is_chinese(text),
+        "token_count": len(tokens),
+    }
+
+
+def parse_text(text_lower: str, original: str) -> dict:
+    """Parse and extract all elements from text (legacy ``_parse_text``)."""
+    parsed = {
+        "tables": [],
+        "columns": [],
+        "conditions": [],
+        "aggregations": [],
+        "time_range": None,
+        "limit": None,
+        "order": None,
+        "joins": [],
+    }
+    # Word-boundary matching for tables to avoid false positives like "order" matching "orders"
+    for pattern, table in TABLE_PATTERNS.items():
+        if re.search(r'\b' + re.escape(pattern) + r'\b', text_lower) and table not in parsed["tables"]:
+            parsed["tables"].append(table)
+    # Word-boundary matching for columns
+    for pattern, column in COLUMN_PATTERNS.items():
+        if re.search(r'\b' + re.escape(pattern) + r'\b', text_lower) and column not in parsed["columns"]:
+            parsed["columns"].append(column)
+    numbers = re.findall(r"\d+", original)
+    if numbers:
+        parsed["numbers"] = numbers
+    return parsed
+
+
+def detect_operation(text: str) -> str:
+    """Detect SQL operation type from text (delegates to core_extract)."""
+    return _detect_operation_impl(text, KEYWORDS)

backend/core/nl2sql_pipeline/ir.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+"""P8 NL2SQL pipeline: Query IR.
+
+The IR is the structured intermediate representation produced by the
+resolution stages and consumed by the renderer.  In P8 it mirrors the
+flat positional-argument shape of the legacy ``_build_sql_enhanced``
+call, plus the ``evidence`` accumulator, so the migration is
+behavior-preserving.
+"""
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple, Union
+
+from ..nl2sql_components.evidence import GenerationEvidence
+
+
+@dataclass
+class QueryIR:
+    """Structured intermediate representation for an NL2SQL query.
+
+    Mirrors the positional-argument shape of the legacy
+    ``_build_sql_enhanced`` call.  ``conditions`` may be a ``list`` of
+    predicate strings or a single ``str`` — the renderer handles both
+    (mirroring current legacy code).
+    """
+
+    operation: str
+    table: str
+    columns: List[str]
+    conditions: Union[List[str], str]
+    aggregations: List[str]
+    group_by: List[str]
+    ordering: Optional[Tuple[str, str]]
+    limit: Optional[int]
+    joins: List[Dict]
+    distinct: bool
+    dialect: str
+    evidence: GenerationEvidence = field(default_factory=GenerationEvidence)
+
+
+def build_ir(
+    operation: str,
+    table: str,
+    columns: List[str],
+    conditions: Union[List[str], str],
+    aggregations: List[str],
+    group_by: List[str],
+    ordering: Optional[Tuple[str, str]],
+    limit: Optional[int],
+    joins: List[Dict],
+    distinct: bool,
+    dialect: str,
+) -> QueryIR:
+    """Thin positional-arg adapter mirroring the legacy call site.
+
+    Constructs a ``QueryIR`` with a fresh ``GenerationEvidence``
+    accumulator, identical to what the legacy code did implicitly.
+    """
+    return QueryIR(
+        operation=operation,
+        table=table,
+        columns=columns,
+        conditions=conditions,
+        aggregations=aggregations,
+        group_by=group_by,
+        ordering=ordering,
+        limit=limit,
+        joins=joins,
+        distinct=distinct,
+        dialect=dialect,
+    )

backend/core/nl2sql_pipeline/models.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""P8 NL2SQL pipeline: result model.
+
+``NL2SQLResult`` is the single canonical result dataclass.  It is re-exported
+from every import path (``nl2sql``, ``nl2sql_legacy``, ``nl2sql_pipeline``)
+so that ``from backend.core.nl2sql import NL2SQLResult as A`` and
+``from backend.core.nl2sql_legacy import NL2SQLResult as B`` satisfy
+``A is B``.
+"""
+from dataclasses import dataclass, field
+
+from ..nl2sql_components.evidence import GenerationEvidence
+
+
+@dataclass
+class NL2SQLResult:
+    """Result of NL2SQL generation."""
+
+    success: bool = False
+    input_text: str = ""
+    sql: str | None = None
+    dialect: str = ""
+    explanation: str = ""
+    confidence: float = 0.0
+    # Structured evidence trail backing ``confidence``. Optional and
+    # backward-compatible: consumers that only need the scalar score can
+    # ignore this field.
+    evidence: GenerationEvidence | None = None
+    suggestions: list = field(default_factory=list)
+    parsed_elements: dict = field(default_factory=dict)