Sync from GitHub main

app/main.py

@@ -2,7 +2,7 @@ import os
 import time
 
 from fastapi import FastAPI, Request, Response, HTTPException
-from fastapi.responses import PlainTextResponse, RedirectResponse
+from fastapi.responses import PlainTextResponse, RedirectResponse, JSONResponse
 from prometheus_client import Counter, Histogram, generate_latest, CONTENT_TYPE_LATEST
 
 from nl2sql.prom import REGISTRY
@@ -38,6 +38,15 @@ application.include_router(nl2sql.router, prefix="/api/v1")
 if os.getenv("APP_ENV", "dev").lower() == "dev":
     application.include_router(dev.router, prefix="/api/v1")
 
+
+@application.exception_handler(HTTPException)
+async def http_exception_to_error_contract(request: Request, exc: HTTPException):
+    if isinstance(exc.detail, dict) and "error" in exc.detail:
+        return JSONResponse(status_code=exc.status_code, content=exc.detail)
+
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+
+
 # ----------------------------------------------------------------------------
 #  Prometheus Metrics Middleware
 # ----------------------------------------------------------------------------

app/routers/nl2sql.py

@@ -23,11 +23,10 @@ from app.services.nl2sql_service import NL2SQLService
 from app.settings import get_settings
 from app.errors import (
     AppError,
-    BadRequestError,
-    SafetyViolationError,
-    DependencyError,
     PipelineRunError,
 )
+from nl2sql.errors.mapper import map_error
+from nl2sql.errors.codes import ErrorCode
 
 logger = logging.getLogger(__name__)
 settings = get_settings()
@@ -358,65 +357,34 @@ def nl2sql_handler(
         qs = result.questions or []
         return ClarifyResponse(ambiguous=True, questions=qs)
 
-    # ---- error path: map pipeline failures to stable HTTP+JSON error contract ----
+    # ---- error path: contract-based mapping (Phase 3) ----
     if (not result.ok) or result.error:
         logger.debug(
             "Pipeline reported failure",
-            extra={"ok": result.ok, "error": result.error, "details": result.details},
+            extra={
+                "ok": result.ok,
+                "error": result.error,
+                "error_code": getattr(result, "error_code", None),
+                "details": result.details,
+            },
         )
 
-        details = list(result.details or [])
-        traces = list(result.traces or [])
-        last_stage = str(traces[-1].get("stage", "unknown")) if traces else "unknown"
-        details_l = " ".join(d.lower() for d in details)
-
-        # 1) Safety violations → 422
-        if last_stage == "safety":
-            raise SafetyViolationError(
-                message="Rejected by safety checks.",
-                details=details or None,
-                extra={"stage": last_stage},
-            )
-
-        # 2) Retryable dependency failures → 503
-        retry_hints = (
-            "timeout",
-            "timed out",
-            "rate limit",
-            "429",
-            "too many requests",
-            "locked",
-            "busy",
-            "unavailable",
-            "connection",
-        )
-        if any(h in details_l for h in retry_hints):
-            raise DependencyError(
-                message="Temporary dependency failure. Please retry.",
-                details=details or None,
-                extra={"stage": last_stage},
-            )
-
-        # 3) User-fixable parse/syntax-ish errors → 400
-        user_hints = (
-            "parse_error",
-            "non-select",
-            "explain not allowed",
-            "multiple statements",
-            "forbidden",
-        )
-        if any(h in details_l for h in user_hints):
-            raise BadRequestError(
-                message="Request could not be processed.",
-                details=details or None,
-                extra={"stage": last_stage},
-            )
-
-        # 4) Default → 500
-        raise PipelineRunError(
-            message="Pipeline failed unexpectedly.",
-            details=details or None,
-            extra={"stage": last_stage},
+        # 1) Normalize code (never string-match here)
+        code = result.error_code or ErrorCode.PIPELINE_CRASH
+
+        # 2) Single source of truth for HTTP semantics
+        status, retryable = map_error(code)
+
+        # 3) Stable error payload for UI/clients
+        raise HTTPException(
+            status_code=status,
+            detail={
+                "error": {
+                    "code": code.value,
+                    "retryable": retryable,
+                    "details": list(result.details or []),
+                }
+            },
         )
 
     # ---- success path → 200 (normalize traces and executor result) ----

nl2sql/errors/codes.py

@@ -0,0 +1,23 @@
+from enum import Enum
+
+
+class ErrorCode(str, Enum):
+    # --- Safety ---
+    SAFETY_NON_SELECT = "SAFETY_NON_SELECT"
+    SAFETY_MULTI_STATEMENT = "SAFETY_MULTI_STATEMENT"
+
+    # --- Verifier ---
+    PLAN_NO_SUCH_TABLE = "PLAN_NO_SUCH_TABLE"
+    PLAN_NO_SUCH_COLUMN = "PLAN_NO_SUCH_COLUMN"
+    PLAN_SYNTAX_ERROR = "PLAN_SYNTAX_ERROR"
+
+    # --- Executor / DB ---
+    DB_LOCKED = "DB_LOCKED"
+    DB_TIMEOUT = "DB_TIMEOUT"
+
+    # --- LLM ---
+    LLM_TIMEOUT = "LLM_TIMEOUT"
+    LLM_BAD_OUTPUT = "LLM_BAD_OUTPUT"
+
+    # --- Internal ---
+    PIPELINE_CRASH = "PIPELINE_CRASH"

nl2sql/errors/mapper.py

@@ -0,0 +1,19 @@
+from nl2sql.errors.codes import ErrorCode
+
+ERROR_MAP = {
+    ErrorCode.SAFETY_NON_SELECT: (422, False),
+    ErrorCode.SAFETY_MULTI_STATEMENT: (422, False),
+    ErrorCode.PLAN_NO_SUCH_TABLE: (422, False),
+    ErrorCode.PLAN_NO_SUCH_COLUMN: (422, False),
+    ErrorCode.PLAN_SYNTAX_ERROR: (422, False),
+    ErrorCode.DB_LOCKED: (503, True),
+    ErrorCode.DB_TIMEOUT: (503, True),
+    ErrorCode.LLM_TIMEOUT: (503, True),
+    ErrorCode.PIPELINE_CRASH: (500, False),
+}
+
+
+def map_error(code: ErrorCode | None) -> tuple[int, bool]:
+    if code is None:
+        return (500, False)
+    return ERROR_MAP.get(code, (500, False))

nl2sql/pipeline.py

@@ -14,6 +14,7 @@ from nl2sql.verifier import Verifier
 from nl2sql.repair import Repair
 from nl2sql.stubs import NoOpExecutor, NoOpRepair, NoOpVerifier
 from nl2sql.metrics import stage_duration_ms, pipeline_runs_total, repair_attempts_total
+from nl2sql.errors.codes import ErrorCode
 
 
 @dataclass(frozen=True)
@@ -21,12 +22,16 @@ class FinalResult:
     ok: bool
     ambiguous: bool
     error: bool
+
     details: Optional[List[str]]
     sql: Optional[str]
     rationale: Optional[str]
     verified: Optional[bool]
     questions: Optional[List[str]]
     traces: List[dict]
+
+    error_code: Optional[ErrorCode] = None
+
     result: Optional[Dict[str, Any]] = None
 
 

nl2sql/types.py

@@ -1,35 +1,62 @@
 from dataclasses import dataclass
 from typing import Any, Dict, Optional, List
 
+from nl2sql.errors.codes import ErrorCode
+
+
+# =====================
+# Tracing / Observability
+# =====================
+
 
 @dataclass(frozen=True)
 class StageTrace:
     stage: str
-    duration_ms: float  # keep float internally if you like
-    summary: str = ""  # ← default to keep legacy call-sites working
+    duration_ms: float
+    summary: str = ""
     notes: Optional[Dict[str, Any]] = None
+
+    # Optional observability fields
     token_in: Optional[int] = None
     token_out: Optional[int] = None
     cost_usd: Optional[float] = None
 
-    # Enriched fields
+    # Enriched / debug-only fields
     sql_length: Optional[int] = None
     row_count: Optional[int] = None
     verified: Optional[bool] = None
-    error_type: Optional[str] = None
     repair_attempts: Optional[int] = None
     skipped: bool = False
 
 
+# =====================
+# Stage-level contract
+# =====================
+
+
 @dataclass(frozen=True)
 class StageResult:
     ok: bool
+
     data: Optional[Any] = None
     trace: Optional[StageTrace] = None
+
+    # Human-readable error messages (debug / UI only)
     error: Optional[List[str]] = None
+
+    # === Contract-level semantics ===
+    error_code: Optional[ErrorCode] = None
+    retryable: Optional[bool] = None
+
+    # Free-form notes (internal use)
     notes: Optional[Dict[str, Any]] = None
 
 
+# =====================
+# Final pipeline result
+# =====================
+
+
 @dataclass(frozen=True)
 class FinalResult:
     """
@@ -37,12 +64,21 @@ class FinalResult:
     Adapters (HTTP/CLI/UI) should serialize this to dict/JSON at the boundary.
     """
 
-    ok: bool  # end-to-end success
+    ok: bool
     ambiguous: bool
     error: bool
+
+    # Output
     sql: Optional[str]
     rationale: Optional[str]
     verified: Optional[bool]
+
+    # Error surface
+    error_code: Optional[ErrorCode]
     details: Optional[List[str]]
+
+    # UX helpers
     questions: Optional[List[str]]
+
+    # Observability
     traces: List[Dict[str, Any]]

nl2sql/verifier.py

@@ -4,6 +4,7 @@ import re
 import time
 from typing import Any, Dict
 
+from nl2sql.errors.codes import ErrorCode
 from nl2sql.metrics import verifier_checks_total, verifier_failures_total
 from nl2sql.types import StageResult, StageTrace
 
@@ -43,6 +44,7 @@ class Verifier:
                     notes,
                     error=["parse_error"],
                     reason=reason,
+                    error_code=ErrorCode.PLAN_SYNTAX_ERROR,  # best-fit for malformed SQL
                 )
 
             # --- semantic sanity: aggregation without GROUP BY (unless allowed) ---
@@ -83,6 +85,7 @@ class Verifier:
                     notes,
                     error=["aggregation_without_group_by"],
                     reason=reason,
+                    error_code=ErrorCode.PLAN_SYNTAX_ERROR,
                 )
 
             # --- DB-backed plan validation (read-only), if adapter provided ---
@@ -94,12 +97,16 @@ class Verifier:
                 except Exception as e:
                     reason = "plan-error"
                     notes["plan_check"] = "failed"
+
+                    code = self._classify_plan_error(e)
+
                     return self._fail(
                         t0,
                         notes,
                         error=[str(e)],
                         reason=reason,
                         exc_type=type(e).__name__,
+                        error_code=code,
                     )
 
             # --- pass ---
@@ -125,6 +132,7 @@ class Verifier:
                 error=[str(e)],
                 reason=reason,
                 exc_type=type(e).__name__,
+                error_code=ErrorCode.PIPELINE_CRASH,
             )
 
     def run(
@@ -137,6 +145,25 @@ class Verifier:
         # exec_result kept for signature compatibility, not used here.
         return self.verify(sql, adapter=adapter)
 
+    def _classify_plan_error(self, e: Exception) -> ErrorCode:
+        msg = str(e).lower()
+
+        # SQLite-style messages
+        if "no such table" in msg:
+            return ErrorCode.PLAN_NO_SUCH_TABLE
+        if "no such column" in msg:
+            return ErrorCode.PLAN_NO_SUCH_COLUMN
+        if "syntax error" in msg:
+            return ErrorCode.PLAN_SYNTAX_ERROR
+
+        # Postgres-style messages (common cases)
+        if "relation" in msg and "does not exist" in msg:
+            return ErrorCode.PLAN_NO_SUCH_TABLE
+        if "column" in msg and "does not exist" in msg:
+            return ErrorCode.PLAN_NO_SUCH_COLUMN
+
+        return ErrorCode.PLAN_SYNTAX_ERROR
+
     def _fail(
         self,
         t0: float,
@@ -145,6 +172,7 @@ class Verifier:
         error: list[str],
         reason: str,
         exc_type: str | None = None,
+        error_code: ErrorCode | None = None,
     ) -> StageResult:
         dt = int(round((time.perf_counter() - t0) * 1000.0))
 
@@ -166,4 +194,6 @@ class Verifier:
             data={"verified": False},
             trace=trace,
             error=error,
+            error_code=error_code,
+            retryable=False,
         )